xlsxrb 0.1.13 → 0.1.15

data/lib/xlsxrb/elements/worksheet.rb

@@ -17,23 +17,139 @@ module Xlsxrb
     class Worksheet
       [Enumerable, CoordinateAccess].each { |m| include m }
 
-      attr_reader :name, :rows, :columns, :charts, :unmapped_data, :errors
+      attr_reader :name, :rows, :columns, :charts, :conditional_formatting, :data_validations, :unmapped_data, :errors, :state, :hyperlinks, :comments, :images, :styles, :date1904, :print_area, :print_titles, :sparkline_groups, :merged_cells, :auto_filter, :tables, :shapes, :freeze_pane, :page_setup, :page_margins, :header_footer, :print_options, :sheet_protection, :sheet_view, :sheet_properties, :sheet_format, :row_breaks, :col_breaks, :protected_ranges, :cell_watches
+      attr_writer :dimension
+      alias conditional_formats conditional_formatting
 
       # @param name [String] The worksheet name (max 31 characters).
       # @param rows [Array<Elements::Row>] Rows in the sheet.
       # @param columns [Array<Elements::Column>] Column definitions.
       # @param charts [Array<Hash>] Charts in the sheet.
+      # @param conditional_formatting [Array<Hash>, nil] Conditional formatting rules.
+      # @param data_validations [Array<Hash>] Data validation rules.
       # @param unmapped_data [Hash] Additional metadata for round-tripping.
       # @param errors [Array<String>, nil] Validation errors.
-      #: (name: String?, ?rows: Array[Elements::Row], ?columns: Array[Elements::Column], ?charts: Array[Hash[Symbol, untyped]], ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void
-      def initialize(name:, rows: [], columns: [], charts: [], unmapped_data: {}, errors: nil)
+      # @param conditional_formats [Array<Hash>, nil] Alias for conditional_formatting.
+      # @param state [Symbol] Sheet visibility state (:visible, :hidden, or :very_hidden).
+      # @param hyperlinks [Hash{String => Hash}] Hyperlink mappings by cell reference.
+      # @param comments [Array<Hash>] Comments and notes in the sheet.
+      # @param images [Array<Elements::Image>] Embedded images in the sheet.
+      # @param styles [Hash, nil] Optional parsed styles hash.
+      # @param dimension [String, nil] Sheet dimension reference string (e.g. "A1:Z50000").
+      # @param trim_empty_rows [Boolean] Whether to omit trailing empty rows during 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.
+      # @param print_area [String, nil] Sheet print area range (e.g. "A1:H50").
+      # @param print_titles [Hash, nil] Repeating print title rows/cols (e.g. { rows: "1:2", cols: "A:B" }).
+      # @param sparkline_groups [Array<Hash>] Sparkline groups in the sheet.
+      # @param merged_cells [Array<String>] Merged cell ranges (e.g. ["A1:B2"]).
+      # @param auto_filter [String, nil] AutoFilter range (e.g. "A1:E10").
+      # @param tables [Array<Hash>] Table definitions in the sheet.
+      # @param shapes [Array<Hash>] Shape definitions in the sheet.
+      # @param freeze_pane [Hash, nil] Freeze pane settings (e.g. { row: 1, col: 0 }).
+      # @param page_setup [Hash] Page setup properties (e.g. orientation, paper size).
+      # @param page_margins [Hash, nil] Page margins settings.
+      # @param header_footer [Hash] Header and footer configurations.
+      # @param print_options [Hash] Print options (e.g. gridlines, headings).
+      # @param sheet_protection [Hash, nil] Sheet protection settings.
+      # @param sheet_view [Hash] Sheet view configurations (e.g. zoom, gridlines).
+      # @param sheet_properties [Hash] Sheet properties (e.g. tabColor, outlinePr).
+      # @param sheet_format [Hash] Sheet format properties (e.g. defaultRowHeight, defaultColWidth).
+      # @param row_breaks [Array<Integer | Hash>] Explicit page row breaks.
+      # @param col_breaks [Array<Integer | Hash>] Explicit page column breaks.
+      # @param protected_ranges [Array<Hash>] Protected range definitions.
+      # @param cell_watches [Array<String>] Watched cell references.
+      #: (name: String?, ?rows: Array[Elements::Row], ?columns: Array[Elements::Column], ?charts: Array[Hash[Symbol, untyped]], ?conditional_formatting: Array[Hash[Symbol, untyped]]?, ?data_validations: Array[Hash[Symbol, untyped]], ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?, ?conditional_formats: Array[Hash[Symbol, untyped]]?, ?state: Symbol, ?hyperlinks: Hash[String, untyped], ?comments: Array[Hash[Symbol, untyped]], ?images: Array[Elements::Image], ?styles: Hash[untyped, untyped]?, ?date1904: bool, ?dimension: String?, ?trim_empty_rows: bool, ?pad_empty_rows: bool, ?pad_empty_cells: bool, ?print_area: String?, ?print_titles: Hash[Symbol, untyped]?, ?sparkline_groups: Array[Hash[Symbol, untyped]], ?merged_cells: Array[String], ?auto_filter: String?, ?tables: Array[Hash[Symbol, untyped]], ?shapes: Array[Hash[Symbol, untyped]], ?freeze_pane: Hash[Symbol, untyped]?, ?page_setup: Hash[Symbol, untyped], ?page_margins: Hash[Symbol, untyped]?, ?header_footer: Hash[Symbol, untyped], ?print_options: Hash[Symbol, untyped], ?sheet_protection: Hash[Symbol, untyped]?, ?sheet_view: Hash[Symbol, untyped], ?sheet_properties: Hash[Symbol, untyped], ?sheet_format: Hash[Symbol, untyped], ?row_breaks: Array[untyped], ?col_breaks: Array[untyped], ?protected_ranges: Array[Hash[Symbol, untyped]], ?cell_watches: Array[String]) -> void
+      def initialize(name:, rows: [], columns: [], charts: [], conditional_formatting: nil, data_validations: [], unmapped_data: {}, errors: nil, conditional_formats: nil, state: :visible, hyperlinks: {}, comments: [], images: [], styles: nil, date1904: false, dimension: nil, trim_empty_rows: false, pad_empty_rows: false, pad_empty_cells: false, print_area: nil, print_titles: nil, sparkline_groups: [], merged_cells: [], auto_filter: nil, tables: [], shapes: [], freeze_pane: nil, page_setup: {}, page_margins: nil, header_footer: {}, print_options: {}, sheet_protection: nil, sheet_view: {}, sheet_properties: {}, sheet_format: {}, row_breaks: [], col_breaks: [], protected_ranges: [], cell_watches: [])
         @name = name
         @rows = (rows || []).freeze
         @columns = (columns || []).freeze
         @charts = (charts || []).freeze
