xlsxrb 0.1.13 → 0.1.14

data/lib/xlsxrb.rb

@@ -27,12 +27,15 @@ require_relative "xlsxrb/ooxml"
 require_relative "xlsxrb/elements"
 require_relative "xlsxrb/stream_row"
 require_relative "xlsxrb/stream_sheet"
+require_relative "xlsxrb/colors"
 require_relative "xlsxrb/style_builder"
 require_relative "xlsxrb/chart_builder"
 require_relative "xlsxrb/dsl_helpers"
 require_relative "xlsxrb/worksheet_builder"
 require_relative "xlsxrb/workbook_builder"
+require_relative "xlsxrb/number_formatter"
 require_relative "xlsxrb/stream_writer"
+require_relative "xlsxrb/utils"
 
 # Modern, streaming-capable, low-memory XLSX reading and writing library for Ruby.
 #
@@ -56,6 +59,9 @@ module Xlsxrb
   # Raised when parsing malformed or invalid XML structures.
   class ParseError < Error; end
 
+  OMITTED_TARGET = Object.new.freeze
+  private_constant :OMITTED_TARGET
+
   # Raised when cell, row, or workbook parameters fail specification validation.
   class ValidationError < Error; end
 
@@ -73,23 +79,61 @@ module Xlsxrb
 
   # Helper to construct {Elements::RichText} objects with formatted text runs.
   #
-  # @example Create multi-run rich text
+  # @example Create multi-run rich text with hashes
   #   rt = Xlsxrb.rich_text({ text: "Total: ", font: { bold: true } }, { text: "$100" })
   #
+  # @example Create rich text with text/font pairs
+  #   rt = Xlsxrb.rich_text("Normal text, ", ["bold text, ", { bold: true }], ["red text", { color: "FF0000" }])
+  #
+  # @example Create rich text with format objects implementing to_font_hash
+  #   rt = Xlsxrb.rich_text("Normal text, ", bold_format, "bold text")
+  #
   # @example Create simple styled text
   #   rt = Xlsxrb.rich_text(text: "Important Notice", bold: true, color: "FF0000")
   #
-  # @param runs [Array<Hash, String>] Optional array of rich text run hashes or string.
+  # @param runs [Array<Hash, String, Array, Elements::RichTextRun, Object>] Optional array of rich text run items.
   # @param text [String, nil] Plain text string (convenience parameter).
   # @param font_props [Hash] Inline font styling options (e.g. bold: true, color: "FF0000").
   # @return [Elements::RichText] The compiled rich text element.
   # @api public
-  #: (*(Hash[Symbol, untyped] | String) runs, ?text: String?, **untyped font_props) -> Elements::RichText
+  #: (*(Hash[Symbol, untyped] | Elements::RichTextRun | String | Array[untyped] | untyped) runs, ?text: String?, **untyped font_props) -> Elements::RichText
   def self.rich_text(*runs, text: nil, **font_props)
     if text
-      runs = [{ text: text, font: font_props }]
+      runs = [Elements::RichTextRun.new(text: text, font: font_props.empty? ? nil : font_props)]
     elsif runs.size == 1 && runs.first.is_a?(String) && !font_props.empty?
-      runs = [{ text: runs.first, font: font_props }]
+      runs = [Elements::RichTextRun.new(text: runs.first, font: font_props)]
+    else
+      normalized_runs = []
+      pending_font = nil
+
+      runs.each do |item|
+        if item.respond_to?(:to_font_hash)
+          pending_font = item.to_font_hash
+        elsif item.is_a?(Hash) && !item.key?(:text)
+          pending_font = item
+        elsif item.is_a?(Elements::RichTextRun)
+          normalized_runs << item
+          pending_font = nil
+        elsif item.is_a?(Hash)
+          f = item[:font] || pending_font
+          f = f.to_font_hash if f.respond_to?(:to_font_hash)
+          normalized_runs << Elements::RichTextRun.new(text: item[:text].to_s, font: f)
+          pending_font = nil
+        elsif item.is_a?(Array)
+          t = item[0].to_s
+          f = item[1] || pending_font
+          f = f.to_font_hash if f.respond_to?(:to_font_hash)
+          f = f.to_h if f.respond_to?(:to_h) && !f.is_a?(Hash)
+          normalized_runs << Elements::RichTextRun.new(text: t, font: f.is_a?(Hash) ? f : nil)
+          pending_font = nil
+        elsif pending_font
+          normalized_runs << Elements::RichTextRun.new(text: item.to_s, font: pending_font)
+          pending_font = nil
+        else
+          normalized_runs << Elements::RichTextRun.new(text: item.to_s)
+        end
+      end
+      runs = normalized_runs
     end
     Elements::RichText.new(runs: runs)
   end
@@ -104,35 +148,196 @@ module Xlsxrb
   #
   # @param expression [String] The formula expression without leading '=' (e.g. "SUM(A1:A10)").
   # @param cached_value [Object, nil] Optional precomputed value for readers that do not evaluate formulas.
+  # @param type [Symbol, String, nil] Formula type (:shared, :array, etc.).
+  # @param ref [String, nil] Target cell or range reference (e.g. "A1:C1").
+  # @return [Elements::Formula]
+  # @api public
+  #: (String expression, ?cached_value: (String | Numeric | bool | nil), ?type: (Symbol | String)?, ?ref: String?) -> Elements::Formula
+  def self.formula(expression, cached_value: nil, type: nil, ref: nil)
+    Elements::Formula.new(
+      expression: expression,
+      cached_value: cached_value,
+      type: type,
+      ref: ref,
+      calculate_always: cached_value.nil? || nil
+    )
+  end
+
+  # Creates an array or dynamic array {Elements::Formula} object.
+  #
+  # @example Create a multi-cell array formula
+  #   formula = Xlsxrb.array_formula("SUM(B1:B10*C1:C10)", "A1:C1", cached_value: 0)
+  #
+  # @example Create a dynamic array formula
+  #   formula = Xlsxrb.array_formula("SORT(UNIQUE(A1:A10))", "D1")
+  #
+  # @param expression [String] The formula expression without leading '='.
+  # @param ref [String, nil] Target cell or range reference (e.g. "A1:C1" or "D1").
+  # @param cached_value [Object, nil] Optional precomputed value.
   # @return [Elements::Formula]
   # @api public
