xlsxrb 0.1.9 → 0.1.11

data/lib/xlsxrb/chart_builder.rb

@@ -0,0 +1,333 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Xlsxrb
+  # Builder for block-style chart definitions.
+  #
+  # @example Create a chart definition
+  #   builder = ChartBuilder.new
+  #   builder.type(:bar)
+  #   builder.title("Quarterly Sales")
+  #   builder.series do |s|
+  #     s.name("2026")
+  #     s.categories("Sheet1!$A$2:$A$5")
+  #     s.values("Sheet1!$B$2:$B$5")
+  #   end
+  #
+  # @api public
+  class ChartBuilder
+    # @return [Hash{Symbol => Object}] The configured chart options.
+    #: () -> void
+    def initialize
+      @options = {}
+    end
+
+    # @return [Hash{Symbol => Object}]
+    #: Hash[Symbol, untyped]
+    attr_reader :options
+
+    # Sets the chart type (e.g. :line, :bar, :pie, :area, :radar, :scatter).
+    #
+    # @param value [Symbol, String] Chart type.
+    # @return [Symbol, String]
+    # @api public
+    #: (Symbol | String value) -> (Symbol | String)
+    def type(value)
+      @options[:type] = value
+    end
+
+    # Sets the chart title.
+    #
+    # @param value [String, Hash, nil] Chart title text or options hash.
+    # @return [String, Hash, nil]
+    # @api public
+    #: (String | Hash[Symbol, untyped] | nil value) -> (String | Hash[Symbol, untyped] | nil)
+    def title(value)
+      @options[:title] = value
+    end
+
+    # Adds a data series to the chart.
+    #
+    # @overload series(value)
+    #   Adds a pre-built series options hash.
+    #   @param value [Hash{Symbol => Object}] Series options hash.
+    #   @return [Array<Hash{Symbol => Object}>]
+    #
+    # @overload series(&block)
+    #   Configures a series using a block.
+    #   @yield [series_builder]
+    #   @yieldparam series_builder [SeriesBuilder]
+    #   @return [Array<Hash{Symbol => Object}>]
+    #
+    # @api public
+    #: (?Hash[Symbol, untyped]? value) ?{ (SeriesBuilder) -> void } -> Array[Hash[Symbol, untyped]]
+    def series(value = nil)
+      @options[:series] ||= []
+      if block_given?
+        sb = SeriesBuilder.new
+        yield sb
+        @options[:series] << sb.options
+      elsif value
+        @options[:series] << value
+      end
+      @options[:series]
+    end
+
+    # Configures the legend property for this chart.
+    #
+    # @param args [Array] Positional arguments (e.g. position string).
+    # @param kwargs [Hash] Keyword arguments for legend styling/layout.
+    # @return [Object] The configured legend property.
+    # @api public
+    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    def legend(*args, **kwargs)
+      @options[:legend] = kwargs.empty? ? args.first : kwargs
+    end
+
+    # Configures the plot_area property for this chart.
+    #
+    # @param args [Array] Positional arguments.
+    # @param kwargs [Hash] Keyword arguments for plot area configuration.
+    # @return [Object] The configured plot_area property.
+    # @api public
+    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    def plot_area(*args, **kwargs)
+      @options[:plot_area] = kwargs.empty? ? args.first : kwargs
+    end
+
+    # Configures the chart_space property for this chart.
+    #
+    # @param args [Array] Positional arguments.
+    # @param kwargs [Hash] Keyword arguments.
+    # @return [Object] The configured chart_space property.
+    # @api public
+    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    def chart_space(*args, **kwargs)
+      @options[:chart_space] = kwargs.empty? ? args.first : kwargs
+    end
+
+    # Configures the style index/id for this chart.
+    #
+    # @param args [Array] Positional arguments.
+    # @param kwargs [Hash] Keyword arguments.
+    # @return [Object] The configured style property.
+    # @api public
+    #: (*(Hash[Symbol, String | Integer | bool | nil] | String | Integer) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String | Integer)
+    def style(*args, **kwargs)
+      @options[:style] = kwargs.empty? ? args.first : kwargs
+    end
+
+    # Configures data labels for this chart.
+    #
+    # @param args [Array] Positional arguments.
+    # @param kwargs [Hash] Keyword arguments.
+    # @return [Object] The configured data_labels property.
+    # @api public
+    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    def data_labels(*args, **kwargs)
+      @options[:data_labels] = kwargs.empty? ? args.first : kwargs
+    end
+
+    # Configures whether to plot visible cells only.
+    #
+    # @param args [Array] Positional arguments.
+    # @param kwargs [Hash] Keyword arguments.
+    # @return [Boolean, String]
+    # @api public
+    #: (*(bool | String) args, **String | Integer | bool | nil kwargs) -> (bool | String)
+    def plot_visible_only(*args, **kwargs)
+      @options[:plot_visible_only] = kwargs.empty? ? args.first : kwargs
+    end
+
+    # Configures how blank cells are displayed in the chart.
+    #
+    # @param args [Array] Positional arguments.
+    # @param kwargs [Hash] Keyword arguments.
+    # @return [String]
+    # @api public
+    #: (*(String) args, **String | Integer | bool | nil kwargs) -> String
+    def display_blanks_as(*args, **kwargs)
+      @options[:display_blanks_as] = kwargs.empty? ? args.first : kwargs
+    end
+
+    # Configures 3D view properties for 3D charts.
+    #
+    # @param args [Array] Positional arguments.
+    # @param kwargs [Hash] Keyword arguments.
+    # @return [Object]
+    # @api public
+    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    def view3d(*args, **kwargs)
+      @options[:view3d] = kwargs.empty? ? args.first : kwargs
+    end
+
+    # Configures the category axis properties for this chart.
+    #
+    # @param args [Array] Positional arguments.
+    # @param kwargs [Hash] Keyword arguments.
+    # @return [Object]
+    # @api public
+    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    def category_axis(*args, **kwargs)
+      @options[:category_axis] = kwargs.empty? ? args.first : kwargs
+    end
+
+    # Configures the value axis properties for this chart.
+    #
+    # @param args [Array] Positional arguments.
+    # @param kwargs [Hash] Keyword arguments.
+    # @return [Object]
+    # @api public
+    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    def value_axis(*args, **kwargs)
+      @options[:value_axis] = kwargs.empty? ? args.first : kwargs
+    end
+
+    # Configures whether to show the legend key in data labels.
+    #
+    # @param args [Array] Positional arguments.
+    # @param kwargs [Hash] Keyword arguments.
+    # @return [Boolean, String]
+    # @api public
+    #: (*(bool | String) args, **String | Integer | bool | nil kwargs) -> (bool | String)
+    def show_legend_key(*args, **kwargs)
+      @options[:show_legend_key] = kwargs.empty? ? args.first : kwargs
+    end
+
+    # Builder for a single series entry in block-style chart definitions.
+    #
+    # @api public
+    class SeriesBuilder
+      #: () -> void
+      def initialize
+        @options = {}
+      end
+
+      # @return [Hash{Symbol => Object}]
+      #: Hash[Symbol, untyped]
+      attr_reader :options
+
+      # Configures categories reference for this series (e.g. "Sheet1!$A$2:$A$10").
+      #
+      # @param args [Array] Positional arguments.
+      # @param kwargs [Hash] Keyword arguments.
+      # @return [Object]
+      # @api public
+      #: (*untyped args, **untyped kwargs) -> untyped
+      def categories(*args, **kwargs)
+        @options[:categories] = kwargs.empty? ? args.first : kwargs
+      end
+
+      # Configures values reference for this series (e.g. "Sheet1!$B$2:$B$10").
+      #
+      # @param args [Array] Positional arguments.
+      # @param kwargs [Hash] Keyword arguments.
+      # @return [Object]
+      # @api public
+      #: (*untyped args, **untyped kwargs) -> untyped
+      def values(*args, **kwargs)
+        @options[:values] = kwargs.empty? ? args.first : kwargs
+      end
+
+      # Configures the name for this series (e.g. "Total Sales" or cell reference "Sheet1!$B$1").
+      #
+      # @param args [Array] Positional arguments.
+      # @param kwargs [Hash] Keyword arguments.
+      # @return [Object]
+      # @api public
+      #: (*untyped args, **untyped kwargs) -> untyped
+      def name(*args, **kwargs)
+        @options[:name] = kwargs.empty? ? args.first : kwargs
+      end
+
+      # Configures data markers for this series.
+      #
+      # @param args [Array] Positional arguments.
+      # @param kwargs [Hash] Keyword arguments.
+      # @return [Object]
+      # @api public
+      #: (*untyped args, **untyped kwargs) -> untyped
+      def marker(*args, **kwargs)
+        @options[:marker] = kwargs.empty? ? args.first : kwargs
+      end
+
+      # Configures fill color/pattern for this series.
+      #
+      # @param args [Array] Positional arguments.
+      # @param kwargs [Hash] Keyword arguments.
+      # @return [Object]
+      # @api public
+      #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+      def fill(*args, **kwargs)
+        @options[:fill] = kwargs.empty? ? args.first : kwargs
+      end
+
+      # Configures line color/thickness for this series.
+      #
+      # @param args [Array] Positional arguments.
+      # @param kwargs [Hash] Keyword arguments.
+      # @return [Object]
+      # @api public
+      #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+      def line(*args, **kwargs)
+        @options[:line] = kwargs.empty? ? args.first : kwargs
+      end
+
+      # Configures trendline for this series.
+      #
+      # @param args [Array] Positional arguments.
+      # @param kwargs [Hash] Keyword arguments.
+      # @return [Object]
+      # @api public
+      #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+      def trendline(*args, **kwargs)
+        @options[:trendline] = kwargs.empty? ? args.first : kwargs
+      end
+
+      # Configures data labels for this series.
+      #
+      # @param args [Array] Positional arguments.
+      # @param kwargs [Hash] Keyword arguments.
+      # @return [Object]
+      # @api public
+      #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+      def data_labels(*args, **kwargs)
+        @options[:data_labels] = kwargs.empty? ? args.first : kwargs
+      end
+
+      # Configures line smoothing for this series.
+      #
+      # @param args [Array] Positional arguments.
+      # @param kwargs [Hash] Keyword arguments.
+      # @return [Boolean, String]
+      # @api public
+      #: (*(bool | String) args, **String | Integer | bool | nil kwargs) -> (bool | String)
+      def smooth(*args, **kwargs)
+        @options[:smooth] = kwargs.empty? ? args.first : kwargs
+      end
+
+      # Configures 3D bar/column shape (e.g. "cylinder", "cone", "pyramid").
+      #
+      # @param args [Array] Positional arguments.
+      # @param kwargs [Hash] Keyword arguments.
+      # @return [String]
+      # @api public
+      #: (*(String) args, **String | Integer | bool | nil kwargs) -> String
+      def shape(*args, **kwargs)
+        @options[:shape] = kwargs.empty? ? args.first : kwargs
+      end
+
+      # Configures individual series chart type override in combo charts.
+      #
+      # @param args [Array] Positional arguments.
+      # @param kwargs [Hash] Keyword arguments.
+      # @return [String]
+      # @api public
+      #: (*(String) args, **String | Integer | bool | nil kwargs) -> String
+      def type(*args, **kwargs)
+        @options[:type] = kwargs.empty? ? args.first : kwargs
+      end
+    end
+  end
+end

