poetry-charts 0.0.2

data/app/components/poetry/charts/area_chart/component.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    # The area chart family.
+    module AreaChart
+      # Renders an area chart - filled trends over an ordered axis,
+      # optionally stacked - as server-computed SVG through the Cartesian
+      # pipeline: the finished chart is in the initial HTML. Slots
+      # compose the whole chart declaratively: grid, axes, series,
+      # legend, tooltip.
+      #
+      # @example Two stacked series with a formatted month axis
+      #   <%= poetry_area_chart(data:, config:, margin: { left: 12, right: 12 }) do |c| %>
+      #     <% c.with_grid %>
+      #     <% c.with_x_axis data_key: :month, tick_formatter: ->(v) { v[0, 3] } %>
+      #     <% c.with_area data_key: :desktop, stack: :a %>
+      #     <% c.with_area data_key: :mobile, stack: :a %>
+      #     <% c.with_legend %>
+      #   <% end %>
+      #
+      # Series colors ride var(--color-<key>) (the Container emission);
+      # per-x pixel coordinates are embedded for the tooltip controller.
+      class Component < Poetry::Core::Component
+        include Poetry::Charts::ChartFamily
+        include Poetry::Charts::TooltipWiring
+        include Poetry::Charts::Motion
+        include Poetry::Charts::Live
+        include Poetry::Charts::ReferenceMarks
+
+        # Projected into the registry and agent surface.
+        AGENT_RULES = [
+          "Compose from slots: with_grid / with_x_axis(data_key:) / with_area(data_key:) / with_legend.",
+          "Stack areas by giving them the same stack: id; offset: :expand makes the stack percent-based.",
+          "Colors come from the config - never set fill/stroke on an area directly.",
+          "gradient: true on an area gets the source's 5%/95% fade fill.",
+          "Charts render complete on the server; the tooltip layer attaches separately.",
+          "Entrance animation is on by default (source parity); animate: false for a static chart. " \
+          "Reduced-motion users always get the finished chart."
+        ].freeze
+
+        # One with_area call's captured series config.
+        Series = Data.define(:key, :stack, :curve, :fill_opacity, :gradient, :stroke_width)
+
+        option :data, ActiveModel::Type::Value.new, required: true,
+                                                    doc: "The rows to plot: an array of hashes, one per x category."
+        option :config, ActiveModel::Type::Value.new, required: true,
+                                                      doc: "The series config - key => { label:, color: } - naming " \
+                                                           "and coloring every series."
+        option :id, :string,
+               doc: "Explicit DOM id token, stable across renders; otherwise the chart gets a unique per-render id."
+        option :width, :integer, default: 640,
+                                 doc: "ViewBox width in pixels; the rendered chart scales to its container."
+        option :height, :integer, default: 360, doc: "ViewBox height in pixels."
+        option :margin, ActiveModel::Type::Value.new,
+               doc: "Plot margin overrides ({ top:, right:, bottom:, left: }), merged over the defaults."
+        option :offset, :symbol, default: :none,
+                                 doc: "Stack baseline mode - :expand normalizes each stack to percentages."
+        option :label, :string,
+               doc: "Accessible name for the chart SVG; defaults to one built from the configured series."
+
+        motion_options
+        live_option
+
+        validates :offset, inclusion: { in: Cartesian::OFFSETS }
+
+        part "chart-svg", "The chart canvas (<svg>) - server-computed geometry in a fixed viewBox; " \
+                          "role=img, or the focusable role=application accessibilityLayer when the " \
+                          "tooltip attaches",
+             states: {
+               "data-animate" => "present when animate (the default) - the motion stylesheet and " \
+                                 "controller key the entrance off it",
+               "data-motion" => { condition: "runtime - the motion rig stamps the animation " \
+                                             "lifecycle (entrance/morph, then settled)",
+                                  values: %w[entrance morph settled] }
+             },
+             vars: {
+               "--poetry-motion-duration" => "the entrance/morph duration (animation_duration, ms)",
+               "--poetry-motion-easing" => "the animation easing keyword (animation_easing)",
+               "--poetry-motion-delay" => "the pre-animation hold (animation_begin, ms)"
+             }
+        part "chart-motion-reveal", "The entrance clipPath rect (the ported area reveal) - the " \
+                                    "motion stylesheet scales it 0 -> 1; only when animate"
+        part "chart-grid", "The gridline group (with_grid) - horizontal and/or vertical rules " \
+                           "across the plot"
+        part "chart-cursor", "The hover cursor, hidden until the tooltip controller positions " \
+                             "and reveals it at the active index - a vertical rule or a " \
+                             "translucent band rect (bar charts)"
+        part "chart-areas", "The area-mark group - a fill path plus top-curve stroke per series, " \
+                            "clipped by the reveal rect while animating"
+        part "chart-area", "One series' fill path (var(--color-<key>) or its gradient)",
+             states: { "data-key" => "the series key" }
+        part "chart-area-stroke", "One series' top-curve stroke path (the source strokes the " \
+                                  "curve, never the area outline)",
+             states: { "data-key" => "the series key" }
+        part "chart-active-dots", "The hover-marker group (with_tooltip) - pre-rendered hidden " \
+                                  "circles for every series x index"
+        part "chart-active-dot", "One hover marker - display=none until the tooltip controller " \
+                                 "reveals the active index's dot",
+             states: {
+               "data-key" => "the series key",
+               "data-index" => "the datum index",
+               "data-active" => "runtime - rides the marker while its index is the active one"
+             }
+        part "chart-x-axis", "The x-axis tick-label group (with_x_axis)"
+        part "chart-y-axis", "The y-axis tick-label group (with_y_axis)"
+        part "chart-coordinates", "The embedded per-index geometry payload " \
+                                  "(<script type=application/json>) the tooltip controller " \
+                                  "reads - zero chart math in the browser"
+
+        renders_many :areas,
+                     doc: "An area series bound to data_key:. Areas sharing a stack: id pile up; gradient: true " \
+                          "fades the fill; curve: picks the interpolation.",
+                     renders: lambda { |data_key:, stack: nil, curve: :natural, fill_opacity: 0.4,
+                                       gradient: false, stroke_width: 1|
+                       raise ArgumentError, "unknown curve #{curve.inspect}" unless CURVES.include?(curve.to_sym)
+
+                       (@series_entries ||= []) << Series.new(key: data_key.to_s, stack:, curve: curve.to_sym,
+                                                              fill_opacity:, gradient:, stroke_width:)
+                       nil
+                     }
+
+        include Poetry::Charts::CartesianFamily
+
+        # The captured Series configs, forcing lazy slot evaluation.
+        # @api private
+        def series_entries
+          areas? # force slot evaluation
+          @series_entries ||= []
+        end
+
+        # The chart's cartesian geometry, built once per render.
+        # @api private
+        def cartesian
+          @cartesian ||= Cartesian.new(
+            data: data,
+            series: series_entries,
+            width: width,
+            height: height,
+            x_key: x_axis_config&.data_key,
+            margin: live_margin,
+            category_axis: x_axis?,
+            value_axis: y_axis?,
+            # The hidden implicit Y axis still drives the scale: default
+            # tick count 5; an explicit with_y_axis supplies its own.
+            y_tick_count: y_axis_config&.tick_count || 5,
+            offset: offset
+          )
+        end
+
+        # One series' fill path (the area between its baseline and top
+        # curve).
+        # @api private
+        def series_path(entry)
+          points = cartesian.points(entry)
+          Geometry::Area.new(
+            x: ->(p, _i) { p[:x] },
+            y0: ->(p, _i) { p[:y0] },
+            y1: ->(p, _i) { p[:y1] },
+            curve: entry.curve,
+            defined: ->(p, _i) { !p[:value].nan? }
+          ).path(points)
+        end
+
+        # The stroke rides a SEPARATE path along the top curve only -
+        # stroking the fill path's outline would also draw the left,
+        # right, and baseline edges.
+        # @api private
+        def series_stroke_path(entry)
+          points = cartesian.points(entry)
+          Geometry::Line.new(
+            x: ->(p, _i) { p[:x] },
+            y: ->(p, _i) { p[:y1] },
+            curve: entry.curve,
+            defined: ->(p, _i) { !p[:value].nan? }
+          ).path(points)
+        end
+
+        # One x tick's label, through the slot's formatter when given.
+        # @api private
+        def x_tick_label(category)
+          formatter = x_axis_config&.tick_formatter
+          formatter ? formatter.call(category).to_s : category.to_s
+        end
+
+        # One y tick's label, through the slot's formatter when given.
+        # @api private
+        def y_tick_label(tick)
+          formatter = y_axis_config&.tick_formatter
+          formatter ? formatter.call(tick).to_s : Geometry.js_number(tick.to_f)
+        end
+
+        # The per-series gradient def's id, scoped by the chart id.
+        # @api private
+        def gradient_id(entry)
+          "#{chart_id}-fill-#{entry.key}"
+        end
+
+        # The series fill: its gradient url when gradient:, else its
+        # config color var.
+        # @api private
+        def fill_for(entry)
+          entry.gradient ? "url(##{gradient_id(entry)})" : "var(--color-#{entry.key})"
+        end
+
+        # ChartFamily#svg_label's chart-type lead-in.
+        # @api private
+        def svg_label_prefix = "Area chart"
+
+        # The embedded per-index geometry payload the tooltip controller
+        # reads.
+        # @api private
+        def coordinates_json
+          cartesian.coordinates.to_json
+        end
+
+        # -- live mode ---------------------------------------------------
+
+        # The chart type in the live spec.
+        # @api private
+        def live_type = :area
+
+        # The series list serialized into the live spec.
+        # @api private
+        def live_series
+          series_entries.map { |e| { data_key: e.key, stack: e.stack, curve: e.curve }.compact }
+        end
+
+        # The axis config serialized into the live spec.
+        # @api private
+        def live_axes
+          axes = {}
+          axes[:x] = { data_key: x_axis_config.data_key } if x_axis_config&.data_key
+          axes[:y] = { tick_count: y_axis_config.tick_count } if y_axis_config
+          axes
+        end
+
+        # The x scale kind the live renderer rebuilds.
+        # @api private
+        def live_x_scale_type = :point
+        # Whether the live frame renders a category axis.
+        # @api private
+        def live_category_axis? = x_axis?
+
+        private :cartesian, :series_path, :series_stroke_path, :x_tick_label, :y_tick_label
+        private :gradient_id, :fill_for, :svg_label_prefix, :coordinates_json, :live_type, :live_series, :live_axes
+        private :live_x_scale_type, :live_category_axis?
+      end
+    end
+  end
+end