-  #: (String expression, ?cached_value: (String | Numeric | bool | nil)) -> Elements::Formula
-  def self.formula(expression, cached_value: nil)
+  #: (String expression, ?String? ref, ?cached_value: (String | Numeric | bool | nil)) -> Elements::Formula
+  def self.array_formula(expression, ref = nil, cached_value: nil)
     Elements::Formula.new(
       expression: expression,
       cached_value: cached_value,
+      type: :array,
+      ref: ref,
       calculate_always: cached_value.nil? || nil
     )
   end
 
+  # Creates an {Elements::Hyperlink} object for use in cell hyperlinks.
+  #
+  # @example Create an external hyperlink with a ScreenTip tooltip
+  #   link = Xlsxrb.hyperlink("https://example.com", tooltip: "Visit Example")
+  #
+  # @example Create an internal worksheet link
+  #   link = Xlsxrb.hyperlink(location: "Sheet2!A1", tooltip: "Go to Sheet 2")
+  #
+  # @param url [String, nil] External hyperlink URL.
+  # @param display [String, nil] Optional display label.
+  # @param tooltip [String, nil] Optional hover ScreenTip text.
+  # @param location [String, nil] Optional internal sheet coordinate.
+  # @return [Elements::Hyperlink]
+  # @api public
+  #: (?String? url, ?display: String?, ?tooltip: String?, ?location: String?) -> Elements::Hyperlink
+  def self.hyperlink(url = nil, display: nil, tooltip: nil, location: nil)
+    Elements::Hyperlink.new(url: url, display: display, tooltip: tooltip, location: location)
+  end
+
+  # Formats a cell value according to an Excel format code string.
+  #
+  # @param value [Object, nil] Value to format.
+  # @param format_code [String, nil] Excel format code string.
+  # @param date1904 [Boolean] Whether the 1904 date system is active.
+  # @return [String] Formatted string representation.
+  # @api public
+  #: (untyped value, ?String? format_code, ?date1904: bool) -> String
+  def self.format(value, format_code = nil, date1904: false)
+    NumberFormatter.format(value, format_code, date1904: date1904)
+  end
+
+  # Converts a Date or Time to an Excel numeric serial number (1900 or 1904 system).
+  #
+  # @example
+  #   Xlsxrb.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)
+    Utils.date_to_serial(date_or_time, date1904: date1904)
+  end
+
+  # Converts an Excel serial number to a Date.
+  #
+  # @example
+  #   Xlsxrb.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)
+    Utils.serial_to_date(serial, date1904: date1904)
+  end
+
+  # Converts a Time or Date to a fractional Excel serial number.
+  #
+  # @example
+  #   Xlsxrb.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)
+    Utils.datetime_to_serial(time, date1904: date1904)
+  end
+
+  # Converts an Excel serial number to a Time (UTC).
+  #
+  # @example
+  #   Xlsxrb.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)
+    Utils.serial_to_time(serial, date1904: date1904)
+  end
+
+  class << self
+    alias serial_to_datetime serial_to_time
+  end
+
+  # Resolves an ECMA-376 indexed color palette index (0..63) to an RRGGBB hex string (or AARRGGBB if alpha: true).
+  #
+  # @example
+  #   Xlsxrb.palette_color(12)               #=> "0000FF"
+  #   Xlsxrb.palette_color(12, alpha: true)  #=> "FF0000FF"
+  #
+  # @param index [Object, nil] Palette index (0..63).
+  # @param alpha [Boolean] Whether to prefix "FF" alpha channel.
+  # @return [String, nil]
+  # @api public
+  #: (untyped index, ?alpha: bool) -> String?
+  def self.palette_color(index, alpha: false)
+    Colors.palette_color(index, alpha: alpha)
+  end
+
+  # Converts any supported color representation (palette index 0..63, CSS name, #RGB, #RRGGBB, #AARRGGBB, integer RGB)
+  # to a normalized hex string.
+  #
+  # @example
+  #   Xlsxrb.to_hex_color(12)                      #=> "0000FF"
+  #   Xlsxrb.to_hex_color(:navy)                   #=> "000080"
+  #   Xlsxrb.to_hex_color("#FF0000")               #=> "FF0000"
+  #
+  # @param color [Integer, String, Symbol, nil]
+  # @param alpha [Boolean] Whether to include the alpha channel (default false -> "RRGGBB").
+  # @return [String, nil]
+  # @api public
+  #: (Integer | String | Symbol | nil color, ?alpha: bool) -> String?
+  def self.to_hex_color(color, alpha: false)
+    Colors.to_hex(color, alpha: alpha)
+  end
+
+  class << self
+    alias color_to_hex to_hex_color
+  end
+
   # Reads an XLSX file (streaming and lazy-loaded by default) from a file path, IO stream, or binary String.
   #
   # Sheets and rows are streamed lazily with O(1) constant memory. If a block is given,
   # yields each {StreamSheet} sequentially. Call {#load} on the returned Workbook or Sheet
   # to convert to an in-memory representation for coordinate random access (`sheet["A1"]`).
   #
-  # @overload read(source, password: nil, &block)
+  # @overload read(source, password: nil, trim_empty_rows: false, pad_empty_rows: false, pad_empty_cells: false, &block)
   #   Yields each {StreamSheet} sequentially in streaming mode.
   #   @param source [String, IO, StringIO] File path, binary content string, or readable IO stream.
   #   @param password [String, nil] Optional password to decrypt password-protected XLSX files.
