heatmap-builder 0.1.0 → 0.2.0

data/lib/heatmap_builder/color_helpers.rb

@@ -0,0 +1,170 @@
+module HeatmapBuilder
+  module ColorHelpers
+    private
+
+    def score_to_color(score, colors:)
+      # Generate color palette if colors is a hash
+      if colors.is_a?(Hash)
+        colors = generate_color_palette(colors[:from], colors[:to], colors[:steps])
+      end
+
+      return colors.first if score == 0
+
+      max_color_index = colors.length - 1
+      color_index = 1 + (score - 1) % max_color_index
+      colors[color_index]
+    end
+
+    def darker_color(hex_color, factor: 0.9)
+      rgb = hex_to_rgb(hex_color)
+      oklch = rgb_to_oklch(*rgb)
+
+      # Reduce lightness (L component) by factor
+      darker_oklch = [oklch[0] * factor, oklch[1], oklch[2]]
+      darker_rgb = oklch_to_rgb(*darker_oklch)
+
+      rgb_to_hex(*darker_rgb)
+    end
+
+    def make_color_inactive(hex_color)
+      # Convert to OKLCH for blending
+      rgb = hex_to_rgb(hex_color)
+      oklch = rgb_to_oklch(*rgb)
+
+      # Reduce chroma (saturation) to make it more muted
+      # Also slightly reduce lightness
+      inactive_oklch = [
+        oklch[0] * 0.85,  # Slightly reduce lightness
+        oklch[1] * 0.4,   # Significantly reduce chroma (saturation)
+        oklch[2]          # Keep hue unchanged
+      ]
+
+      inactive_rgb = oklch_to_rgb(*inactive_oklch)
+      rgb_to_hex(*inactive_rgb)
+    end
+
+    def rgb_to_oklch(r, g, b)
+      # Convert to linear RGB first
+      r_linear = srgb_to_linear(r / 255.0)
+      g_linear = srgb_to_linear(g / 255.0)
+      b_linear = srgb_to_linear(b / 255.0)
+
+      # Linear RGB to OKLab using the Oklab transformation matrix
+      l = 0.4122214708 * r_linear + 0.5363325363 * g_linear + 0.0514459929 * b_linear
+      m = 0.2119034982 * r_linear + 0.6806995451 * g_linear + 0.1073969566 * b_linear
+      s = 0.0883024619 * r_linear + 0.2817188376 * g_linear + 0.6299787005 * b_linear
+
+      # Apply cube root
+      l_root = (l >= 0) ? l**(1.0 / 3) : -((-l)**(1.0 / 3))
+      m_root = (m >= 0) ? m**(1.0 / 3) : -((-m)**(1.0 / 3))
+      s_root = (s >= 0) ? s**(1.0 / 3) : -((-s)**(1.0 / 3))
+
+      # Convert to OKLab
+      ok_l = 0.2104542553 * l_root + 0.7936177850 * m_root - 0.0040720468 * s_root
+      ok_a = 1.9779984951 * l_root - 2.4285922050 * m_root + 0.4505937099 * s_root
+      ok_b = 0.0259040371 * l_root + 0.7827717662 * m_root - 0.8086757660 * s_root
+
+      # Convert OKLab to OKLCH
+      chroma = Math.sqrt(ok_a * ok_a + ok_b * ok_b)
+      hue = Math.atan2(ok_b, ok_a) * 180.0 / Math::PI
+      hue += 360 if hue < 0
+
+      [ok_l, chroma, hue]
+    end
+
+    def oklch_to_rgb(ok_l, chroma, hue)
+      # Convert OKLCH to OKLab
+      hue_rad = hue * Math::PI / 180.0
+      ok_a = chroma * Math.cos(hue_rad)
+      ok_b = chroma * Math.sin(hue_rad)
+
+      # OKLab to linear RGB
+      l_root = ok_l + 0.3963377774 * ok_a + 0.2158037573 * ok_b
+      m_root = ok_l - 0.1055613458 * ok_a - 0.0638541728 * ok_b
+      s_root = ok_l - 0.0894841775 * ok_a - 1.2914855480 * ok_b
+
+      # Cube the values
+      l = l_root * l_root * l_root
+      m = m_root * m_root * m_root
+      s = s_root * s_root * s_root
+
+      # Convert to linear RGB
+      r_linear = +4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s
+      g_linear = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s
+      b_linear = -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s
+
+      # Convert to sRGB
+      r = linear_to_srgb(r_linear)
+      g = linear_to_srgb(g_linear)
+      b = linear_to_srgb(b_linear)
+
+      # Clamp to 0-255 and convert to integers
+      r = (r * 255).clamp(0, 255).round
+      g = (g * 255).clamp(0, 255).round
+      b = (b * 255).clamp(0, 255).round
+
+      [r, g, b]
+    end
+
+    def srgb_to_linear(component)
+      (component <= 0.04045) ? component / 12.92 : ((component + 0.055) / 1.055)**2.4
+    end
+
+    def linear_to_srgb(component)
+      (component <= 0.0031308) ? component * 12.92 : 1.055 * (component**(1.0 / 2.4)) - 0.055
+    end
+
+    def interpolate_oklch(oklch1, oklch2, ratio)
+      # Handle hue interpolation (shortest path around the circle)
+      hue1, hue2 = oklch1[2], oklch2[2]
+      hue_diff = hue2 - hue1
+
+      # Take shorter path around the circle
+      if hue_diff > 180
+        hue_diff -= 360
+      elsif hue_diff < -180
+        hue_diff += 360
+      end
+
+      interpolated_hue = hue1 + hue_diff * ratio
+      interpolated_hue += 360 if interpolated_hue < 0
+      interpolated_hue -= 360 if interpolated_hue >= 360
+
+      [
+        oklch1[0] + (oklch2[0] - oklch1[0]) * ratio, # L (lightness)
+        oklch1[1] + (oklch2[1] - oklch1[1]) * ratio, # C (chroma)
+        interpolated_hue                              # H (hue)
+      ]
+    end
+
+    def hex_to_rgb(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)
+      [r, g, b]
+    end
+
+    def rgb_to_hex(r, g, b)
+      "#%02x%02x%02x" % [r, g, b]
+    end
+
+    def generate_color_palette(from_color, to_color, steps)
+      from_rgb = hex_to_rgb(from_color)
+      to_rgb = hex_to_rgb(to_color)
+
+      from_oklch = rgb_to_oklch(*from_rgb)
+      to_oklch = rgb_to_oklch(*to_rgb)
+
+      colors = []
+      (0...steps).each do |i|
+        ratio = i.to_f / (steps - 1)
+        interpolated_oklch = interpolate_oklch(from_oklch, to_oklch, ratio)
+        interpolated_rgb = oklch_to_rgb(*interpolated_oklch)
+        colors << rgb_to_hex(*interpolated_rgb)
+      end
+
+      colors
+    end
+  end
+end

