heatmap-builder 0.1.0 → 0.4.3

data/lib/heatmap_builder/value_conversion.rb

@@ -0,0 +1,68 @@
+module HeatmapBuilder
+  module ValueConversion
+    private
+
+    def value_min
+      @value_min ||= options[:value_min] || calculated_min_from_values
+    end
+
+    def value_max
+      @value_max ||= options[:value_max] || calculated_max_from_values
+    end
+
+    def calculated_min_from_values
+      raise NotImplementedError, "Subclasses must implement #calculated_min_from_values"
+    end
+
+    def calculated_max_from_values
+      raise NotImplementedError, "Subclasses must implement #calculated_max_from_values"
+    end
+
+    def color_count
+      @color_count ||= begin
+        colors_option = options[:colors]
+        if colors_option.is_a?(Array)
+          colors_option.length
+        elsif colors_option.is_a?(Hash)
+          colors_option[:steps]
+        else
+          raise Error, "colors must be an array or hash"
+        end
+      end
+    end
+
+    def convert_value_to_score(value, **params)
+      if options[:value_to_score]
+        score = options[:value_to_score].call(
+          value: value.nil? ? value_min : value,
+          min: value_min,
+          max: value_max,
+          max_score: color_count - 1,
+          **params
+        )
+
+        unless score.is_a?(Integer) && score >= 0 && score < color_count
+          raise Error, "value_to_score must return an integer between 0 and #{color_count - 1}, got #{score.inspect}"
+        end
+
+        return score
+      end
+
+      # Score 0 is reserved for empty cells (zero or missing values). Any
+      # non-zero value maps into 1..max_score so even the smallest activity is
+      # visibly distinct from an empty day.
+      return 0 if value.nil? || value.zero?
+
+      max_score = color_count - 1
+      clamped_value = value.clamp(value_min, value_max)
+
+      if value_min == value_max
+        max_score
+      else
+        range = value_max - value_min
+        normalized = (clamped_value - value_min).to_f / range
+        1 + (normalized * (max_score - 1)).round
+      end
+    end
+  end
+end

data/lib/heatmap_builder/version.rb

@@ -1,3 +1,3 @@
 module HeatmapBuilder
-  VERSION = "0.1.0"
+  VERSION = "0.4.3"
 end

metadata

@@ -1,55 +1,55 @@
 --- !ruby/object:Gem::Specification
 name: heatmap-builder
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.4.3
 platform: ruby
 authors:
 - Alex Musayev
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-19 00:00:00.000000000 Z
+date: 2026-06-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '13.0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '5.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '5.0'
 - !ruby/object:Gem::Dependency
@@ -66,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
 description: A Ruby gem that generates embeddable GitHub-style heatmap visualization
   in SVG format.
 email:
@@ -85,19 +99,28 @@ files:
 - README.md
 - Rakefile
 - bin/console
+- bin/generate_examples
 - bin/setup
+- examples/calendar_blue_ocean.svg
+- examples/calendar_cell_borders.svg
+- examples/calendar_default.svg
 - examples/calendar_github_style.svg
+- examples/calendar_month_spacing_rounded.svg
+- examples/calendar_no_borders.svg
+- examples/calendar_purple_vibes.svg
+- examples/calendar_red_to_green.svg
+- examples/calendar_rounded_corners.svg
+- examples/calendar_rounded_corners_max_radius.svg
 - examples/calendar_sunday_start.svg
+- examples/calendar_warm_sunset.svg
 - examples/calendar_with_outside_cells.svg
-- examples/generate_samples.rb
-- examples/large_cells.svg
-- examples/weekly_progress.svg
 - heatmap-builder.gemspec
 - lib/heatmap-builder.rb
-- lib/heatmap_builder/calendar_heatmap_builder.rb
-- lib/heatmap_builder/linear_heatmap_builder.rb
+- lib/heatmap_builder/calendar.rb
+- lib/heatmap_builder/color_helpers.rb
+- lib/heatmap_builder/svg_helpers.rb
+- lib/heatmap_builder/value_conversion.rb
 - lib/heatmap_builder/version.rb
-- mise.toml
 homepage: https://github.com/dreikanter/heatmap-builder
 licenses:
 - MIT
@@ -114,7 +137,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/examples/generate_samples.rb

