xlsxrb 0.1.13 → 0.1.14

data/lib/xlsxrb/elements/image.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Xlsxrb
+  module Elements
+    # Represents an embedded image anchored to worksheet cells.
+    # Coordinates (from_row, from_col, to_row, to_col) are 0-based.
+    #
+    # @example Access image properties
+    #   image = sheet.images.first
+    #   image.filename       #=> "image1.png"
+    #   image.cell_ref       #=> "B3"
+    #   image.content_type   #=> "image/png"
+    #   image.data           #=> "\x89PNG..."
+    #
+    # @api public
+    class Image < Data.define(:name, :filename, :content_type, :data, :from_col, :from_row, :to_col, :to_row, :cx, :cy, :unmapped_data)
+      MIME_TYPES = {
+        "png" => "image/png",
+        "jpg" => "image/jpeg",
+        "jpeg" => "image/jpeg",
+        "gif" => "image/gif",
+        "svg" => "image/svg+xml",
+        "tif" => "image/tiff",
+        "tiff" => "image/tiff",
+        "bmp" => "image/bmp",
+        "webp" => "image/webp",
+        "emf" => "image/x-emf",
+        "wmf" => "image/x-wmf"
+      }.freeze
+
+      # @param filename [String] Target filename (e.g. "image1.png").
+      # @param name [String, nil] Image or shape name.
+      # @param content_type [String, nil] MIME content type (e.g. "image/png").
+      # @param data [String, nil] Raw binary image data.
+      # @param from_col [Integer] 0-based starting column index.
+      # @param from_row [Integer] 0-based starting row index.
+      # @param to_col [Integer, nil] 0-based ending column index (nil for 1-cell anchor).
+      # @param to_row [Integer, nil] 0-based ending row index (nil for 1-cell anchor).
+      # @param cx [Integer, nil] Extent width in EMUs (English Metric Units).
+      # @param cy [Integer, nil] Extent height in EMUs (English Metric Units).
+      # @param unmapped_data [Hash] Additional metadata from drawing XML.
+      #: (filename: String, ?name: String?, ?content_type: String?, ?data: String?, ?from_col: Integer, ?from_row: Integer, ?to_col: Integer?, ?to_row: Integer?, ?cx: Integer?, ?cy: Integer?, ?unmapped_data: Hash[untyped, untyped]) -> void
+      # rubocop:disable Naming/MethodParameterName
+      def initialize(filename:, name: nil, content_type: nil, data: nil, from_col: 0, from_row: 0,
+                     to_col: nil, to_row: nil, cx: nil, cy: nil, unmapped_data: EMPTY_HASH)
+        # rubocop:enable Naming/MethodParameterName
+        ext = File.extname(filename).delete_prefix(".").downcase
+        mime = content_type || MIME_TYPES[ext] || "application/octet-stream"
+        super(
+          name: name,
+          filename: filename,
+          content_type: mime,
+          data: data&.b,
+          from_col: from_col,
+          from_row: from_row,
+          to_col: to_col,
+          to_row: to_row,
+          cx: cx,
+          cy: cy,
+          unmapped_data: unmapped_data
+        )
+      end
+
+      # Returns the top-left cell coordinate reference string (e.g. "A1").
+      #
+      # @return [String]
+      # @api public
+      #: () -> String
+      def cell_ref
+        "#{Cell.column_letter(from_col)}#{from_row + 1}"
+      end
+      alias cell cell_ref
+      alias ref cell_ref
+
+      # Returns the bottom-right cell coordinate reference string (e.g. "B5"), or nil for 1-cell anchors.
+      #
+      # @return [String, nil]
+      # @api public
+      #: () -> String?
+      def to_cell_ref
+        return nil if to_col.nil? || to_row.nil?
+
+        "#{Cell.column_letter(to_col)}#{to_row + 1}"
+      end
+
+      # Returns whether this image uses a one-cell anchor.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def one_cell_anchor?
+        to_col.nil? || to_row.nil?
+      end
+
+      # Returns whether this image uses a two-cell anchor.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def two_cell_anchor?
+        !one_cell_anchor?
+      end
+
+      # Returns the size of the binary image data in bytes.
+      #
+      # @return [Integer]
+      # @api public
+      #: () -> Integer
+      def bytesize
+        data ? data.bytesize : 0
+      end
+
+      # Writes the image data directly to a file on disk.
+      #
+      # @param path [String] Target file path.
+      # @return [Integer] Number of bytes written.
+      # @api public
+      #: (String path) -> Integer
+      def write_to(path)
+        raise Error, "No image binary data available to write" unless data
+
+        File.binwrite(path, data)
+      end
+    end
+  end
+end

