heatmap-builder 0.1.0 → 0.2.0

data/examples/weekly_progress.svg

@@ -1,3 +1 @@
-<svg width="132" height="18" xmlns="http://www.w3.org/2000/svg">
-  <rect x="0" y="0" width="18" height="18" fill="#ebedf0"/><rect x="0.5" y="0.5" width="17" height="17" fill="none" stroke="#a4a5a8" stroke-width="1"/><text x="9" y="11.8" text-anchor="middle" font-family="Arial, sans-serif" font-size="8" fill="#000000">0</text><rect x="19" y="0" width="18" height="18" fill="#9be9a8"/><rect x="19.5" y="0.5" width="17" height="17" fill="none" stroke="#6ca375" stroke-width="1"/><text x="28" y="11.8" text-anchor="middle" font-family="Arial, sans-serif" font-size="8" fill="#000000">1</text><rect x="38" y="0" width="18" height="18" fill="#30a14e"/><rect x="38.5" y="0.5" width="17" height="17" fill="none" stroke="#217036" stroke-width="1"/><text x="47" y="11.8" text-anchor="middle" font-family="Arial, sans-serif" font-size="8" fill="#ffffff">3</text><rect x="57" y="0" width="18" height="18" fill="#40c463"/><rect x="57.5" y="0.5" width="17" height="17" fill="none" stroke="#2c8945" stroke-width="1"/><text x="66" y="11.8" text-anchor="middle" font-family="Arial, sans-serif" font-size="8" fill="#000000">2</text><rect x="76" y="0" width="18" height="18" fill="#216e39"/><rect x="76.5" y="0.5" width="17" height="17" fill="none" stroke="#174d27" stroke-width="1"/><text x="85" y="11.8" text-anchor="middle" font-family="Arial, sans-serif" font-size="8" fill="#ffffff">4</text><rect x="95" y="0" width="18" height="18" fill="#9be9a8"/><rect x="95.5" y="0.5" width="17" height="17" fill="none" stroke="#6ca375" stroke-width="1"/><text x="104" y="11.8" text-anchor="middle" font-family="Arial, sans-serif" font-size="8" fill="#000000">1</text><rect x="114" y="0" width="18" height="18" fill="#ebedf0"/><rect x="114.5" y="0.5" width="17" height="17" fill="none" stroke="#a4a5a8" stroke-width="1"/><text x="123" y="11.8" text-anchor="middle" font-family="Arial, sans-serif" font-size="8" fill="#000000">0</text>
-</svg>
+<svg width="132" height="18" xmlns="http://www.w3.org/2000/svg"><rect x="0" y="0" width="18" height="18" fill="#ebedf0"/><rect x="0.5" y="0.5" width="17" height="17" fill="none" stroke="#ccced1" stroke-width="1"/><text x="9" y="11.8" text-anchor="middle" font-family="Arial, sans-serif" font-size="8" fill="#000000">0</text><rect x="19" y="0" width="18" height="18" fill="#9be9a8"/><rect x="19.5" y="0.5" width="17" height="17" fill="none" stroke="#7fcc8d" stroke-width="1"/><text x="28" y="11.8" text-anchor="middle" font-family="Arial, sans-serif" font-size="8" fill="#000000">1</text><rect x="38" y="0" width="18" height="18" fill="#30a14e"/><rect x="38.5" y="0.5" width="17" height="17" fill="none" stroke="#108d3b" stroke-width="1"/><text x="47" y="11.8" text-anchor="middle" font-family="Arial, sans-serif" font-size="8" fill="#000000">3</text><rect x="57" y="0" width="18" height="18" fill="#40c463"/><rect x="57.5" y="0.5" width="17" height="17" fill="none" stroke="#1dac4d" stroke-width="1"/><text x="66" y="11.8" text-anchor="middle" font-family="Arial, sans-serif" font-size="8" fill="#000000">2</text><rect x="76" y="0" width="18" height="18" fill="#216e39"/><rect x="76.5" y="0.5" width="17" height="17" fill="none" stroke="#0d602c" stroke-width="1"/><text x="85" y="11.8" text-anchor="middle" font-family="Arial, sans-serif" font-size="8" fill="#000000">4</text><rect x="95" y="0" width="18" height="18" fill="#9be9a8"/><rect x="95.5" y="0.5" width="17" height="17" fill="none" stroke="#7fcc8d" stroke-width="1"/><text x="104" y="11.8" text-anchor="middle" font-family="Arial, sans-serif" font-size="8" fill="#000000">1</text><rect x="114" y="0" width="18" height="18" fill="#ebedf0"/><rect x="114.5" y="0.5" width="17" height="17" fill="none" stroke="#ccced1" stroke-width="1"/><text x="123" y="11.8" text-anchor="middle" font-family="Arial, sans-serif" font-size="8" fill="#000000">0</text></svg>