+        cf = conditional_formatting || conditional_formats || []
+        @conditional_formatting = cf.freeze
+        @data_validations = (data_validations || []).freeze
         @unmapped_data = (unmapped_data || {}).freeze
         computed_errors = errors || self.class.validate(@name, @rows)
         @errors = computed_errors.freeze
+        @state = state ? state.to_sym : :visible
+        @hyperlinks = (hyperlinks || {}).freeze
+        @comments = (comments || []).freeze
+        @images = (images || []).freeze
+        @styles = styles
+        @date1904 = date1904 ? true : false
+        @dimension = dimension
+        @print_area = print_area
+        @print_titles = print_titles&.freeze
+        @sparkline_groups = (sparkline_groups || []).freeze
+        @trim_empty_rows = trim_empty_rows ? true : false
+        @pad_empty_rows = pad_empty_rows ? true : false
+        @pad_empty_cells = pad_empty_cells ? true : false
+        @merged_cells = (merged_cells || []).freeze
+        @auto_filter = auto_filter
+        @tables = (tables || []).freeze
+        @shapes = (shapes || []).freeze
+        @freeze_pane = freeze_pane&.freeze
+        @page_setup = (page_setup || {}).freeze
+        @page_margins = page_margins&.freeze
+        @header_footer = (header_footer || {}).freeze
+        @print_options = (print_options || {}).freeze
+        @sheet_protection = sheet_protection&.freeze
+        @sheet_view = (sheet_view || {}).freeze
+        @sheet_properties = (sheet_properties || {}).freeze
+        @sheet_format = (sheet_format || unmapped_data[:sheet_format] || unmapped_data.dig(:facade, :sheet_format) || {}).freeze
+        @row_breaks = (row_breaks || []).freeze
+        @col_breaks = (col_breaks || []).freeze
+        @protected_ranges = (protected_ranges || unmapped_data[:protected_ranges] || unmapped_data.dig(:facade, :protected_ranges) || []).freeze
+        @cell_watches = (cell_watches || unmapped_data[:cell_watches] || unmapped_data.dig(:facade, :cell_watches) || []).freeze
+      end
+
+      # Returns whether trailing empty rows are omitted during iteration.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def trim_empty_rows?
+        @trim_empty_rows ? true : false
+      end
+      alias trim_empty_rows trim_empty_rows?
+
+      # Returns whether skipped rows are padded during iteration.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def pad_empty_rows?
+        @pad_empty_rows ? true : false
+      end
+      alias pad_empty_rows pad_empty_rows?
+
+      # Returns whether missing cells within rows are padded during iteration.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def pad_empty_cells?
+        @pad_empty_cells ? true : false
+      end
+      alias pad_empty_cells pad_empty_cells?
+
+      # Returns whether the worksheet uses the 1904 date system.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def date1904?
+        @date1904
+      end
+
+      # Returns the worksheet dimension reference string (e.g. "A1:Z50000"),
+      # or computes it dynamically from rows if not explicitly set.
+      #
+      # @return [String, nil]
+      # @api public
+      #: () -> String?
+      def dimension
+        @dimension ||= compute_dimension
       end
 
       # Iterate over rows in the worksheet.