data/app/components/poetry/charts/area_chart/preview.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    module AreaChart
+      # The area family across its variants: default (natural),
+      # linear, step, stacked, percent-stacked, gradient, legend, and the
+      # visible-axes variant. Shared sample data (visitors by month).
+      class Preview < Poetry::Core::Preview::Base
+        DATA = [
+          { month: "January", desktop: 186, mobile: 80 },
+          { month: "February", desktop: 305, mobile: 200 },
+          { month: "March", desktop: 237, mobile: 120 },
+          { month: "April", desktop: 73, mobile: 190 },
+          { month: "May", desktop: 209, mobile: 130 },
+          { month: "June", desktop: 214, mobile: 140 }
+        ].freeze
+
+        ONE = { desktop: { label: "Desktop", color: "var(--chart-1)" } }.freeze
+        TWO = {
+          desktop: { label: "Desktop", color: "var(--chart-1)" },
+          mobile: { label: "Mobile", color: "var(--chart-2)" }
+        }.freeze
+
+        MARGIN = { left: 12, right: 12 }.freeze
+
+        def default
+          simple_chart(id: "area-default", tooltip: true)
+        end
+
+        def linear
+          simple_chart(id: "area-linear", curve: :linear)
+        end
+
+        def step
+          simple_chart(id: "area-step", curve: :step)
+        end
+
+        def stacked
+          two_series_chart(id: "area-stacked")
+        end
+
+        def stacked_expanded
+          two_series_chart(id: "area-expand", offset: :expand)
+        end
+
+        def gradient
+          two_series_chart(id: "area-gradient", gradient: true)
+        end
+
+        def legend
+          two_series_chart(id: "area-legend", &:with_legend)
+        end
+
+        def axes
+          two_series_chart(id: "area-axes") { |chart| chart.with_y_axis(tick_count: 3) }
+        end
+
+        # The full live-window surface in one frame (see BarChart::Preview#
+        # live_window) - no tick_formatter: lambdas cannot ride the payload.
+        def live_window
+          render_component(data: DATA, config: ONE, id: "area-live", margin: MARGIN, live: true,
+                           zoom: true, sync: "area-demo") do |chart|
+            chart.with_grid
+            chart.with_x_axis(data_key: :month)
+            chart.with_area(data_key: :desktop)
+            chart.with_tooltip(indicator: :line)
+            chart.with_brush
+          end
+        end
+
+        private
+
+        def simple_chart(id:, curve: :natural, tooltip: false)
+          render_component(data: DATA, config: ONE, id: id, margin: MARGIN) do |chart|
+            chart.with_grid
+            chart.with_x_axis(data_key: :month, tick_formatter: ->(v) { v[0, 3] })
+            chart.with_area(data_key: :desktop, curve: curve)
+            chart.with_tooltip(indicator: :line) if tooltip
+          end
+        end
+
+        def two_series_chart(id:, offset: :none, gradient: false)
+          render_component(data: DATA, config: TWO, id: id, offset: offset, margin: MARGIN) do |chart|
+            chart.with_grid
+            chart.with_x_axis(data_key: :month, tick_formatter: ->(v) { v[0, 3] })
+            chart.with_area(data_key: :mobile, stack: :a, gradient: gradient)
+            chart.with_area(data_key: :desktop, stack: :a, gradient: gradient)
+            yield chart if block_given?
+          end
+        end
+      end
+    end
+  end
+end