data/heatmap-builder.gemspec

@@ -40,4 +40,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "minitest", "~> 5.0"
   spec.add_development_dependency "standard", "~> 1.0"
+  spec.add_development_dependency "simplecov", "~> 0.22"
 end

data/lib/heatmap-builder.rb

@@ -1,15 +1,59 @@
 require_relative "heatmap_builder/version"
+require_relative "heatmap_builder/svg_helpers"
+require_relative "heatmap_builder/color_helpers"
+require_relative "heatmap_builder/value_conversion"
+require_relative "heatmap_builder/builder"
 require_relative "heatmap_builder/linear_heatmap_builder"
 require_relative "heatmap_builder/calendar_heatmap_builder"
 
 module HeatmapBuilder
   class Error < StandardError; end
 
+  GITHUB_GREEN = Builder::GITHUB_GREEN
+  BLUE_OCEAN = Builder::BLUE_OCEAN
+  WARM_SUNSET = Builder::WARM_SUNSET
+  PURPLE_VIBES = Builder::PURPLE_VIBES
+  RED_TO_GREEN = Builder::RED_TO_GREEN
+
+  # Builds a linear (single-row) heatmap visualization.
+  #
+  # @param scores [Array<Integer>, nil] Pre-calculated score values (0 to num_colors-1). Required unless values provided.
+  # @param values [Array<Numeric>, nil] Raw numeric values to be mapped to scores. Required unless scores provided.
+  # @param options [Hash] Customization options
+  # @return [String] SVG markup
+  # @see https://github.com/dreikanter/heatmap-builder#linear-heatmaps Full documentation
+  # @example
+  #   HeatmapBuilder.build_linear(scores: [0, 1, 2, 3, 4])
+  #   HeatmapBuilder.build_linear(values: [10, 25, 50, 75, 100], value_min: 0, value_max: 100)
+  def self.build_linear(scores: nil, values: nil, **options)
+    LinearHeatmapBuilder.new(scores: scores, values: values, **options).build
+  end
+
+  # Builds a calendar (GitHub-style) heatmap visualization.
+  #
+  # @param scores [Hash<Date, Integer>, Hash<String, Integer>, nil] Pre-calculated score values by date. Required unless values provided.
+  # @param values [Hash<Date, Numeric>, Hash<String, Numeric>, nil] Raw numeric values by date. Required unless scores provided.
+  # @param options [Hash] Customization options
+  # @return [String] SVG markup
+  # @see https://github.com/dreikanter/heatmap-builder#calendar-heatmaps Full documentation
+  # @example
+  #   HeatmapBuilder.build_calendar(scores: { '2024-01-01' => 2, '2024-01-02' => 4 })
+  #   HeatmapBuilder.build_calendar(values: { Date.new(2024, 1, 1) => 45.2 })
+  def self.build_calendar(scores: nil, values: nil, **options)
+    CalendarHeatmapBuilder.new(scores: scores, values: values, **options).build
+  end
+
+  # @deprecated Use {.build_linear} instead
   def self.generate(scores, options = {})
-    LinearHeatmapBuilder.new(scores, options).generate
+    warn "[DEPRECATION] `HeatmapBuilder.generate(scores, options)` is deprecated and will be removed in v1.0.0. " \
+         "Use `HeatmapBuilder.build_linear(scores: scores, **options)` instead."
+    build_linear(scores: scores, **options)
   end
 