@@ -43,16 +159,27 @@ module Xlsxrb
       #     puts row.to_a.inspect
       #   end
       #
-      # @yield [row]
-      # @yieldparam row [Elements::Row]
-      # @return [Enumerator, void]
+      # @overload each(trim_empty_rows: nil, pad_empty_rows: nil, pad_empty_cells: nil, &block)
+      #   @param trim_empty_rows [Boolean, nil] Whether to omit trailing empty rows.
+      #   @param pad_empty_rows [Boolean, nil] Whether to yield empty rows for skipped row numbers.
+      #   @param pad_empty_cells [Boolean, nil] Whether to pad missing cells within rows.
+      #   @yield [row]
+      #   @yieldparam row [Elements::Row]
+      #   @return [void]
+      #
+      # @overload each(trim_empty_rows: nil, pad_empty_rows: nil, pad_empty_cells: nil)
+      #   @param trim_empty_rows [Boolean, nil] Whether to omit trailing empty rows.
+      #   @param pad_empty_rows [Boolean, nil] Whether to yield empty rows for skipped row numbers.
+      #   @param pad_empty_cells [Boolean, nil] Whether to pad missing cells within rows.
+      #   @return [Enumerator<Elements::Row, void>]
+      #
       # @api public
-      #: () { (Elements::Row) -> void } -> void
-      #: () -> Enumerator[Elements::Row, void]
-      def each(&)
-        return to_enum(:each) unless block_given?
+      #: (?trim_empty_rows: bool?, ?pad_empty_rows: bool?, ?pad_empty_cells: bool?) { (Elements::Row) -> void } -> void
+      #: (?trim_empty_rows: bool?, ?pad_empty_rows: bool?, ?pad_empty_cells: bool?) -> Enumerator[Elements::Row, void]
+      def each(trim_empty_rows: nil, pad_empty_rows: nil, pad_empty_cells: nil, &)
+        return to_enum(:each, trim_empty_rows: trim_empty_rows, pad_empty_rows: pad_empty_rows, pad_empty_cells: pad_empty_cells) unless block_given?
 
-        rows.each(&)
+        each_row(trim_empty_rows: trim_empty_rows, pad_empty_rows: pad_empty_rows, pad_empty_cells: pad_empty_cells, &)
       end
 
       # Iterate over rows in the worksheet.
@@ -62,16 +189,104 @@ module Xlsxrb
       #     puts "Row #{row.index}: #{row.to_a.inspect}"
       #   end
       #
