heatmap-builder 0.1.0 → 0.4.3

data/lib/heatmap_builder/calendar.rb

@@ -0,0 +1,426 @@
+require "date"
+require_relative "svg_helpers"
+require_relative "color_helpers"
+require_relative "value_conversion"
+
+module HeatmapBuilder
+  class Calendar
+    include SvgHelpers
+    include ValueConversion
+
+    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: 12,
+      cell_spacing: 1,
+      font_size: 8,
+      border_width: 1,
+      border_lightness_factor: 0.9,
+      corner_radius: 0,
+      colors: GITHUB_GREEN,
+      start_of_week: :monday,
+      month_spacing: 0,
+      show_month_labels: true,
+      show_day_labels: true,
+      show_outside_cells: false,
+      day_labels: %w[S M T W T F S],
+      month_labels: %w[Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec],
+      tooltip: nil,
+      tooltip_attribute: "data-tooltip"
+    }.freeze
+
+    VALID_START_DAYS = %i[sunday monday tuesday wednesday thursday friday saturday].freeze
+
+    LABEL_COLOR = "#666666"
+    FONT_VERTICAL_CENTER_RATIO = 0.35
+    MONTH_LABEL_Y_RATIO = 1.25
+    MONTH_LABEL_HEIGHT_RATIO = 1.625
+    MONTH_LABEL_INDENT_RATIO = 0.1
+
+    WEEK_START_WDAY = {
+      sunday: 0,
+      monday: 1,
+      tuesday: 2,
+      wednesday: 3,
+      thursday: 4,
+      friday: 5,
+      saturday: 6
+    }.freeze
+
+    def initialize(scores: nil, values: nil, **options)
+      @scores = scores
+      @values = values
+      @options = DEFAULT_OPTIONS.merge(options)
+      validate_options!
+      normalize_options!
+    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
+
+      cell_size_with_spacing = options[:cell_size] + options[:cell_spacing]
+      width = dow_label_offset + total_column_count * cell_size_with_spacing + total_month_spacing
+      height = month_label_offset + 7 * cell_size_with_spacing
+
+      svg_container(width: width, height: height) { svg_content.join }
+    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
+
+    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?
+      raise Error, "border_lightness_factor must be positive" unless options[:border_lightness_factor].positive?
+      validate_colors_option!
+      validate_scores_or_values!
+      validate_value_boundaries! if values
+      validate_tooltip_option!
+
+      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)
+
+      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 validate_tooltip_option!
+      return unless options[:tooltip]
+      raise Error, "tooltip must be callable" unless options[:tooltip].respond_to?(:call)
+    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 color_palette
+      @color_palette ||= begin
+        colors_option = options[:colors]
+        if colors_option.is_a?(Hash)
+          ColorHelpers.generate_color_palette(colors_option[:from], colors_option[:to], colors_option[:steps])
+        else
+          colors_option
+        end
+      end
+    end
+
+    def start_date
+      @start_date ||= parsed_date_range.first
+    end
+
+    def end_date
+      @end_date ||= parsed_date_range.last
+    end
+
+    def scores_by_date
+      @scores_by_date ||= if scores
+        scores
+      else
+        result = {}
+        current_date = start_date
+
+        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
+
+        result
+      end
+    end
+
+    def calculated_min_from_values
+      # Zero is rendered as the reserved empty bucket, so the activity gradient
+      # starts at the smallest non-zero value. Anchoring the minimum here keeps
+      # the lightest activity color reachable.
+      candidates = values.values.compact.reject(&:zero?)
+      candidates.empty? ? 0 : candidates.min
+    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?
+
+        [dates.min, dates.max]
+      end
+    end
+
+    def column_layout
+      @column_layout ||= build_column_layout
+    end
+
+    def build_column_layout
+      columns = []
+      current_date = calendar_start_date
+      cal_end = calendar_end_date_with_full_weeks
+      split_enabled = options[:month_spacing] > 0
+      col_idx = 0
+      x_offset = 0
+      last_month = nil
+      labeled_months = {}
+
+      while current_date <= cal_end
+        week_start = current_date
+        week_end = current_date + 6
+
+        if split_enabled && week_start.month != week_end.month
+          split_at = (0..6).find { |i| (week_start + i).month != week_start.month }
+          new_month_date = week_start + split_at
+
+          # Column A: old month days (day_index 0..split_at-1)
+          # Partial column — month labels are only placed on the first full
+          # week, so neither split column carries a label.
+          days_a = (0...split_at).map { |i| [week_start + i, i] }
+          columns << {index: col_idx, x_offset: x_offset, days: days_a, month_date: week_start, first_of_month: false}
+          col_idx += 1
+
+          # Spacing between columns A and B
+          if last_month && month_overlaps_timeframe?(new_month_date)
+            x_offset += options[:month_spacing]
+          end
+          last_month = new_month_date.month
+
+          # Column B: new month days (day_index split_at..6)
+          # Don't place month label on split column — defer to first full column
+          days_b = (split_at..6).map { |i| [week_start + i, i] }
+          columns << {index: col_idx, x_offset: x_offset, days: days_b, month_date: new_month_date, first_of_month: false}
+        else
+          end_of_week_month = week_end.month
+          if end_of_week_month != last_month && !last_month.nil? && month_overlaps_timeframe?(week_end)
+            x_offset += options[:month_spacing]
+          end
+          last_month = end_of_week_month
+
+          # Label on the first fully visible week of a month. A month whose only
+          # visible week is incomplete (a leading or trailing sliver) gets no
+          # label, so the first label can't crowd into the next month's column.
+          days = (0..6).map { |i| [week_start + i, i] }
+          month_key = [week_start.year, week_start.month]
+          first = !labeled_months.key?(month_key) && week_fully_visible?(week_start)
+          labeled_months[month_key] = true if first
+          columns << {index: col_idx, x_offset: x_offset, days: days, month_date: week_start, first_of_month: first}
+        end
+
+        col_idx += 1
+        current_date += 7
+      end
+
+      columns
+    end
+
+    def calendar_cells_svg
+      svg = ""
+      column_layout.each do |col|
+        col[:days].each do |date, day_index|
+          svg << render_cell(date, col[:index], day_index, col[:x_offset])
+        end
+      end
+      svg
+    end
+
+    def render_cell(current_date, column_index, day_index, x_offset)
+      x = dow_label_offset + column_index * (options[:cell_size] + options[:cell_spacing]) + x_offset
+      y = month_label_offset + day_index * (options[:cell_size] + options[:cell_spacing])
+
+      if current_date.between?(start_date, end_date)
+        score = scores_by_date[current_date] || scores_by_date[current_date.to_s] || 0
+        cell_svg(score, x, y, false, date: current_date)
+      elsif options[:show_outside_cells]
+        cell_svg(0, x, y, true)
+      else
+        ""
+      end
+    end
+
+    def cell_svg(score, x, y, inactive = false, date: nil)
+      color = ColorHelpers.score_to_color(score, colors: color_palette)
+      color = ColorHelpers.make_color_inactive(color) if inactive
+
+      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],
+        border_lightness_factor: options[:border_lightness_factor],
+        corner_radius: options[:corner_radius]
+      )
+
+      cell_content = "#{colored_rect}#{border_rect}"
+
+      if options[:tooltip] && !inactive && date
+        cell_with_tooltip(cell_content, resolve_tooltip(date, score))
+      else
+        cell_content
+      end
+    end
+
+    def resolve_tooltip(date, score)
+      raw_value = values ? (values[date] || values[date.to_s]) : nil
+      options[:tooltip].call(date: date, score: score, value: raw_value)
+    end
+
+    def cell_with_tooltip(content, text)
+      title_element = svg_element("title") { escape_xml(text) }
+      group_attrs = {}
+      group_attrs[options[:tooltip_attribute]] = text if options[:tooltip_attribute]
+      svg_element("g", group_attrs) { "#{title_element}#{content}" }
+    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 = month_label_offset + index * (options[:cell_size] + options[:cell_spacing]) + options[:cell_size] / 2 + options[:font_size] * FONT_VERTICAL_CENTER_RATIO
+        svg << svg_text(
+          day_name,
+          x: options[:font_size], y: y,
+          font_size: options[:font_size], fill: LABEL_COLOR
+        )
+      end
+
+      svg
+    end
+
+    def month_labels_svg
+      return "" unless options[:show_month_labels]
+
+      svg = ""
+      column_layout.each do |col|
+        if col[:first_of_month]
+          svg << month_label_at(col[:index], col[:x_offset], col[:month_date])
+        end
+      end
+      svg
+    end
+
+    # A week carries its month's label only when every one of its seven days
+    # falls within the data range; partial boundary weeks are not labelable.
+    def week_fully_visible?(week_start)
+      week_start >= start_date && (week_start + 6) <= end_date
+    end
+
+    def month_overlaps_timeframe?(date)
+      month_start = Date.new(date.year, date.month, 1)
+      month_end = Date.new(date.year, date.month, -1)
+
+      month_start <= end_date && month_end >= start_date
+    end
+
+    def month_label_at(column_index, x_offset, month_date)
+      cell_size_with_spacing = options[:cell_size] + options[:cell_spacing]
+      x = dow_label_offset + column_index * cell_size_with_spacing + x_offset + options[:cell_size] * MONTH_LABEL_INDENT_RATIO
+      month_name = options[:month_labels][month_date.month - 1]
+
+      svg_text(
+        month_name,
+        x: x,
+        y: calculate_month_label_y,
+        text_anchor: "start", font_family: "Arial, sans-serif", font_size: options[:font_size], fill: LABEL_COLOR
+      )
+    end
+
+    def calculate_month_label_y
+      options[:font_size] * MONTH_LABEL_Y_RATIO
+    end
+
+    def total_column_count
+      column_layout.length
+    end
+
+    def total_month_spacing
+      column_layout.last&.dig(:x_offset) || 0
+    end
+
+    # Find the start of the week containing start_date
+    def calendar_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
+      days_forward = (6 - (end_date.wday - week_start_wday)) % 7
+      end_date + days_forward
+    end
+
+    def week_start_wday
+      WEEK_START_WDAY[options[:start_of_week]]
+    end
+
+    def day_names_for_week_start
+      start_index = week_start_wday
+      options[:day_labels].rotate(start_index)
+    end
+
+    def dow_label_offset
+      options[:show_day_labels] ? options[:font_size] * 2 : 0
+    end
+
+    def month_label_offset
+      options[:show_month_labels] ? options[:font_size] * MONTH_LABEL_HEIGHT_RATIO : 0
+    end
+  end
+end

