trackplot 0.1.0 → 0.2.0

data/app/helpers/trackplot/chart_helper.rb

@@ -5,5 +5,10 @@ module Trackplot
       capture(builder, &block) if block_given?
       builder.render(self)
     end
+
+    def trackplot_sparkline(data, key:, **options)
+      builder = SparklineBuilder.new(data, key: key, **options)
+      builder.render(self)
+    end
   end
 end

data/lib/generators/trackplot/install_generator.rb

@@ -1,21 +1,107 @@
 module Trackplot
   module Generators
     class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+      class_option :stimulus, type: :boolean, default: false,
+        desc: "Copy a Stimulus controller for auto-refresh polling and export actions"
+
       desc "Install Trackplot into your Rails application"
 
-      def add_import
-        js_file = Rails.root.join("app/javascript/application.js")
+      def detect_and_install_js
+        if importmap?
+          install_importmap
+        elsif jsbundling?
+          install_jsbundling
+        else
+          say "Could not detect JS setup (no config/importmap.rb or package.json found).", :red
+          say "Please add `import \"trackplot\"` to your JavaScript entrypoint manually."
+        end
+      end
+
+      def copy_stimulus_controller
+        return unless options[:stimulus]
+
+        dest = Rails.root.join("app/javascript/controllers/trackplot_controller.js")
+        if File.exist?(dest)
+          say "Stimulus controller already exists at #{dest}", :yellow
+        else
+          copy_file "trackplot_controller.js", dest
+          say "Copied Stimulus controller to #{dest}", :green
+        end
+      end
+
+      def print_post_install
+        say ""
+        say "Trackplot installed successfully!", :green
+        say ""
+        say "Quick start — add this to any ERB view:"
+        say ""
+        say '  <%= trackplot_chart([{month: "Jan", revenue: 100}, {month: "Feb", revenue: 200}]) do |c| %>'
+        say "    <% c.axis :x, data_key: :month %>"
+        say "    <% c.axis :y, format: :currency %>"
+        say "    <% c.line :revenue, curve: true %>"
+        say "    <% c.tooltip format: :currency %>"
+        say "    <% c.legend %>"
+        say "  <% end %>"
+        say ""
+      end
+
+      private
+
+      def importmap?
+        File.exist?(Rails.root.join("config/importmap.rb"))
+      end
+
+      def jsbundling?
+        File.exist?(Rails.root.join("package.json")) && !importmap?
+      end
+
+      def install_importmap
+        say "Detected importmap setup", :cyan
+        # Engine auto-registers pins via config/importmap.rb in the engine,
+        # so we just need the import in application.js
+        ensure_import_in_application_js
+      end
+
+      def install_jsbundling
+        say "Detected jsbundling setup", :cyan
+        pm = detect_package_manager
+        say "Using #{pm} to install packages...", :cyan
+
+        install_cmd = case pm
+        when "yarn" then "yarn add d3 trackplot"
+        when "pnpm" then "pnpm add d3 trackplot"
+        else "npm install d3 trackplot"
+        end
+
+        run install_cmd
+        ensure_import_in_application_js
+      end
 
-        if File.exist?(js_file)
-          content = File.read(js_file)
-          if content.include?('import "trackplot"')
-            say "trackplot import already present in application.js", :yellow
-          else
-            append_to_file js_file, "\nimport \"trackplot\"\n"
-            say "Added trackplot import to application.js", :green
-          end
+      def detect_package_manager
+        if File.exist?(Rails.root.join("yarn.lock"))
+          "yarn"
+        elsif File.exist?(Rails.root.join("pnpm-lock.yaml"))
+          "pnpm"
         else
+          "npm"
+        end
+      end
+
+      def ensure_import_in_application_js
+        js_file = Rails.root.join("app/javascript/application.js")
+
+        unless File.exist?(js_file)
           say "Could not find app/javascript/application.js — please add `import \"trackplot\"` manually", :red