-      # @yield [row]
-      # @yieldparam row [Elements::Row]
-      # @return [Enumerator, void]
+      # @overload each_row(trim_empty_rows: nil, pad_empty_rows: nil, pad_empty_cells: nil, &block)
+      #   @param trim_empty_rows [Boolean, nil] Whether to omit trailing empty rows.
+      #   @param pad_empty_rows [Boolean, nil] Whether to yield empty rows for skipped row numbers.
+      #   @param pad_empty_cells [Boolean, nil] Whether to pad missing cells within rows.
+      #   @yield [row]
+      #   @yieldparam row [Elements::Row]
+      #   @return [void]
+      #
+      # @overload each_row(trim_empty_rows: nil, pad_empty_rows: nil, pad_empty_cells: nil)
+      #   @param trim_empty_rows [Boolean, nil] Whether to omit trailing empty rows.
+      #   @param pad_empty_rows [Boolean, nil] Whether to yield empty rows for skipped row numbers.
+      #   @param pad_empty_cells [Boolean, nil] Whether to pad missing cells within rows.
+      #   @return [Enumerator<Elements::Row, void>]
+      #
+      # @api public
+      #: (?trim_empty_rows: bool?, ?pad_empty_rows: bool?, ?pad_empty_cells: bool?) { (Elements::Row) -> void } -> void
+      #: (?trim_empty_rows: bool?, ?pad_empty_rows: bool?, ?pad_empty_cells: bool?) -> Enumerator[Elements::Row, void]
+      def each_row(trim_empty_rows: nil, pad_empty_rows: nil, pad_empty_cells: nil, &block)
+        return to_enum(:each_row, trim_empty_rows: trim_empty_rows, pad_empty_rows: pad_empty_rows, pad_empty_cells: pad_empty_cells) unless block
+
+        trim = if trim_empty_rows.nil?
+                 @trim_empty_rows
+               else
+                 (trim_empty_rows ? true : false)
+               end
+        pad_rows = if pad_empty_rows.nil?
+                     @pad_empty_rows
+                   else
+                     (pad_empty_rows ? true : false)
+                   end
+        pad_cells = if pad_empty_cells.nil?
+                      @pad_empty_cells
+                    else
+                      (pad_empty_cells ? true : false)
+                    end
+
+        row_consumer = if trim
+                         pending_empty = []
+                         lambda do |row|
+                           if row.empty?
+                             pending_empty << row
+                           else
+                             pending_empty.each(&block)
+                             pending_empty.clear
+                             block.call(row)
+                           end
+                         end
+                       else
+                         block
+                       end
+
+        if pad_rows
+          current_expected_idx = 0
+          inner_consumer = row_consumer
+          row_consumer = lambda do |row|
+            while current_expected_idx < row.index
+              empty_row = Row.new(index: current_expected_idx)
+              inner_consumer.call(pad_cells ? empty_row.pad_empty_cells : empty_row)
+              current_expected_idx += 1
+            end
+            inner_consumer.call(row)
+            current_expected_idx = row.index + 1
+          end
+        end
+
+        rows.each do |row|
+          row_to_yield = pad_cells ? row.pad_empty_cells : row
+          row_consumer.call(row_to_yield)
+        end
+      end
+
+      # Iterates over row values as Arrays.
+      #
+      # @overload each_row_values(type_cast: false, trim_empty_rows: nil, pad_empty_rows: nil, pad_empty_cells: nil, &block)
+      #   @param type_cast [Boolean] Whether to coerce date/time serial numbers into Date/Time instances.
+      #   @param trim_empty_rows [Boolean, nil] Whether to omit trailing empty rows.
+      #   @param pad_empty_rows [Boolean, nil] Whether to yield empty rows for skipped row numbers.
+      #   @param pad_empty_cells [Boolean, nil] Whether to pad missing cells within rows.
+      #   @yield [values]
+      #   @yieldparam values [Array<Object>] Row values array.
+      #   @return [void]
+      #
+      # @overload each_row_values(type_cast: false, trim_empty_rows: nil, pad_empty_rows: nil, pad_empty_cells: nil)
+      #   @param type_cast [Boolean] Whether to coerce date/time serial numbers into Date/Time instances.
+      #   @param trim_empty_rows [Boolean, nil] Whether to omit trailing empty rows.
+      #   @param pad_empty_rows [Boolean, nil] Whether to yield empty rows for skipped row numbers.
+      #   @param pad_empty_cells [Boolean, nil] Whether to pad missing cells within rows.
+      #   @return [Enumerator<Array<Object>, void>]
+      #
       # @api public
-      #: () { (Elements::Row) -> void } -> void
-      #: () -> Enumerator[Elements::Row, void]
-      def each_row(&)
-        return to_enum(:each_row) unless block_given?
+      #: (?type_cast: bool, ?trim_empty_rows: bool?, ?pad_empty_rows: bool?, ?pad_empty_cells: bool?) { (Array[untyped]) -> void } -> void
+      #: (?type_cast: bool, ?trim_empty_rows: bool?, ?pad_empty_rows: bool?, ?pad_empty_cells: bool?) -> Enumerator[Array[untyped], void]
+      def each_row_values(type_cast: false, trim_empty_rows: nil, pad_empty_rows: nil, pad_empty_cells: nil, &block)
+        return to_enum(:each_row_values, type_cast: type_cast, trim_empty_rows: trim_empty_rows, pad_empty_rows: pad_empty_rows, pad_empty_cells: pad_empty_cells) unless block
 