data/lib/xlsxrb/elements/row.rb

@@ -14,7 +14,7 @@ module Xlsxrb
     #
     # @api public
     # rubocop:disable Style/DataInheritance -- Required as class syntax for mutant subject matcher
-    class Row < Data.define(:index, :cells, :height, :hidden, :custom_height, :outline_level, :unmapped_data, :errors)
+    class Row < Data.define(:index, :cells, :height, :hidden, :custom_height, :collapsed, :outline_level, :unmapped_data, :errors)
       # rubocop:enable Style/DataInheritance
       [Enumerable].each { |m| include m }
 
@@ -23,17 +23,18 @@ module Xlsxrb
       # @param height [Float, Integer, nil] Row height in points.
       # @param hidden [Boolean] Whether the row is hidden.
       # @param custom_height [Boolean] Whether custom height is set.
+      # @param collapsed [Boolean] Whether the row is collapsed.
       # @param outline_level [Integer, nil] Grouping/outline level.
       # @param unmapped_data [Hash] Additional metadata.
       # @param errors [Array<String>, nil] Validation errors.
-      #: (index: Integer, ?cells: Array[Elements::Cell], ?height: Float | Integer | nil, ?hidden: bool, ?custom_height: bool, ?outline_level: Integer | nil, ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void
-      def initialize(index:, cells: EMPTY_CELLS, height: nil, hidden: false, custom_height: false, outline_level: nil,
-                     unmapped_data: EMPTY_HASH, errors: nil)
+      #: (index: Integer, ?cells: Array[Elements::Cell], ?height: Float | Integer | nil, ?hidden: bool, ?custom_height: bool, ?collapsed: bool, ?outline_level: Integer | nil, ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void
+      def initialize(index:, cells: EMPTY_CELLS, height: nil, hidden: false, custom_height: false, collapsed: false,
+                     outline_level: nil, unmapped_data: EMPTY_HASH, errors: nil)
         computed_errors = errors || self.class.validate(index, cells)
         computed_errors = computed_errors.freeze unless computed_errors.frozen?
         cells = cells.freeze unless cells.frozen?
         super(index: index, cells: cells, height: height, hidden: hidden,
-              custom_height: custom_height, outline_level: outline_level,
+              custom_height: custom_height, collapsed: collapsed, outline_level: outline_level,
               unmapped_data: unmapped_data, errors: computed_errors)
       end
 
@@ -53,18 +54,144 @@ module Xlsxrb
         when Symbol
           case col_index
           when :cells then cells
+          when :values then values
+          when :raw_values then raw_values
+          when :formatted_values then formatted_values
+          when :formulas then formulas
           when :index then index
           when :height then height
           when :hidden then hidden
           when :custom_height then custom_height
+          when :collapsed then collapsed
           when :outline_level then outline_level
-          when :attrs then { height: height, hidden: hidden, custom_height: custom_height, outline_level: outline_level }
+          when :style_index then style_index
+          when :hidden? then hidden?
+          when :collapsed? then collapsed?
+          when :custom_height? then custom_height?
+          when :attributes then attributes
+          when :cells_hash then cells_hash
+          when :attrs
+            h = { height: height, hidden: hidden, custom_height: custom_height, collapsed: collapsed, outline_level: outline_level }
+            h[:style_index] = style_index if style_index
+            h
           end
         else
           cells[col_index]
         end
       end
 