+  #   @param trim_empty_rows [Boolean] Whether to omit trailing empty rows during sheet iteration.
+  #   @param pad_empty_rows [Boolean] Whether to yield empty rows for skipped row numbers.
+  #   @param pad_empty_cells [Boolean] Whether to pad missing cells within rows.
   #   @yield [sheet]
   #   @yieldparam sheet [StreamSheet] The streaming worksheet object.
   #   @return [void]
   #
-  # @overload read(source, password: nil)
+  # @overload read(source, password: nil, trim_empty_rows: false, pad_empty_rows: false, pad_empty_cells: false)
   #   Returns a lazy {Elements::Workbook} object.
   #   @param source [String, IO, StringIO] File path, binary content string, or readable IO stream.
   #   @param password [String, nil] Optional password to decrypt password-protected XLSX files.
+  #   @param trim_empty_rows [Boolean] Whether to omit trailing empty rows during sheet iteration.
+  #   @param pad_empty_rows [Boolean] Whether to yield empty rows for skipped row numbers.
+  #   @param pad_empty_cells [Boolean] Whether to pad missing cells within rows.
   #   @return [Elements::Workbook]
   #
   # @example Streaming read across sheets and rows (O(1) constant memory)
@@ -153,9 +358,9 @@ module Xlsxrb
   # @raise [InvalidPasswordError] If the supplied password is incorrect.
   # @raise [ParseError] If the spreadsheet XML structure is invalid.
   # @api public
-  #: (untyped source, ?password: String?) { (StreamSheet) -> void } -> void
-  #: (untyped source, ?password: String?) -> Elements::Workbook
-  def self.read(source, password: nil, &)
+  #: (untyped source, ?password: String?, ?trim_empty_rows: bool, ?pad_empty_rows: bool, ?pad_empty_cells: bool) { (StreamSheet) -> void } -> void
+  #: (untyped source, ?password: String?, ?trim_empty_rows: bool, ?pad_empty_rows: bool, ?pad_empty_cells: bool) -> Elements::Workbook
+  def self.read(source, password: nil, trim_empty_rows: false, pad_empty_rows: false, pad_empty_cells: false, &)
     prepared_source = prepare_source_io(source, password)
     zip_reader = Ooxml::ZipReader.open(prepared_source)
     begin
@@ -163,7 +368,9 @@ module Xlsxrb
       shared_strings = Ooxml::SharedStringsParser.parse(shared_strings_xml)
 
       workbook_xml = zip_reader.read_entry("xl/workbook.xml")
-      workbook_sheets = Ooxml::WorkbookParser.parse(workbook_xml)
+      wb_parsed = Ooxml::WorkbookParser.parse_with_properties(workbook_xml)
+      workbook_sheets = wb_parsed[:sheets]
+      is_date1904 = wb_parsed[:date1904]
 
       rels_xml = zip_reader.read_entry("xl/_rels/workbook.xml.rels")
       rels = Ooxml::RelationshipsParser.parse(rels_xml)
@@ -186,11 +393,25 @@ module Xlsxrb
           shared_strings,
           styles,
           zip_reader: zip_reader,
-          entry_name: sheet_path
+          entry_name: sheet_path,
+          state: sheet_info[:state] || :visible,
+          date1904: is_date1904,
+          trim_empty_rows: trim_empty_rows,
+          pad_empty_rows: pad_empty_rows,
+          pad_empty_cells: pad_empty_cells
         )
       end.compact
 
-      wb = Elements::Workbook.new(sheets: sheets, shared_strings: shared_strings, styles: styles)
+      wb_unmapped = {}
+      wb_unmapped[:workbook_properties] = { date1904: true } if is_date1904
+      defined_names = wb_parsed[:defined_names] || []
+      wb = Elements::Workbook.new(
+        sheets: sheets,
+        shared_strings: shared_strings,
+        styles: styles,
+        unmapped_data: wb_unmapped,
+        defined_names: defined_names
+      )
 
       if block_given?
         sheets.each(&)
@@ -203,17 +424,22 @@ module Xlsxrb
     end
   end
 
+  class << self
+    alias stream read
+  end
+
   # Writes an XLSX file or IO stream (streaming or in-memory), or returns a binary string.
   #
-  # @overload write(target, password: nil, encryption_mode: :standard, strict_excel_mode: true, &block)
+  # @overload write(?target, password: nil, encryption_mode: :standard, strict_excel_mode: true, &block)
   #   Streaming write: yields a {StreamWriter} context for high-speed, zero-allocation XLSX generation.
-  #   @param target [String, IO, StringIO] Destination file path or writable IO object.
+  #   If target is omitted, returns the generated XLSX as an in-memory binary String.
+  #   @param target [String, IO, StringIO, nil] Optional destination file path or writable IO object.
   #   @param password [String, nil] Optional password to encrypt the generated XLSX file.
   #   @param encryption_mode [Symbol] Encryption algorithm (:standard or :agile).
   #   @param strict_excel_mode [Boolean] Whether to enforce Microsoft Excel specification limits.
   #   @yield [stream_writer]
   #   @yieldparam stream_writer [Xlsxrb::StreamWriter]
-  #   @return [void]
+  #   @return [String, void] Binary data if target is omitted, or void if written to target.
   #
   # @overload write(workbook, password: nil, encryption_mode: :standard)
   #   In-memory write: exports the workbook to an in-memory binary String.
@@ -235,6 +461,11 @@ module Xlsxrb
   #     writer.sheet("Sheet1") { |s| s.row(["Hello", "World"]) }
   #   end
   #
+  # @example Streaming write to in-memory binary string (target omitted)
+  #   binary_data = Xlsxrb.write do |writer|
+  #     writer.sheet("Sheet1") { |s| s.row(["Hello", "World"]) }
+  #   end
+  #
   # @example Password-protected streaming write
   #   Xlsxrb.write("protected.xlsx", password: "SecretPassword123") do |writer|
   #     writer.sheet("Confidential") { |s| s.row(["Private Data", 100]) }
