xlsxrb 0.1.13 → 0.1.15

data/lib/xlsxrb/stream_writer.rb

@@ -6,6 +6,7 @@ require "tempfile"
 require_relative "style_builder"
 require_relative "chart_builder"
 require_relative "dsl_helpers"
+require_relative "worksheet_builder"
 require_relative "ooxml/writer"
 require_relative "ooxml/worksheet_writer"
 require_relative "ooxml/workbook_writer"
@@ -70,9 +71,12 @@ module Xlsxrb
       @current_images = []
       @current_shapes = []
       @current_sheet_properties = {}
+      @current_sheet_format = {}
       @current_sheet_view = {}
       @current_row_breaks = []
       @current_col_breaks = []
+      @current_protected_ranges = []
+      @current_cell_watches = []
       @current_cells = {}
       @styles = {} # { style_name => StyleBuilder }
       @style_writer = Ooxml::Writer.new
@@ -220,15 +224,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 +306,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
 
@@ -344,15 +363,24 @@ module Xlsxrb
 
       # Adds data validation rules to a range.
       #
+      # Adds data validation to a cell or range.
+      #
       # @example Dropdown list validation
       #   s.validate_data("B2:B100", type: "list", formula1: '"High,Medium,Low"')
       #
-      # @param range [String] The cell range (e.g. "B2:B10").
-      # @param type [String, Symbol] Validation type ("list", "whole", "decimal", "date", "time", "textLength", "custom").
+      # @example Block syntax
+      #   s.validate_data("B2:B100") do |dv|
+      #     dv.type :list
+      #     dv.formula1 '"High,Medium,Low"'
+      #   end
+      #
+      # @param range [String, nil] The cell range (e.g. "B2:B10").
+      # @param type [String, Symbol, nil] Validation type ("list", "whole", "decimal", "date", "time", "textLength", "custom").
       # @param opts [Hash] Validation options.
+      # @yield [data_validation_builder] Optional configuration block.
       # @return [void]
       # @api public
-      #: (String range, ?type: String | Symbol, **untyped opts) -> void
+      #: (?String? range, ?type: (String | Symbol)?, **untyped opts) ?{ (DataValidationBuilder) -> void } -> void
       def validate_data(...)
         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
 
@@ -378,18 +406,25 @@ module Xlsxrb
 
       # Adds a formatted Excel Table to the sheet.
       #
-      # @example
+      # @example Standard keyword arguments
       #   s.table("A1:C10", columns: ["ID", "Name", "Total"], name: "SalesTable", style: "TableStyleMedium9")
       #
-      # @param ref [String] The cell range for the table (e.g. "A1:D10").
-      # @param columns [Array<String>, Array<Hash>] Column names or definitions.
+      # @example Block syntax
+      #   s.table("A1:C10") do |t|
+      #     t.columns ["ID", "Name", "Total"]
+      #     t.style "TableStyleMedium9"
+      #   end
+      #
+      # @param ref [String, nil] The cell range for the table (e.g. "A1:D10").
+      # @param columns [Array<String>, Array<Hash>, nil] Column names or definitions.
       # @param name [String, nil] Table name.
       # @param display_name [String, nil] Display name.
       # @param style [String, nil] Table style name.
       # @param opts [Hash] Additional options.
+      # @yield [table_builder] Optional configuration block.
       # @return [void]
       # @api public
-      #: (String ref, columns: untyped, ?name: String?, ?display_name: String?, ?style: String?, **untyped opts) -> void
+      #: (?String? ref, ?columns: untyped, ?name: String?, ?display_name: String?, ?style: String?, **untyped opts) ?{ (TableBuilder) -> void } -> void
       def table(...)
         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 +495,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 +613,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.
@@ -765,6 +850,20 @@ module Xlsxrb
         @writer.sheet_view(...)
       end
 