-        rows.each(&)
+        each_row(trim_empty_rows: trim_empty_rows, pad_empty_rows: pad_empty_rows, pad_empty_cells: pad_empty_cells) do |row|
+          block.call(row.values(type_cast: type_cast))
+        end
       end
 
       # Iterate over all cells across rows.
@@ -88,6 +303,39 @@ module Xlsxrb
         cells.each(&)
       end
 
+      # Returns all images anchored at a specific cell reference or 0-based coordinate.
+      #
+      # @param ref_or_row [String, Symbol, Integer] Cell reference (e.g. "A1") or 0-based row index.
+      # @param col [Integer, nil] Optional 0-based column index.
+      # @return [Array<Elements::Image>]
+      # @api public
+      #: (String | Symbol | Integer ref_or_row, ?Integer? col) -> Array[Elements::Image]
+      def images_at(ref_or_row, col = nil)
+        ref = if col
+                "#{Cell.column_letter(col)}#{ref_or_row.to_i + 1}"
+              else
+                ref_or_row.to_s.upcase
+              end
+        images.select { |img| img.cell_ref == ref }
+      end
+
+      # Yields self with images loaded or returns self.
+      #
+      # @yield [sheet]
+      # @yieldparam sheet [Elements::Worksheet]
+      # @return [Elements::Worksheet, void]
+      # @api public
+      #: () { (Elements::Worksheet) -> void } -> void
+      #: () -> Elements::Worksheet
+      def with_images
+        if block_given?
+          yield self
+          nil
+        else
+          self
+        end
+      end
+
       # Returns whether the worksheet is valid according to OOXML specifications.
       #
       # @return [Boolean]
@@ -96,6 +344,95 @@ module Xlsxrb
         errors.empty?
       end
 
+      # Returns whether the worksheet is hidden (:hidden or :very_hidden).
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def hidden?
+        @state == :hidden || @state == :very_hidden
+      end
+
+      # Returns whether the worksheet is visible.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def visible?
+        @state == :visible
+      end
+
+      # Returns hyperlink metadata for the given cell reference, or nil.
+      #
+      # @param ref_or_row [String, Symbol, Integer] Cell reference (e.g. "A1") or 0-based row index.
+      # @param col [Integer, nil] Optional 0-based column index if ref_or_row is a row index.
+      # @return [Hash, nil]
+      # @api public
+      #: (String | Symbol | Integer ref_or_row, ?Integer? col) -> Hash[Symbol, untyped]?
+      def hyperlink(ref_or_row, col = nil)
+        ref = if col
+                "#{Cell.column_letter(col)}#{ref_or_row.to_i + 1}"
+              else
+                ref_or_row.to_s.upcase
+              end
+        @hyperlinks[ref]
+      end
+
+      # Returns comment metadata for the given cell reference, or nil.
+      #
+      # @param ref_or_row [String, Symbol, Integer] Cell reference (e.g. "A1") or 0-based row index.
+      # @param col [Integer, nil] Optional 0-based column index if ref_or_row is a row index.
+      # @return [Hash, nil]
+      # @api public
+      #: (String | Symbol | Integer ref_or_row, ?Integer? col) -> Hash[Symbol, untyped]?
+      def comment(ref_or_row, col = nil)
+        ref = if col
+                "#{Cell.column_letter(col)}#{ref_or_row.to_i + 1}"
+              else
+                ref_or_row.to_s.upcase
+              end
+        comments_by_ref[ref]
+      end
+
+      # Returns comments indexed by cell reference.
+      #
+      # @return [Hash<String, Hash[Symbol, untyped]>]
+      # @api public
+      #: () -> Hash[String, Hash[Symbol, untyped]]
+      def comments_by_ref
+        @comments_by_ref ||= @comments.each_with_object({}) do |c, acc|
+          r = c[:ref] || c[:cell]
+          acc[r.to_s.upcase] = c if r
+        end
+      end
+
+      # Access a cell by reference or 0-based coordinates.
+      #
+      # @param ref_or_row [String, Symbol, Integer] Cell reference (e.g. "A1") or 0-based row index.
+      # @param col [Integer, nil] Optional 0-based column index.
+      # @return [Elements::Cell, nil]
+      # @api public
+      #: (String | Symbol | Integer ref_or_row, ?Integer? col) -> Elements::Cell?
+      def cell(ref_or_row, col = nil)
+        if col
+          row = row_at(ref_or_row.to_i)
+          row&.cell_at(col.to_i)
+        else
+          self[ref_or_row]
+        end
+      end
+
+      # Returns the formatted string representation of a cell's value.
+      #
+      # @param ref_or_row [String, Symbol, Integer] Cell reference (e.g. "A1") or 0-based row index.
+      # @param col [Integer, nil] Optional 0-based column index.
+      # @return [String, nil]
+      # @api public
+      #: (String | Symbol | Integer ref_or_row, ?Integer? col) -> String?
+      def formatted_value(ref_or_row, col = nil)
+        cell(ref_or_row, col)&.formatted_value
+      end
+
       # Returns a new Worksheet with the specified cell updated.
       #
       # @example
