poetry-charts 0.0.2

data/config/controllers_manifest.json

@@ -0,0 +1,100 @@
+{
+  "poetry--charts--tooltip": {
+    "targets": [
+      "data",
+      "svg",
+      "tooltip"
+    ],
+    "values": {
+      "sync": {
+        "type": "String"
+      }
+    },
+    "methods": [
+      "blur",
+      "connect",
+      "count",
+      "disconnect",
+      "enter",
+      "focus",
+      "keydown",
+      "leave",
+      "move",
+      "refresh",
+      "show"
+    ],
+    "events": [
+      "poetry--charts--tooltip:hide",
+      "poetry--charts--tooltip:show"
+    ]
+  },
+  "poetry--charts--adapter": {
+    "targets": [
+      "mount",
+      "spec"
+    ],
+    "values": {
+      "engine": {
+        "type": "String"
+      }
+    },
+    "methods": [
+      "connect",
+      "disconnect"
+    ],
+    "events": [
+      "poetry--charts--adapter:rendered"
+    ]
+  },
+  "poetry--charts--motion": {
+    "targets": [],
+    "values": {},
+    "methods": [
+      "connect",
+      "disconnect"
+    ],
+    "events": [
+      "poetry--charts--motion:settled"
+    ]
+  },
+  "poetry--charts--live": {
+    "targets": [
+      "payload"
+    ],
+    "values": {},
+    "methods": [
+      "connect",
+      "disconnect",
+      "receive",
+      "setWindow",
+      "toggleSeries",
+      "update"
+    ],
+    "events": [
+      "poetry--charts--live:settled",
+      "poetry--charts--live:updated"
+    ]
+  },
+  "poetry--charts--window": {
+    "targets": [],
+    "values": {
+      "zoom": {
+        "type": "Boolean"
+      },
+      "plot": {
+        "type": "Array"
+      },
+      "brush": {
+        "type": "Array"
+      }
+    },
+    "methods": [
+      "connect",
+      "disconnect",
+      "reset",
+      "startBrush",
+      "startZoom"
+    ],
+    "events": []
+  }
+}

data/config/importmap.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# poetry-charts' importmap pins (the importmap-first channel): the
+# host app's importmap merges these, so the tooltip chrome runs with zero
+# build. Bundler hosts use the @poetry/charts npm package instead - one
+# source, two channels.
+
+pin "@poetry/charts", to: "poetry/charts/index.js"
+pin_all_from File.expand_path("../app/javascript/poetry/charts", __dir__),
+             under: "@poetry/charts", to: "poetry/charts"