+          return
+        end
+
+        content = File.read(js_file)
+        if content.include?('import "trackplot"')
+          say "trackplot import already present in application.js", :yellow
+        else
+          append_to_file js_file, "\nimport \"trackplot\"\n"
+          say "Added trackplot import to application.js", :green
         end
       end
     end

data/lib/generators/trackplot/templates/trackplot_controller.js

@@ -0,0 +1,52 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Auto-refreshing chart controller for Trackplot.
+//
+// Usage:
+//   <div data-controller="trackplot"
+//        data-trackplot-url-value="/api/chart_data.json"
+//        data-trackplot-interval-value="5000">
+//     <trackplot-chart config='<%= chart_config_json %>'></trackplot-chart>
+//   </div>
+//
+// Actions:
+//   <button data-action="trackplot#exportPng">Download PNG</button>
+//   <button data-action="trackplot#exportSvg">Download SVG</button>
+
+export default class extends Controller {
+  static values = {
+    url: String,
+    interval: { type: Number, default: 0 }
+  }
+
+  connect() {
+    this.chart = this.element.querySelector("trackplot-chart")
+    if (this.urlValue && this.intervalValue > 0) {
+      this.poll = setInterval(() => this.refresh(), this.intervalValue)
+    }
+  }
+
+  disconnect() {
+    if (this.poll) clearInterval(this.poll)
+  }
+
+  async refresh() {
+    if (!this.urlValue || !this.chart) return
+    try {
+      const response = await fetch(this.urlValue)
+      if (!response.ok) return
+      const data = await response.json()
+      this.chart.updateData(data)
+    } catch (e) {
+      console.warn("Trackplot: refresh failed", e)
+    }
+  }
+
+  exportPng() {
+    this.chart?.exportPNG()
+  }
+
+  exportSvg() {
+    this.chart?.exportSVG()
+  }
+}

data/lib/trackplot/chart_builder.rb

@@ -81,29 +81,69 @@ module Trackplot
       nil
     end
 
+    def data_label(**opts)
+      @components << Components::DataLabel.new(**opts)
+      nil
+    end
+
+    def brush(**opts)
+      @components << Components::Brush.new(**opts)
+      nil
+    end
+
+    def heatmap(**opts)
+      @components << Components::Heatmap.new(**opts)
+      nil
+    end
+
+    def treemap(**opts)
+      @components << Components::Treemap.new(**opts)
+      nil
+    end
+
+    def drilldown(key, **opts)
+      @components << Components::Drilldown.new(key: key, **opts)
+      nil
+    end
+
     def render(view_context)
       chart_id = options[:id] || "trackplot-#{SecureRandom.hex(8)}"
       config = build_config
 