data/app/components/poetry/charts/area_chart/style.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    module AreaChart
+      # The cartesian chart chrome, riding the SHARED cn-chart-* theme
+      # rules - what would otherwise be container-level descendant
+      # overrides lands as direct classes on parts poetry owns. Series
+      # fill/stroke are var(--color-<key>) ATTRIBUTES, never classes.
+      class Style < Poetry::Core::Style
+        base ""
+
+        element :frame, "contents"
+        element :svg, "w-full min-h-0 flex-1"
+        element :grid_line, "cn-chart-grid-line"
+        element :tick, "cn-chart-tick"
+        element :cursor_line, "cn-chart-cursor-line"
+        element :cursor_band, "cn-chart-cursor-band"
+        element :reference_line, "cn-chart-reference-line"
+        element :reference_area, "cn-chart-reference-area"
+        element :reference_dot, "cn-chart-reference-dot"
+        element :error_bar, "cn-chart-error-bar"
+        element :brush_track, "cn-chart-brush-track"
+        element :brush_window, "cn-chart-brush-window"
+        element :brush_handle, "cn-chart-brush-handle"
+      end
+    end
+  end
+end

data/app/components/poetry/charts/bar_chart/component.html.erb

@@ -0,0 +1,95 @@
+<%= render Poetry::Charts::Container::Component.new(config: chart_config, id: chart_id.delete_prefix("chart-")) do %>
+  <%= content_tag(:div, frame_attributes.merge("class" => css(:frame))) do %>
+  <svg viewBox="0 0 <%= width %> <%= height %>" class="<%= css(:svg) %>" data-slot="chart-svg" aria-label="<%= svg_label %>" preserveAspectRatio="xMidYMid meet" <%= tag.attributes(svg_interaction_attributes) %>>
+    <% if grid? %>
+      <g data-slot="chart-grid" aria-hidden="true">
+        <% if horizontal? %>
+          <%# Value ticks run along X in the horizontal layout. %>
+          <% if grid_config.vertical %>
+            <% cartesian.y_ticks.each do |tick| %>
+              <line class="<%= css(:grid_line) %>" x1="<%= fnum(cartesian.y_scale.call(tick)) %>" x2="<%= fnum(cartesian.y_scale.call(tick)) %>" y1="<%= fnum(cartesian.plot_top) %>" y2="<%= fnum(cartesian.plot_bottom) %>" />
+            <% end %>
+          <% end %>
+          <% if grid_config.horizontal %>
+            <% cartesian.x_centers.each do |y| %>
+              <line class="<%= css(:grid_line) %>" x1="<%= fnum(cartesian.plot_left) %>" x2="<%= fnum(cartesian.plot_right) %>" y1="<%= fnum(y) %>" y2="<%= fnum(y) %>" />
+            <% end %>
+          <% end %>
+        <% else %>
+          <% if grid_config.horizontal %>
+            <% cartesian.y_ticks.each do |tick| %>
+              <line class="<%= css(:grid_line) %>" x1="<%= fnum(cartesian.plot_left) %>" x2="<%= fnum(cartesian.plot_right) %>" y1="<%= fnum(cartesian.y_scale.call(tick)) %>" y2="<%= fnum(cartesian.y_scale.call(tick)) %>" />
+            <% end %>
+          <% end %>
+          <% if grid_config.vertical %>
+            <% cartesian.x_centers.each do |x| %>
+              <line class="<%= css(:grid_line) %>" x1="<%= fnum(x) %>" x2="<%= fnum(x) %>" y1="<%= fnum(cartesian.plot_top) %>" y2="<%= fnum(cartesian.plot_bottom) %>" />
+            <% end %>
+          <% end %>
+        <% end %>
+      </g>
+    <% end %>
+    <%= cursor_svg(:band) %>
+    <g data-slot="chart-bars">
+      <% series_entries.each do |entry| %>
+        <g data-slot="chart-bar-series" data-key="<%= entry.key %>">
+          <% cells(entry).each do |cell| %>
+            <path data-slot="chart-bar" data-key="<%= entry.key %>" data-index="<%= cell[:index] %>" d="<%= bar_path(entry, cell) %>" fill="<%= cell_fill(entry, cell) %>"<% if animate? %> data-motion-origin="<%= motion_origin(cell) %>"<% end %><% if active?(entry, cell) %> fill-opacity="0.8" stroke="<%= cell_fill(entry, cell) %>" stroke-width="<%= entry.stroke_width %>" stroke-dasharray="4" stroke-dashoffset="4" data-active=""<% end %> />
+          <% end %>
+        </g>
+        <% if entry.error_key && !horizontal? %>
+          <g data-slot="chart-error-bars" data-key="<%= entry.key %>" aria-hidden="true">
+            <% cells(entry).each do |cell| %>
+              <% range = error_range(cell[:row], entry.error_key, cell[:value]) %>
+              <% if range %>
+                <path class="<%= css(:error_bar) %>" d="<%= error_bar_path(cell[:x] + (cell[:width] / 2.0), cartesian.y_scale.call(range[0]), cartesian.y_scale.call(range[1]), entry.error_width) %>" fill="none" />
+              <% end %>
+            <% end %>
+          </g>
+        <% end %>
+        <% if entry.labels %>
+          <g data-slot="chart-labels" data-key="<%= entry.key %>">
+            <% cells(entry).each do |cell| %>
+              <text class="<%= css(:label) %>" x="<%= fnum(cell[:x] + (cell[:width] / 2.0)) %>" y="<%= fnum(cell[:y] - 12) %>" text-anchor="middle"><%= cell_label(entry, cell) %></text>
+            <% end %>
+          </g>
+        <% end %>
+      <% end %>
+    </g>
+    <%= reference_marks_svg %>
+    <% if horizontal? %>
+      <% if y_axis? %>
+        <%# The category labels down the left strip (the horizontal/mixed blocks). %>
+        <g data-slot="chart-y-axis">
+          <% cartesian.categories.each_with_index do |category, i| %>
+            <text class="<%= css(:tick) %>" x="<%= fnum(cartesian.plot_left - y_axis_config.tick_margin) %>" y="<%= fnum(cartesian.x_centers[i]) %>" dy="0.355em" text-anchor="end"><%= category_tick_label(category) %></text>
+          <% end %>
+        </g>
+      <% end %>
+    <% else %>
+      <% if x_axis? %>
+        <g data-slot="chart-x-axis">
+          <% cartesian.categories.each_with_index do |category, i| %>
+            <text class="<%= css(:tick) %>" x="<%= fnum(cartesian.x_centers[i]) %>" y="<%= fnum(cartesian.plot_bottom + x_axis_config.tick_margin) %>" dy="0.71em" text-anchor="middle"><%= x_tick_label(category) %></text>
+          <% end %>
+        </g>
+      <% end %>
+      <% if y_axis? %>
+        <g data-slot="chart-y-axis">
+          <% cartesian.y_ticks.each do |tick| %>
+            <text class="<%= css(:tick) %>" x="<%= fnum(cartesian.plot_left - y_axis_config.tick_margin) %>" y="<%= fnum(cartesian.y_scale.call(tick)) %>" dy="0.355em" text-anchor="end"><%= y_tick_label(tick) %></text>
+          <% end %>
+        </g>
+      <% end %>
+    <% end %>
+    <%= brush_svg %>
+    <%= zoom_selection_svg %>
+  </svg>
+  <% if legend? %>
+    <%= render legend_component %>
+  <% end %>
+  <% if tooltip? %><%= render tooltip_layer_component %><% end %>
+  <script type="application/json" data-slot="chart-coordinates" <%= tag.attributes(stimulus_attributes_for(:coordinates)) %>><%= script_json(coordinates_json) %></script>
+  <% if live? %><script type="application/json" data-slot="chart-live-payload" <%= tag.attributes(stimulus_attributes_for(:live_payload)) %>><%= script_json(live_payload_json) %></script>
+<% end %>  <% end %>
+<% end %>