poetry-charts 0.0.2

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

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    # The pie chart family.
+    module PieChart
+      # Renders a pie or donut chart as server-computed polar sectors.
+      # Slices color from their row's fill key, the donut hole comes from
+      # inner_radius, stacked pies nest two rings with their own data,
+      # and the center label is plain SVG text. The 250x250 viewBox pairs
+      # with a square, max-height-capped container, so absolute-pixel
+      # radii (inner_radius: 60, active pop-outs of +10) keep the same
+      # proportion everywhere. Slices meet flush by default;
+      # stroke_width: N opts into var(--background) separators, which
+      # hold up in dark mode where a hard-coded white would not.
+      #
+      # @example A donut with a tooltip
+      #   <%= poetry_chart :pie, data: browsers, config: config do |c| %>
+      #     <% c.with_pie data_key: :visitors, name_key: :browser, inner_radius: 60 %>
+      #     <% c.with_tooltip %>
+      #   <% end %>
+      class Component < Poetry::Core::Component
+        include Poetry::Charts::ChartFamily
+        include Poetry::Charts::TooltipWiring
+        include Poetry::Charts::Motion
+
+        # Projected into the registry and agent surface.
+        AGENT_RULES = [
+          "Rows carry their slice color in a fill key (var(--color-<name>)); the config maps names to labels.",
+          "inner_radius: 60 makes the donut; with_center_label(title:, subtitle:) fills the hole.",
+          "Stacked pies: two with_pie slots with their own data: and non-overlapping radii.",
+          "active_index: pops one slice out by 10px (the donut-active look).",
+          "The tooltip walks slices by hover AND arrow keys (role=application when attached).",
+          "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_pie call's captured series config.
+        Series = Data.define(:data, :data_key, :name_key, :inner_radius, :outer_radius,
+                             :padding_angle, :stroke_width, :color_key, :labels, :label_key,
+                             :active_index, :active_grow)
+
+        option :data, ActiveModel::Type::Value.new,
+               doc: "Default rows for pies that don't bring their own data: - one hash per slice."
+        option :config, ActiveModel::Type::Value.new, required: true,
+                                                      doc: "The series config - name => { label:, color: } - naming " \
+                                                           "and coloring the slices."
+        option :id, :string,
+               doc: "Explicit DOM id token, stable across renders; otherwise the chart gets a unique per-render id."
+        option :width, :integer, default: 250,
+                                 doc: "ViewBox width in pixels; the rendered chart scales to its container."
+        option :height, :integer, default: 250, doc: "ViewBox height in pixels."
+        option :margin, ActiveModel::Type::Value.new,
+               doc: "Margin overrides ({ top:, right:, bottom:, left: }), merged over the slim polar default."
+        option :label, :string,
+               doc: "Accessible name for the chart SVG; defaults to one built from the configured series."
+
+        motion_options(delay: 400)
+
+        part "chart-svg", "The chart canvas (<svg>) - the aria-label surface, the tooltip's " \
+                          "focus/keyboard surface (role=application when it attaches), and " \
+                          "the motion rig's mount",
+             states: {
+               "data-animate" => "when animate (the default) - the entrance tier's flag the " \
+                                 "motion stylesheet and controller key off",
+               "data-motion" => { condition: "runtime, when animate - the motion engine's lifecycle stamp",
+                                  values: %w[entrance morph settled] }
+             },
+             vars: {
+               "--poetry-motion-delay" => "the motion rig's entrance delay (animation_begin)",
+               "--poetry-motion-duration" => "the motion rig's entrance duration (animation_duration)",
+               "--poetry-motion-easing" => "the motion rig's easing keyword (animation_easing)"
+             }
+        part "chart-pie", "One pie's slice group (<g>) - a ring per with_pie slot",
+             states: { "data-key" => "always - the series key" }
+        part "chart-pie-sector", "One slice (<path>) - fill from its row's color, popped out when active",
+             states: {
+               "data-key" => "always - the series key",
+               "data-index" => "on the first pie's slices - the datum index the tooltip walks",
+               "data-active" => "the active slice - server-rendered via active_index:, and reflected " \
+                                "onto the hovered/arrow-keyed index by the tooltip controller at runtime",
+               "data-motion-group" => "when animate - the motion rig's sweep group (one per ring)",
+               "data-motion-sector" => "when animate - the motion rig's server-computed sector params " \
+                                       "for the fan-out sweep"
+             }
+        part "chart-labels", "A series' value labels (<g> of <text>, aria-hidden), rendered when " \
+                             "the series opts into labels",
+             states: { "data-key" => "always - the series key" }
+        part "chart-center-label", "The center text (<text>) - title tspan plus optional subtitle " \
+                                   "filling the chart's middle"
+        part "chart-coordinates", "The embedded JSON payload (<script>) the tooltip controller " \
+                                  "reads - per-category anchors and pre-formatted values, zero " \
+                                  "chart math in the browser"
+
+        renders_many :pies,
+                     doc: "One ring of slices reading data_key: values and name_key: slice names. inner_radius: " \
+                          "makes the donut; padding_angle: spaces the slices; active_index: pops one out by " \
+                          "active_grow: pixels.",
+                     renders: lambda { |data_key:, data: nil, name_key: :name, inner_radius: 0,
+                                      outer_radius: "80%", padding_angle: 0, stroke_width: 0,
+                                      color_key: :fill, labels: nil, label_key: nil,
+                                      active_index: nil, active_grow: 10|
+                       (@series_entries ||= []) << Series.new(data: data, data_key: data_key.to_s,
+                                                              name_key: name_key.to_s, inner_radius:,
+                                                              outer_radius:, padding_angle:, stroke_width:,
+                                                              color_key: color_key&.to_s, labels: labels&.to_sym,
+                                                              label_key: label_key&.to_s, active_index:, active_grow:)
+                       nil
+                     }
+        # ActiveSupport singularizes "pies" to "py" - give the grammar its
+        # real name.
+        alias with_pie with_py
+
+        renders_one :center_label,
+                    doc: "The donut-hole text: a title line plus an optional subtitle.",
+                    renders: lambda { |title:, subtitle: nil|
+                      @center_label_config = { title: title, subtitle: subtitle }
+                      nil
+                    }
+
+        renders_one :legend,
+                    doc: "The legend row: align:, items:, and hide_icon:.",
+                    renders: lambda { |**options|
+                      @legend_config = options
+                      nil
+                    }
+
+        renders_one :tooltip,
+                    doc: "The hover tooltip; the slice name carries the label, so hide_label defaults on.",
+                    renders: lambda { |**options|
+                      @tooltip_config = { hide_label: true }.merge(options)
+                      nil
+                    }
+
+        # The polar chassis: margin/plot/center geometry plus the
+        # per-slice pointerover hit; the single-series tooltip chrome and
+        # payload ride the polar_* hooks below.
+        include Poetry::Charts::PolarFamily
+        include Poetry::Charts::PolarFamily::SingleSeriesTooltip
+
+        # The captured Series configs, forcing lazy slot evaluation.
+        # @api private
+        def series_entries
+          pies? # force slot evaluation (slots evaluate lazily)
+          @series_entries ||= []
+        end
+
+        # The center-label slot's captured config, forcing lazy slot
+        # evaluation.
+        # @api private
+        def center_label_config
+          center_label?
+          @center_label_config
+        end
+
+        # -- geometry ---------------------------------------------------------
+
+        # Memoized per SLOT (object identity), never per data_key: two rings
+        # may share a data_key with different data:, and a key-keyed memo
+        # would silently render the first ring's rows twice.
+        # @api private
+        def rows(entry)
+          @rows ||= {}.compare_by_identity
+          @rows[entry] ||= (entry.data || data || []).map { |row| row.to_h.transform_keys(&:to_s) }
+        end
+
+        # One computed slice: its sector geometry plus name, value, and
+        # fill.
+        Slice = Data.define(:index, :name, :value, :fill, :path, :mid_angle, :middle_radius, :label_point,
+                            :inner, :outer, :start_angle, :end_angle)
+
+        # Slot-identity memo, matching rows (a shared data_key must not
+        # collapse two rings into one geometry).
+        # @api private
+        def slices(entry)
+          @slices ||= {}.compare_by_identity
+          @slices[entry] ||= begin
+            entry_rows = rows(entry)
+            values = entry_rows.map { |row| row[entry.data_key] }
+            max = Polar.max_radius(plot[:width], plot[:height])
+            inner = Polar.percent_value(entry.inner_radius, max, 0)
+            outer = Polar.percent_value(entry.outer_radius, max, max * 0.8)
+
+            Polar.pie_sectors(values, padding_angle: entry.padding_angle).each_with_index.filter_map do |sector, i|
+              next if sector[:start_angle] == sector[:end_angle] && entry_rows.length != 1
+
+              grown = entry.active_index == i ? outer + entry.active_grow : outer
+              middle_radius = (inner + grown) / 2.0
+              Slice.new(
+                index: i,
+                name: entry_rows[i][entry.name_key].to_s,
+                value: sector[:value],
+                fill: slice_fill(entry, entry_rows[i]),
+                path: Polar.sector_path(cx: cx, cy: cy, inner_radius: inner, outer_radius: grown,
+                                        start_angle: sector[:start_angle], end_angle: sector[:end_angle]),
+                mid_angle: sector[:mid_angle],
+                middle_radius: middle_radius,
+                label_point: Polar.polar_to_cartesian(cx, cy, middle_radius, sector[:mid_angle]),
+                inner: inner,
+                outer: grown,
+                start_angle: sector[:start_angle],
+                end_angle: sector[:end_angle]
+              )
+            end
+          end
+        end
+
+        # A slice's fill: the color_key row value (CSS-validated), else
+        # the config color for its name, else the series color var.
+        # @api private
+        def slice_fill(entry, row)
+          color = row[entry.color_key].to_s if entry.color_key
+          if color.present?
+            raise ArgumentError, "slice fill #{color.inspect} is not CSS-safe" unless color.match?(Config::COLOR)
+
+            color
+          else
+            name = row[entry.name_key].to_s
+            chart_config[name]&.color || "var(--color-#{entry.data_key})"
+          end
+        end
+
+        # Named labels resolve through the config (raw "chrome" ->
+        # "Chrome"), the same lookup the tooltip and legend already do.
+        # @api private
+        def slice_label(entry, slice)
+          return slice.value.to_i.to_s unless entry.label_key
+
+          raw = rows(entry)[slice.index][entry.label_key].to_s
+          chart_config.label_for(raw, raw)
+        end
+
+        # -- the tooltip payload (polar shape) ---------------------------------
+
+        # The SingleSeriesTooltip hooks: the FIRST pie's slices are the
+        # items, anchored at their label points; values read that pie's
+        # own rows.
+        # @api private
+        def polar_items(entry) = slices(entry)
+        # Where the tooltip anchors on one slice.
+        # @api private
+        def polar_anchor(slice) = slice.label_point
+        # The rows the tooltip values read from.
+        # @api private
+        def polar_value_rows(entry) = rows(entry)
+
+        # ChartFamily#svg_label's chart-type lead-in.
+        # @api private
+        def svg_label_prefix = "Pie chart"
+
+        private :center_label_config, :rows, :slices, :slice_fill, :slice_label, :polar_items
+        private :polar_anchor, :polar_value_rows, :svg_label_prefix
+      end
+    end
+  end
+end

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

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    module PieChart
+      # The pie family across its variants: simple, donut,
+      # donut-with-center-text, label-list (names inside slices), legend,
+      # stacked (two nested rings), and the popped active slice.
+      class Preview < Poetry::Core::Preview::Base
+        CONFIG = {
+          visitors: { label: "Visitors" },
+          chrome: { label: "Chrome", color: "var(--chart-1)" },
+          safari: { label: "Safari", color: "var(--chart-2)" },
+          firefox: { label: "Firefox", color: "var(--chart-3)" },
+          edge: { label: "Edge", color: "var(--chart-4)" },
+          other: { label: "Other", color: "var(--chart-5)" }
+        }.freeze
+
+        DATA = [
+          { browser: "chrome", visitors: 275, fill: "var(--color-chrome)" },
+          { browser: "safari", visitors: 200, fill: "var(--color-safari)" },
+          { browser: "firefox", visitors: 187, fill: "var(--color-firefox)" },
+          { browser: "edge", visitors: 173, fill: "var(--color-edge)" },
+          { browser: "other", visitors: 90, fill: "var(--color-other)" }
+        ].freeze
+
+        # The stacked block's second ring: desktop vs mobile by month.
+        MONTH_DATA = [
+          { month: "january", desktop: 186, fill: "var(--color-january)" },
+          { month: "february", desktop: 305, fill: "var(--color-february)" },
+          { month: "march", desktop: 237, fill: "var(--color-march)" }
+        ].freeze
+
+        STACKED_CONFIG = CONFIG.merge(
+          desktop: { label: "Desktop" },
+          january: { label: "January", color: "var(--chart-1)" },
+          february: { label: "February", color: "var(--chart-2)" },
+          march: { label: "March", color: "var(--chart-3)" }
+        ).freeze
+
+        def simple
+          render_component(data: DATA, config: CONFIG, id: "pie-simple") do |chart|
+            chart.with_pie(data_key: :visitors, name_key: :browser)
+            chart.with_tooltip
+          end
+        end
+
+        def donut
+          render_component(data: DATA, config: CONFIG, id: "pie-donut") do |chart|
+            chart.with_pie(data_key: :visitors, name_key: :browser, inner_radius: 60)
+            chart.with_tooltip
+          end
+        end
+
+        def donut_text
+          render_component(data: DATA, config: CONFIG, id: "pie-donut-text") do |chart|
+            chart.with_pie(data_key: :visitors, name_key: :browser, inner_radius: 60)
+            chart.with_center_label(title: "925", subtitle: "Visitors")
+          end
+        end
+
+        def label_list
+          render_component(data: DATA, config: CONFIG, id: "pie-label-list") do |chart|
+            chart.with_pie(data_key: :visitors, name_key: :browser, labels: :list, label_key: :browser)
+          end
+        end
+
+        def legend
+          render_component(data: DATA, config: CONFIG, id: "pie-legend") do |chart|
+            chart.with_pie(data_key: :visitors, name_key: :browser)
+            chart.with_legend
+          end
+        end
+
+        def stacked
+          render_component(config: STACKED_CONFIG, id: "pie-stacked") do |chart|
+            chart.with_pie(data: DATA, data_key: :visitors, name_key: :browser, outer_radius: 60)
+            chart.with_pie(data: MONTH_DATA, data_key: :desktop, name_key: :month,
+                           inner_radius: 70, outer_radius: 90)
+          end
+        end
+
+        def donut_active
+          render_component(data: DATA, config: CONFIG, id: "pie-donut-active") do |chart|
+            chart.with_pie(data_key: :visitors, name_key: :browser, inner_radius: 60, active_index: 0)
+          end
+        end
+
+        # A sync group member: the sync value the stimulus contract
+        # holds to the DOM.
+        def synced
+          render_component(data: DATA, config: CONFIG, id: "pie-synced", sync: "pie-demo") do |chart|
+            chart.with_pie(data_key: :visitors, name_key: :browser)
+            chart.with_tooltip
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    module PieChart
+      # The polar chrome on the cn-chart-* theme rules: inside labels
+      # ride fill-background, the donut center label keeps its 3xl type.
+      class Style < Poetry::Core::Style
+        base ""
+
+        element :frame, "contents"
+        element :svg, "w-full min-h-0 flex-1"
+        element :inside_label, "cn-chart-inside-label"
+        element :center_title, "cn-chart-center-title"
+        element :center_subtitle, "cn-chart-center-subtitle"
+      end
+    end
+  end
+end

data/app/components/poetry/charts/polar_family.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    # The polar family chassis (pie/radar/radial): the shared margin +
+    # plot/center geometry, and the per-sector pointer hit - polar marks
+    # are hit by pointerover on the marked sector/wedge, not bisect, so
+    # the svg gains the enter action after TooltipWiring's pointer/
+    # keyboard set (include order is emission order - include this after
+    # TooltipWiring).
+    #
+    # @example Adding the polar chassis to a family
+    #   class GaugeChart::Component < Poetry::Core::Component
+    #     include Poetry::Charts::ChartFamily
+    #     include Poetry::Charts::TooltipWiring
+    #     include Poetry::Charts::PolarFamily
+    #     include Poetry::Charts::PolarFamily::SingleSeriesTooltip
+    #   end
+    module PolarFamily
+      # The default polar margin - a slim, even inset on all sides.
+      MARGIN = { top: 5, right: 5, bottom: 5, left: 5 }.freeze
+
+      def self.included(base)
+        base.use_stimulus do
+          on :svg do
+            controller(TooltipWiring::CONTROLLER, if: :tooltip?) { action :enter, on: :pointerover }
+          end
+        end
+      end
+
+      # The margin-inset plot rect the polar geometry centers in.
+      # @api private
+      def plot
+        @plot ||= begin
+          m = MARGIN.merge((margin || {}).to_h.symbolize_keys)
+          { left: m[:left].to_f, top: m[:top].to_f,
+            width: width - m[:left] - m[:right], height: height - m[:top] - m[:bottom] }
+        end
+      end
+
+      # The polar center's x coordinate.
+      # @api private
+      def cx = plot[:left] + (plot[:width] / 2.0)
+      # The polar center's y coordinate.
+      # @api private
+      def cy = plot[:top] + (plot[:height] / 2.0)
+
+      # The single-series polar tooltip (pie/radial): the FIRST series
+      # drives the chrome, and per-index names/colors retint the one row.
+      # Families supply polar_items (the sector geometry), polar_anchor
+      # (where the tooltip anchors on one item), and polar_value_rows (the
+      # rows the values read from). Radar keeps TooltipWiring's
+      # multi-series chrome and its own payload, so it includes
+      # PolarFamily alone.
+      module SingleSeriesTooltip
+        # The embedded per-sector geometry payload the tooltip controller
+        # reads: polar layout, anchors, and per-index names/colors/values.
+        # @api private
+        def coordinates_json
+          entry = series_entries.first
+          return "{}" unless entry
+
+          items = polar_items(entry)
+          {
+            "layout" => "polar",
+            "categories" => items.map { |s| chart_config.label_for(s.name, s.name) },
+            "names" => items.map { |s| chart_config.label_for(s.name, s.name) },
+            "colors" => items.map(&:fill),
+            "anchors" => items.map { |s| polar_anchor(s).map { |v| v.round(2) } },
+            "values" => { entry.data_key => polar_value_rows(entry).map do |row|
+              Poetry::Charts.display_value(row[entry.data_key])
+            end }
+          }.to_json
+        end
+
+        # The TooltipLayer child scoped to the first series, label hidden
+        # by default (the per-index name carries it).
+        # @api private
+        def tooltip_layer_component
+          TooltipLayer::Component.new(
+            config: chart_config,
+            series_keys: [series_entries.first&.data_key].compact,
+            indicator: tooltip_config.fetch(:indicator, :dot),
+            hide_label: tooltip_config.fetch(:hide_label, true),
+            hide_indicator: tooltip_config.fetch(:hide_indicator, false)
+          )
+        end
+
+        private :coordinates_json, :tooltip_layer_component
+      end
+
+      private :plot, :cx, :cy
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+<%= 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-polar-grid" aria-hidden="true">
+        <%# Linework FIRST (rings + spokes), so the tinted fills below can
+            wash over it - the translucent ring fills stack on top of the
+            grid strokes, leaving them near-invisible. %>
+        <% grid_radii.each do |radius| %>
+          <% if grid_config.type == :circle %>
+            <circle class="<%= css(:grid_line) %>" cx="<%= fnum(cx) %>" cy="<%= fnum(cy) %>" r="<%= fnum(radius) %>" />
+          <% else %>
+            <path class="<%= css(:grid_line) %>" d="<%= grid_polygon(radius) %>" />
+          <% end %>
+        <% end %>
+        <% if grid_config.radial_lines %>
+          <% rows.each_index do |i| %>
+            <% x, y = spoke_end(i) %>
+            <line class="<%= css(:grid_line) %>" x1="<%= fnum(cx) %>" y1="<%= fnum(cy) %>" x2="<%= fnum(x) %>" y2="<%= fnum(y) %>" />
+          <% end %>
+        <% end %>
+        <%# The tinted fills: EVERY ring fills at the low opacity,
+            painted OVER the linework, overlaps compounding toward the
+            center - one fill+opacity across the whole grid. Inline
+            style, because grid_line sets fill-none and a fill
+            ATTRIBUTE loses to that CSS. %>
+        <% if grid_fill_attribute %>
+          <% grid_radii.each do |radius| %>
+            <% if grid_config.type == :circle %>
+              <circle class="<%= css(:grid_fill) %>" cx="<%= fnum(cx) %>" cy="<%= fnum(cy) %>" r="<%= fnum(radius) %>" style="fill: <%= grid_fill_attribute %>" fill-opacity="<%= grid_config.opacity %>" />
+            <% else %>
+              <path class="<%= css(:grid_fill) %>" d="<%= grid_polygon(radius) %>" style="fill: <%= grid_fill_attribute %>" fill-opacity="<%= grid_config.opacity %>" />
+            <% end %>
+          <% end %>
+        <% end %>
+      </g>
+    <% end %>
+    <g data-slot="chart-radars">
+      <% series_entries.each do |entry| %>
+        <path data-slot="chart-radar" data-key="<%= entry.data_key %>" d="<%= series_path(entry) %>" fill="var(--color-<%= entry.data_key %>)" fill-opacity="<%= entry.fill_opacity %>"<% if entry.stroke_width.positive? %> stroke="var(--color-<%= entry.data_key %>)" stroke-width="<%= entry.stroke_width %>"<% end %> />
+        <% if entry.dots %>
+          <g data-slot="chart-dots" data-key="<%= entry.data_key %>">
+            <% rows.each_index do |i| %>
+              <% x, y = vertex(entry, i) %>
+              <circle data-slot="chart-dot" cx="<%= fnum(x) %>" cy="<%= fnum(y) %>" r="<%= entry.dot_radius %>" fill="var(--color-<%= entry.data_key %>)" />
+            <% end %>
+          </g>
+        <% end %>
+      <% end %>
+    </g>
+    <% if angle_axis? %>
+      <g data-slot="chart-angle-axis">
+        <% rows.each_index do |i| %>
+          <% placement = angle_label(i) %>
+          <text class="<%= css(:tick) %>" x="<%= fnum(placement[:x]) %>" y="<%= fnum(placement[:y]) %>" dy="0.355em" text-anchor="<%= placement[:anchor] %>"><%= placement[:text] %></text>
+        <% end %>
+      </g>
+    <% end %>
+    <% if tooltip? %>
+      <g data-slot="chart-hit-wedges">
+        <% rows.each_index do |i| %>
+          <path data-slot="chart-hit-wedge" data-index="<%= i %>" d="<%= hit_wedge(i) %>" fill="transparent" />
+        <% end %>
+      </g>
+    <% end %>
+  </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>
+  <% end %>
+<% end %>