+      # Returns a new Row with missing cells padded up to the maximum column index.
+      #
+      # @return [Elements::Row]
+      # @api public
+      #: () -> Elements::Row
+      def pad_empty_cells
+        return self if cells.empty?
+
+        max_col = cells.map(&:column_index).max || 0
+        return self if cells.size == max_col + 1
+
+        is_d1904 = cells.first ? cells.first.date1904? : false
+        cell_map = {}
+        cells.each { |c| cell_map[c.column_index] = c }
+        padded = Array.new(max_col + 1)
+        (0..max_col).each do |c_idx|
+          padded[c_idx] = cell_map[c_idx] || Cell.fast_create(index, c_idx, nil, nil, nil, nil, nil, is_d1904)
+        end
+        Row.new(
+          index: index,
+          cells: padded,
+          height: height,
+          hidden: hidden,
+          custom_height: custom_height,
+          collapsed: collapsed,
+          outline_level: outline_level,
+          unmapped_data: unmapped_data,
+          errors: errors
+        )
+      end
+
+      # Returns a coordinate-keyed Hash of cell values (e.g. {"A1" => "value", "B1" => 123}).
+      #
+      # @param type_cast [Boolean] Whether to coerce date/time serial numbers into Date/Time instances.
+      # @return [Hash{String => Object}]
+      # @api public
+      #: (?type_cast: bool) -> Hash[String, untyped]
+      def cells_hash(type_cast: false)
+        result = {}
+        cells.each do |c|
+          val = c.value
+          if type_cast && val.is_a?(Numeric) && c.format_code
+            fmt_type = NumberFormatter.format_type(c.format_code)
+            begin
+              case fmt_type
+              when :date
+                val = Ooxml::Utils.serial_to_date(val, date1904: c.date1904?)
+              when :datetime, :time
+                val = Ooxml::Utils.serial_to_datetime(val, date1904: c.date1904?)
+              end
+            rescue StandardError
+              # Keep val numeric on failure
+            end
+          end
+          result[c.ref] = val
+        end
+        result
+      end
+
+      # Returns whether the row is hidden.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def hidden?
+        hidden == true
+      end
+
+      # Returns whether the row is collapsed.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def collapsed?
+        collapsed == true
+      end
+
+      # Returns whether custom height is set.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def custom_height?
+        custom_height == true
+      end
+
+      # Returns a frozen Hash of row attributes.
+      #
+      # @return [Hash{Symbol => Object}]
+      # @api public
+      #: () -> Hash[Symbol, untyped]
+      def attributes
+        h = {
+          index: index,
+          height: height,
+          hidden: hidden,
+          custom_height: custom_height,
+          collapsed: collapsed,
+          outline_level: outline_level
+        }
+        h[:style_index] = style_index if style_index
+        h.freeze
+      end
+
+      # Returns style_index if present in unmapped_data.
+      #
+      # @return [Integer, nil]
+      #: () -> Integer?
+      def style_index
+        unmapped_data[:style_index]
+      end
+
       # Iterate over cells in this row.
       #
       # @example
@@ -130,6 +257,17 @@ module Xlsxrb
         errors.empty?
       end
 
+      # Returns whether the row contains no cell values (or all cell values are nil or empty strings).
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def empty?
+        return true if cells.empty?
+
+        cells.all? { |c| c.value.nil? || (c.value.is_a?(String) && c.value.empty?) }
+      end
+
       # Returns the cell at the given 0-based column index, or nil.
       #
       # @param column_index [Integer] 0-based column index.
@@ -142,15 +280,74 @@ module Xlsxrb
 
       # Returns cell values as an Array (sparse columns get nil).
       #
+      # @param type_cast [Boolean] Whether to coerce date/time serial numbers into Date/Time instances.
       # @return [Array<Object>]
       # @api public
-      #: () -> Array[untyped]
-      def values
+      #: (?type_cast: bool) -> Array[untyped]
+      def values(type_cast: false)
+        return [] if cells.empty?
+
+        max_col = cells.max_by(&:column_index)&.column_index || 0
+        result = Array.new(max_col + 1)
+        cells.each do |c|
+          val = c.value
+          if type_cast && val.is_a?(Numeric) && c.format_code
+            fmt_type = NumberFormatter.format_type(c.format_code)
+            begin
+              case fmt_type
+              when :date
+                val = Ooxml::Utils.serial_to_date(val, date1904: c.date1904?)
+              when :datetime, :time
+                val = Ooxml::Utils.serial_to_datetime(val, date1904: c.date1904?)
+              end
+            rescue StandardError
+              # Keep val numeric on failure
+            end
+          end
+          result[c.column_index] = val
+        end
+        result
+      end
+
+      # Returns unparsed raw cell values as an Array (sparse columns get nil).
+      #
+      # @return [Array<String, nil>]
+      # @api public
+      #: () -> Array[String?]
+      def raw_values
+        return [] if cells.empty?
+
+        max_col = cells.max_by(&:column_index).column_index
+        result = Array.new(max_col + 1)
+        cells.each { |c| result[c.column_index] = c.raw_value }
+        result
+      end
+
+      # Returns formatted string representations of cell values as an Array (sparse columns get nil).
+      #
+      # @return [Array<String, nil>]
+      # @api public
+      #: () -> Array[String?]
+      def formatted_values
+        return [] if cells.empty?
+
+        max_col = cells.max_by(&:column_index).column_index
+        result = Array.new(max_col + 1)
+        cells.each { |c| result[c.column_index] = c.formatted_value }
+        result
+      end
+
+      # Returns formula expressions without leading '=' as an Array (sparse columns get nil).
+      #
+      # @return [Array<String, nil>]
+      # @api public
+      #: () -> Array[String?]
+      def formulas
         return [] if cells.empty?
 
         max_col = cells.max_by(&:column_index).column_index
         result = Array.new(max_col + 1)