@@ -1,114 +0,0 @@
-#!/usr/bin/env ruby
-
-require "date"
-$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
-require "heatmap-builder"
-
-def generate_sample_svgs
-  # Create examples directory for SVG files
-  Dir.mkdir("examples") unless Dir.exist?("examples")
-
-  generated_files = []
-
-  # Basic weekly progress
-  puts "Generating basic weekly progress..."
-  weekly_scores = [0, 1, 3, 2, 4, 1, 0]
-  svg = HeatmapBuilder.generate(weekly_scores, cell_size: 18)
-  filepath = "examples/weekly_progress.svg"
-  File.write(filepath, svg)
-  generated_files << filepath
-
-  # Large cells example
-  puts "Generating large cells example..."
-  large_cell_scores = [1, 2, 3, 4, 5, 6, 7]
-  svg = HeatmapBuilder.generate(large_cell_scores, {
-    cell_size: 35,
-    cell_spacing: 1,
-    font_size: 20
-  })
-  filepath = "examples/large_cells.svg"
-  File.write(filepath, svg)
-  generated_files << filepath
-
-  # GitHub-style calendar
-  puts "Generating GitHub-style calendar..."
-  calendar_data = sample_calendar_data
-  svg = HeatmapBuilder.generate_calendar(calendar_data, {
-    cell_size: 14,
-    month_spacing: 0
-  })
-  filepath = "examples/calendar_github_style.svg"
-  File.write(filepath, svg)
-  generated_files << filepath
-
-  # Calendar with Sunday start
-  puts "Generating calendar with Sunday start..."
-  svg = HeatmapBuilder.generate_calendar(calendar_data, {
-    cell_size: 14,
-    start_of_week: :sunday,
-    month_spacing: 0
-  })
-  filepath = "examples/calendar_sunday_start.svg"
-  File.write(filepath, svg)
-  generated_files << filepath
-
-  # Calendar with outside cells
-  puts "Generating calendar with outside cells..."
-  svg = HeatmapBuilder.generate_calendar(calendar_data, {
-    cell_size: 14,
-    show_outside_cells: true,
-    month_spacing: 0
-  })
-  filepath = "examples/calendar_with_outside_cells.svg"
-  File.write(filepath, svg)
-  generated_files << filepath
-
-  puts "\n✅ Sample SVG files generated successfully!"
-  puts "📁 Generated files:"
-  generated_files.each do |file|
-    puts "   - #{file}"
-  end
-  puts "📂 Total files: #{generated_files.length}"
-end
-
-def sample_calendar_data
-  # Generate sample data for a full year
-  end_date = Date.today
-  start_date = Date.new(end_date.year, 1, 1)
-
-  data = {}
-  current_date = start_date
-
-  while current_date <= end_date
-    # Create some realistic activity patterns with seasonal variation
-    base_activity = case current_date.month
-    when 1, 2, 12 # Winter - lower activity
-      [0, 0, 0, 1, 1, 2]
-    when 3, 4, 5 # Spring - increasing activity
-      [0, 1, 1, 2, 2, 3, 3]
-    when 6, 7, 8 # Summer - peak activity
-      [1, 2, 2, 3, 3, 4, 4, 5]
-    when 9, 10, 11 # Fall - moderate activity
-      [0, 1, 2, 2, 3, 3]
-    end
-
-    # Weekend vs weekday patterns
-    score = case current_date.wday
-    when 0, 6 # Weekend - reduced activity
-      ([0, 0] + base_activity.take(3)).sample
-    else # Weekday - normal patterns
-      base_activity.sample
-    end
-
-    data[current_date.to_s] = score
-
-    current_date += 1
-  end
-
-  data
-end
-
-# Run the generator
-if __FILE__ == $0
-  generate_sample_svgs
-end

data/examples/large_cells.svg