-      view_context.content_tag(
-        "trackplot-chart",
-        nil,
+      html_options = {
         id: chart_id,
         config: config.to_json,
         style: chart_style,
         class: css_classes
+      }
+
+      if options[:title]
+        html_options[:role] = "img"
+        html_options[:"aria-label"] = options[:title]
+      end
+
+      view_context.content_tag(
+        "trackplot-chart",
+        nil,
+        html_options
       )
     end
 
     private
 
     def build_config
-      {
+      config = {
         data: data,
         components: components.map(&:to_config),
         animate: options.fetch(:animate, true),
         theme: Theme.resolve(options[:theme])
       }
+
+      config[:title] = options[:title] if options[:title]
+      config[:description] = options[:description] if options[:description]
+      config[:empty_message] = options[:empty_message] if options[:empty_message]
+
+      config
     end
 
     def chart_style

data/lib/trackplot/color_scale.rb

@@ -0,0 +1,158 @@
+module Trackplot
+  module ColorScale
+    module_function
+
+    # Light-to-dark palette from a single base color.
+    # Extracts hue + saturation, varies lightness from 0.90 to 0.25.
+    def sequential(hex, count: 8)
+      validate_hex!(hex)
+      return [] if count == 0
+
+      h, s, _ = hex_to_hsl(hex)
+      if count == 1
+        return [hsl_to_hex(h, s, 0.5)]
+      end
+
+      (0...count).map do |i|
+        l = lerp(0.90, 0.25, i.to_f / (count - 1))
+        hsl_to_hex(h, s, l)
+      end
+    end
+
+    # Two-color gradient with parabolic lightness curve peaking at 0.95 at midpoint.
+    def diverging(hex1, hex2, count: 8)
+      validate_hex!(hex1)
+      validate_hex!(hex2)
+      return [] if count == 0
+
+      h1, s1, _ = hex_to_hsl(hex1)
+      h2, s2, _ = hex_to_hsl(hex2)
+
+      if count == 1
+        return [hsl_to_hex(lerp_hue(h1, h2, 0.5), lerp(s1, s2, 0.5), 0.95)]
+      end
+
+      (0...count).map do |i|
+        t = i.to_f / (count - 1)
+        h = lerp_hue(h1, h2, t)
+        s = lerp(s1, s2, t)
+        # Parabolic curve: l = 0.95 at t=0.5, dropping to ~0.35 at edges
+        l = 0.95 - 2.4 * (t - 0.5)**2
+        hsl_to_hex(h, s, l)
+      end
+    end
+
+    # Evenly-spaced hues, preserving base color's saturation and lightness.
+    def categorical(hex, count: 8)
+      validate_hex!(hex)
+      return [] if count == 0
+
+      h, s, l = hex_to_hsl(hex)
+      step = 360.0 / count
+
+      (0...count).map do |i|
+        hue = (h + step * i) % 360
+        hsl_to_hex(hue, s, l)
+      end
+    end
+
+    # ── Private helpers ──────────────────────────────────────
+
+    def validate_hex!(hex)
+      unless hex.is_a?(String) && hex.match?(/\A#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})\z/)
+        raise ArgumentError, "Invalid hex color: #{hex.inspect}. Expected format: #RGB or #RRGGBB"
+      end
+    end
+
+    def hex_to_rgb(hex)
+      hex = hex.delete_prefix("#")
+      if hex.length == 3
+        hex = hex.chars.map { |c| c * 2 }.join
+      end
+      [hex[0..1], hex[2..3], hex[4..5]].map { |c| c.to_i(16) }
+    end
+
+    def rgb_to_hsl(r, g, b)
+      r /= 255.0
+      g /= 255.0
+      b /= 255.0
+
+      max = [r, g, b].max
+      min = [r, g, b].min
+      l = (max + min) / 2.0
+
+      if max == min
+        h = s = 0.0
+      else
+        d = max - min
+        s = (l > 0.5) ? d / (2.0 - max - min) : d / (max + min)
+
+        h = case max
+        when r then ((g - b) / d + ((g < b) ? 6 : 0)) / 6.0
+        when g then ((b - r) / d + 2) / 6.0
+        when b then ((r - g) / d + 4) / 6.0
+        end
+      end
+
+      [h * 360.0, s, l]
+    end
+
+    def hsl_to_rgb(h, s, l)
+      h /= 360.0
+
+      if s == 0
+        val = (l * 255).round
+        return [val, val, val]
+      end
+
+      q = (l < 0.5) ? l * (1 + s) : l + s - l * s
+      p = 2 * l - q
+
+      r = hue_to_rgb(p, q, h + 1.0 / 3)
+      g = hue_to_rgb(p, q, h)
+      b = hue_to_rgb(p, q, h - 1.0 / 3)
+
+      [(r * 255).round, (g * 255).round, (b * 255).round]
+    end
+
+    def hue_to_rgb(p, q, t)
+      t += 1.0 if t < 0
+      t -= 1.0 if t > 1
+
+      return p + (q - p) * 6 * t if t < 1.0 / 6
+      return q if t < 1.0 / 2
+      return p + (q - p) * (2.0 / 3 - t) * 6 if t < 2.0 / 3
+      p
+    end
+
+    def rgb_to_hex(r, g, b)
+      "#%02x%02x%02x" % [r.clamp(0, 255), g.clamp(0, 255), b.clamp(0, 255)]
+    end
+
+    def hex_to_hsl(hex)
+      r, g, b = hex_to_rgb(hex)
+      rgb_to_hsl(r, g, b)
+    end
+
+    def hsl_to_hex(h, s, l)
+      r, g, b = hsl_to_rgb(h, s, l)
+      rgb_to_hex(r, g, b)
+    end
+
+    def lerp(a, b, t)
+      a + (b - a) * t
+    end
+
+    def lerp_hue(h1, h2, t)
+      diff = h2 - h1
+      if diff.abs > 180
+        diff += (diff > 0) ? -360 : 360
+      end
+      (h1 + diff * t) % 360
+    end
+
+    private_class_method :validate_hex!, :hex_to_rgb, :rgb_to_hsl, :hsl_to_rgb,
+      :hue_to_rgb, :rgb_to_hex, :hex_to_hsl, :hsl_to_hex,
+      :lerp, :lerp_hue
+  end
+end

data/lib/trackplot/component.rb

@@ -0,0 +1,21 @@
+begin
+  require "view_component"
+rescue LoadError
+  # ViewComponent is an optional dependency
+end
+
+module Trackplot
+  if defined?(ViewComponent::Base)
+    class Component < ViewComponent::Base
+      def initialize(data:, **options, &block)
+        @builder = ChartBuilder.new(data, **options)
+        @block = block
+      end
+
+      def call
+        @block&.call(@builder)
+        @builder.render(self)
+      end
+    end
+  end
+end

data/lib/trackplot/components/area.rb

@@ -16,7 +16,8 @@ module Trackplot
           curve: options.fetch(:curve, false),
           opacity: options[:opacity] || 0.3,
           stroke_width: options[:stroke_width] || 2,
-          stack: options[:stack]
+          stack: options[:stack],
+          y_axis: options[:y_axis]&.to_s
         }.compact
       end
     end

data/lib/trackplot/components/axis.rb

@@ -24,7 +24,8 @@ module Trackplot
           label: options[:label],
           format: resolve_format(options[:format]),
           tick_count: options[:tick_count],
-          tick_rotation: options[:tick_rotation]
+          tick_rotation: options[:tick_rotation],
+          axis_id: options[:axis_id]&.to_s
         }.compact
       end
 

data/lib/trackplot/components/bar.rb

@@ -15,7 +15,8 @@ module Trackplot
           color: options[:color],
           opacity: options[:opacity],
           radius: options[:radius] || 4,
-          stack: options[:stack]
+          stack: options[:stack],
+          y_axis: options[:y_axis]&.to_s
         }.compact
       end
     end