@@ -105,10 +442,12 @@ module Xlsxrb
       # @param value [Object] The new cell value.
       # @param style_index [Integer, String, nil] Optional new style index.
       # @param formula [Elements::Formula, nil] Optional new formula.
+      # @param hyperlink [Hash, String, nil] Optional new hyperlink.
+      # @param comment [Hash, String, nil] Optional new comment.
       # @return [Worksheet] A new Worksheet instance.
       # @api public
-      #: (String ref, ?value: untyped, ?style_index: Integer | String | nil, ?formula: Elements::Formula?) -> Elements::Worksheet
-      def update_cell(ref, value: nil, style_index: nil, formula: nil)
+      #: (String ref, ?value: untyped, ?style_index: Integer | String | nil, ?formula: Elements::Formula?, ?hyperlink: (Hash[Symbol, untyped] | String)?, ?comment: (Hash[Symbol, untyped] | String)?) -> Elements::Worksheet
+      def update_cell(ref, value: nil, style_index: nil, formula: nil, hyperlink: nil, comment: nil)
         parsed = Cell.parse_ref(ref)
         raise ArgumentError, "invalid cell reference: #{ref}" unless parsed
 
@@ -121,10 +460,12 @@ module Xlsxrb
                        existing_cell.with(
                          value: value || existing_cell.value,
                          style_index: style_index || existing_cell.style_index,
-                         formula: formula || existing_cell.formula
+                         formula: formula || existing_cell.formula,
+                         hyperlink: hyperlink || existing_cell.hyperlink,
+                         comment: comment || existing_cell.comment
                        )
                      else
-                       Cell.new(row_index: row_idx, column_index: col_idx, value: value, style_index: style_index, formula: formula)
+                       Cell.new(row_index: row_idx, column_index: col_idx, value: value, style_index: style_index, formula: formula, hyperlink: hyperlink, comment: comment)
                      end
 
           # Replace cell in the existing row
@@ -136,11 +477,18 @@ module Xlsxrb
           new_rows = rows.map { |r| r.index == row_idx ? new_row : r }
         else
           # Row doesn't exist, create it
-          new_cell = Cell.new(row_index: row_idx, column_index: col_idx, value: value, style_index: style_index, formula: formula)
+          new_cell = Cell.new(row_index: row_idx, column_index: col_idx, value: value, style_index: style_index, formula: formula, hyperlink: hyperlink, comment: comment)
           new_row = Row.new(index: row_idx, cells: [new_cell])
           new_rows = (rows + [new_row]).sort_by!(&:index)
         end
-        with(rows: new_rows)
+        new_hyperlinks = hyperlink ? hyperlinks.merge(ref.upcase => hyperlink) : hyperlinks
+        new_comments = if comment
+                         entry = comment.is_a?(Hash) ? comment.merge(ref: ref.upcase) : { ref: ref.upcase, text: comment }
+                         @comments.reject { |c| (c[:ref] || c[:cell])&.to_s&.upcase == ref.upcase } + [entry]
+                       else
+                         @comments
+                       end
+        with(rows: new_rows, hyperlinks: new_hyperlinks, comments: new_comments)
       end
 
       # Returns a new Worksheet with attributes replaced (Data-like behavior).
@@ -154,23 +502,122 @@ module Xlsxrb
         new_rows = changes.key?(:rows) ? changes[:rows] : rows
         new_cols = changes.key?(:columns) ? changes[:columns] : columns
         new_charts = changes.key?(:charts) ? changes[:charts] : charts