-        cells.each { |c| result[c.column_index] = c.value }
+        cells.each { |c| result[c.column_index] = c.formula_expression }
         result
       end
 

data/lib/xlsxrb/elements/styles.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require_relative "../number_formatter"
+require_relative "../ooxml/utils"
+
+module Xlsxrb
+  module Elements
+    # Represents the workbook stylesheet definitions (fonts, fills, borders, cellXfs, and numFmts).
+    # Inherits from Hash for backward compatibility with existing styles hash structures,
+    # while providing precomputed O(1) number format classifications.
+    #
+    # @api public
+    class Styles < Hash #[untyped, untyped]
+      # Initializes the styles container, optionally wrapping an existing styles hash.
+      #
+      # @param initial_hash [Hash, nil] Initial styles dictionary.
+      #: (?Hash[untyped, untyped]? initial_hash) -> void
+      def initialize(initial_hash = nil)
+        super()
+        merge!(initial_hash) if initial_hash.is_a?(Hash)
+        @format_codes = nil
+        @format_types = nil
+        @date_flags = nil
+        @datetime_flags = nil
+        @time_flags = nil
+      end
+
+      # Returns the format code string for a given style index.
+      #
+      # @param style_index [Integer, nil]
+      # @return [String, nil]
+      # @api public
+      #: (Integer? style_index) -> String?
+      def number_format(style_index)
+        return nil unless style_index.is_a?(Integer) && style_index >= 0
+
+        precompute! unless @format_codes
+        @format_codes[style_index]
+      end
+      alias format_code number_format
+      alias format_code_for number_format
+
+      # Returns the classified format category (:date, :datetime, :time, :number, :text, :general) for a style index.
+      #
+      # @param style_index [Integer, nil]
+      # @return [Symbol, nil]
+      # @api public
+      #: (Integer? style_index) -> Symbol?
+      def format_type(style_index)
+        return nil unless style_index.is_a?(Integer) && style_index >= 0
+
+        precompute! unless @format_types
+        @format_types[style_index]
+      end
+      alias classification_for format_type
+
+      # Returns whether the style index represents a date, datetime, or time pattern.
+      #
+      # @param style_index [Integer, nil]
+      # @return [Boolean]
+      # @api public
+      #: (Integer? style_index) -> bool
+      def date_format?(style_index)
+        return false unless style_index.is_a?(Integer) && style_index >= 0
+
+        precompute! unless @date_flags
+        @date_flags[style_index] || false
+      end
+
+      # Returns whether the style index represents a datetime pattern.
+      #
+      # @param style_index [Integer, nil]
+      # @return [Boolean]
+      # @api public
+      #: (Integer? style_index) -> bool
+      def datetime_format?(style_index)
+        return false unless style_index.is_a?(Integer) && style_index >= 0
+
+        precompute! unless @datetime_flags
+        @datetime_flags[style_index] || false
+      end
+
+      # Returns whether the style index represents a time pattern.
+      #
+      # @param style_index [Integer, nil]
+      # @return [Boolean]
+      # @api public
+      #: (Integer? style_index) -> bool
+      def time_format?(style_index)
+        return false unless style_index.is_a?(Integer) && style_index >= 0
+
+        precompute! unless @time_flags
+        @time_flags[style_index] || false
+      end
+
+      # Returns whether the style index represents a date-only pattern.
+      #
+      # @param style_index [Integer, nil]
+      # @return [Boolean]
+      # @api public
+      #: (Integer? style_index) -> bool
+      def date_only_format?(style_index)
+        format_type(style_index) == :date
+      end
+
+      # Precomputes format code and type classification lookups for all cellXfs.
+      #
+      # @return [self]
+      # @api public
+      #: () -> self
+      def precompute!
+        cell_xfs = self[:cell_xfs]
+        size = cell_xfs.is_a?(Array) ? cell_xfs.size : 0
+
+        codes = Array.new(size)
+        types = Array.new(size)
+        d_flags = Array.new(size, false)
+        dt_flags = Array.new(size, false)
+        t_flags = Array.new(size, false)
+
+        if size.positive?
+          cell_style_xfs = self[:cell_style_xfs]
+          num_fmts = self[:num_fmts] || {}
+
+          size.times do |i|
+            xf = cell_xfs[i]
+            next unless xf.is_a?(Hash)
+
+            num_fmt_id = xf[:num_fmt_id]
+            if (num_fmt_id.nil? || num_fmt_id.zero?) && xf[:xf_id] && cell_style_xfs.is_a?(Array)
+              parent_xf = cell_style_xfs[xf[:xf_id]]
+              num_fmt_id = parent_xf[:num_fmt_id] if parent_xf.is_a?(Hash)
+            end
+
+            code = num_fmt_id ? (num_fmts[num_fmt_id] || Ooxml::Utils::BUILTIN_NUM_FMT_CODES[num_fmt_id]) : nil
+
+            codes[i] = code
+            type = NumberFormatter.format_type(code)
+            types[i] = type
+            d_flags[i] = %i[date datetime time].include?(type)
+            dt_flags[i] = (type == :datetime)
+            t_flags[i] = (type == :time)
+          end
+        end
+
+        @format_codes = codes
+        @format_types = types
+        @date_flags = d_flags
+        @datetime_flags = dt_flags
+        @time_flags = t_flags
+        self
+      end
+    end
+  end
+end