data/lib/xlsxrb/elements/cell.rb

@@ -15,7 +15,9 @@ module Xlsxrb
     #   cell.to_date     # Date value
     #
     # @api public
-    Cell = Data.define(:row_index, :column_index, :value, :formula, :style_index, :unmapped_data, :errors) do
+    class Cell
+      attr_reader :row_index, :column_index, :value, :formula, :style_index, :unmapped_data, :errors
+
       # @param row_index [Integer] 0-based row index.
       # @param column_index [Integer] 0-based column index.
       # @param value [Object, nil] The cell's value.
@@ -23,12 +25,66 @@ module Xlsxrb
       # @param style_index [Integer, String, nil] Style identifier.
       # @param unmapped_data [Hash] Additional metadata.
       # @param errors [Array<String>, nil] Validation errors.
-      #: (row_index: Integer, column_index: Integer, ?value: untyped, ?formula: Elements::Formula?, ?style_index: Integer | String | nil, ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void
+      #: (row_index: untyped, column_index: untyped, ?value: untyped, ?formula: (Elements::Formula | String)?, ?style_index: (Integer | String)?, ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void
       def initialize(row_index:, column_index:, value: nil, formula: nil, style_index: nil, unmapped_data: EMPTY_HASH, errors: nil)
+        @row_index = row_index
+        @column_index = column_index
+        @value = value
+        @formula = formula
+        @style_index = style_index
+        @unmapped_data = unmapped_data || EMPTY_HASH
         computed_errors = errors || self.class.validate(row_index, column_index, value)