+      # Configures sheet format properties (e.g. default_row_height, default_col_width).
+      #
+      # @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[Symbol, untyped]]
+      # @api public
+      #: (?Symbol | String | Hash[Symbol, untyped] | nil name, ?untyped value, **untyped opts) -> Hash[Symbol, untyped]
+      def sheet_format(...)
+        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.sheet_format(...)
+      end
+
       # simplecov:disable
       # Edge case / untested delegation block
       # Adds a horizontal page break after the given row index.
@@ -794,6 +893,35 @@ module Xlsxrb
         @writer.page_break_col(...)
       end
       # simplecov:enable
+
+      # Adds a protected range to the sheet.
+      #
+      # @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(...)
+        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.protected_range(...)
+      end
+      alias add_protected_range protected_range
+
+      # Adds a cell watch to the sheet.
+      #
+      # @param ref [String] Cell reference (e.g. "A1").
+      # @return [void]
+      # @api public
+      #: (String ref) -> void
+      def cell_watch(...)
+        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.cell_watch(...)
+      end
+      alias add_cell_watch cell_watch
     end
 
     # Adds a new sheet to the workbook and starts streaming rows into it.
@@ -829,7 +957,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 = []
@@ -856,9 +985,12 @@ module Xlsxrb
       @current_images = []
       @current_shapes = []
       @current_sheet_properties = {}
+      @current_sheet_format = {}
       @current_sheet_view = {}
       @current_row_breaks = []
       @current_col_breaks = []
+      @current_protected_ranges = []
+      @current_cell_watches = []
       @current_cells = {}
 
       return unless block_given?
@@ -883,14 +1015,26 @@ 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,
         freeze_pane: @current_freeze_pane,
         split_pane: @current_split_pane,
         selection: @current_selection,
-        sheet_view: @current_sheet_view.empty? ? nil : @current_sheet_view
+        sheet_view: @current_sheet_view.empty? ? nil : @current_sheet_view,
+        sheet_format: @current_sheet_format.empty? ? nil : @current_sheet_format
       )
       @zip.write_data(@current_row_buffer) unless @current_row_buffer.empty?
       @current_row_buffer.clear
@@ -906,8 +1050,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 +1075,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 +1161,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
@@ -1042,13 +1219,22 @@ module Xlsxrb
 
     # Adds a data validation rule.
     #
-    # @param sqref [String] Cell range.
+    # @param sqref [String, nil] Cell range.
     # @param opts [Hash] Validation options.
+    # @yield [data_validation_builder] Optional configuration block.
     # @return [void]
     # @api public
-    #: (untyped sqref, **untyped opts) -> void
-    def validate_data(sqref, **opts)
+    #: (?String? sqref, **untyped opts) ?{ (DataValidationBuilder) -> void } -> void
+    def validate_data(sqref = nil, **opts)
       sheet if @current_sheet.nil?
+      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
+
       @current_data_validations << opts.merge(sqref: sqref)
     end
 
@@ -1066,18 +1252,33 @@ module Xlsxrb
 
     # Adds an Excel Table (ListObject).
     #
-    # @param ref [String] Table range.
-    # @param columns [Array<String>] Column names.
+    # @param ref [String, nil] Table range.
+    # @param columns [Array<String>, nil] Column names.
     # @param name [String, nil] Table name.
     # @param display_name [String, nil] Display name.
     # @param style [String, nil] Table style.
     # @param opts [Hash] Additional options.
+    # @yield [table_builder] Optional configuration block.
     # @return [void]
     # @api public
-    #: (untyped ref, columns: untyped, ?name: untyped, ?display_name: untyped, ?style: untyped, **untyped opts) -> void
-    def table(ref, columns:, name: nil, display_name: nil, style: nil, **)
+    #: (?String? ref, ?columns: untyped, ?name: untyped, ?display_name: untyped, ?style: untyped, **untyped opts) ?{ (TableBuilder) -> void } -> void
+    def table(ref = nil, columns: nil, name: nil, display_name: nil, style: nil, **opts)
       sheet if @current_sheet.nil?