data/lib/xlsxrb/elements/types.rb

@@ -53,6 +53,43 @@ module Xlsxrb
       end
     end
 
+    # Represents a formatted text run within a rich text string.
+    #
+    # @example
+    #   run = Elements::RichTextRun.new(text: "Hello", font: { bold: true })
+    #
+    # @api public
+    RichTextRun = Data.define(:text, :font) do
+      # @param text [String] Plain text for this run.
+      # @param font [Hash, nil] Optional font styling properties.
+      #: (?text: String, ?font: Hash[Symbol, untyped]?) -> void
+      def initialize(text: "", font: nil)
+        super
+      end
+
+      # Supports hash-like key access for backwards compatibility.
+      #
+      # @param key [Symbol]
+      # @return [Object, nil]
+      # @api public
+      #: (Symbol key) -> untyped
+      def [](key)
+        case key
+        when :text then text
+        when :font then font
+        end
+      end
+
+      # Returns the plain text of this run.
+      #
+      # @return [String]
+      # @api public
+      #: () -> String
+      def to_s
+        text
+      end
+    end
+
     # Represents a rich text string with multiple formatting runs.
     #
     # @example
@@ -66,7 +103,64 @@ module Xlsxrb
       # @api public
       #: () -> String
       def to_s
-        runs.map { |r| r[:text] }.join
+        runs.map { |r| r[:text] || r.to_s }.join
+      end
+    end
+
+    # Represents a worksheet hyperlink with an optional target URL, display text, tooltip (ScreenTip), and internal location.
+    #
+    # @example Create a hyperlink
+    #   link = Elements::Hyperlink.new(url: "https://example.com", tooltip: "Visit website")
+    #
+    # @api public
+    # rubocop:disable Lint/DataDefineOverride -- :display represents the hyperlink display text attribute in OOXML
+    Hyperlink = Data.define(:url, :display, :tooltip, :location) do
+      # rubocop:enable Lint/DataDefineOverride
+      # @param url [String, nil] Target external URL or URI.
+      # @param display [String, nil] Optional friendly display label.
+      # @param tooltip [String, nil] Optional hover ScreenTip text.
+      # @param location [String, nil] Optional internal sheet/cell reference.
+      #: (?url: String?, ?display: String?, ?tooltip: String?, ?location: String?) -> void
+      def initialize(url: nil, display: nil, tooltip: nil, location: nil)
+        super
+      end
+
+      # Supports hash-like key access for backwards compatibility.
+      #
+      # @param key [Symbol]
+      # @return [Object, nil]
+      # @api public
+      #: (Symbol key) -> untyped
+      def [](key)
+        case key
+        when :url then url
+        when :display then display
+        when :tooltip then tooltip
+        when :location then location
+        end
+      end
+
+      # Supports Hash conversion.
+      #
+      # @return [Hash{Symbol => String}]
+      # @api public
+      #: () -> Hash[Symbol, String]
+      def to_h
+        h = {}
+        h[:url] = url if url
+        h[:display] = display if display
+        h[:tooltip] = tooltip if tooltip
+        h[:location] = location if location
+        h
+      end
+
+      # Returns the target URL or location string.
+      #
+      # @return [String, nil]
+      # @api public
+      #: () -> String?
+      def to_s
+        url || location
       end
     end
   end