data/lib/poetry/charts/cartesian.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    # The server-side cartesian layout pipeline: data + series ->
+    # plot rectangle, scales, ticks, and per-series pixel points -
+    # computed top-down in one pass, everything a renderer needs before
+    # writing a path.
+    #
+    # Layout conventions: default margin 5 on every side, x-axis strip
+    # height 30 at the bottom when shown, category x positions from a
+    # zero-padding point scale (first/last categories AT the plot
+    # edges - add left/right margin 12 when edge labels need room),
+    # numeric y domain [0, auto] niced decimal-exactly (implicit tick
+    # count 5), stacking per stack id with :none/:expand offsets.
+    #
+    # @example Lay out a plot and read one series' pixel points
+    #   plot = Poetry::Charts::Cartesian.new(
+    #     data: rows, series: series, width: 600, height: 300
+    #   )
+    #   plot.points(series.first) # => [{x:, y0:, y1:, value:}, ...]
+    class Cartesian
+      # The default plot margin - a slim, even inset on all sides.
+      DEFAULT_MARGIN = { top: 5, right: 5, bottom: 5, left: 5 }.freeze
+      # The bottom strip reserved for the category axis when shown.
+      X_AXIS_HEIGHT = 30
+      # The reserved left strip - where a visible value axis's labels
+      # (or the horizontal layout's category labels) live.
+      Y_AXIS_WIDTH = 60
+
+      # The stack baseline modes: raw values, or 100%-normalized.
+      OFFSETS = %i[none expand].freeze
+      # The chart orientations: :vertical columns, or :horizontal bars.
+      LAYOUTS = %i[vertical horizontal].freeze
+
+      attr_reader :width, :height, :margin, :y_tick_count, :offset, :layout
+
+      # @param data [Array<Hash>] the rows, one hash per category
+      # @param series [Array<#key>] series entries (key + optional stack id)
+      # @param width [Numeric] outer SVG width in pixels
+      # @param height [Numeric] outer SVG height in pixels
+      # @param x_key [String, Symbol, nil] the category key; nil indexes rows
+      # @param margin [Hash] per-side overrides merged over DEFAULT_MARGIN
+      # @param category_axis [Boolean] reserve the category-axis strip
+      # @param value_axis [Boolean] a visible value axis reserves the left strip
+      # @param y_tick_count [Integer] requested tick count for the niced domain
+      # @param offset [Symbol] :none, or :expand for 100%-stacked
+      # @param x_scale_type [Symbol] :point (line/area) or :band (bars)
+      # @param layout [Symbol] :vertical (values up y) or :horizontal
+      def initialize(data:, series:, width:, height:, x_key: nil, margin: {},
+                     category_axis: true, value_axis: false, y_tick_count: 5, offset: :none,
+                     x_scale_type: :point, layout: :vertical)
+        @data = data.map { |row| row.to_h.transform_keys(&:to_s) }
+        @series = series
+        @width = width.to_f
+        @height = height.to_f
+        @x_key = x_key&.to_s
+        @margin = DEFAULT_MARGIN.merge(margin.to_h.symbolize_keys)
+        @category_axis = category_axis
+        @value_axis = value_axis
+        @y_tick_count = y_tick_count
+        @x_scale_type = x_scale_type.to_sym
+        @layout = layout.to_sym
+        raise ArgumentError, "unknown layout #{layout.inspect}" unless LAYOUTS.include?(@layout)
+        raise ArgumentError, "unknown offset #{offset.inspect}" unless OFFSETS.include?(offset.to_sym)
+
+        @offset = offset.to_sym
+      end
+
+      # Whether categories run down the Y side (bars growing rightward).
+      def horizontal?
+        layout == :horizontal
+      end
+
+      # -- the plot rectangle ---------------------------------------------------
+      # The category-axis strip sits at the bottom (vertical layout, height
+      # 30) or the left (horizontal layout, width 60). A VISIBLE value
+      # axis in the vertical layout reserves the same left strip - without
+      # it, shown y labels would clip at the plot edge.
+
+      # The plot rect's left edge, inset for a reserved left strip.
+      def plot_left
+        reserved = (horizontal? && @category_axis) || (!horizontal? && @value_axis)
+        margin[:left].to_f + (reserved ? Y_AXIS_WIDTH : 0)
+      end
+
+      # The plot rect's right edge.
+      def plot_right = width - margin[:right]
+      # The plot rect's top edge.
+      def plot_top = margin[:top].to_f
+
+      # The plot rect's bottom edge, inset for the category axis strip.
+      def plot_bottom
+        height - margin[:bottom] - (!horizontal? && @category_axis ? X_AXIS_HEIGHT : 0)
+      end
+
+      # -- x: categories on a point scale ---------------------------------------
+
+      # The category values: the x_key column, else bare row indexes.
+      def categories
+        @categories ||= @x_key ? @data.map { |row| row[@x_key] } : (0...@data.length).to_a
+      end
+
+      # Point for line/area (categories AT the edges); band for bars
+      # (a zero-padding band - the bar gaps come from the gap math inside
+      # the band, not scale padding). Horizontal layout runs the category
+      # scale down the Y side.
+      def category_range
+        horizontal? ? [plot_top, plot_bottom] : [plot_left, plot_right]
+      end
+
+      # The category scale over the category range (point or band).
+      def x_scale
+        @x_scale ||= if @x_scale_type == :band
+                       Geometry::Scale::Band.new(domain: categories, range: category_range)
+                     else
+                       Geometry::Scale::Point.new(domain: categories, range: category_range)
+                     end
+      end
+
+      # Each category's scale position (a band's leading edge).
+      def x_positions
+        x_scale.positions
+      end
+
+      # One category band's width (0 on a point scale).
+      def band_width
+        x_scale.bandwidth
+      end
+
+      # The per-category CENTER - where ticks, vertical grid lines, and the
+      # tooltip's hit columns sit (band centers; point positions verbatim).
+      def x_centers
+        @x_centers ||= if @x_scale_type == :band
+                         half = band_width / 2.0
+                         x_positions.map { |x| x + half }
+                       else
+                         x_positions
+                       end
+      end
+
+      # -- y: numeric domain, auto-niced -----------------------------------------
+
+      # The niced value ticks ([0, 1] when 100%-stacked).
+      def y_ticks
+        @y_ticks ||= if offset == :expand
+                       Geometry::NiceTicks.nice_ticks([0, 1], y_tick_count)
+                     else
+                       Geometry::NiceTicks.nice_ticks(raw_domain, y_tick_count)
+                     end
+      end
+
+      # The niced value domain - the first and last tick.
+      def y_domain
+        [y_ticks.first, y_ticks.last]
+      end
+
+      # The value scale: y in the vertical layout (inverted - SVG y grows
+      # down), x in the horizontal one.
+      def y_scale
+        @y_scale ||= Geometry::Scale::Linear.new(
+          domain: y_domain,
+          range: horizontal? ? [plot_left, plot_right] : [plot_bottom, plot_top]
+        )
+      end
+
+      # The area baseline: the y pixel of 0, clamped into the domain so
+      # an all-positive domain pins the baseline at its bottom edge.
+      def baseline
+        y_scale.call(0.0.clamp(y_domain.first, y_domain.last))
+      end
+
+      # -- per-series points -----------------------------------------------------
+
+      # [{x:, y0:, y1:, value:}] for one series entry - stacked entries ride
+      # their stack group's offsets; independent entries base on the
+      # baseline. NaN values (missing data) flow through as NaN, which the
+      # generators' defined-gap machinery turns into path gaps.
+      #
+      # @param entry [#key] a series entry (key + optional stack id)
+      # @return [Array<Hash>] one orientation-aware point hash per category
+      def points(entry)
+        key = entry.key
+        if entry.stack
+          bands = stacked_bands(entry.stack)[key]
+          bands.each_with_index.map do |(lo, hi), i|
+            point_for(i, key, y_scale.call(lo), y_scale.call(hi))
+          end
+        else
+          @data.each_with_index.map do |_row, i|
+            point_for(i, key, baseline, y_scale.call(value_at(i, key)))
+          end
+        end
+      end
+
+      # -- the tooltip handoff: the embedded coordinates -------------------------
+
+      # Compact per-series pixel coordinates the tooltip controller reads -
+      # no chart math in the browser.
+      def coordinates
+        top_key = horizontal? ? :x1 : :y1
+        band = ({ "x" => x_positions.map { |x| x.round(2) }, "width" => band_width.round(2) } if @x_scale_type == :band)
+        {
+          "layout" => layout.to_s,
+          "categories" => categories,
+          # The category-center axis the tooltip bisects along: x in the
+          # vertical layout, y in the horizontal one.
+          (horizontal? ? "y" : "x") => x_centers.map { |c| c.round(2) },
+          "series" => @series.to_h do |entry|
+            tops = points(entry).map { |p| p[top_key].nan? ? nil : p[top_key].round(2) }
+            [entry.key, tops]
+          end,
+          # PRE-FORMATTED display strings (from the RAW row values, so
+          # integers stay integers) - the controller never formats.
+          "values" => @series.to_h do |entry|
+            [entry.key, @data.map { |row| display_value(row[entry.key]) }]
+          end
+        }.merge(band ? { "band" => band } : {})
+      end
+
+      private
+
+      # Orientation-aware point: vertical = {x, y0, y1}; horizontal =
+      # {y, x0, x1} (values run along x, categories down y).
+      def point_for(index, key, base_px, top_px)
+        value = value_at(index, key)
+        if horizontal?
+          { y: x_centers[index], x0: base_px, x1: top_px, value: value }
+        else
+          { x: x_centers[index], y0: base_px, y1: top_px, value: value }
+        end
+      end
+
+      def value_at(index, key)
+        value = @data[index][key]
+        value.nil? ? Float::NAN : value.to_f
+      end
+
+      def display_value(value)
+        Poetry::Charts.display_value(value)
+      end
+
+      # Stack bands per stack id, memoized: { key => [[lo, hi], ...] }.
+      def stacked_bands(stack_id)
+        @stacked_bands ||= {}
+        @stacked_bands[stack_id] ||= begin
+          keys = @series.select { |entry| entry.stack == stack_id }.map(&:key)
+          stack = Geometry::Stack.new(keys: keys, offset: offset == :expand ? :expand : :none)
+          stack.series(@data).to_h { |series| [series.key, series.points] }
+        end
+      end
+
+      # The raw numeric domain before nicing: [min(0, data), max(data)] -
+      # the default [0, auto] domain, stacked series contributing their
+      # cumulative tops.
+      def raw_domain
+        values = []
+        @series.each do |entry|
+          if entry.stack
+            stacked_bands(entry.stack)[entry.key].each do |lo, hi|
+              values << lo unless lo.nan?
+              values << hi unless hi.nan?
+            end
+          else
+            @data.each_index do |i|
+              value = value_at(i, entry.key)
+              values << value unless value.nan?
+            end
+          end
+        end
+        return [0, 1] if values.empty?
+
+        [[0, values.min].min, values.max]
+      end
+    end
+  end
+end