@@ -246,9 +477,16 @@ module Xlsxrb
   # @api public
   #: (Elements::Workbook workbook, ?password: String?, ?encryption_mode: Symbol) -> String
   #: (untyped target, Elements::Workbook | untyped workbook, ?password: String?, ?encryption_mode: Symbol) -> void
-  #: (untyped target_or_workbook, ?Elements::Workbook | untyped workbook_or_nil, ?password: String?, ?encryption_mode: Symbol, ?strict_excel_mode: bool) ?{ (StreamWriter) -> void } -> untyped
-  def self.write(target_or_workbook, workbook_or_nil = nil, password: nil, encryption_mode: :standard, strict_excel_mode: true, &block)
+  #: (?untyped target_or_workbook, ?Elements::Workbook | untyped workbook_or_nil, ?password: String?, ?encryption_mode: Symbol, ?strict_excel_mode: bool) ?{ (StreamWriter) -> void } -> untyped
+  def self.write(target_or_workbook = OMITTED_TARGET, workbook_or_nil = nil, password: nil, encryption_mode: :standard, strict_excel_mode: true, &)
     if block_given?
+      if target_or_workbook.equal?(OMITTED_TARGET)
+        io = StringIO.new
+        io.binmode
+        write(io, password: password, encryption_mode: encryption_mode, strict_excel_mode: strict_excel_mode, &)
+        return io.string.b
+      end
+
       target = target_or_workbook
       raise Error, "target is required" if target.nil?
 
@@ -282,6 +520,8 @@ module Xlsxrb
     end
 
     if workbook_or_nil.nil?
+      raise Error, "workbook must be an Elements::Workbook" if target_or_workbook.equal?(OMITTED_TARGET)
+
       wb = target_or_workbook
       raise Error, "workbook must be an Elements::Workbook" unless wb.is_a?(Elements::Workbook)
 
@@ -299,6 +539,15 @@ module Xlsxrb
     sst = []
     sst_index = {}
 
+    if workbook.shared_strings && !workbook.shared_strings.empty?
+      workbook.shared_strings.each do |val|
+        if (val.is_a?(String) || val.is_a?(Elements::RichText)) && !sst_index.key?(val)
+          sst << val
+          sst_index[val] = sst.size - 1
+        end
+      end
+    end
+
     # Collect shared strings and build index without allocating new Hashes
     sheet_data = workbook.sheets.map do |raw_ws|
       ws = raw_ws.respond_to?(:load) ? raw_ws.load : raw_ws
@@ -314,21 +563,51 @@ module Xlsxrb
       columns = ws.columns.map do |col|
         # simplecov:disable
         # Edge case / untested delegation block
-        { index: col.index, width: col.width, hidden: col.hidden, custom_width: col.custom_width, outline_level: col.outline_level }
+        style_idx = col.unmapped_data&.[](:style_index) || col.unmapped_data&.[](:style) || (col.respond_to?(:style_index) && col.style_index)
+        { index: col.index, width: col.width, hidden: col.hidden, custom_width: col.custom_width, outline_level: col.outline_level, style_index: style_idx }
         # simplecov:enable
       end
       sd = { name: ws.name, rows: ws.rows, columns: columns }
       sd[:charts] = ws.charts unless ws.charts.empty?
+      sd[:conditional_formats] = ws.conditional_formatting unless ws.conditional_formatting.empty?
+      sd[:data_validations] = ws.data_validations unless ws.data_validations.empty?
 
       # Extract facade metadata from unmapped_data
       facade = ws.unmapped_data[:facade]
-      facade&.each { |key, val| sd[key] = val }
+      facade&.each { |key, val| sd[key] ||= val }
+
+      sd[:state] ||= ws.state if ws.respond_to?(:state) && ws.state && ws.state != :visible
+      sd[:comments] ||= ws.comments if ws.respond_to?(:comments) && !ws.comments.empty?
+      if ws.respond_to?(:hyperlinks) && !ws.hyperlinks.empty?
+        sd[:hyperlinks] ||= ws.hyperlinks.is_a?(Hash) ? ws.hyperlinks.values : ws.hyperlinks
+      end
+      sd[:sparkline_groups] ||= ws.sparkline_groups if ws.respond_to?(:sparkline_groups) && !ws.sparkline_groups.empty?
 
       sd
     end
 
     # Extract workbook-level facade metadata
     wb_facade = workbook.unmapped_data[:facade] || {}
+    wb_properties = workbook.unmapped_data[:workbook_properties] || wb_facade[:workbook_properties]
+    raw_dns = wb_facade[:defined_names] || (workbook.respond_to?(:defined_names) && !workbook.defined_names.empty? ? workbook.defined_names : nil)
+    defined_names = raw_dns ? raw_dns.map(&:dup) : []
+
+    # Auto-generate _xlnm.Print_Area and _xlnm.Print_Titles from worksheet definitions if not already present
+    workbook.sheets.each_with_index do |ws, idx|
+      sheet_name = ws.name || "Sheet#{idx + 1}"
+      if ws.respond_to?(:print_area) && ws.print_area && defined_names.none? { |dn| dn[:name] == "_xlnm.Print_Area" && (dn[:local_sheet_id] == idx || dn[:local_sheet_name] == sheet_name) }
+        val = "'#{sheet_name}'!#{DslHelpers.absolute_range(ws.print_area)}"
+        defined_names << { name: "_xlnm.Print_Area", value: val, local_sheet_id: idx }
+      end
+      next unless ws.respond_to?(:print_titles) && ws.print_titles && defined_names.none? { |dn| dn[:name] == "_xlnm.Print_Titles" && (dn[:local_sheet_id] == idx || dn[:local_sheet_name] == sheet_name) }
+
+      pt = ws.print_titles
+      parts = []
+      parts << "'#{sheet_name}'!$#{pt[:cols].sub(":", ":$")}" if pt[:cols]
+      parts << "'#{sheet_name}'!$#{pt[:rows].sub(":", ":$")}" if pt[:rows]
+      defined_names << { name: "_xlnm.Print_Titles", value: parts.join(","), local_sheet_id: idx } unless parts.empty?
+    end
+    defined_names = nil if defined_names.empty?
 
     if password && !password.empty?
       buf = StringIO.new