-        computed_errors = computed_errors.freeze unless computed_errors.frozen?
-        super(row_index: row_index, column_index: column_index, value: value, formula: formula,
-              style_index: style_index, unmapped_data: unmapped_data, errors: computed_errors)
+        @errors = computed_errors.frozen? ? computed_errors : computed_errors.freeze
+      end
+
+      def self.fast_create(row_index, column_index, value, style_index = nil, formula = nil)
+        inst = allocate
+        inst.instance_variable_set(:@row_index, row_index)
+        inst.instance_variable_set(:@column_index, column_index)
+        inst.instance_variable_set(:@value, value)
+        inst.instance_variable_set(:@formula, formula)
+        inst.instance_variable_set(:@style_index, style_index)
+        inst.instance_variable_set(:@unmapped_data, EMPTY_HASH)
+        inst.instance_variable_set(:@errors, EMPTY_ERRORS)
+        inst
+      end
+
+      def ==(other)
+        other.is_a?(Cell) &&
+          row_index == other.row_index &&
+          column_index == other.column_index &&
+          value == other.value &&
+          formula == other.formula &&
+          style_index == other.style_index &&
+          unmapped_data == other.unmapped_data &&
+          errors == other.errors
+      end
+      alias eql? ==
+
+      def hash
+        [row_index, column_index, value, formula, style_index, unmapped_data, errors].hash
+      end
+
+      def deconstruct
+        [row_index, column_index, value, formula, style_index, unmapped_data, errors]
+      end
+
+      def deconstruct_keys(keys)
+        h = { row_index: row_index, column_index: column_index, value: value, formula: formula,
+              style_index: style_index, unmapped_data: unmapped_data, errors: errors }
+        keys ? h.slice(*keys) : h
+      end
+
+      def with(**changes)
+        self.class.new(
+          row_index: changes.fetch(:row_index, row_index),
+          column_index: changes.fetch(:column_index, column_index),
+          value: changes.fetch(:value, value),
+          formula: changes.fetch(:formula, formula),
+          style_index: changes.fetch(:style_index, style_index),
+          unmapped_data: changes.fetch(:unmapped_data, unmapped_data),
+          errors: changes.fetch(:errors, errors)
+        )
       end
 
       # Returns whether the cell is valid according to OOXML specifications.