data/lib/heatmap_builder/linear_heatmap_builder.rb

@@ -1,128 +1,74 @@
+require_relative "builder"
+require_relative "value_conversion"
+
 module HeatmapBuilder
-  class LinearHeatmapBuilder
-    DEFAULT_OPTIONS = {
-      cell_size: 10,
-      cell_spacing: 1,
-      font_size: 8,
-      cells_per_row: 7,
-      border_width: 1,
-      colors: %w[#ebedf0 #9be9a8 #40c463 #30a14e #216e39]
-    }.freeze
-
-    def initialize(scores, options = {})
-      @scores = scores
-      @options = DEFAULT_OPTIONS.merge(options)
-      validate_options!
-    end
+  class LinearHeatmapBuilder < Builder
+    include ValueConversion
 
-    def generate
-      build_svg
+    def build
+      svg_content = computed_scores.map.with_index do |score, index|
+        cell_svg(score, index)
+      end.join
+
+      svg_container(
+        width: computed_scores.length * options[:cell_size] + (computed_scores.length - 1) * options[:cell_spacing],
+        height: options[:cell_size]
+      ) { svg_content }
     end
 
     private
 
-    attr_reader :scores, :options
-
     def validate_options!
-      raise Error, "scores must be an array" unless scores.is_a?(Array)
-      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, "cells_per_row must be positive" unless options[:cells_per_row] > 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
+      super
+
+      raise Error, "scores must be an array" if scores && !scores.is_a?(Array)
+      raise Error, "values must be an array" if values && !values.is_a?(Array)
     end
 
-    def build_svg
-      width = svg_width
-      height = svg_height
+    def computed_scores
+      @computed_scores ||= scores || values.map.with_index { |value, index| convert_value_to_score(value, index: index) }
+    end
 
-      svg_content = scores.first(options[:cells_per_row]).map.with_index do |score, index|
-        cell_svg(score, index)
-      end.join
+    def calculated_min_from_values
+      non_nil_values = values.compact
+      non_nil_values.empty? ? 0 : non_nil_values.min
+    end
 
-      <<~SVG
-        <svg width="#{width}" height="#{height}" xmlns="http://www.w3.org/2000/svg">
-          #{svg_content}
-        </svg>
-      SVG
+    def calculated_max_from_values
+      non_nil_values = values.compact
+      non_nil_values.empty? ? 0 : non_nil_values.max
     end
 
     def cell_svg(score, index)
-      # Calculate x position - each cell takes cell_size + spacing
       x = index * (options[:cell_size] + options[:cell_spacing])
       y = 0
 
-      color = score_to_color(score)
-
-      # Create colored square (full cell size)
-      colored_rect = "<rect x=\"#{x}\" y=\"#{y}\" width=\"#{options[:cell_size]}\" height=\"#{options[:cell_size]}\" fill=\"#{color}\"/>"
-
-      # Create border overlay completely inside the colored square
-      border_rect = if options[:border_width] > 0
-        # Inset the border rect by half the stroke width so stroke stays inside
-        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
-
-      # Calculate text position (center of cell)
-      text_x = x + options[:cell_size] / 2
-      # For better vertical centering: cell center + font_size * 0.35 (accounts for baseline)
-      text_y = y + options[:cell_size] / 2 + options[:font_size] * 0.35
-
-      text_element = "<text x=\"#{text_x}\" y=\"#{text_y}\" text-anchor=\"middle\" font-family=\"Arial, sans-serif\" font-size=\"#{options[:font_size]}\" fill=\"#{text_color(color)}\">#{score}</text>"
+      color = score_to_color(score, colors: color_palette)
 
-      "#{colored_rect}#{border_rect}#{text_element}"
-    end
-
-    def score_to_color(score)
-      return options[:colors].first if score == 0
-
-      max_color_index = options[:colors].length - 1
-      # Map score to color index, ensuring we don't exceed available colors
-      color_index = 1 + (score - 1) % max_color_index
-      options[:colors][color_index]
-    end
-
-    def text_color(background_color)
-      # Simple contrast check - if dark background, use white text
-      hex = background_color.delete("#")
-      r = hex[0..1].to_i(16)
-      g = hex[2..3].to_i(16)
-      b = hex[4..5].to_i(16)
-      brightness = (r * 299 + g * 587 + b * 114) / 1000
-      (brightness > 128) ? "#000000" : "#ffffff"
-    end
+      colored_rect = svg_rect(
+        x: x, y: y,
+        width: options[:cell_size], height: options[:cell_size],
+        rx: options[:corner_radius],
+        fill: color
+      )
 
-    def svg_width
-      options[:cells_per_row] * options[:cell_size] +
-        (options[:cells_per_row] - 1) * options[:cell_spacing]
-    end
-
-    def svg_height
-      options[:cell_size]
-    end
-
-    def darker_color(hex_color)
-      # Remove # if present
-      hex = hex_color.delete("#")
+      border_rect = cell_border(
+        x, y, color,
+        cell_size: options[:cell_size],
+        border_width: options[:border_width],
+        corner_radius: options[:corner_radius]
+      )
 
-      # Extract RGB values
-      r = hex[0..1].to_i(16)
-      g = hex[2..3].to_i(16)
-      b = hex[4..5].to_i(16)
+      text_x = x + options[:cell_size] / 2
+      text_y = y + options[:cell_size] / 2 + options[:font_size] * 0.35
 
-      # Make 30% darker
-      r = (r * 0.7).to_i
-      g = (g * 0.7).to_i
-      b = (b * 0.7).to_i
+      text_element = svg_text(
+        score,
+        x: text_x, y: text_y,
+        font_size: options[:font_size], fill: options[:text_color]
+      )
 
-      "#%02x%02x%02x" % [r, g, b]
+      "#{colored_rect}#{border_rect}#{text_element}"
     end
   end
 end

data/lib/heatmap_builder/svg_helpers.rb

@@ -0,0 +1,75 @@
+module HeatmapBuilder
+  module SvgHelpers
+    private
+
+    def svg_element(tag, attributes = {}, &block)
+      attr_string = attributes.map do |key, value|
+        "#{kebab_case(key)}=\"#{value}\""
+      end.join(" ")
+
+      attr_string = " #{attr_string}" unless attr_string.empty?
+
+      if block_given?
+        content = block.call
+        "<#{tag}#{attr_string}>#{content}</#{tag}>"
+      else
+        "<#{tag}#{attr_string}/>"
+      end
+    end
+
+    def svg_rect(x:, y:, width:, height:, rx: nil, **attributes)
+      attrs = {
+        x: x,
+        y: y,
+        width: width,
+        height: height
+      }
+
+      attrs[:rx] = rx if rx && rx > 0
+      svg_element("rect", attrs.merge(attributes))
+    end
+
+    def svg_text(content, x:, y:, **attributes)
+      default_attrs = {
+        text_anchor: "middle",
+        font_family: "Arial, sans-serif"
+      }
+
+      svg_element("text", {x: x, y: y}.merge(default_attrs).merge(attributes)) { content }
+    end
+
+    def svg_container(width:, height:, &block)
+      svg_element("svg", {
+        width: width,
+        height: height,
+        xmlns: "http://www.w3.org/2000/svg"
+      }, &block)
+    end
+
+    def kebab_case(key)
+      key.to_s.tr("_", "-")
+    end
+
+    def cell_border(x, y, color, cell_size:, border_width:, corner_radius:)
+      return "" unless border_width > 0
+
+      inset = border_width / 2.0
+      border_x = x + inset
+      border_y = y + inset
+      border_size = cell_size - border_width
+      border_color = darker_color(color)
+      border_radius = (corner_radius > 0) ? [corner_radius - inset, 0].max : 0
+
+      svg_rect(
+        x: border_x,
+        y: border_y,
+        width: border_size,
+        height: border_size,
+        rx: border_radius,
+        fill: "none",
+        stroke: border_color,
+        stroke_width: border_width
+      )
+    end
+  end
+end

data/lib/heatmap_builder/value_conversion.rb

@@ -0,0 +1,64 @@
+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)
+      value = value_min if value.nil?
+
+      if options[:value_to_score]
+        score = options[:value_to_score].call(
+          value: 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
+
+      clamped_value = value.clamp(value_min, value_max)
+
+      if value_min == value_max
+        0
+      else
+        range = value_max - value_min
+        normalized = (clamped_value - value_min).to_f / range
+        (normalized * (color_count - 1)).round
+      end
+    end
+  end
+end

data/lib/heatmap_builder/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: heatmap-builder
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Alex Musayev
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-19 00:00:00.000000000 Z
+date: 2025-10-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -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,37 @@ files:
 - README.md
 - Rakefile
 - bin/console
+- bin/generate_examples
 - bin/setup
+- examples/calendar_blue_ocean.svg
+- examples/calendar_default.svg
 - examples/calendar_github_style.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/linear_blue_ocean.svg
+- examples/linear_github_green.svg
+- examples/linear_neon_gradient.svg
+- examples/linear_purple_vibes.svg
+- examples/linear_red_to_green.svg
+- examples/linear_rounded_corners.svg
+- examples/linear_rounded_corners_max_radius.svg
+- examples/linear_warm_sunset.svg
 - examples/weekly_progress.svg
 - heatmap-builder.gemspec
 - lib/heatmap-builder.rb
+- lib/heatmap_builder/builder.rb
 - lib/heatmap_builder/calendar_heatmap_builder.rb
+- lib/heatmap_builder/color_helpers.rb
 - lib/heatmap_builder/linear_heatmap_builder.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

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/mise.toml

@@ -1,2 +0,0 @@
-[tools]
-ruby = "3.3"