@@ -339,12 +618,12 @@ module Xlsxrb
         shared_strings: sst,
         shared_strings_index: sst_index,
         styles: workbook.styles,
-        defined_names: wb_facade[:defined_names],
+        defined_names: defined_names,
         core_properties: wb_facade[:core_properties],
         app_properties: wb_facade[:app_properties],
         custom_properties: wb_facade[:custom_properties],
         workbook_protection: wb_facade[:workbook_protection],
-        workbook_properties: wb_facade[:workbook_properties]
+        workbook_properties: wb_properties
       )
       encrypted_bytes = Ooxml::Crypto.encrypt(buf.string.b, password, mode: encryption_mode)
       if target.is_a?(String)
@@ -359,12 +638,12 @@ module Xlsxrb
         shared_strings: sst,
         shared_strings_index: sst_index,
         styles: workbook.styles,
-        defined_names: wb_facade[:defined_names],
+        defined_names: defined_names,
         core_properties: wb_facade[:core_properties],
         app_properties: wb_facade[:app_properties],
         custom_properties: wb_facade[:custom_properties],
         workbook_protection: wb_facade[:workbook_protection],
-        workbook_properties: wb_facade[:workbook_properties]
+        workbook_properties: wb_properties
       )
     end
   end
@@ -422,7 +701,8 @@ module Xlsxrb
         initial_sst_size = shared_strings.size
 
         workbook_xml = zip_reader.read_entry("xl/workbook.xml")
-        workbook_sheets = workbook_xml ? Ooxml::WorkbookParser.parse(workbook_xml) : []
+        wb_parsed = workbook_xml ? Ooxml::WorkbookParser.parse_with_properties(workbook_xml) : { sheets: [], date1904: false, defined_names: [] }
+        workbook_sheets = wb_parsed[:sheets]
 
         rels_xml = zip_reader.read_entry("xl/_rels/workbook.xml.rels")
         rels = rels_xml ? Ooxml::RelationshipsParser.parse(rels_xml) : {}
@@ -440,13 +720,14 @@ module Xlsxrb
 
           sheet_entry_map[sheet_info[:name]] = sheet_path
           sheet_xml = zip_reader.read_entry(sheet_path) || ""
-          build_worksheet(sheet_info[:name], sheet_xml, shared_strings, styles)
+          build_worksheet(sheet_info[:name], sheet_xml, shared_strings, styles, state: sheet_info[:state] || :visible, zip_reader: zip_reader, entry_name: sheet_path)
         end.compact
 
         original_workbook = Elements::Workbook.new(
           sheets: loaded_sheets,
           shared_strings: shared_strings,
-          styles: styles
+          styles: styles,
+          defined_names: wb_parsed[:defined_names] || []
         )
         mutable_shared_strings = shared_strings.dup
 
@@ -546,59 +827,271 @@ module Xlsxrb
   class << self
     private
 
-    #: (String name, String? sheet_xml, Array[String] shared_strings, untyped _styles) -> Elements::Worksheet
-    def build_worksheet(name, sheet_xml, shared_strings, _styles)
-      return Elements::Worksheet.new(name: name) if sheet_xml.nil? || sheet_xml.empty?
+    #: (String name, String? sheet_xml, Array[String] shared_strings, untyped styles, ?state: Symbol, ?zip_reader: Ooxml::ZipReader?, ?entry_name: String?, ?hyperlinks: Hash[String, Hash[Symbol, untyped]]?, ?comments: Array[Hash[Symbol, untyped]]?, ?images: Array[Elements::Image]?, ?date1904: bool, ?dimension: String?, ?trim_empty_rows: bool, ?pad_empty_rows: bool, ?pad_empty_cells: bool) -> Elements::Worksheet
+    def build_worksheet(name, sheet_xml, shared_strings, styles, state: :visible, zip_reader: nil, entry_name: nil, hyperlinks: nil, comments: nil, images: nil, date1904: false, dimension: nil, trim_empty_rows: false, pad_empty_rows: false, pad_empty_cells: false)
+      sheet_dimension = dimension || sheet_xml&.slice(/<(?:[a-zA-Z0-9_]+:)?dimension\b[^>]*\bref=["']([^"']+)["']/, 1)
+      return Elements::Worksheet.new(name: name, state: state, styles: styles, images: images || [], date1904: date1904, dimension: sheet_dimension, trim_empty_rows: trim_empty_rows, pad_empty_rows: pad_empty_rows, pad_empty_cells: pad_empty_cells) if sheet_xml.nil? || sheet_xml.empty?
 
-      raw_rows = Ooxml::WorksheetParser.parse(sheet_xml, shared_strings: shared_strings)
+      sheet_hyperlinks = hyperlinks || resolve_hyperlinks(sheet_xml, zip_reader: zip_reader, entry_name: entry_name)
+      sheet_comments = comments || resolve_comments(zip_reader: zip_reader, entry_name: entry_name)
+      sheet_images = images || resolve_images(zip_reader: zip_reader, entry_name: entry_name)
+      raw_rows = Ooxml::WorksheetParser.parse(sheet_xml, shared_strings: shared_strings, styles: styles)
       raw_columns = Ooxml::WorksheetParser.parse_columns(sheet_xml)
 
-      rows = raw_rows.map { |rr| build_row_from_raw(rr) }
+      rows = raw_rows.map { |rr| build_row_from_raw(rr, sheet_hyperlinks, sheet_comments, styles, date1904: date1904) }
       columns = raw_columns.map do |rc|
         # Columns from OOXML are 1-based min/max ranges; convert to 0-based