data/lib/trackplot/components/brush.rb

@@ -0,0 +1,13 @@
+module Trackplot
+  module Components
+    class Brush < Base
+      def to_config
+        {
+          type: "brush",
+          axis: (options[:axis] || :x).to_s,
+          height: options[:height] || 40
+        }.compact
+      end
+    end
+  end
+end

data/lib/trackplot/components/data_label.rb

@@ -0,0 +1,30 @@
+module Trackplot
+  module Components
+    class DataLabel < Base
+      FORMAT_SYMBOLS = {
+        currency: "currency",
+        percent: "percent",
+        compact: "compact",
+        decimal: "decimal",
+        integer: "integer"
+      }.freeze
+
+      def to_config
+        {
+          type: "data_label",
+          format: resolve_format(options[:format]),
+          position: (options[:position] || :top).to_s,
+          font_size: options[:font_size] || 11
+        }.compact
+      end
+
+      private
+
+      def resolve_format(fmt)
+        return nil if fmt.nil?
+
+        FORMAT_SYMBOLS.fetch(fmt, fmt).to_s
+      end
+    end
+  end
+end

data/lib/trackplot/components/drilldown.rb

@@ -0,0 +1,12 @@
+module Trackplot
+  module Components
+    class Drilldown < Base
+      def to_config
+        {
+          type: "drilldown",
+          key: options[:key].to_s
+        }
+      end
+    end
+  end
+end

data/lib/trackplot/components/heatmap.rb

