poetry-charts 0.0.2

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

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    module LineChart
+      # The line family across its variants: default (natural),
+      # linear, step, multiple series, dots, per-point dot colors, and
+      # point labels. Shared sample data.
+      class Preview < Poetry::Core::Preview::Base
+        DATA = AreaChart::Preview::DATA
+        ONE = AreaChart::Preview::ONE
+        TWO = AreaChart::Preview::TWO
+        MARGIN = AreaChart::Preview::MARGIN
+
+        BROWSER_CONFIG = {
+          visitors: { label: "Visitors", color: "var(--chart-2)" },
+          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
+
+        BROWSER_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
+
+        def default
+          simple_chart(id: "line-default", tooltip: true)
+        end
+
+        def linear
+          simple_chart(id: "line-linear", curve: :linear)
+        end
+
+        def step
+          simple_chart(id: "line-step", curve: :step)
+        end
+
+        def multiple
+          render_component(data: DATA, config: TWO, id: "line-multiple", margin: MARGIN) do |chart|
+            chart.with_grid
+            chart.with_x_axis(data_key: :month, tick_formatter: ->(v) { v[0, 3] })
+            chart.with_line(data_key: :desktop)
+            chart.with_line(data_key: :mobile)
+          end
+        end
+
+        def dots
+          simple_chart(id: "line-dots", dots: true)
+        end
+
+        def dots_colors
+          render_component(data: BROWSER_DATA, config: BROWSER_CONFIG, id: "line-dots-colors",
+                           margin: { top: 24, left: 24, right: 24 }) do |chart|
+            chart.with_grid
+            chart.with_line(data_key: :visitors, dots: true, dot_radius: 5, dot_color_key: :fill)
+          end
+        end
+
+        def label
+          render_component(data: DATA, config: ONE, id: "line-label",
+                           margin: { top: 20, left: 12, right: 12 }) do |chart|
+            chart.with_grid
+            chart.with_x_axis(data_key: :month, tick_formatter: ->(v) { v[0, 3] })
+            chart.with_line(data_key: :desktop, dots: true, labels: true)
+          end
+        end
+
+        def references_and_errors
+          data = AreaChart::Preview::DATA.map.with_index do |row, i|
+            row.merge(err: [12 + (i * 3), 20 - i])
+          end
+          render_component(data: data, config: ONE, id: "line-refs",
+                           margin: { left: 12, right: 12 }) do |chart|
+            chart.with_grid
+            chart.with_x_axis(data_key: :month, tick_formatter: ->(v) { v[0, 3] })
+            chart.with_line(data_key: :desktop, error_key: :err)
+            chart.with_reference_line(y: 204, label: "avg")
+            chart.with_reference_area(y1: 280, y2: 320, label: "goal")
+            chart.with_tooltip
+          end
+        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: "line-live", margin: MARGIN, live: true,
+                           zoom: true, sync: "line-demo") do |chart|
+            chart.with_grid
+            chart.with_x_axis(data_key: :month)
+            chart.with_line(data_key: :desktop)
+            chart.with_tooltip(hide_label: true)
+            chart.with_brush
+          end
+        end
+
+        private
+
+        def simple_chart(id:, curve: :natural, dots: false, 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_line(data_key: :desktop, curve: curve, dots: dots)
+            chart.with_tooltip(hide_label: true) if tooltip
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    module LineChart
+      # The cartesian chrome on the shared cn-chart-* theme rules
+      # + the point-label look.
+      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"
+        element :label, "cn-chart-label"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    # Live mode: a chart that opts in with `live: true` embeds a
+    # {spec, frame} payload the client renderer recomputes geometry from
+    # when data changes too often to round-trip to the server. `spec` is
+    # the FROZEN spec v1 built by the same Poetry::Charts::Spec the
+    # adapter seam uses (the spec stays closed); `frame` is a PRIVATE engine
+    # envelope carrying the geometry-affecting knobs the spec deliberately
+    # omits. Everything else about the chart stays server-rendered.
+    #
+    # Live charts cannot carry Ruby lambdas to the browser: tick
+    # formatters and label slots raise a teaching error - format data
+    # host-side (pre-formatted category strings) instead.
+    module Live
+      # The live controller's full-string identifier.
+      CONTROLLER = "poetry--charts--live"
+
+      def self.included(base)
+        base.extend(ClassMethods)
+
+        # Declared after TooltipWiring's and Motion's frame wirings
+        # (include order IS emission order): live registration + the host
+        # update hook, the tooltip re-read on live's updated dispatch, and
+        # the window controller's server-computed rects. The SVG gains the
+        # zoom drag actions; the payload <script> is live's data target.
+        base.use_stimulus do
+          on :frame do
+            controller CONTROLLER, if: :live? do
+              register
+              action :receive, on: "poetry-chart:update"
+            end
+            controller TooltipWiring::CONTROLLER, if: -> { live? && tooltip? } do
+              action :refresh, on: event(CONTROLLER, :updated)
+            end
+            controller WINDOW_CONTROLLER, if: :window_features? do
+              register
+              value :zoom, from: :zoom?
+              value :plot, from: :window_plot_json
+              value :brush, from: :window_brush_json, if: -> { brush_config }
+            end
+          end
+          on :svg do
+            controller WINDOW_CONTROLLER, if: :zoom? do
+              action :startZoom, on: :pointerdown
+              action :reset, on: :dblclick
+            end
+          end
+          on :live_payload do
+            controller(CONTROLLER) { target :payload }
+          end
+          # Rendered by brush_svg via the stimulus_action descriptor -
+          # declared so the contract owns the token (and flags drift).
+          on :brush do
+            controller(WINDOW_CONTROLLER, if: -> { brush_config }) do
+              action :startBrush, on: :pointerdown
+            end
+          end
+        end
+
+        # The live-window anatomy (all server-rendered; the window
+        # controller only drags and repaints) - declared here so every
+        # live-capable family publishes the same styling surface.
+        base.part "chart-brush", "The brush strip group (with_brush): track + window + two " \
+                                 "handles below the x axis"
+        base.part "chart-brush-track", "The full-width brush rail"
+        base.part "chart-brush-window", "The selected-range rect the drag moves"
+        base.part "chart-brush-handle", "One draggable window edge",
+                  states: { "data-edge" => { condition: "always - which edge",
+                                             values: %w[start end] } }
+        base.part "chart-zoom-selection", "The zoom drag-selection overlay (zoom: true), " \
+                                          "hidden until a drag starts"
+        base.part "chart-live-payload", "The embedded {spec, frame} JSON the live renderer " \
+                                        "recomputes geometry from"
+      end
+
+      # The class-level macro families call to opt into live mode.
+      module ClassMethods
+        # Declares the live-mode surface: the live: and zoom: options plus
+        # the with_brush slot.
+        def live_option
+          option :live, :boolean, default: false,
+                                  doc: "Embeds the {spec, frame} payload so the client renderer can recompute " \
+                                       "geometry when data changes without a server round-trip."
+          option :zoom, :boolean, default: false,
+                                  doc: "Drag-to-zoom on the plot; slices the data client-side, so it needs live: true."
+          renders_one :brush,
+                      doc: "The brush strip below the x axis - drag its window to slice the visible range; needs " \
+                           "live: true.",
+                      renders: lambda { |height: 30|
+                        @brush_config = { height: height.to_f }
+                        nil
+                      }
+        end
+      end
+
+      # The live: option cast to a strict boolean.
+      # @api private
+      def live?
+        !!live
+      end
+
+      # The window controller's full-string identifier.
+      WINDOW_CONTROLLER = "poetry--charts--window"
+      # Pixels between the plot's bottom margin and the brush strip.
+      BRUSH_GAP = 8
+
+      # The brush slot's captured config, guarded: the window recomputes
+      # client-side, so a brush without live: true raises.
+      # @api private
+      def brush_config
+        brush?
+        if @brush_config && !live?
+          raise ArgumentError, "with_brush needs live: true - the window recomputes client-side"
+        end
+
+        @brush_config
+      end
+
+      # The zoom: option, guarded the same way as the brush.
+      # @api private
+      def zoom?
+        raise ArgumentError, "zoom: true needs live: true - the window recomputes client-side" if zoom && !live?
+
+        !!zoom
+      end
+
+      # Whether any windowing feature (brush or zoom) is active.
+      # @api private
+      def window_features?
+        !!brush_config || zoom?
+      end
+
+      # The brush strip reserves space below the x axis by growing the
+      # bottom margin the cartesian sees.
+      # @api private
+      def live_margin
+        base = (margin || {}).to_h.symbolize_keys
+        return base unless brush_config
+
+        bottom = (base[:bottom] || Cartesian::DEFAULT_MARGIN[:bottom]).to_f
+        base.merge(bottom: bottom + brush_config[:height] + BRUSH_GAP)
+      end
+
+      # The brush strip's y position - below the plot, above the reserved
+      # margin.
+      # @api private
+      def brush_top
+        original_bottom = (margin || {}).to_h.symbolize_keys.fetch(:bottom, Cartesian::DEFAULT_MARGIN[:bottom]).to_f
+        height - original_bottom - brush_config[:height]
+      end
+
+      # The strip: track + window + two handles, all server-rendered; the
+      # window controller drags them and repaints on window changes.
+      # @api private
+      def brush_svg
+        config = brush_config
+        return unless config
+
+        left = cartesian.plot_left
+        width = cartesian.plot_right - left
+        top = brush_top
+        handle = 6.0
+
+        tag.g("data-slot": "chart-brush", "aria-hidden": true,
+              "data-action": stimulus_action(:startBrush, on: :pointerdown)) do
+          safe_join([
+                      tag.rect(class: css(:brush_track), "data-slot": "chart-brush-track",
+                               x: fnum(left), y: fnum(top), width: fnum(width),
+                               height: fnum(config[:height]), rx: 4),
+                      tag.rect(class: css(:brush_window), "data-slot": "chart-brush-window",
+                               x: fnum(left), y: fnum(top), width: fnum(width),
+                               height: fnum(config[:height]), rx: 4),
+                      tag.rect(class: css(:brush_handle), "data-slot": "chart-brush-handle", "data-edge": "start",
+                               x: fnum(left - (handle / 2)), y: fnum(top), width: fnum(handle),
+                               height: fnum(config[:height]), rx: 2),
+                      tag.rect(class: css(:brush_handle), "data-slot": "chart-brush-handle", "data-edge": "end",
+                               x: fnum(left + width - (handle / 2)), y: fnum(top), width: fnum(handle),
+                               height: fnum(config[:height]), rx: 2)
+                    ])
+        end
+      end
+
+      # The zoom drag-selection overlay (hidden until a drag starts).
+      # @api private
+      def zoom_selection_svg
+        return unless zoom?
+
+        tag.rect(class: css(:reference_area), "data-slot": "chart-zoom-selection", "aria-hidden": true,
+                 x: 0, y: fnum(cartesian.plot_top), width: 0,
+                 height: fnum(cartesian.plot_bottom - cartesian.plot_top),
+                 "fill-opacity": 0.15, display: "none")
+      end
+
+      # Value readers for the window controller's declared frame wiring:
+      # the plot rect and the brush strip rect, server-computed (the
+      # controller's only layout math is fractions of these).
+      # @api private
+      def window_plot_json
+        [cartesian.plot_left, cartesian.plot_right, cartesian.plot_top, cartesian.plot_bottom].to_json
+      end
+
+      # The brush strip rect for the window controller, server-computed.
+      # @api private
+      def window_brush_json
+        [cartesian.plot_left, brush_top, cartesian.plot_right - cartesian.plot_left,
+         brush_config[:height]].to_json
+      end
+
+      # The embedded {spec, frame} payload the live renderer recomputes
+      # geometry from, validated for serializability first.
+      # @api private
+      def live_payload
+        ensure_live_compatible!
+        {
+          "version" => 1,
+          "spec" => live_spec.to_h,
+          "frame" => live_frame
+        }
+      end
+
+      # The payload serialized for the embedded <script> tag.
+      # @api private
+      def live_payload_json
+        live_payload.to_json
+      end
+
+      # The chart reduced to the closed spec (type, data, series, axes).
+      # @api private
+      def live_spec
+        Spec.new(type: live_type, data: data, series: live_series, axes: live_axes)
+      end
+
+      # The geometry-affecting knobs shared by the cartesian trio; families
+      # merge their extras (bar gaps/radii) via live_frame_extras.
+      # @api private
+      def live_frame
+        {
+          "width" => width,
+          "height" => height,
+          # live_margin, NOT the raw margin: the brush reserve must survive
+          # into client recomputes, or every window change drops the plot
+          # into the brush strip (the y-baseline sliding ~35px down).
+          "margin" => Cartesian::DEFAULT_MARGIN.merge(live_margin)
+                                               .transform_keys(&:to_s),
+          "layout" => cartesian.layout.to_s,
+          "xScaleType" => live_x_scale_type.to_s,
+          "categoryAxis" => live_category_axis?,
+          "valueAxis" => !cartesian.horizontal? && !y_axis_config.nil?,
+          "yTickCount" => cartesian.y_tick_count,
+          "offset" => cartesian.offset.to_s,
+          "xTickMargin" => x_axis_config&.tick_margin,
+          "yTickMargin" => y_axis_config&.tick_margin
+        }.merge(live_frame_extras).compact
+      end
+
+      # Hook: families merge extra geometry-affecting knobs into the frame
+      # envelope.
+      # @api private
+      def live_frame_extras
+        {}
+      end
+
+      # Lambdas cannot ride a JSON payload - fail at render, with the fix.
+      # @api private
+      def ensure_live_compatible!
+        if x_axis_config&.tick_formatter || y_axis_config&.tick_formatter
+          raise ArgumentError, "live: charts cannot serialize tick_formatter lambdas - " \
+                               "pre-format the category strings in your data instead"
+        end
+        if series_entries.any? { |entry| entry.respond_to?(:error_key) && entry.error_key }
+          raise ArgumentError, "live: charts do not support error bars yet - " \
+                               "drop error_key: or render without live:"
+        end
+        if respond_to?(:reference_marks) && reference_marks.any?
+          raise ArgumentError, "live: charts do not support reference marks yet"
+        end
+        return unless live_labels_configured?
+
+        raise ArgumentError, "live: charts do not support labels yet - " \
+                             "drop labels: or render without live:"
+      end
+
+      # Whether any series slot asked for value labels.
+      # @api private
+      def live_labels_configured?
+        series_entries.any? { |entry| entry.respond_to?(:labels) && entry.labels }
+      end
+
+      private :brush_config, :zoom?, :window_features?, :live_margin, :brush_top, :brush_svg
+      private :zoom_selection_svg, :window_plot_json, :window_brush_json, :live_payload, :live_payload_json, :live_spec
+      private :live_frame, :live_frame_extras, :ensure_live_compatible!, :live_labels_configured?
+    end
+  end
+end

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    # Shared animation surface for the chart families: chart-level
+    # options (animate / animation_duration / animation_easing /
+    # animation_begin, defaults set per family), emitted as data-animate plus
+    # --poetry-motion-* custom properties on the SVG. The animations
+    # themselves are CSS (the motion stylesheet) and the motion controller -
+    # the server computes all geometry; the client only interpolates
+    # between server-computed states.
+    module Motion
+      # The allowed animation_easing keywords.
+      EASINGS = %i[ease linear ease_in ease_out ease_in_out].freeze
+      # The motion controller's full-string identifier.
+      CONTROLLER = "poetry--charts--motion"
+
+      def self.included(base)
+        base.extend(ClassMethods)
+
+        # The motion controller rides the same frame element TooltipWiring
+        # declares (include order IS emission order: tooltip, motion, then
+        # live/window).
+        base.use_stimulus do
+          on :frame do
+            controller(CONTROLLER, if: :animate?) { register }
+          end
+        end
+      end
+
+      # The class-level macro families call to declare their animation
+      # options.
+      module ClassMethods
+        # Declares the animation options with the family's defaults
+        # (bar 400ms, pie delayed 400ms, scatter 400ms linear,
+        # everything else 1500ms ease with no delay).
+        def motion_options(duration: 1500, delay: 0, easing: :ease)
+          option :animate, :boolean, default: true,
+                                     doc: "Entrance animation switch - reduced-motion users always get the finished " \
+                                          "chart regardless."
+          option :animation_duration, :integer, default: duration, doc: "Entrance/morph duration in milliseconds."
+          option :animation_easing, :symbol, default: easing, doc: "Animation easing keyword (see EASINGS)."
+          option :animation_begin, :integer, default: delay, doc: "Pre-animation hold in milliseconds."
+        end
+      end
+
+      # The animate: option cast to a strict boolean.
+      # @api private
+      def animate?
+        !!animate
+      end
+
+      # Merged into the SVG tag by TooltipWiring#svg_interaction_attributes.
+      # Duration/begin are :integer-typed and easing is enum-validated, so
+      # nothing user-controlled reaches the style attribute unguarded.
+      # @api private
+      def motion_svg_attributes
+        return {} unless animate?
+
+        { "data-animate" => "", "style" => motion_style }
+      end
+
+      # The --poetry-motion-* custom-property declarations for the SVG's
+      # style attribute.
+      # @api private
+      def motion_style
+        easing = animation_easing.to_sym
+        raise ArgumentError, "unknown easing #{animation_easing.inspect}" unless EASINGS.include?(easing)
+
+        style = "--poetry-motion-duration: #{animation_duration}ms; " \
+                "--poetry-motion-easing: #{easing.to_s.tr("_", "-")}; " \
+                "--poetry-motion-delay: #{animation_begin}ms"
+        extra = motion_style_extras
+        extra ? "#{style}; #{extra}" : style
+      end
+
+      # Hook: families append extra custom properties (radar ships the
+      # polar center so CSS can scale from it).
+      #
+      # @return [String, nil]
+      def motion_style_extras
+        nil
+      end
+
+      # data-motion-sector: the server-computed sector params the
+      # fan-out sweep reads (4-decimal formatting, matching sector_path's
+      # own fmt so mid-sweep client paths stay byte-compatible).
+      # @api private
+      def motion_sector_value(cx, cy, inner, outer, start_angle, end_angle)
+        [cx, cy, inner, outer, start_angle, end_angle]
+          .map { |v| Geometry.js_number((v.to_f * 10_000).round / 10_000.0) }
+          .join(" ")
+      end
+
+      private :animate?, :motion_style, :motion_sector_value
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+<%= 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) %>>
+    <% series_entries.each_with_index do |entry, pie_index| %>
+      <g data-slot="chart-pie" data-key="<%= entry.data_key %>">
+        <% slices(entry).each do |slice| %>
+          <path data-slot="chart-pie-sector" data-key="<%= entry.data_key %>"<% if pie_index.zero? %> data-index="<%= slice.index %>"<% end %><% if entry.active_index == slice.index %> data-active=""<% end %><% if animate? %> data-motion-sector="<%= motion_sector_value(cx, cy, slice.inner, slice.outer, slice.start_angle, slice.end_angle) %>" data-motion-group="pie-<%= pie_index %>"<% end %> d="<%= slice.path %>" fill="<%= slice.fill %>"<% if entry.stroke_width.positive? %> stroke="var(--background)" stroke-width="<%= entry.stroke_width %>"<% end %> />
+        <% end %>
+      </g>
+      <% if entry.labels == :list %>
+        <g data-slot="chart-labels" data-key="<%= entry.data_key %>" aria-hidden="true">
+          <% slices(entry).each do |slice| %>
+            <text class="<%= css(:inside_label) %>" x="<%= fnum(slice.label_point[0]) %>" y="<%= fnum(slice.label_point[1]) %>" text-anchor="middle" dy="0.355em"><%= slice_label(entry, slice) %></text>
+          <% end %>
+        </g>
+      <% end %>
+    <% end %>
+    <% if center_label? %>
+      <%# dy=0.355em centers each line's midline on its y (the
+          dominant-baseline: middle offset, stated inline); the subtitle
+          sits 24 below the title, both absolute. %>
+      <text data-slot="chart-center-label" x="<%= fnum(cx) %>" y="<%= fnum(cy) %>" text-anchor="middle">
+        <tspan class="<%= css(:center_title) %>" x="<%= fnum(cx) %>" y="<%= fnum(cy) %>" dy="0.355em"><%= center_label_config[:title] %></tspan>
+        <% if center_label_config[:subtitle] %>
+          <tspan class="<%= css(:center_subtitle) %>" x="<%= fnum(cx) %>" y="<%= fnum(cy + 24) %>" dy="0.355em"><%= center_label_config[:subtitle] %></tspan>
+        <% end %>
+      </text>
+    <% 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 %>