+        col_unmapped = {}
+        col_unmapped[:style_index] = rc[:style_index] if rc[:style_index]
         Elements::Column.new(
           index: (rc[:min] || 1) - 1,
           width: rc[:width],
           hidden: rc[:hidden] || false,
           custom_width: rc[:custom_width] || false,
-          outline_level: rc[:outline_level]
+          outline_level: rc[:outline_level],
+          style_index: rc[:style_index],
+          unmapped_data: col_unmapped
         )
       end
 
-      Elements::Worksheet.new(name: name, rows: rows, columns: columns)
+      cfs = if sheet_xml.include?("<conditionalFormatting")
+              listener = Ooxml::Reader::ConditionalFormattingListener.new
+              Ooxml::XmlParser.parse(sheet_xml, listener)
+              listener.rules
+            else
+              []
+            end
+
+      dvs = if sheet_xml.include?("<dataValidation")
+              listener = Ooxml::Reader::DataValidationsListener.new
+              Ooxml::XmlParser.parse(sheet_xml, listener)
+              listener.validations
+            else
+              []
+            end
+
+      Elements::Worksheet.new(
+        name: name,
+        rows: rows,
+        columns: columns,
+        conditional_formatting: cfs,
+        data_validations: dvs,
+        state: state,
+        hyperlinks: sheet_hyperlinks,
+        comments: sheet_comments,
+        images: sheet_images,
+        styles: styles,
+        date1904: date1904,
+        dimension: sheet_dimension,
+        trim_empty_rows: trim_empty_rows,
+        pad_empty_rows: pad_empty_rows,
+        pad_empty_cells: pad_empty_cells
+      )
+    end
+
+    #: (String? sheet_xml, ?zip_reader: Ooxml::ZipReader?, ?entry_name: String?, ?rels_xml: String?) -> Hash[String, Hash[Symbol, untyped]]
+    def resolve_hyperlinks(sheet_xml, zip_reader: nil, entry_name: nil, rels_xml: nil)
+      return {} if sheet_xml.nil? || !sheet_xml.include?("hyperlink")
+
+      links = Ooxml::WorksheetParser.parse_hyperlinks(sheet_xml)
+      return {} if links.empty?
+
+      rid_to_url = {}
+      if rels_xml && !rels_xml.empty?
+        rid_to_url = Ooxml::RelationshipsParser.parse(rels_xml)
+      elsif zip_reader && entry_name
+        rels_path = entry_name.sub(%r{([^/]+)$}, '_rels/\1.rels')
+        rels_content = zip_reader.read_entry(rels_path)
+        rid_to_url = Ooxml::RelationshipsParser.parse(rels_content) if rels_content && !rels_content.empty?
+      end
+
+      result = {}
+      links.each do |link|
+        entry = {}
+        if link[:rid]
+          url = rid_to_url[link[:rid]]
+          entry[:url] = url if url
+        end
+        entry[:display] = link[:display] if link[:display]
+        entry[:tooltip] = link[:tooltip] if link[:tooltip]
+        entry[:location] = link[:location] if link[:location]
+        result[link[:ref]] = entry unless entry.empty?
+      end
+      result
     end
 
-    #: (untyped raw_row) -> (Elements::Row | untyped)
-    def build_row_from_raw(raw_row)
+    #: (String base_dir, String target) -> String
+    def resolve_relative_path(base_dir, target)
+      if target.start_with?("/")
+        target.delete_prefix("/")
+      elsif target.start_with?("..")
+        parts = base_dir.split("/") + target.split("/")
+        resolved = []
+        parts.each { |p| p == ".." ? resolved.pop : resolved << p }
+        resolved.join("/")
+      else
+        "#{base_dir}/#{target}"
+      end
+    end
+
+    #: (?zip_reader: Ooxml::ZipReader?, ?entry_name: String?) -> Array[Hash[Symbol, untyped]]
+    def resolve_comments(zip_reader: nil, entry_name: nil)
+      return [] unless zip_reader && entry_name
+
+      rels_path = entry_name.sub(%r{([^/]+)$}, '_rels/\1.rels')
+      rels_xml = zip_reader.read_entry(rels_path)
+      return [] if rels_xml.nil? || rels_xml.empty?
+
+      parser = REXML::Parsers::SAX2Parser.new(rels_xml)
+      listener = Ooxml::Reader::RelsListener.new
+      parser.listen(listener)
+      parser.parse
+
+      rel = listener.relationships.find { |r| r[:type]&.end_with?("/comments") }
+      return [] unless rel
+
+      base_dir = File.dirname(entry_name)
+      comments_path = resolve_relative_path(base_dir, rel[:target])
+
+      xml = zip_reader.read_entry(comments_path)
+      return [] if xml.nil? || xml.empty?
+
+      c_parser = REXML::Parsers::SAX2Parser.new(xml)
+      c_listener = Ooxml::Reader::CommentsListener.new
+      c_parser.listen(c_listener)
+      c_parser.parse
+      c_listener.comments
+    end
+
+    #: (?zip_reader: Ooxml::ZipReader?, ?entry_name: String?) -> Array[Elements::Image]
+    def resolve_images(zip_reader: nil, entry_name: nil)
+      return [] unless zip_reader && entry_name
+
+      rels_path = entry_name.sub(%r{([^/]+)$}, '_rels/\1.rels')
+      rels_xml = zip_reader.read_entry(rels_path)
+      return [] if rels_xml.nil? || rels_xml.empty?
+
+      parser = REXML::Parsers::SAX2Parser.new(rels_xml)
+      listener = Ooxml::Reader::RelsListener.new
+      parser.listen(listener)
+      parser.parse
+
+      drawing_rel = listener.relationships.find { |r| r[:type]&.end_with?("/drawing") }
+      return [] unless drawing_rel
+
+      base_dir = File.dirname(entry_name)
+      target = drawing_rel[:target]
+      drawing_path = resolve_relative_path(base_dir, target)
+      drawing_xml = zip_reader.read_entry(drawing_path)
+      return [] if drawing_xml.nil? || drawing_xml.empty?
+
+      drawing_rels_path = drawing_path.sub(%r{([^/]+)$}, '_rels/\1.rels')
+      drawing_rels_xml = zip_reader.read_entry(drawing_rels_path)
+      drawing_rels = {}
+      if drawing_rels_xml && !drawing_rels_xml.empty?
+        d_parser = REXML::Parsers::SAX2Parser.new(drawing_rels_xml)
+        d_listener = Ooxml::Reader::RelsListener.new
+        d_parser.listen(d_listener)
+        d_parser.parse
+        d_listener.relationships.each do |r|
+          drawing_rels[r[:id]] = r[:target]
+        end
+      end
+
+      p_parser = REXML::Parsers::SAX2Parser.new(drawing_xml)
+      img_listener = Ooxml::Reader::DrawingImagesListener.new
+      p_parser.listen(img_listener)
+      p_parser.parse
+
+      drawing_dir = File.dirname(drawing_path)
+      img_listener.images.map do |raw_img|
+        rid = raw_img[:embed_rid]
+        media_target = drawing_rels[rid]
+        img_data = nil
+        filename = nil
+        if media_target
+          media_path = resolve_relative_path(drawing_dir, media_target)
+          filename = File.basename(media_path)
+          img_data = zip_reader.read_entry(media_path)
+        end
+
+        from_col = raw_img[:from_col] || 0
+        from_row = raw_img[:from_row] || 0
+        to_col = raw_img[:to_col]
+        to_row = raw_img[:to_row]
+        cx = raw_img[:cx]
+        cy = raw_img[:cy]
+        name = raw_img[:name]
+
+        Elements::Image.new(
+          filename: filename || "image.png",
+          name: name,
+          data: img_data,
+          from_col: from_col,
+          from_row: from_row,
+          to_col: to_col,
+          to_row: to_row,
+          cx: cx,
+          cy: cy,
+          unmapped_data: raw_img
+        )
+      end
+    end
+
+    #: (untyped raw_row, ?Hash[String, Hash[Symbol, untyped]] hyperlinks, ?(Array[Hash[Symbol, untyped]] | Hash[String, Hash[Symbol, untyped]]) comments, ?Hash[untyped, untyped]? styles, ?date1904: bool) -> (Elements::Row | untyped)
+    def build_row_from_raw(raw_row, hyperlinks = {}, comments = [], styles = nil, date1904: false)
       return raw_row if raw_row.is_a?(Elements::Row)
 