@@ -57,7 +113,8 @@ module Xlsxrb
       def [](key)
         case key
         when :value then value
-        when :formula then formula
+        when :formula
+          formula.is_a?(Formula) ? formula.expression : formula
         when :style_index then style_index
         when :ref then ref
         when :column_index then column_index
@@ -114,9 +171,8 @@ module Xlsxrb
       def to_date
         return value if value.is_a?(Date)
 
-        # Excel epoch is 1899-12-30
         if value.is_a?(Numeric)
-          Date.new(1899, 12, 30) + value.to_i
+          Ooxml::Utils.serial_to_date(value)
         else
           begin
             Date.parse(value.to_s)
@@ -135,9 +191,7 @@ module Xlsxrb
         return value if value.is_a?(Time)
 
         if value.is_a?(Numeric)
-          days = value.to_f
-          base_time = Time.utc(1899, 12, 30)
-          base_time + (days * 86_400)
+          Ooxml::Utils.serial_to_datetime(value)
         else
           begin
             Time.parse(value.to_s)
@@ -168,7 +222,7 @@ module Xlsxrb
       # @param index [Integer] 0-based column index.
       # @return [String] Excel column letter.
       # @api public
-      #: (Integer index) -> String
+      #: (untyped index) -> String
       def self.column_letter(index)
         raise ArgumentError, "Column index must be a non-negative Integer, got #{index.inspect}" unless index.is_a?(Integer) && index >= 0
 

data/lib/xlsxrb/elements/workbook.rb

@@ -131,10 +131,10 @@ module Xlsxrb
       # @example
       #   wb.save("output.xlsx")
       #
-      # @param filepath [String, IO] Destination file path or IO stream.
+      # @param filepath [String, IO, StringIO] Destination file path or IO stream.
       # @return [void]
       # @api public
-      #: (untyped filepath) -> void
+      #: (String | IO | StringIO filepath) -> void
       def save(filepath)
         Xlsxrb.write(filepath, self)
       end