data/lib/heatmap_builder/color_helpers.rb

@@ -0,0 +1,150 @@
+module HeatmapBuilder
+  module ColorHelpers
+    class << self
+      def score_to_color(score, colors:)
+        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 adjust_lightness(hex_color, factor:)
+        rgb = hex_to_rgb(hex_color)
+        oklch = rgb_to_oklch(*rgb)
+
+        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)
+        rgb = hex_to_rgb(hex_color)
+        oklch = rgb_to_oklch(*rgb)
+
+        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 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
+
+      private
+
+      def rgb_to_oklch(r, g, b)
+        r_linear = srgb_to_linear(r / 255.0)
+        g_linear = srgb_to_linear(g / 255.0)
+        b_linear = srgb_to_linear(b / 255.0)
+
+        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
+
+        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))
+
+        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
+
+        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)
+        hue_rad = hue * Math::PI / 180.0
+        ok_a = chroma * Math.cos(hue_rad)
+        ok_b = chroma * Math.sin(hue_rad)
+
+        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
+
+        l = l_root * l_root * l_root
+        m = m_root * m_root * m_root
+        s = s_root * s_root * s_root
+
+        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
+
+        r = linear_to_srgb(r_linear)
+        g = linear_to_srgb(g_linear)
+        b = linear_to_srgb(b_linear)
+
+        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)
+        hue1, hue2 = oklch1[2], oklch2[2]
+        hue_diff = hue2 - hue1
+
+        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,
+          oklch1[1] + (oklch2[1] - oklch1[1]) * ratio,
+          interpolated_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
+    end
+  end
+end

data/lib/heatmap_builder/svg_helpers.rb

@@ -0,0 +1,82 @@
+module HeatmapBuilder
+  module SvgHelpers
+    private
+
+    def svg_element(tag, attributes = {}, &block)
+      attr_string = attributes.map do |key, value|
+        "#{kebab_case(key)}=\"#{escape_xml(value.to_s)}\""
+      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)) { escape_xml(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 escape_xml(str)
+      str.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;").gsub('"', "&quot;")
+    end
+
+    def cell_border(x, y, color, cell_size:, border_width:, corner_radius:, border_lightness_factor: 0.9)
+      return "" unless border_width > 0
+      # A factor of 1 leaves the color unchanged, so the border matches the
+      # fill exactly and would be invisible. Skip drawing it entirely.
+      return "" if border_lightness_factor == 1
+
+      inset = border_width / 2.0
+      border_x = x + inset
+      border_y = y + inset
+      border_size = cell_size - border_width
+      border_color = ColorHelpers.adjust_lightness(color, factor: border_lightness_factor)
+      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