+      comments_map = if comments.is_a?(Hash)
+                       comments
+                     else
+                       comments.each_with_object({}) { |c, acc| (r = c[:ref] || c[:cell]) && (acc[r.to_s.upcase] = c) }
+                     end
+
       raw_cells = raw_row[:cells]
-      cells = if raw_cells.empty? || raw_cells.first.is_a?(Elements::Cell)
-                raw_cells
-              else
-                raw_cells.map do |rc|
-                  parsed = Elements::Cell.parse_ref(rc[:ref]) if rc[:ref]
-                  row_idx = parsed ? parsed[0] : raw_row[:index]
-                  col_idx = parsed ? parsed[1] : 0
-
-                  val = rc[:value]
-                  cell_errors = Elements::Cell.validate(row_idx, col_idx, val)
-                  if !cell_errors.empty? && rc[:source]
-                    cell_errors = cell_errors.map do |err|
-                      "#{err} (at #{rc[:source][:part]} row #{rc[:source][:row] + 1} cell #{rc[:ref] || "unknown"})"
-                    end
-                  end
-
-                  Elements::Cell.new(
-                    row_index: row_idx,
-                    column_index: col_idx,
-                    value: val,
-                    formula: rc[:formula],
-                    style_index: rc[:style_index],
-                    errors: cell_errors
-                  )
-                end
-              end
+      cells = raw_cells.map do |rc|
+        if rc.is_a?(Elements::Cell)
+          hl = hyperlinks && !hyperlinks.empty? ? hyperlinks[rc.ref] : nil
+          cm = comments_map && !comments_map.empty? ? comments_map[rc.ref] : nil
+          fmt = rc.format_code || (NumberFormatter.format_code_for(rc.style_index, styles) if styles && rc.style_index)
+          if hl || cm || (fmt && rc.format_code != fmt) || (date1904 && !rc.date1904?)
+            rc.with(hyperlink: hl || rc.hyperlink, comment: cm || rc.comment, format_code: fmt || rc.format_code, date1904: date1904 || rc.date1904?)
+          else
+            rc
+          end
+        else
+          parsed = Elements::Cell.parse_ref(rc[:ref]) if rc[:ref]
+          row_idx = parsed ? parsed[0] : raw_row[:index]
+          col_idx = parsed ? parsed[1] : 0
+          ref = rc[:ref] || "#{Elements::Cell.column_letter(col_idx)}#{row_idx + 1}"
+          hl = hyperlinks ? hyperlinks[ref] : nil
+          cm = comments_map ? comments_map[ref] : nil
+          fmt = rc[:format_code] || (NumberFormatter.format_code_for(rc[:style_index], styles) if styles && rc[:style_index])
+
+          val = rc[:value]
+          raw_val = rc[:raw_value] || val&.to_s
+          cell_errors = Elements::Cell.validate(row_idx, col_idx, val)
+          if !cell_errors.empty? && rc[:source]
+            cell_errors = cell_errors.map do |err|
+              "#{err} (at #{rc[:source][:part]} row #{rc[:source][:row] + 1} cell #{rc[:ref] || "unknown"})"
+            end
+          end
+
+          Elements::Cell.new(
+            row_index: row_idx,
+            column_index: col_idx,
+            value: val,
+            formula: rc[:formula],
+            style_index: rc[:style_index],
+            hyperlink: hl,
+            comment: cm,
+            raw_value: raw_val,
+            format_code: fmt,
+            errors: cell_errors,
+            date1904: date1904
+          )
+        end
+      end
       attrs = raw_row[:attrs] || {}
       row_errors = Elements::Row.validate(raw_row[:index], cells)
       if !row_errors.empty? && raw_row[:source]