-      @current_tables << DslHelpers.normalize_table_options(ref, columns: columns, name: name, display_name: display_name, style: style, **)
+      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?
+
+      @current_tables << DslHelpers.normalize_table_options(ref, columns: columns, name: name, display_name: display_name, style: style, **opts)
     end
 
     # Adds a Pivot Table.
@@ -1134,6 +1335,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.
@@ -1322,6 +1555,25 @@ module Xlsxrb
       @current_sheet_view[name] = value
     end
 
+    # Configures sheet format properties (e.g. default_row_height, default_col_width).
+    #
+    # @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[Symbol, untyped]]
+    # @api public
+    #: (?Symbol | String | Hash[Symbol, untyped] | nil name, ?untyped value, **untyped opts) -> Hash[Symbol, untyped]
+    def sheet_format(name = nil, value = nil, **opts)
+      sheet if @current_sheet.nil?
+      if name.is_a?(Hash)
+        @current_sheet_format.merge!(name)
+      elsif name && value
+        @current_sheet_format[name.to_sym] = value
+      end
+      @current_sheet_format.merge!(opts) unless opts.empty?
+      @current_sheet_format
+    end
+
     # Inserts a horizontal page break before a row.
     #
     # @param row_num [Integer] 1-based row number.
@@ -1351,6 +1603,36 @@ module Xlsxrb
       # simplecov:enable
     end
 
+    # Adds a protected range to the current sheet.
+    #
+    # @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)
+      sheet if @current_sheet.nil?
+      entry = { name: name.to_s, sqref: sqref.to_s }
+      entry[:password] = password if password
+      entry.merge!(opts) unless opts.empty?
+      @current_protected_ranges << DslHelpers.normalize_protection_options(entry)
+    end
+    alias add_protected_range protected_range
+
+    # Adds a cell watch to the current sheet.
+    #
+    # @param ref [String] Cell reference (e.g. "A1").
+    # @return [void]
+    # @api public
+    #: (String ref) -> void
+    def cell_watch(ref)
+      sheet if @current_sheet.nil?
+      @current_cell_watches << ref.to_s
+    end
+    alias add_cell_watch cell_watch
+
     # --- Workbook-Level Methods ---
 
     # Adds a defined name.
@@ -1398,6 +1680,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 +1693,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.
@@ -1623,9 +1959,12 @@ module Xlsxrb
         images: @current_images,
         shapes: @current_shapes,
         sheet_properties: @current_sheet_properties,
+        sheet_format: @current_sheet_format,
         sheet_view: @current_sheet_view,
         row_breaks: @current_row_breaks,
-        col_breaks: @current_col_breaks
+        col_breaks: @current_col_breaks,
+        protected_ranges: @current_protected_ranges,
+        cell_watches: @current_cell_watches
       }
       sheet_data[:cells] = @current_cells if @current_cells && !@current_cells.empty?
       @current_cells = nil
@@ -1636,6 +1975,7 @@ module Xlsxrb
       @current_row_writer.finish(
         drawing_rid: info[:drawing_rid],
         sheet_protection: @current_sheet_protection,
+        protected_ranges: @current_protected_ranges.empty? ? nil : @current_protected_ranges,
         auto_filter: @current_auto_filter,
         filter_columns: @current_filter_columns.empty? ? nil : @current_filter_columns,
         sort_state: @current_sort_state,
@@ -1649,6 +1989,7 @@ module Xlsxrb
         header_footer: @current_header_footer.empty? ? nil : @current_header_footer,
         row_breaks: @current_row_breaks.empty? ? nil : @current_row_breaks,
         col_breaks: @current_col_breaks.empty? ? nil : @current_col_breaks,
+        cell_watches: @current_cell_watches.empty? ? nil : @current_cell_watches,
         tables: @current_tables.empty? ? nil : @current_tables,
         table_start_rid: info[:table_start_rid],
         legacy_drawing_rid: info[:vml_rid],