+        new_cf = if changes.key?(:conditional_formatting)
+                   changes[:conditional_formatting]
+                 elsif changes.key?(:conditional_formats)
+                   changes[:conditional_formats]
+                 else
+                   conditional_formatting
+                 end
+        new_dv = changes.key?(:data_validations) ? changes[:data_validations] : data_validations
         new_unmapped = changes.key?(:unmapped_data) ? changes[:unmapped_data] : unmapped_data
         new_errors = changes.key?(:errors) ? changes[:errors] : errors
+        new_state = changes.key?(:state) ? changes[:state] : state
+        new_hyperlinks = changes.key?(:hyperlinks) ? changes[:hyperlinks] : hyperlinks
+        new_comments = changes.key?(:comments) ? changes[:comments] : comments
+        new_styles = changes.key?(:styles) ? changes[:styles] : styles
+        new_date1904 = changes.key?(:date1904) ? changes[:date1904] : date1904
+        new_dim = changes.key?(:dimension) ? changes[:dimension] : @dimension
+        new_print_area = changes.key?(:print_area) ? changes[:print_area] : print_area
+        new_print_titles = changes.key?(:print_titles) ? changes[:print_titles] : print_titles
+        new_sparklines = changes.key?(:sparkline_groups) ? changes[:sparkline_groups] : sparkline_groups
+        new_trim = changes.key?(:trim_empty_rows) ? changes[:trim_empty_rows] : @trim_empty_rows
+        new_merged = changes.key?(:merged_cells) ? changes[:merged_cells] : merged_cells
+        new_auto_filter = changes.key?(:auto_filter) ? changes[:auto_filter] : auto_filter
+        new_tables = changes.key?(:tables) ? changes[:tables] : tables
+        new_shapes = changes.key?(:shapes) ? changes[:shapes] : shapes
+        new_freeze_pane = changes.key?(:freeze_pane) ? changes[:freeze_pane] : freeze_pane
+        new_page_setup = changes.key?(:page_setup) ? changes[:page_setup] : page_setup
+        new_page_margins = changes.key?(:page_margins) ? changes[:page_margins] : page_margins
+        new_header_footer = changes.key?(:header_footer) ? changes[:header_footer] : header_footer
+        new_print_options = changes.key?(:print_options) ? changes[:print_options] : print_options
+        new_sheet_protection = changes.key?(:sheet_protection) ? changes[:sheet_protection] : sheet_protection
+        new_sheet_view = changes.key?(:sheet_view) ? changes[:sheet_view] : sheet_view
+        new_sheet_properties = changes.key?(:sheet_properties) ? changes[:sheet_properties] : sheet_properties
+        new_sheet_format = changes.key?(:sheet_format) ? changes[:sheet_format] : sheet_format
+        new_row_breaks = changes.key?(:row_breaks) ? changes[:row_breaks] : row_breaks
+        new_col_breaks = changes.key?(:col_breaks) ? changes[:col_breaks] : col_breaks
+        new_protected_ranges = changes.key?(:protected_ranges) ? changes[:protected_ranges] : protected_ranges
+        new_cell_watches = changes.key?(:cell_watches) ? changes[:cell_watches] : cell_watches
 
         self.class.new(
           name: new_name,
           rows: new_rows,
           columns: new_cols,
           charts: new_charts,
+          conditional_formatting: new_cf,
+          data_validations: new_dv,
           unmapped_data: new_unmapped,
-          errors: new_errors
+          errors: new_errors,
+          state: new_state,
+          hyperlinks: new_hyperlinks,
+          comments: new_comments,
+          styles: new_styles,
+          date1904: new_date1904,
+          dimension: new_dim,
+          print_area: new_print_area,
+          print_titles: new_print_titles,
+          sparkline_groups: new_sparklines,
+          trim_empty_rows: new_trim,
+          merged_cells: new_merged,
+          auto_filter: new_auto_filter,
+          tables: new_tables,
+          shapes: new_shapes,
+          freeze_pane: new_freeze_pane,
+          page_setup: new_page_setup,
+          page_margins: new_page_margins,
+          header_footer: new_header_footer,
+          print_options: new_print_options,
+          sheet_protection: new_sheet_protection,
+          sheet_view: new_sheet_view,
+          sheet_properties: new_sheet_properties,
+          sheet_format: new_sheet_format,
+          row_breaks: new_row_breaks,
+          col_breaks: new_col_breaks,
+          protected_ranges: new_protected_ranges,
+          cell_watches: new_cell_watches
         )
       end
 
       # Support pattern matching.
       #: (Array[Symbol]?) -> Hash[Symbol, untyped]
       def deconstruct_keys(_keys)