data/lib/poetry/charts/config.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    # The chart config contract:
+    # series key -> { label:, icon:, color: } or { label:, icon:, theme:
+    # { light:, dark: } }. The config is the SINGLE place series get their
+    # human labels and colors; the container's <style> emission, the tooltip
+    # chrome, and the legend chrome all resolve through it.
+    #
+    # Values land inside a <style> element and inline style attributes, so
+    # every color (and key) is validated against a conservative character
+    # set at wrap time - a config can never smuggle CSS out of its block.
+    #
+    # @example
+    #   config = Poetry::Charts::Config.new(
+    #     revenue: { label: "Revenue", color: "var(--chart-1)" }
+    #   )
+    #   config.label_for("revenue") # => "Revenue"
+    class Config
+      # A series key becomes a --color-<key> custom property.
+      KEY = /\A[a-zA-Z][a-zA-Z0-9_-]*\z/
+      # Any CSS color form (var(--chart-1), #hex, oklch(...), named...) minus
+      # everything that could terminate a declaration or escape the block.
+      COLOR = /\A[^{};<>&"']+\z/
+
+      # The theme map's allowed modes.
+      THEMES = %i[light dark].freeze
+
+      # One validated config entry: a series key with its label, icon,
+      # and flat or themed color.
+      Entry = Data.define(:key, :label, :icon, :color, :theme) do
+        # The per-theme color: the flat color, or the theme map's value.
+        def color_for(theme_name)
+          theme ? theme[theme_name] : color
+        end
+
+        # Whether the entry carries any color (flat or themed).
+        def colored?
+          !!(color || theme)
+        end
+      end
+
+      class << self
+        # Accepts a Config (pass-through) or a Hash keyed by series name.
+        #
+        # @param source [Config, Hash, nil]
+        # @return [Config]
+        def wrap(source)
+          source.is_a?(Config) ? source : new(source || {})
+        end
+      end
+
+      attr_reader :entries
+
+      # Builds and validates entries from a Hash keyed by series name;
+      # a CSS-unsafe key or color raises here, at wrap time.
+      #
+      # @param hash [Hash]
+      def initialize(hash)
+        raise ArgumentError, "chart config must be a Hash, got #{hash.class}" unless hash.is_a?(Hash)
+
+        @entries = hash.map { |key, value| build_entry(key, value || {}) }
+      end
+
+      # The entry for a series key.
+      #
+      # @param key [String, Symbol]
+      # @return [Entry, nil]
+      def [](key)
+        key = key.to_s
+        entries.find { |entry| entry.key == key }
+      end
+
+      # Every series key, in config order.
+      #
+      # @return [Array<String>]
+      def keys
+        entries.map(&:key)
+      end
+
+      # The entries that carry a color (flat or themed) - the set the
+      # container's <style> emission covers, in config order.
+      def color_entries
+        entries.select(&:colored?)
+      end
+
+      # The label for a series key, falling back to the key itself - the
+      # tooltip/legend resolution rule.
+      #
+      # @param key [String, Symbol] the series key
+      # @param fallback [String, nil] preferred over the key when no label is set
+      # @return [String]
+      def label_for(key, fallback = nil)
+        self[key]&.label || fallback || key.to_s
+      end
+
+      # The config back as a plain Hash (label/color/theme per key),
+      # compacted.
+      #
+      # @return [Hash]
+      def to_h
+        entries.to_h do |entry|
+          value = { label: entry.label }.compact
+          value[:color] = entry.color if entry.color
+          value[:theme] = entry.theme if entry.theme
+          [entry.key, value]
+        end
+      end
+
+      private
+
+      def build_entry(key, value)
+        key = key.to_s
+        raise ArgumentError, "chart config key #{key.inspect} is not CSS-safe" unless key.match?(KEY)
+
+        value = value.symbolize_keys
+        color = validate_color!(key, value[:color])
+        theme = validate_theme!(key, value[:theme])
+        raise ArgumentError, "chart config #{key.inspect} sets both color: and theme:" if color && theme
+
+        Entry.new(key:, label: value[:label], icon: value[:icon], color:, theme:)
+      end
+
+      def validate_color!(key, color)
+        return nil if color.nil?
+
+        color = color.to_s
+        unless color.match?(COLOR)
+          raise ArgumentError,
+                "chart config #{key.inspect} color #{color.inspect} is not CSS-safe"
+        end
+
+        color
+      end
+
+      def validate_theme!(key, theme)
+        return nil if theme.nil?
+        raise ArgumentError, "chart config #{key.inspect} theme must be a Hash" unless theme.is_a?(Hash)
+
+        theme = theme.symbolize_keys
+        unknown = theme.keys - THEMES
+        raise ArgumentError, "chart config #{key.inspect} theme has unknown modes #{unknown.inspect}" if unknown.any?
+
+        theme.to_h { |mode, color| [mode, validate_color!(key, color)] }
+      end
+    end
+  end
+end

data/lib/poetry/charts/engine.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module Poetry
+  module Charts
+    # The Rails engine: wires poetry-charts into the host app - component
+    # autoload paths, the Stimulus controllers manifest, the view helper,
+    # preview and asset paths, and the importmap pins. Loading the gem is
+    # the only integration step.
+    #
+    # @example Install via the host Gemfile
+    #   gem "poetry-charts"
+    class Engine < ::Rails::Engine
+      # Standard engine layout: app/components is picked up like poetry-ui's.
+      config.autoload_paths << "#{Poetry::Charts.root}/app/components"
+      config.eager_load_paths << "#{Poetry::Charts.root}/app/components"
+
+      # The charts controllers manifest joins core's catalog, so the
+      # Builder and use_stimulus declarations validate poetry--charts--*
+      # names exactly like core's own (runs before components load -
+      # declarations validate at class-load time).
+      initializer "poetry_charts.controllers_manifest", before: :eager_load! do
+        Poetry::Core::Stimulus::Manifest.register(
+          "#{Poetry::Charts.root}/config/controllers_manifest.json"
+        )
+      end
+
+      # ComponentsHelper lives in app/helpers (Zeitwerk-autoloaded), so it is
+      # NOT loaded at gem-require time. A host that forces ActionView to load
+      # during initialization (an editor gem patching a view helper at
+      # require time) fires the on_load(:action_view) hook right here, before
+      # the engine's app/helpers constant is resolvable - NameError at boot.
+      # Registering the hook from a to_prepare block runs it only once the
+      # autoload paths are wired (and re-runs safely on reload); the same fix
+      # as poetry-ui's. poetry-core's TagHelper avoids it only because it
+      # lives in lib/ and is required eagerly. EngineBootTest guards this.
+      initializer "poetry_charts.helpers" do |app|
+        app.config.to_prepare do
+          ActiveSupport.on_load(:action_view) do
+            include Poetry::Charts::ComponentsHelper
+          end
+        end
+      end
+
+      initializer "poetry_charts.previews" do |app|
+        if app.config.respond_to?(:view_component)
+          app.config.view_component.previews.paths << "#{Poetry::Charts.root}/app/components"
+        end
+      end
+
+      # Lookbook is a dev-only dependency; guard so the engine never crashes
+      # a production (or lean test) host that does not load it (the
+      # poetry-core pattern).
+      initializer "poetry_charts.setup_lookbook" do |app|
+        app.config.lookbook.preview_paths << "#{Poetry::Charts.root}/app/components" if defined?(Lookbook)
+      end
+
+      # Make the client chrome + the motion stylesheet servable by Propshaft.
+      initializer "poetry_charts.assets" do |app|
+        if app.config.respond_to?(:assets)
+          app.config.assets.paths << Poetry::Charts.root.join("app/javascript").to_s
+          app.config.assets.paths << Poetry::Charts.root.join("app/assets/stylesheets").to_s
+        end
+      end
+
+      # The importmap-first JS channel (the poetry-core shape).
+      initializer "poetry_charts.importmap", before: "importmap" do |app|
+        if app.config.respond_to?(:importmap)
+          app.config.importmap.paths << Poetry::Charts.root.join("config/importmap.rb")
+          app.config.importmap.cache_sweepers << Poetry::Charts.root.join("app/javascript")
+        end
+      end
+    end
+  end
+end

data/lib/poetry/charts/geometry/area.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    module Geometry
+      # The area generator: the filled band between a top line (x/x1, y1)
+      # and a baseline (x0, y0), walked forward along the top and
+      # BACKWARD along the buffered baseline per defined-segment (the
+      # x0z/y0z buffers). Stacked areas feed y0/y1 from Stack series;
+      # simple areas use a constant y0 (the axis line).
+      #
+      # @example A simple area over a constant baseline
+      #   Poetry::Charts::Geometry::Area.new(y0: 250.0).path(points)
+      class Area
+        def initialize(x: nil, x1: nil, y0: nil, y1: nil, curve: :linear, defined: nil, digits: 3)
+          @x0 = Line::Accessor.wrap(x) { |d, _i| d[0] }
+          @x1 = x1.nil? ? nil : Line::Accessor.wrap(x1) { |d, _i| d[0] }
+          @y0 = Line::Accessor.wrap(y0) { |_d, _i| 0.0 }
+          @y1 = y1.nil? ? nil : Line::Accessor.wrap(y1) { |d, _i| d[1] }
+          @curve = curve
+          @digits = digits
+          @defined = Line::Accessor.wrap(defined) { |_d, _i| true }
+        end
+
+        # The SVG path for the data (nil when nothing was defined).
+        #
+        # @param data [Enumerable]
+        # @return [String, nil]
+        def path(data)
+          data = data.to_a
+          n = data.length
+          buffer = Path.new(digits: @digits)
+          output = Curve.build(@curve, buffer)
+          defined0 = false
+          x0z = Array.new(n)
+          y0z = Array.new(n)
+          j = 0
+
+          (0..n).each do |i|
+            d = i < n ? data[i] : nil
+            if (!(i < n && @defined.call(d, i))) == defined0
+              defined0 = !defined0
+              if defined0
+                j = i
+                output.area_start
+                output.line_start
+              else
+                output.line_end
+                output.line_start
+                (i - 1).downto(j) { |k| output.point(x0z[k], y0z[k]) }
+                output.line_end
+                output.area_end
+              end
+            end
+            next unless defined0
+
+            x0z[i] = @x0.call(d, i).to_f
+            y0z[i] = @y0.call(d, i).to_f
+            output.point(@x1 ? @x1.call(d, i).to_f : x0z[i],
+                         @y1 ? @y1.call(d, i).to_f : y0z[i])
+          end
+
+          buffer.empty? ? nil : buffer.to_s
+        end
+      end
+    end
+  end
+end