-  def self.generate_calendar(scores_by_date, options = {})
-    CalendarHeatmapBuilder.new(scores_by_date, options).generate
+  # @deprecated Use {.build_calendar} instead
+  def self.generate_calendar(scores, options = {})
+    warn "[DEPRECATION] `HeatmapBuilder.generate_calendar(scores_by_date, options)` is deprecated and will be removed in v1.0.0. " \
+         "Use `HeatmapBuilder.build_calendar(scores: scores_by_date, **options)` instead."
+    build_calendar(scores: scores, **options)
   end
 end

data/lib/heatmap_builder/builder.rb

@@ -0,0 +1,100 @@
+require_relative "svg_helpers"
+require_relative "color_helpers"
+
+module HeatmapBuilder
+  class Builder
+    include SvgHelpers
+    include ColorHelpers
+
+    GITHUB_GREEN = %w[#ebedf0 #9be9a8 #40c463 #30a14e #216e39].freeze
+    BLUE_OCEAN = %w[#f0f9ff #bae6fd #7dd3fc #38bdf8 #0ea5e9].freeze
+    WARM_SUNSET = %w[#fef3e2 #fed7aa #fdba74 #fb923c #f97316].freeze
+    PURPLE_VIBES = %w[#f3e8ff #d8b4fe #c084fc #a855f7 #9333ea].freeze
+    RED_TO_GREEN = %w[#f5f5f5 #ff9999 #f7ad6a #d2c768 #99dd99].freeze
+
+    DEFAULT_OPTIONS = {
+      cell_size: 10,
+      cell_spacing: 1,
+      font_size: 8,
+      border_width: 1,
+      corner_radius: 0,
+      colors: GITHUB_GREEN,
+      text_color: "#000000"
+    }.freeze
+
+    def initialize(scores: nil, values: nil, **options)
+      @scores = scores
+      @values = values
+      @options = default_options.merge(options)
+      validate_options!
+      normalize_options!
+    end
+
+    def build
+      raise NotImplementedError, "Subclasses must implement #build"
+    end
+
+    private
+
+    attr_reader :scores, :values, :options
+
+    def normalize_options!
+      max_radius = (options[:cell_size] / 2.0).floor
+      @options[:corner_radius] = options[:corner_radius].clamp(0, max_radius)
+    end
+
+    # Override in subclasses to add specific validations by calling super first
+    def validate_options!
+      raise Error, "cell_size must be positive" unless options[:cell_size].positive?
+      raise Error, "font_size must be positive" unless options[:font_size].positive?
+      validate_colors_option!
+      validate_scores_or_values!
+      validate_value_boundaries! if values
+    end
+
+    def validate_scores_or_values!
+      if scores && values
+        raise Error, "cannot provide both scores and values"
+      end
+
+      unless scores || values
+        raise Error, "must provide either scores or values"
+      end
+    end
+
+    def validate_value_boundaries!
+      return unless options[:value_min] && options[:value_max]
+      return unless options[:value_min] > options[:value_max]
+      raise Error, "value_min must be less than or equal to value_max"
+    end
+
+    def validate_colors_option!
+      colors = options[:colors]
+
+      if colors.is_a?(Array)
+        raise Error, "must have at least 2 colors" unless colors.length >= 2
+      elsif colors.is_a?(Hash)
+        raise Error, "colors hash must have from, to, and steps keys" unless colors.key?(:from) && colors.key?(:to) && colors.key?(:steps)
+        raise Error, "steps must be a number" unless colors[:steps].is_a?(Integer)
+        raise Error, "steps must be at least 2" unless colors[:steps] >= 2
+      else
+        raise Error, "colors must be an array or hash with from/to/steps"
+      end
+    end
+
+    def default_options
+      DEFAULT_OPTIONS
+    end
+
+    def color_palette
+      @color_palette ||= begin
+        colors_option = options[:colors]
+        if colors_option.is_a?(Hash)
+          generate_color_palette(colors_option[:from], colors_option[:to], colors_option[:steps])
+        else
+          colors_option
+        end
+      end
+    end
+  end
+end

data/lib/heatmap_builder/calendar_heatmap_builder.rb

@@ -1,79 +1,102 @@
 require "date"
+require_relative "builder"
+require_relative "value_conversion"
 
 module HeatmapBuilder
-  class CalendarHeatmapBuilder
-    DEFAULT_OPTIONS = {
-      cell_size: 12,
-      cell_spacing: 1,
-      font_size: 8,
-      border_width: 1,
-      colors: %w[#ebedf0 #9be9a8 #40c463 #30a14e #216e39],
-      start_of_week: :monday, # :sunday, :monday, :tuesday, etc.
-      month_spacing: 5, # extra vertical space between months
-      show_month_labels: true,
-      show_day_labels: true,
-      show_outside_cells: false # show cells outside the timeframe with inactive styling
+  class CalendarHeatmapBuilder < Builder
+    include ValueConversion
+
+    VALID_START_DAYS = %i[sunday monday tuesday wednesday thursday friday saturday].freeze
+
+    WEEK_START_WDAY = {
+      sunday: 0,
+      monday: 1,
+      tuesday: 2,
+      wednesday: 3,
+      thursday: 4,
+      friday: 5,
+      saturday: 6
     }.freeze
 
-    def initialize(scores_by_date, options = {})
-      @scores_by_date = scores_by_date
-      @options = DEFAULT_OPTIONS.merge(options)
-      validate_options!
-      @start_date = parse_date_range.first
-      @end_date = parse_date_range.last
-    end
+    def build
+      svg_content = []
+
+      if options[:show_day_labels]
+        svg_content << day_labels_svg
+      end
+
+      svg_content << calendar_cells_svg
+
+      if options[:show_month_labels]
+        svg_content << month_labels_svg
+      end
 
-    def generate
-      build_svg
+      weeks_count = ((calendar_end_date_with_full_weeks - calendar_start_date) / 7).ceil
+      month_spacing_total = (months_in_range - 1) * options[:month_spacing]
+
+      cell_size_with_spacing = options[:cell_size] + options[:cell_spacing]
+      width = dow_label_offset + weeks_count * cell_size_with_spacing + month_spacing_total
+      height = month_label_offset + 7 * cell_size_with_spacing
+
+      svg_container(width: width, height: height) { svg_content.join }
     end
 
     private
 
-    attr_reader :scores_by_date, :options, :start_date, :end_date
+    def start_date
+      @start_date ||= parsed_date_range.first
+    end
 
-    def validate_options!
-      raise Error, "scores_by_date must be a hash" unless scores_by_date.is_a?(Hash)
-      raise Error, "cell_size must be positive" unless options[:cell_size] > 0
-      raise Error, "font_size must be positive" unless options[:font_size] > 0
-      raise Error, "colors must be an array" unless options[:colors].is_a?(Array)
-      raise Error, "must have at least 2 colors" unless options[:colors].length >= 2
-
-      valid_start_days = %i[sunday monday tuesday wednesday thursday friday saturday]
-      unless valid_start_days.include?(options[:start_of_week])
-        raise Error, "start_of_week must be one of: #{valid_start_days.join(", ")}"
-      end
+    def end_date
+      @end_date ||= parsed_date_range.last
     end
 
-    def parse_date_range
-      dates = scores_by_date.keys.map { |d| d.is_a?(Date) ? d : Date.parse(d.to_s) }
-      return [Date.today - 365, Date.today] if dates.empty?
+    def validate_options!
+      super
+
+      raise Error, "scores must be a hash" if scores && !scores.is_a?(Hash)
+      raise Error, "values must be a hash" if values && !values.is_a?(Hash)
 
-      [dates.min, dates.max]
+      unless VALID_START_DAYS.include?(options[:start_of_week])
+        raise Error, "start_of_week must be one of: #{VALID_START_DAYS.join(", ")}"
+      end
     end
 
-    def build_svg
-      width = svg_width
-      height = svg_height
+    def scores_by_date
+      @scores_by_date ||= if scores
+        scores
+      else
+        result = {}
+        current_date = start_date
 
-      svg_content = []
+        while current_date <= end_date
+          value = values[current_date] || values[current_date.to_s]
+          result[current_date] = convert_value_to_score(value, date: current_date)
+          current_date += 1
+        end
 
-      # Add day labels if enabled
-      if options[:show_day_labels]
-        svg_content << day_labels_svg
+        result
       end
+    end
 
-      # Add month labels and cells
-      svg_content << calendar_cells_svg
+    def calculated_min_from_values
+      non_nil_values = values.values.compact
+      non_nil_values.empty? ? 0 : non_nil_values.min
+    end
 
-      if options[:show_month_labels]
-        svg_content << month_labels_svg
-      end
+    def calculated_max_from_values
+      non_nil_values = values.values.compact
+      non_nil_values.empty? ? 0 : non_nil_values.max
+    end
+
+    def parsed_date_range
+      @parsed_date_range ||= begin
+        data_keys = (scores || values || {}).keys
+        dates = data_keys.map { |d| d.is_a?(Date) ? d : Date.parse(d.to_s) }
+        return [Date.today - 365, Date.today] if dates.empty?
 
-      <<~SVG
-        <svg width="#{width}" height="#{height}" xmlns="http://www.w3.org/2000/svg">
-          #{svg_content.join}
-        </svg>
-      SVG
+        [dates.min, dates.max]
+      end
     end
 
     def calendar_cells_svg
@@ -93,8 +116,8 @@ module HeatmapBuilder
 
         # Generate week column - always fill all 7 days
         7.times do |day_index|
-          x = label_offset + week_index * (options[:cell_size] + options[:cell_spacing]) + current_x_offset
-          y = day_label_offset + day_index * (options[:cell_size] + options[:cell_spacing])
+          x = dow_label_offset + week_index * (options[:cell_size] + options[:cell_spacing]) + current_x_offset
+          y = month_label_offset + day_index * (options[:cell_size] + options[:cell_spacing])
 
           if current_date.between?(start_date, end_date)
             # Active cell within the specified timeframe
@@ -115,27 +138,25 @@ module HeatmapBuilder
     end
 
     def cell_svg(score, x, y, inactive = false)
-      color = score_to_color(score)
+      color = score_to_color(score, colors: color_palette)
 
-      # Make inactive cells duller by reducing opacity
       if inactive
         color = make_color_inactive(color)
       end
 
-      # Create colored square
-      colored_rect = "<rect x=\"#{x}\" y=\"#{y}\" width=\"#{options[:cell_size]}\" height=\"#{options[:cell_size]}\" fill=\"#{color}\"/>"
-
-      # Create border overlay
-      border_rect = if options[:border_width] > 0
-        inset = options[:border_width] / 2.0
-        border_x = x + inset
-        border_y = y + inset
-        border_size = options[:cell_size] - options[:border_width]
-        border_color = darker_color(color)
-        "<rect x=\"#{border_x}\" y=\"#{border_y}\" width=\"#{border_size}\" height=\"#{border_size}\" fill=\"none\" stroke=\"#{border_color}\" stroke-width=\"#{options[:border_width]}\"/>"
-      else
-        ""
-      end
+      colored_rect = svg_rect(
+        x: x, y: y,
+        width: options[:cell_size], height: options[:cell_size],
+        rx: options[:corner_radius],
+        fill: color
+      )
+
+      border_rect = cell_border(
+        x, y, color,
+        cell_size: options[:cell_size],
+        border_width: options[:border_width],
+        corner_radius: options[:corner_radius]
+      )
 
       "#{colored_rect}#{border_rect}"
     end
@@ -147,8 +168,12 @@ module HeatmapBuilder
       svg = ""
 
       day_names.each_with_index do |day_name, index|
-        y = day_label_offset + index * (options[:cell_size] + options[:cell_spacing]) + options[:cell_size] / 2 + options[:font_size] * 0.35
-        svg << "<text x=\"#{options[:font_size]}\" y=\"#{y}\" text-anchor=\"middle\" font-family=\"Arial, sans-serif\" font-size=\"#{options[:font_size]}\" fill=\"#666666\">#{day_name}</text>"
+        y = month_label_offset + index * (options[:cell_size] + options[:cell_spacing]) + options[:cell_size] / 2 + options[:font_size] * 0.35
+        svg << svg_text(
+          day_name,
+          x: options[:font_size], y: y,
+          font_size: options[:font_size], fill: "#666666"
+        )
       end
 
       svg
@@ -158,138 +183,128 @@ module HeatmapBuilder
       return "" unless options[:show_month_labels]
 
       svg = ""
-      current_date = calendar_start_date
-      week_index = 0
       last_month = nil
-      displayed_months = {}
-      current_x_offset = 0
-      calendar_end_date = calendar_end_date_with_full_weeks
-
-      while current_date <= calendar_end_date
-        # Check if we need to add month spacing
-        if current_date.month != last_month && !last_month.nil?
-          current_x_offset += options[:month_spacing]
-        end
 
-        # Add month label at start of each month, but only if the month overlaps with our specified timeframe
-        if current_date.month != last_month && !displayed_months[current_date.month]
-          # Check if this month has any days within our specified timeframe
-          month_start = Date.new(current_date.year, current_date.month, 1)
-          month_end = Date.new(current_date.year, current_date.month, -1)
-
-          if month_start <= end_date && month_end >= start_date
-            x = label_offset + week_index * (options[:cell_size] + options[:cell_spacing]) + current_x_offset
-            y = options[:font_size] + 2
-            month_name = current_date.strftime("%b")
-            svg << "<text x=\"#{x}\" y=\"#{y}\" font-family=\"Arial, sans-serif\" font-size=\"#{options[:font_size]}\" fill=\"#666666\">#{month_name}</text>"
-          end
+      each_week do |current_date, _week_index|
+        current_month = [current_date.year, current_date.month]
 
-          displayed_months[current_date.month] = true
+        if current_month != last_month && month_overlaps_timeframe?(current_date)
+          svg << render_month_label(current_date)
+          last_month = current_month
         end
-
-        last_month = current_date.month
-        current_date += 7
-        week_index += 1
       end
 
       svg
     end
 
-    def score_to_color(score)
-      return options[:colors].first if score == 0
+    def month_overlaps_timeframe?(current_date)
+      month_start = Date.new(current_date.year, current_date.month, 1)
+      month_end = Date.new(current_date.year, current_date.month, -1)
+
+      month_start <= end_date && month_end >= start_date
+    end
+
+    def render_month_label(current_date)
+      first_day_of_month = Date.new(current_date.year, current_date.month, 1)
+      month_name = options[:month_labels][current_date.month - 1]
+
+      svg_text(
+        month_name,
+        x: calculate_month_label_x(first_day_of_month),
+        y: calculate_month_label_y,
+        text_anchor: "start", font_family: "Arial, sans-serif", font_size: options[:font_size], fill: "#666666"
+      )
+    end
+
+    def calculate_month_label_y
+      options[:font_size] * 1.25
+    end
+
+    def calculate_month_label_x(first_day_of_month)
+      days_from_start = (first_day_of_month - calendar_start_date).to_i
+      week_index = days_from_start / 7
+      x_offset = calculate_x_offset_for_week(week_index)
 
-      max_color_index = options[:colors].length - 1
-      color_index = 1 + (score - 1) % max_color_index
-      options[:colors][color_index]
+      dow_label_offset + week_index * (options[:cell_size] + options[:cell_spacing]) + x_offset + options[:cell_size] * 0.1
     end
 
-    def darker_color(hex_color)
-      hex = hex_color.delete("#")
-      r = hex[0..1].to_i(16)
-      g = hex[2..3].to_i(16)
-      b = hex[4..5].to_i(16)
+    def calculate_x_offset_for_week(target_week_index)
+      x_offset = 0
+      last_month = nil
+
+      each_week do |current_date, week_index|
+        break if week_index >= target_week_index
 
-      # Much more subtle border - only 10% darker instead of 30%
-      r = (r * 0.9).to_i
-      g = (g * 0.9).to_i
-      b = (b * 0.9).to_i
+        if current_date.month != last_month && !last_month.nil?
+          x_offset += options[:month_spacing]
+        end
+
+        last_month = current_date.month
+      end
 
-      "#%02x%02x%02x" % [r, g, b]
+      x_offset
     end
 
+    def each_week
+      current_date = calendar_start_date
+      week_index = 0
+
+      while current_date <= calendar_end_date_with_full_weeks
+        yield current_date, week_index
+
+        current_date += 7
+        week_index += 1
+      end
+    end
+
+    # Find the start of the week containing start_date
     def calendar_start_date
-      # Find the start of the week containing start_date
       days_back = (start_date.wday - week_start_wday) % 7
       start_date - days_back
     end
 
+    # Find the end of the week containing end_date
     def calendar_end_date_with_full_weeks
-      # Find the end of the week containing end_date
       days_forward = (6 - (end_date.wday - week_start_wday)) % 7
       end_date + days_forward
     end
 
-    def make_color_inactive(hex_color)
-      # Make color duller by reducing saturation and increasing lightness
-      hex = hex_color.delete("#")
-      r = hex[0..1].to_i(16)
-      g = hex[2..3].to_i(16)
-      b = hex[4..5].to_i(16)
-
-      # Blend with light gray to make it appear duller/inactive
-      gray = 230
-      mix_ratio = 0.6 # 60% original color, 40% gray
-
-      r = (r * mix_ratio + gray * (1 - mix_ratio)).to_i
-      g = (g * mix_ratio + gray * (1 - mix_ratio)).to_i
-      b = (b * mix_ratio + gray * (1 - mix_ratio)).to_i
-
-      "#%02x%02x%02x" % [r, g, b]
-    end
-
     def week_start_wday
-      case options[:start_of_week]
-      when :sunday then 0
-      when :monday then 1
-      when :tuesday then 2
-      when :wednesday then 3
-      when :thursday then 4
-      when :friday then 5
-      when :saturday then 6
-      end
+      WEEK_START_WDAY[options[:start_of_week]]
     end
 
     def day_names_for_week_start
-      all_days = %w[S M T W T F S]
       start_index = week_start_wday
-      all_days.rotate(start_index)
+      options[:day_labels].rotate(start_index)
     end
 
     def month_spacing_weeks
       options[:month_spacing] / (options[:cell_size] + options[:cell_spacing])
     end
 
-    def label_offset
+    def dow_label_offset
       options[:show_day_labels] ? options[:font_size] * 2 : 0
     end
 
-    def day_label_offset
-      options[:show_month_labels] ? options[:font_size] + 5 : 0
-    end
-
-    def svg_width
-      weeks_count = ((calendar_end_date_with_full_weeks - calendar_start_date) / 7).ceil
-      month_spacing_total = (months_in_range - 1) * options[:month_spacing]
-
-      label_offset + weeks_count * (options[:cell_size] + options[:cell_spacing]) + month_spacing_total
-    end
-
-    def svg_height
-      day_label_offset + 7 * (options[:cell_size] + options[:cell_spacing])
+    def month_label_offset
+      options[:show_month_labels] ? options[:font_size] * 1.625 : 0
     end
 
     def months_in_range
       ((end_date.year - start_date.year) * 12 + end_date.month - start_date.month + 1)
     end
+
+    def default_options
+      DEFAULT_OPTIONS.merge({
+        cell_size: 12,
+        start_of_week: :monday,
+        month_spacing: 5, # extra horizontal space between months
+        show_month_labels: true,
+        show_day_labels: true,
+        show_outside_cells: false, # show cells outside the timeframe with inactive styling
+        day_labels: %w[S M T W T F S], # day abbreviations starting from Sunday
+        month_labels: %w[Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec] # month abbreviations
+      })
+    end
   end
 end