-        { name: name, rows: rows, columns: columns, charts: charts, unmapped_data: unmapped_data, errors: errors }
+        {
+          name: name,
+          rows: rows,
+          columns: columns,
+          charts: charts,
+          conditional_formatting: conditional_formatting,
+          conditional_formats: conditional_formatting,
+          data_validations: data_validations,
+          unmapped_data: unmapped_data,
+          errors: errors,
+          state: state,
+          hyperlinks: hyperlinks,
+          comments: comments,
+          styles: styles,
+          date1904: date1904,
+          dimension: dimension,
+          print_area: print_area,
+          print_titles: print_titles,
+          sparkline_groups: sparkline_groups,
+          trim_empty_rows: @trim_empty_rows,
+          merged_cells: merged_cells,
+          auto_filter: auto_filter,
+          tables: tables,
+          shapes: shapes,
+          freeze_pane: freeze_pane,
+          page_setup: page_setup,
+          page_margins: page_margins,
+          header_footer: header_footer,
+          print_options: print_options,
+          sheet_protection: sheet_protection,
+          sheet_view: sheet_view,
+          sheet_properties: sheet_properties,
+          sheet_format: sheet_format,
+          row_breaks: row_breaks,
+          col_breaks: col_breaks
+        }
       end
 
       # Compare worksheets for equality.
@@ -178,13 +625,27 @@ module Xlsxrb
       def ==(other)
         return false unless other.is_a?(Worksheet)
 
-        name == other.name && rows == other.rows && columns == other.columns && charts == other.charts
+        name == other.name && rows == other.rows && columns == other.columns && charts == other.charts &&
+          conditional_formatting == other.conditional_formatting && data_validations == other.data_validations &&
+          state == other.state && hyperlinks == other.hyperlinks && comments == other.comments &&
+          merged_cells == other.merged_cells && auto_filter == other.auto_filter &&
+          tables == other.tables && shapes == other.shapes && freeze_pane == other.freeze_pane &&
+          page_setup == other.page_setup && page_margins == other.page_margins &&
+          header_footer == other.header_footer && print_options == other.print_options &&
+          sheet_protection == other.sheet_protection && sheet_view == other.sheet_view &&
+          sheet_properties == other.sheet_properties && sheet_format == other.sheet_format &&
+          row_breaks == other.row_breaks && col_breaks == other.col_breaks
       end
       alias eql? ==
 
       #: () -> Integer
       def hash
-        [self.class, name, rows, columns, charts].hash
+        [
+          self.class, name, rows, columns, charts, conditional_formatting, data_validations,
+          state, hyperlinks, comments, merged_cells, auto_filter, tables, shapes, freeze_pane,
+          page_setup, page_margins, header_footer, print_options, sheet_protection, sheet_view,
+          sheet_properties, sheet_format, row_breaks, col_breaks
+        ].hash
       end
 
       # Returns self when load is called on an already in-memory Worksheet.
@@ -237,6 +698,35 @@ module Xlsxrb
         end
         errs
       end
+
+      private
+
+      #: () -> String?
+      def compute_dimension
+        return nil if rows.empty?
+
+        min_r = nil
+        max_r = nil
+        min_c = nil
+        max_c = nil
+
+        rows.each do |r|
+          next if r.cells.empty?
+
+          min_r = r.index if min_r.nil? || r.index < min_r
+          max_r = r.index if max_r.nil? || r.index > max_r
+          r.cells.each do |c|
+            min_c = c.column_index if min_c.nil? || c.column_index < min_c
+            max_c = c.column_index if max_c.nil? || c.column_index > max_c
+          end
+        end
+
+        return nil if min_r.nil? || min_c.nil?
+
+        start_cell = "#{Elements::Cell.column_letter(min_c)}#{min_r + 1}"
+        end_cell = "#{Elements::Cell.column_letter(max_c)}#{max_r + 1}"
+        start_cell == end_cell ? start_cell : "#{start_cell}:#{end_cell}"
+      end
     end
   end
 end

data/lib/xlsxrb/elements.rb

@@ -9,6 +9,8 @@ require_relative "elements/column"
 require_relative "elements/coordinate_access"
 require_relative "elements/worksheet"
 require_relative "elements/workbook"
+require_relative "elements/styles"
+require_relative "elements/image"
 
 module Xlsxrb
   # High-level domain model layer.