xlsxrb 0.1.13 → 0.1.14

data/lib/xlsxrb/style_builder.rb

@@ -20,6 +20,281 @@ module Xlsxrb
       grey: "FF808080"
     }.freeze
 
+    CSS_COLORS = {
+      aliceblue: "F0F8FF",
+      antiquewhite: "FAEBD7",
+      aqua: "00FFFF",
+      aquamarine: "7FFFD4",
+      azure: "F0FFFF",
+      beige: "F5F5DC",
+      bisque: "FFE4C4",
+      black: "000000",
+      blanchedalmond: "FFEBCD",
+      blue: "0000FF",
+      blueviolet: "8A2BE2",
+      brown: "A52A2A",
+      burlywood: "DEB887",
+      cadetblue: "5F9EA0",
+      chartreuse: "7FFF00",
+      chocolate: "D2691E",
+      coral: "FF7F50",
+      cornflowerblue: "6495ED",
+      cornsilk: "FFF8DC",
+      crimson: "DC143C",
+      cyan: "00FFFF",
+      darkblue: "00008B",
+      darkcyan: "008B8B",
+      darkgoldenrod: "B8860B",
+      darkgray: "A9A9A9",
+      darkgrey: "A9A9A9",
+      darkgreen: "006400",
+      darkkhaki: "BDB76B",
+      darkmagenta: "8B008B",
+      darkolivegreen: "556B2F",
+      darkorange: "FF8C00",
+      darkorchid: "9932CC",
+      darkred: "8B0000",
+      darksalmon: "E9967A",
+      darkseagreen: "8FBC8F",
+      darkslateblue: "483D8B",
+      darkslategray: "2F4F4F",
+      darkslategrey: "2F4F4F",
+      darkturquoise: "00CED1",
+      darkviolet: "9400D3",
+      deeppink: "FF1493",
+      deepskyblue: "00BFFF",
+      dimgray: "696969",
+      dimgrey: "696969",
+      dodgerblue: "1E90FF",
+      firebrick: "B22222",
+      floralwhite: "FFFAF0",
+      forestgreen: "228B22",
+      fuchsia: "FF00FF",
+      gainsboro: "DCDCDC",
+      ghostwhite: "F8F8FF",
+      gold: "FFD700",
+      goldenrod: "DAA520",
+      gray: "808080",
+      grey: "808080",
+      green: "00FF00",
+      greenyellow: "ADFF2F",
+      honeydew: "F0FFF0",
+      hotpink: "FF69B4",
+      indianred: "CD5C5C",
+      indigo: "4B0082",
+      ivory: "FFFFF0",
+      khaki: "F0E68C",
+      lavender: "E6E6FA",
+      lavenderblush: "FFF0F5",
+      lawngreen: "7CFC00",
+      lemonchiffon: "FFFACD",
+      lightblue: "ADD8E6",
+      lightcoral: "F08080",
+      lightcyan: "E0FFFF",
+      lightgoldenrodyellow: "FAFAD2",
+      lightgray: "D3D3D3",
+      lightgrey: "D3D3D3",
+      lightgreen: "90EE90",
+      lightpink: "FFB6C1",
+      lightsalmon: "FFA07A",
+      lightseagreen: "20B2AA",
+      lightskyblue: "87CEFA",
+      lightslategray: "778899",
+      lightslategrey: "778899",
+      lightsteelblue: "B0C4DE",
+      lightyellow: "FFFFE0",
+      lime: "00FF00",
+      limegreen: "32CD32",
+      linen: "FAF0E6",
+      magenta: "FF00FF",
+      maroon: "800000",
+      mediumaquamarine: "66CDAA",
+      mediumblue: "0000CD",
+      mediumorchid: "BA55D3",
+      mediumpurple: "9370DB",
+      mediumseagreen: "3CB371",
+      mediumslateblue: "7B68EE",
+      mediumspringgreen: "00FA9A",
+      mediumturquoise: "48D1CC",
+      mediumvioletred: "C71585",
+      midnightblue: "191970",
+      mintcream: "F5FFFA",
+      mistyrose: "FFE4E1",
+      moccasin: "FFE4B5",
+      navajowhite: "FFDEAD",
+      navy: "000080",
+      oldlace: "FDF5E6",
+      olive: "808000",
+      olivedrab: "6B8E23",
+      orange: "FFA500",
+      orangered: "FF4500",
+      orchid: "DA70D6",
+      palegoldenrod: "EEE8AA",
+      palegreen: "98FB98",
+      paleturquoise: "AFEEEE",
+      palevioletred: "DB7093",
+      papayawhip: "FFEFD5",
+      peachpuff: "FFDAB9",
+      peru: "CD853F",
+      pink: "FFC0CB",
+      plum: "DDA0DD",
+      powderblue: "B0E0E6",
+      purple: "800080",
+      rebeccapurple: "663399",
+      red: "FF0000",
+      rosybrown: "BC8F8F",
+      royalblue: "4169E1",
+      saddlebrown: "8B4513",
+      salmon: "FA8072",
+      sandybrown: "F4A460",
+      seagreen: "2E8B57",
+      seashell: "FFF5EE",
+      sienna: "A0522D",
+      silver: "C0C0C0",
+      skyblue: "87CEEB",
+      slateblue: "6A5ACD",
+      slategray: "708090",
+      slategrey: "708090",
+      snow: "FFFAFA",
+      springgreen: "00FF7F",
+      steelblue: "4682B4",
+      tan: "D2B48C",
+      teal: "008080",
+      thistle: "D8BFD8",
+      tomato: "FF6347",
+      turquoise: "40E0D0",
+      violet: "EE82EE",
+      wheat: "F5DEB3",
+      white: "FFFFFF",
+      whitesmoke: "F5F5F5",
+      yellow: "FFFF00",
+      yellowgreen: "9ACD32"
+    }.freeze
+
+    BORDER_STYLES = {
+      none: :none,
+      thin: :thin,
+      medium: :medium,
+      dashed: :dashed,
+      dotted: :dotted,
+      thick: :thick,
+      double: :double,
+      hair: :hair,
+      medium_dashed: :mediumDashed,
+      mediumdashed: :mediumDashed,
+      mediumDashed: :mediumDashed,
+      dash_dot: :dashDot,
+      dashdot: :dashDot,
+      dashDot: :dashDot,
+      medium_dash_dot: :mediumDashDot,
+      mediumdashdot: :mediumDashDot,
+      mediumDashDot: :mediumDashDot,
+      dash_dot_dot: :dashDotDot,
+      dashdotdot: :dashDotDot,
+      dashDotDot: :dashDotDot,
+      medium_dash_dot_dot: :mediumDashDotDot,
+      mediumdashdotdot: :mediumDashDotDot,
+      mediumDashDotDot: :mediumDashDotDot,
+      slant_dash_dot: :slantDashDot,
+      slantdashdot: :slantDashDot,
+      slantDashDot: :slantDashDot
+    }.freeze
+
+    BORDER_INDEX_MAP = {
+      0 => :none,
+      1 => :thin,
+      2 => :medium,
+      3 => :dashed,
+      4 => :dotted,
+      5 => :thick,
+      6 => :double,
+      7 => :hair,
+      8 => :mediumDashed,
+      9 => :dashDot,
+      10 => :mediumDashDot,
+      11 => :dashDotDot,
+      12 => :mediumDashDotDot,
+      13 => :slantDashDot
+    }.freeze
+
+    # Normalizes a color definition (CSS color name, hex code, or RGB integer) to an OpenXML hex color string.
+    #
+    # @example
+    #   StyleBuilder.normalize_color(:navy)                 #=> "FF000080"
+    #   StyleBuilder.normalize_color("#FF0000")             #=> "FFFF0000"
+    #   StyleBuilder.normalize_color("#F00")                #=> "FFFF0000"
+    #   StyleBuilder.normalize_color("FF0000", alpha: false) #=> "FF0000"
+    #   StyleBuilder.normalize_color(0xFF0000)              #=> "FFFF0000"
+    #
+    # @param color [String, Symbol, Integer, nil]
+    # @param alpha [Boolean] Whether to include the alpha channel ("AARRGGBB" vs "RRGGBB").
+    # @return [String, nil]
+    # @api public
+    #: (String | Symbol | Integer | nil color, ?alpha: bool) -> String?
+    def self.normalize_color(color, alpha: true)
+      return nil if color.nil?
+
+      hex = case color
+            when Symbol, defined?(String) && String
+              str = color.to_s.strip
+              return nil if str.empty?
+
+              # Strip leading colon (e.g. ":red")
+              str = str.sub(/^:/, "")
+              return nil if str.empty?
+
+              sym_key = str.downcase.to_sym
+              if CSS_COLORS.key?(sym_key)
+                CSS_COLORS[sym_key]
+              else
+                # Hex string parsing
+                clean_hex = str.sub(/^#/, "")
+                case clean_hex.length
+                when 3
+                  if clean_hex.match?(/\A[0-9a-fA-F]{3}\z/)
+                    r, g, b = clean_hex.chars
+                    "#{r}#{r}#{g}#{g}#{b}#{b}".upcase
+                  end
+                when 6
+                  clean_hex.upcase if clean_hex.match?(/\A[0-9a-fA-F]{6}\z/)
+                when 8
+                  if clean_hex.match?(/\A[0-9a-fA-F]{8}\z/)
+                    return alpha ? clean_hex.upcase : clean_hex[2..7].upcase
+                  end
+                end
+              end
+            when Integer
+              format("%06X", color & 0xFFFFFF)
+            end
+
+      return nil unless hex
+
+      alpha ? "FF#{hex}" : hex
+    end
+
+    # Normalizes a border style symbol, string, or integer index to an OOXML ST_BorderStyle symbol.
+    #
+    # @example
+    #   StyleBuilder.normalize_border_style(:border_thin)      #=> :thin
+    #   StyleBuilder.normalize_border_style(1)                 #=> :thin
+    #   StyleBuilder.normalize_border_style(:medium_dashed)    #=> :mediumDashed
+    #   StyleBuilder.normalize_border_style("double")          #=> :double
+    #   StyleBuilder.normalize_border_style(0)                 #=> :none
+    #
+    # @param style [Symbol, String, Integer, nil]
+    # @return [Symbol, nil]
+    # @api public
+    #: (Symbol | String | Integer | nil style) -> Symbol?
+    def self.normalize_border_style(style)
+      return nil if style.nil?
+
+      return BORDER_INDEX_MAP[style] if style.is_a?(Integer)
+
+      str = style.to_s.sub(/^border_/, "")
+      sym = str.to_sym
+      BORDER_STYLES[sym] || BORDER_STYLES[str.downcase.to_sym]
+    end
+
     # Resolves a color symbol, string, or prefix to an aRGB hex string.
     #
     # @param color [Symbol, String, Object, nil]
@@ -28,10 +303,15 @@ module Xlsxrb
     def self.resolve_color(color)
       return nil unless color
 
+      return Colors.palette_color(color, alpha: true) if color.is_a?(Integer) && defined?(Colors) && color >= 0 && color < Colors::INDEXED_COLORS.size
+
       if color.is_a?(Symbol) || (color.is_a?(String) && color.start_with?(":") && color.length > 1)
         key = color.to_s.sub(/^:/, "").to_sym
-        return COLORS[key] || color.to_s
+        return COLORS[key] || (CSS_COLORS[key] ? "FF#{CSS_COLORS[key]}" : nil) || color.to_s
       end
+
+      return normalize_color(color, alpha: true) || color.to_s if color.is_a?(String) && color.start_with?("#")
+
       color.to_s
     end
 
@@ -314,75 +594,81 @@ module Xlsxrb
     end
 
     # Sets all borders.
-    # @param style [String, Symbol] The border style.
+    # @param style [String, Symbol, Integer] The border style.
     # @param color [String, Symbol, nil] The color.
     # @return [self]
     # @api public
-    #: (?style: String | Symbol, ?color: String | Symbol | nil) -> self
+    #: (?style: String | Symbol | Integer, ?color: String | Symbol | nil) -> self
     def border_all(style: "thin", color: nil)
+      norm_style = self.class.normalize_border_style(style)&.to_s || style.to_s
       color_opt = color ? { color: resolve_color(color) } : {}
-      @border_props[:left] = { style: style, **color_opt }
-      @border_props[:right] = { style: style, **color_opt }
-      @border_props[:top] = { style: style, **color_opt }
-      @border_props[:bottom] = { style: style, **color_opt }
+      @border_props[:left] = { style: norm_style, **color_opt }
+      @border_props[:right] = { style: norm_style, **color_opt }
+      @border_props[:top] = { style: norm_style, **color_opt }
+      @border_props[:bottom] = { style: norm_style, **color_opt }
       self
     end
 
     # Sets the left border.
-    # @param style [String, Symbol] The border style.
+    # @param style [String, Symbol, Integer] The border style.
     # @param color [String, Symbol, nil] The color.
     # @return [self]
     # @api public
-    #: (?style: String | Symbol, ?color: String | Symbol | nil) -> self
+    #: (?style: String | Symbol | Integer, ?color: String | Symbol | nil) -> self
     def border_left(style: "thin", color: nil)
-      @border_props[:left] = { style: style, color: resolve_color(color) }.compact
+      norm_style = self.class.normalize_border_style(style)&.to_s || style.to_s
+      @border_props[:left] = { style: norm_style, color: resolve_color(color) }.compact
       self
     end
 
     # Sets the right border.
-    # @param style [String, Symbol] The border style.
+    # @param style [String, Symbol, Integer] The border style.
     # @param color [String, Symbol, nil] The color.
     # @return [self]
     # @api public
-    #: (?style: String | Symbol, ?color: String | Symbol | nil) -> self
+    #: (?style: String | Symbol | Integer, ?color: String | Symbol | nil) -> self
     def border_right(style: "thin", color: nil)
-      @border_props[:right] = { style: style, color: resolve_color(color) }.compact
+      norm_style = self.class.normalize_border_style(style)&.to_s || style.to_s
+      @border_props[:right] = { style: norm_style, color: resolve_color(color) }.compact
       self
     end
 
     # Sets the top border.
-    # @param style [String, Symbol] The border style.
+    # @param style [String, Symbol, Integer] The border style.
     # @param color [String, Symbol, nil] The color.
     # @return [self]
     # @api public
-    #: (?style: String | Symbol, ?color: String | Symbol | nil) -> self
+    #: (?style: String | Symbol | Integer, ?color: String | Symbol | nil) -> self
     def border_top(style: "thin", color: nil)
-      @border_props[:top] = { style: style, color: resolve_color(color) }.compact
+      norm_style = self.class.normalize_border_style(style)&.to_s || style.to_s
+      @border_props[:top] = { style: norm_style, color: resolve_color(color) }.compact
       self
     end
 
     # Sets the bottom border.
-    # @param style [String, Symbol] The border style.
+    # @param style [String, Symbol, Integer] The border style.
     # @param color [String, Symbol, nil] The color.
     # @return [self]
     # @api public
-    #: (?style: String | Symbol, ?color: String | Symbol | nil) -> self
+    #: (?style: String | Symbol | Integer, ?color: String | Symbol | nil) -> self
     def border_bottom(style: "thin", color: nil)
-      @border_props[:bottom] = { style: style, color: resolve_color(color) }.compact
+      norm_style = self.class.normalize_border_style(style)&.to_s || style.to_s
+      @border_props[:bottom] = { style: norm_style, color: resolve_color(color) }.compact
       self
     end
 
     # rubocop:disable Naming/MethodParameterName
     # Sets diagonal borders.
-    # @param style [String, Symbol] The border style.
+    # @param style [String, Symbol, Integer] The border style.
     # @param color [String, Symbol, nil] The color.
     # @param up [Boolean] Diagonal up.
     # @param down [Boolean] Diagonal down.
     # @return [self]
     # @api public
-    #: (?style: String | Symbol, ?color: String | Symbol | nil, ?up: bool, ?down: bool) -> self
+    #: (?style: String | Symbol | Integer, ?color: String | Symbol | nil, ?up: bool, ?down: bool) -> self
     def border_diagonal(style: "thin", color: nil, up: false, down: false)
-      @border_props[:diagonal] = { style: style, color: resolve_color(color) }.compact
+      norm_style = self.class.normalize_border_style(style)&.to_s || style.to_s
+      @border_props[:diagonal] = { style: norm_style, color: resolve_color(color) }.compact
       @border_props[:diagonal_up] = true if up
       @border_props[:diagonal_down] = true if down
       self

data/lib/xlsxrb/utils.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require_relative "elements/cell"
+require_relative "ooxml/utils"
+
+module Xlsxrb
+  # Public coordinate conversion and reference parsing utilities.
+  #
+  # @api public
+  module Utils
+    # Converts a cell reference string (e.g. "A1", "BC100") to 0-based [row, col] coordinates.
+    #
+    # @example
+    #   Xlsxrb::Utils.ref_to_row_col("A1")    #=> [0, 0]
+    #   Xlsxrb::Utils.ref_to_row_col("BC100") #=> [99, 54]
+    #
+    # @param cell_ref [String, nil] Excel cell reference string.
+    # @return [Array(Integer, Integer), nil] 0-based [row_idx, col_idx] tuple, or nil if invalid.
+    # @api public
+    #: (String? cell_ref) -> [Integer, Integer]?
+    def self.ref_to_row_col(cell_ref)
+      Elements::Cell.parse_ref(cell_ref)
+    end
+
+    # Converts 0-based [row_idx, col_idx] coordinates to an A1-style reference string.
+    #
+    # @example
+    #   Xlsxrb::Utils.row_col_to_ref(0, 0)   #=> "A1"
+    #   Xlsxrb::Utils.row_col_to_ref(99, 54) #=> "BC100"
+    #
+    # @param row_idx [Integer] 0-based row index.
+    # @param col_idx [Integer] 0-based column index.
+    # @return [String] A1-style reference string.
+    # @api public
+    #: (Integer row_idx, Integer col_idx) -> String
+    def self.row_col_to_ref(row_idx, col_idx)
+      "#{Elements::Cell.column_letter(col_idx)}#{row_idx + 1}"
+    end
+
+    # Converts a column letter name (e.g. "A", "BC") to a 0-based integer index.
+    #
+    # @example
+    #   Xlsxrb::Utils.col_name_to_index("A")  #=> 0
+    #   Xlsxrb::Utils.col_name_to_index("BC") #=> 54
+    #
+    # @param col_name [String, Symbol, Integer] Column letter or index.
+    # @return [Integer] 0-based column index.
+    # @api public
+    #: (String | Symbol | Integer col_name) -> Integer
+    def self.col_name_to_index(col_name)
+      Elements::Cell.column_index(col_name)
+    end
+
+    # Converts a 0-based column integer index to a column letter name (e.g. 0 -> "A", 54 -> "BC").
+    #
+    # @example
+    #   Xlsxrb::Utils.col_index_to_name(0)  #=> "A"
+    #   Xlsxrb::Utils.col_index_to_name(54) #=> "BC"
+    #
+    # @param col_idx [Integer] 0-based column index.
+    # @return [String] Column letter name.
+    # @api public
+    #: (Integer col_idx) -> String
+    def self.col_index_to_name(col_idx)
+      Elements::Cell.column_letter(col_idx)
+    end
+
+    # Splits an A1-style cell reference into its column name and 1-based row number.
+    #
+    # @example
+    #   Xlsxrb::Utils.split_coordinate("A1")    #=> ["A", 1]
+    #   Xlsxrb::Utils.split_coordinate("BC100") #=> ["BC", 100]
+    #
+    # @param cell_ref [String, nil] Excel cell reference string.
+    # @return [Array(String, Integer), nil] [col_name, row_number] tuple (1-based row), or nil if invalid.
+    # @api public
+    #: (String? cell_ref) -> [String, Integer]?
+    def self.split_coordinate(cell_ref)
+      return nil unless cell_ref
+
+      coords = Elements::Cell.parse_ref(cell_ref)
+      return nil unless coords
+
+      row_idx, col_idx = coords
+      [Elements::Cell.column_letter(col_idx), row_idx + 1]
+    end
+
+    # Converts a Date or Time to an Excel numeric serial number (1900 or 1904 system).
+    #
+    # @example
+    #   Xlsxrb::Utils.date_to_serial(Date.new(2026, 1, 1)) #=> 46023
+    #
+    # @param date_or_time [Date, Time] Date or Time instance.
+    # @param date1904 [Boolean] Whether to use the 1904 date system.
+    # @return [Integer, Float] Serial number.
+    # @api public
+    #: (Date | Time date_or_time, ?date1904: bool) -> (Integer | Float)
+    def self.date_to_serial(date_or_time, date1904: false)
+      if date_or_time.is_a?(Time)
+        Ooxml::Utils.datetime_to_serial(date_or_time, date1904: date1904)
+      else
+        Ooxml::Utils.date_to_serial(date_or_time, date1904: date1904)
+      end
+    end
+
+    # Converts an Excel serial number to a Date.
+    #
+    # @example
+    #   Xlsxrb::Utils.serial_to_date(46023) #=> #<Date: 2026-01-01>
+    #
+    # @param serial [Numeric] Excel serial number.
+    # @param date1904 [Boolean] Whether to use the 1904 date system.
+    # @return [Date]
+    # @api public
+    #: (Numeric serial, ?date1904: bool) -> Date
+    def self.serial_to_date(serial, date1904: false)
+      Ooxml::Utils.serial_to_date(serial, date1904: date1904)
+    end
+
+    # Converts a Time or Date to a fractional Excel serial number.
+    #
+    # @example
+    #   Xlsxrb::Utils.datetime_to_serial(Time.utc(2026, 1, 1, 12, 0, 0)) #=> 46023.5
+    #
+    # @param time [Time, Date] Time or Date instance.
+    # @param date1904 [Boolean] Whether to use the 1904 date system.
+    # @return [Float] Fractional serial number.
+    # @api public
+    #: (Time | Date time, ?date1904: bool) -> Float
+    def self.datetime_to_serial(time, date1904: false)
+      if time.is_a?(Time)
+        Ooxml::Utils.datetime_to_serial(time, date1904: date1904)
+      else
+        Ooxml::Utils.date_to_serial(time, date1904: date1904).to_f
+      end
+    end
+
+    # Converts an Excel serial number to a Time (UTC).
+    #
+    # @example
+    #   Xlsxrb::Utils.serial_to_time(46023.5) #=> 2026-01-01 12:00:00 UTC
+    #
+    # @param serial [Numeric] Excel serial number.
+    # @param date1904 [Boolean] Whether to use the 1904 date system.
+    # @return [Time]
+    # @api public
+    #: (Numeric serial, ?date1904: bool) -> Time
+    def self.serial_to_time(serial, date1904: false)
+      Ooxml::Utils.serial_to_datetime(serial, date1904: date1904)
+    end
+
+    class << self
+      alias serial_to_datetime serial_to_time
+    end
+  end
+end

data/lib/xlsxrb/version.rb

@@ -3,5 +3,5 @@
 # rbs_inline: enabled
 
 module Xlsxrb
-  VERSION = "0.1.13"
+  VERSION = "0.1.14"
 end

data/lib/xlsxrb/workbook_builder.rb

@@ -63,7 +63,12 @@ module Xlsxrb
       raise ArgumentError, "Sheet name '#{name}' contains invalid characters (ECMA-376 OOXML specification)" if name.match?(%r{[\[\]*?/\\]})
       raise ArgumentError, "Sheet name '#{name}' is already used. Excel requires unique sheet names." if @strict_excel_mode && @sheets.map { |s| s.respond_to?(:name) ? s.name.downcase : s.to_s.downcase }.include?(name.downcase)
 
-      sheet_builder = WorksheetBuilder.new(name, strict_excel_mode: @strict_excel_mode)
+      state = opts.delete(:state)
+      hidden = opts.delete(:hidden)
+      state ||= :hidden if hidden
+      state ||= :visible
+
+      sheet_builder = WorksheetBuilder.new(name, strict_excel_mode: @strict_excel_mode, state: state)
       opts.each { |k, v| sheet_builder.sheet_properties(k, v) }
       yield sheet_builder if block_given?
       @sheet_builders << sheet_builder
@@ -112,6 +117,11 @@ module Xlsxrb
     #: (?rows: String?, ?cols: String?, ?sheet: String?) -> void
     def print_titles(rows: nil, cols: nil, sheet: nil)
       sheet_name = sheet || @sheets.last&.name || "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
@@ -120,6 +130,55 @@ module Xlsxrb
       defined_name("_xlnm.Print_Titles", value, sheet: sheet_name)
     end
 
+    # 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(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 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(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 structure and window protection.
     #
     # @param opts [Hash] Protection options (e.g. lock_structure: true, password: "secret").
@@ -190,9 +249,16 @@ module Xlsxrb
       # Process styles from all sheets and collect style definitions
       processed_sheets, styles_definition = process_styles(@sheets)
 
+      # Auto-register print_area and print_titles defined names from sheet builders if not explicitly defined
+      @sheet_builders.each do |sb|
+        print_area(sb.print_area, sheet: sb.name) if sb.print_area && @defined_names.none? { |dn| dn[:name] == "_xlnm.Print_Area" && dn[:local_sheet_name] == sb.name }
+        print_titles(rows: sb.print_titles[:rows], cols: sb.print_titles[:cols], sheet: sb.name) if sb.print_titles && @defined_names.none? { |dn| dn[:name] == "_xlnm.Print_Titles" && dn[:local_sheet_name] == sb.name }
+      end
+
       # Store workbook-level metadata in unmapped_data
       wb_meta = {}
-      wb_meta[:defined_names] = resolve_defined_names(@defined_names, processed_sheets) unless @defined_names.empty?
+      dns = resolve_defined_names(@defined_names, processed_sheets)
+      wb_meta[:defined_names] = dns unless dns.empty?
       wb_meta[:core_properties] = @core_properties unless @core_properties.empty?
       wb_meta[:app_properties] = @app_properties unless @app_properties.empty?
       wb_meta[:custom_properties] = @custom_properties unless @custom_properties.empty?
@@ -202,7 +268,8 @@ module Xlsxrb
       Elements::Workbook.new(
         sheets: processed_sheets,
         styles: styles_definition,
-        unmapped_data: wb_meta.empty? ? {} : { facade: wb_meta }
+        unmapped_data: wb_meta.empty? ? {} : { facade: wb_meta },
+        defined_names: dns
       )
     end
 
@@ -275,6 +342,7 @@ module Xlsxrb
             height: row.height,
             hidden: row.hidden,
             custom_height: row.custom_height,
+            collapsed: row.collapsed,
             outline_level: row.outline_level,
             unmapped_data: row.unmapped_data,
             errors: row.errors
@@ -285,6 +353,8 @@ module Xlsxrb
           rows: new_rows,
           columns: sheet.columns,
           charts: sheet.charts,
+          conditional_formatting: sheet.conditional_formatting,
+          data_validations: sheet.data_validations,
           unmapped_data: sheet.unmapped_data,
           errors: sheet.errors
         )