@@ -609,19 +1102,23 @@ module Xlsxrb
           # simplecov:enable
         end
       end
+      row_unmapped = {}
+      row_unmapped[:style_index] = attrs[:style_index] if attrs[:style_index]
       Elements::Row.new(
         index: raw_row[:index],
         cells: cells,
         height: attrs[:height],
         hidden: attrs[:hidden] || false,
         custom_height: attrs[:custom_height] || false,
+        collapsed: attrs[:collapsed] || false,
         outline_level: attrs[:outline_level],
+        unmapped_data: row_unmapped,
         errors: row_errors
       )
     end
 
-    #: (Elements::Cell cell, Array[String] sst, Hash[String, Integer] sst_index) -> Hash[Symbol, untyped]
-    def build_raw_cell(cell, sst, sst_index)
+    #: (Elements::Cell cell, Array[String] sst, Hash[String, Integer] sst_index, ?date1904: bool) -> Hash[Symbol, untyped]
+    def build_raw_cell(cell, sst, sst_index, date1904: false)
       # simplecov:disable
       # Edge case / untested delegation block
       ref = cell.ref
@@ -645,9 +1142,9 @@ module Xlsxrb
         result[:value] = value.code
         result[:type] = "e"
       when Date
-        result[:value] = Xlsxrb::Ooxml::Utils.date_to_serial(value)
+        result[:value] = Xlsxrb::Ooxml::Utils.date_to_serial(value, date1904: date1904)
       when Time
-        result[:value] = Xlsxrb::Ooxml::Utils.datetime_to_serial(value)
+        result[:value] = Xlsxrb::Ooxml::Utils.datetime_to_serial(value, date1904: date1904)
       # simplecov:enable
       when NilClass
         # empty cell
@@ -687,6 +1184,7 @@ module Xlsxrb
       attrs[:height] = row.height if row.height
       attrs[:hidden] = true if row.hidden
       attrs[:custom_height] = true if row.custom_height
+      attrs[:collapsed] = true if row.collapsed
       attrs[:outline_level] = row.outline_level if row.outline_level
       attrs
       # simplecov:enable
@@ -695,12 +1193,13 @@ module Xlsxrb
     #: (untyped source, String? password) -> untyped
     def prepare_source_io(source, password)
       if source.is_a?(String)
-        if source.start_with?("PK\x03\x04") || source.include?("\x00") || Ooxml::Cfb::Reader.cfb?(source)
-          if Ooxml::Cfb::Reader.cfb?(source)
-            decrypted_zip = Ooxml::Crypto.decrypt(source, password)
+        bin_source = source.encoding == Encoding::BINARY ? source : source.b
+        if bin_source.start_with?("PK\x03\x04".b) || bin_source.include?("\x00".b) || Ooxml::Cfb::Reader.cfb?(bin_source)
+          if Ooxml::Cfb::Reader.cfb?(bin_source)
+            decrypted_zip = Ooxml::Crypto.decrypt(bin_source, password)
             StringIO.new(decrypted_zip)
           else
-            StringIO.new(source)
+            StringIO.new(bin_source)
           end
         elsif File.file?(source)
           first_bytes = begin
@@ -861,11 +1360,11 @@ module Xlsxrb
       sheet_xml.sub(/<dimension\b([^>]*)\bref="[^"]*"/, "<dimension\\1ref=\"#{dim_ref}\"")
     end
 
-    #: (Array[Elements::Row] rows, Array[untyped] shared_strings, Hash[untyped, Integer] sst_index, ?use_sst: bool) -> String
-    def serialize_sheet_data_xml(rows, shared_strings, sst_index, use_sst: true)
+    #: (Array[Elements::Row] rows, Array[untyped] shared_strings, Hash[untyped, Integer] sst_index, ?use_sst: bool, ?date1904: bool) -> String
+    def serialize_sheet_data_xml(rows, shared_strings, sst_index, use_sst: true, date1904: false)
       io = StringIO.new
       io.write("<sheetData>")
-      ws = Ooxml::WorksheetWriter.new(io)
+      ws = Ooxml::WorksheetWriter.new(io, date1904: date1904)
       ws.instance_variable_set(:@started, true)
 
       rows.each do |row|
@@ -915,8 +1414,8 @@ module Xlsxrb
   # @param sst_index [Hash{String => Integer}] Shared strings index mapping.
   # @return [Hash{Symbol => Object}] Raw cell hash.
   # @api public
-  #: (Integer row_index, Integer col_index, untyped value, Array[String] sst, Hash[String, Integer] sst_index) -> Hash[Symbol, untyped]
-  def self.build_raw_cell_from_value(row_index, col_index, value, sst, sst_index)
+  #: (Integer row_index, Integer col_index, untyped value, Array[String] sst, Hash[String, Integer] sst_index, ?date1904: bool) -> Hash[Symbol, untyped]
+  def self.build_raw_cell_from_value(row_index, col_index, value, sst, sst_index, date1904: false)
     # simplecov:disable
     # Edge case / untested delegation block
     ref = "#{Elements::Cell.column_letter(col_index)}#{row_index + 1}"
@@ -943,9 +1442,9 @@ module Xlsxrb
       result[:value] = value.code
       result[:type] = "e"
     when Date
-      result[:value] = Xlsxrb::Ooxml::Utils.date_to_serial(value)
+      result[:value] = Xlsxrb::Ooxml::Utils.date_to_serial(value, date1904: date1904)
     when Time
-      result[:value] = Xlsxrb::Ooxml::Utils.datetime_to_serial(value)
+      result[:value] = Xlsxrb::Ooxml::Utils.datetime_to_serial(value, date1904: date1904)
     # simplecov:enable
     when NilClass
       # empty cell