@@ -0,0 +1,16 @@
+module Trackplot
+  module Components
+    class Heatmap < Base
+      def to_config
+        {
+          type: "heatmap",
+          x_key: options[:x_key],
+          y_key: options[:y_key],
+          value_key: options[:value_key],
+          color_range: options[:color_range] || ["#f0f9ff", "#1e40af"],
+          radius: options[:radius] || 2
+        }.compact
+      end
+    end
+  end
+end

data/lib/trackplot/components/line.rb

@@ -17,7 +17,8 @@ module Trackplot
           dashed: options.fetch(:dashed, false),
           stroke_width: options[:stroke_width] || 2,
           dot: options.fetch(:dot, true),
-          dot_size: options[:dot_size] || 4
+          dot_size: options[:dot_size] || 4,
+          y_axis: options[:y_axis]&.to_s
         }.compact
       end
     end

data/lib/trackplot/components/scatter.rb

@@ -16,7 +16,8 @@ module Trackplot
           color: options[:color],
           dot_size: options[:dot_size] || 5,
           opacity: options[:opacity] || 0.7,
-          shape: options[:shape] || "circle"
+          shape: options[:shape] || "circle",
+          y_axis: options[:y_axis]&.to_s
         }.compact
       end
     end

data/lib/trackplot/components/treemap.rb

@@ -0,0 +1,14 @@
+module Trackplot
+  module Components
+    class Treemap < Base
+      def to_config
+        {
+          type: "treemap",
+          value_key: options[:value_key],
+          label_key: options[:label_key],
+          parent_key: options[:parent_key]
+        }.compact
+      end
+    end
+  end
+end

data/lib/trackplot/phlex_component.rb

@@ -0,0 +1,45 @@
+begin
+  require "phlex"
+rescue LoadError
+  # Phlex is an optional dependency
+end
+
+module Trackplot
+  if defined?(Phlex::HTML)
+    class PhlexComponent < Phlex::HTML
+      def initialize(data:, **options, &block)
+        @data = data
+        @options = options
+        @block = block
+      end
+
+      def view_template
+        builder = ChartBuilder.new(@data, **@options)
+        @block&.call(builder)
+        config = builder.send(:build_config)
+
+        chart_id = @options[:id] || "trackplot-#{SecureRandom.hex(8)}"
+        width = @options[:width] || "100%"
+        height = @options[:height] || "400px"
+
+        tag(
+          "trackplot-chart",
+          id: chart_id,
+          config: config.to_json,
+          style: "display:block;width:#{width};height:#{height};",
+          class: ["trackplot-chart", @options[:class]].compact.join(" "),
+          role: @options[:title] ? "img" : nil,
+          **aria_attributes
+        )
+      end
+
+      private
+
+      def aria_attributes
+        attrs = {}
+        attrs[:"aria-label"] = @options[:title] if @options[:title]
+        attrs
+      end
+    end
+  end
+end

data/lib/trackplot/sparkline_builder.rb

@@ -0,0 +1,44 @@
+require "securerandom"
+require "json"
+
+module Trackplot
+  class SparklineBuilder
+    attr_reader :data, :options
+
+    def initialize(data, **options)
+      @data = DataAdapter.normalize(data)
+      @options = options
+    end
+
+    def render(view_context)
+      config = build_config
+
+      view_context.content_tag(
+        "trackplot-sparkline",
+        nil,
+        config: config.to_json,
+        style: sparkline_style
+      )
+    end
+
+    private
+
+    def build_config
+      {
+        data: data,
+        key: options[:key].to_s,
+        type: (options[:type] || :line).to_s,
+        color: options[:color] || "#6366f1",
+        fill: options[:fill],
+        stroke_width: options[:stroke_width] || 1.5,
+        dot: options.fetch(:dot, false)
+      }.compact
+    end
+
+    def sparkline_style
+      width = options[:width] || "120px"
+      height = options[:height] || "32px"
+      "display:inline-block;width:#{width};height:#{height};"
+    end
+  end
+end

data/lib/trackplot/version.rb

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