@@ -1,3 +0,0 @@
-<svg width="251" height="35" xmlns="http://www.w3.org/2000/svg">
-  <rect x="0" y="0" width="35" height="35" fill="#9be9a8"/><rect x="0.5" y="0.5" width="34" height="34" fill="none" stroke="#6ca375" stroke-width="1"/><text x="17" y="24.0" text-anchor="middle" font-family="Arial, sans-serif" font-size="20" fill="#000000">1</text><rect x="36" y="0" width="35" height="35" fill="#40c463"/><rect x="36.5" y="0.5" width="34" height="34" fill="none" stroke="#2c8945" stroke-width="1"/><text x="53" y="24.0" text-anchor="middle" font-family="Arial, sans-serif" font-size="20" fill="#000000">2</text><rect x="72" y="0" width="35" height="35" fill="#30a14e"/><rect x="72.5" y="0.5" width="34" height="34" fill="none" stroke="#217036" stroke-width="1"/><text x="89" y="24.0" text-anchor="middle" font-family="Arial, sans-serif" font-size="20" fill="#ffffff">3</text><rect x="108" y="0" width="35" height="35" fill="#216e39"/><rect x="108.5" y="0.5" width="34" height="34" fill="none" stroke="#174d27" stroke-width="1"/><text x="125" y="24.0" text-anchor="middle" font-family="Arial, sans-serif" font-size="20" fill="#ffffff">4</text><rect x="144" y="0" width="35" height="35" fill="#9be9a8"/><rect x="144.5" y="0.5" width="34" height="34" fill="none" stroke="#6ca375" stroke-width="1"/><text x="161" y="24.0" text-anchor="middle" font-family="Arial, sans-serif" font-size="20" fill="#000000">5</text><rect x="180" y="0" width="35" height="35" fill="#40c463"/><rect x="180.5" y="0.5" width="34" height="34" fill="none" stroke="#2c8945" stroke-width="1"/><text x="197" y="24.0" text-anchor="middle" font-family="Arial, sans-serif" font-size="20" fill="#000000">6</text><rect x="216" y="0" width="35" height="35" fill="#30a14e"/><rect x="216.5" y="0.5" width="34" height="34" fill="none" stroke="#217036" stroke-width="1"/><text x="233" y="24.0" text-anchor="middle" font-family="Arial, sans-serif" font-size="20" fill="#ffffff">7</text>
-</svg>

data/examples/weekly_progress.svg

@@ -1,3 +0,0 @@
-<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>

data/lib/heatmap_builder/calendar_heatmap_builder.rb

@@ -1,295 +0,0 @@
-require "date"
-
-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
-    }.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 generate
-      build_svg
-    end
-
-    private
-
-    attr_reader :scores_by_date, :options, :start_date, :end_date
-
-    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
-    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?
-
-      [dates.min, dates.max]
-    end
-
-    def build_svg
-      width = svg_width
-      height = svg_height
-
-      svg_content = []
-
-      # Add day labels if enabled
-      if options[:show_day_labels]
-        svg_content << day_labels_svg
-      end
-
-      # Add month labels and cells
-      svg_content << calendar_cells_svg
-
-      if options[:show_month_labels]
-        svg_content << month_labels_svg
-      end
-
-      <<~SVG
-        <svg width="#{width}" height="#{height}" xmlns="http://www.w3.org/2000/svg">
-          #{svg_content.join}
-        </svg>
-      SVG
-    end
-
-    def calendar_cells_svg
-      svg = ""
-      current_date = calendar_start_date
-      week_index = 0
-      last_month = nil
-      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
-        last_month = current_date.month
-
-        # 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])
-
-          if current_date.between?(start_date, end_date)
-            # Active cell within the specified timeframe
-            score = scores_by_date[current_date] || scores_by_date[current_date.to_s] || 0
-            svg << cell_svg(score, x, y, false)
-          elsif options[:show_outside_cells]
-            # Inactive cell outside the specified timeframe
-            svg << cell_svg(0, x, y, true)
-          end
-
-          current_date += 1
-        end
-
-        week_index += 1
-      end
-
-      svg
-    end
-
-    def cell_svg(score, x, y, inactive = false)
-      color = score_to_color(score)
-
-      # 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}#{border_rect}"
-    end
-
-    def day_labels_svg
-      return "" unless options[:show_day_labels]
-
-      day_names = day_names_for_week_start
-      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>"
-      end
-
-      svg
-    end
-
-    def month_labels_svg
-      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
-
-          displayed_months[current_date.month] = true
-        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
-
-      max_color_index = options[:colors].length - 1
-      color_index = 1 + (score - 1) % max_color_index
-      options[:colors][color_index]
-    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)
-
-      # 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
-
-      "#%02x%02x%02x" % [r, g, b]
-    end
-
-    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
-
-    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
-    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)
-    end
-
-    def month_spacing_weeks
-      options[:month_spacing] / (options[:cell_size] + options[:cell_spacing])
-    end
-
-    def 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])
-    end
-
-    def months_in_range
-      ((end_date.year - start_date.year) * 12 + end_date.month - start_date.month + 1)
-    end
-  end
-end