poetry-charts 0.0.2

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    module Container
+      # The frame previewed standalone: config-driven series colors flowing
+      # into inline SVG through var(--color-<key>) - the whole container
+      # contract, before any engine exists.
+      class Preview < Poetry::Core::Preview::Base
+        CONFIG = {
+          desktop: { label: "Desktop", color: "var(--chart-1)" },
+          mobile: { label: "Mobile", color: "var(--chart-2)" }
+        }.freeze
+
+        def default
+          render_component(config: CONFIG, id: "preview") do
+            <<~SVG.html_safe
+              <svg viewBox="0 0 300 150" style="height:100%;width:100%" role="img" aria-label="Placeholder chart">
+                <rect x="20" y="60" width="40" height="80" rx="4" fill="var(--color-desktop)"></rect>
+                <rect x="70" y="30" width="40" height="110" rx="4" fill="var(--color-mobile)"></rect>
+                <rect x="130" y="80" width="40" height="60" rx="4" fill="var(--color-desktop)"></rect>
+                <rect x="180" y="45" width="40" height="95" rx="4" fill="var(--color-mobile)"></rect>
+              </svg>
+            SVG
+          end
+        end
+
+        def themed
+          render_component(
+            config: {
+              revenue: { label: "Revenue", theme: { light: "oklch(0.6 0.15 250)", dark: "oklch(0.75 0.12 250)" } }
+            },
+            id: "preview-themed"
+          ) do
+            <<~SVG.html_safe
+              <svg viewBox="0 0 300 150" style="height:100%;width:100%" role="img" aria-label="Themed placeholder chart">
+                <circle cx="150" cy="75" r="50" fill="var(--color-revenue)"></circle>
+              </svg>
+            SVG
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    module Container
+      # The chart frame chrome, with NO descendant overrides into the
+      # chart body - descendant selectors exist to style DOM one does not
+      # own, and poetry OWNS its SVG, so tick text (muted-foreground),
+      # grid (border/50), and sector/dot outline-hidden land as direct
+      # classes on the engine's own parts; the container keeps only what
+      # is truly container-level. Adapter/island content brings its own
+      # inner styling (a declared degradation).
+      class Style < Poetry::Core::Style
+        # relative anchors the absolute tooltip layer (visual no-op).
+        # flex-col stacks the legend under (or over, via order-first) the
+        # chart SVG, reserving plot space for it; a row layout would park
+        # the legend beside the plot.
+        base "relative flex aspect-video flex-col items-center justify-center text-xs [&_svg]:outline-hidden"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    # Error bars for line, bar, and scatter series. A series slot takes
+    # error_key: naming a row key holding either a symmetric offset (err)
+    # or [low, high] offsets from the value; the whisker renders
+    # cap - stem - cap in the foreground color (a neutral that stays
+    # visible over same-colored marks), width 5.
+    # @api private
+    module ErrorBars
+      # Whisker cap width in pixels.
+      DEFAULT_WIDTH = 5
+
+      # [low_value, high_value] in DATA units, or nil when the row has no
+      # error entry.
+      def error_range(row, error_key, value)
+        err = row.to_h.transform_keys(&:to_s)[error_key.to_s]
+        return nil if err.nil?
+
+        low, high = err.is_a?(Array) ? err : [err, err]
+        [value - low.to_f, value + high.to_f]
+      end
+
+      # cap - stem - cap around a vertical span, in pixels.
+      def error_bar_path(center_x, y_low, y_high, width)
+        half = width.to_f / 2.0
+        f = ->(v) { fnum(v) }
+        "M#{f.call(center_x - half)},#{f.call(y_low)}H#{f.call(center_x + half)}" \
+          "M#{f.call(center_x)},#{f.call(y_low)}V#{f.call(y_high)}" \
+          "M#{f.call(center_x - half)},#{f.call(y_high)}H#{f.call(center_x + half)}"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,10 @@
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <% rows.each do |row| %>
+    <%= content_tag(toggle ? :button : :div, **(toggle ? toggle_attributes(row) : { data: { slot: "chart-legend-item" }, class: css(:item) })) do %>
+      <% unless hide_icon || row[:color].nil? %>
+        <div data-slot="chart-legend-swatch" class="<%= css(:swatch) %>" style="<%= swatch_style(row[:color]) %>"></div>
+      <% end %>
+      <%= row[:name] %>
+    <% end %>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    # The chart legend chrome.
+    module LegendContent
+      # The legend chrome: a centered row of swatch + label pairs. Items
+      # default to the config's colored entries (the common case - every
+      # configured series, in config order); pass items: [{ key:, color: }]
+      # to override, e.g. per-slice pie legends.
+      #
+      # @example
+      #   <%= poetry_chart_legend_content(config: config) %>
+      class Component < Poetry::Core::Component
+        # Projected into the registry and agent surface.
+        AGENT_RULES = [
+          "The legend derives from the chart config by default - omit items: unless slices differ from series.",
+          "align: :top pads below (pb-3), :bottom (default) pads above (pt-3) - matching the chart edge it sits on."
+        ].freeze
+
+        style :align, default: :bottom, required: true, variants: %i[top bottom],
+                      doc: "Which chart edge the legend sits on: :top pads below it, :bottom (the default) pads " \
+                           "above. A style axis, not an option - options silently drop the dictionary's variant " \
+                           "classes."
+
+        option :config, ActiveModel::Type::Value.new, required: true,
+                                                      doc: "The series config - key => { label:, color: } - the " \
+                                                           "default item source."
+        option :items, ActiveModel::Type::Value.new,
+               doc: "Explicit entries ([{ key:, name:, color: }]) overriding the config-derived list."
+        option :hide_icon, :boolean, default: false, doc: "Hides the color swatches, leaving labels only."
+        option :toggle, :boolean, default: false,
+                                  doc: "Interactive legend: items render as buttons that toggle their series through " \
+                                       "the live controller (the host chart guards that live: is on)."
+
+        part "chart-legend-content", "The legend row (<div>) - centered swatch + label pairs"
+        part "chart-legend-item", "One legend entry (<div>; a <button> in toggle mode)",
+             states: {
+               "data-key" => "in toggle mode - the series key the button toggles",
+               "data-hidden" => "in toggle mode - the item's series is toggled off (the live " \
+                                "controller stamps it at runtime; the item dims)"
+             }
+        part "chart-legend-swatch", "The color swatch (<div>) - inline background-color carries " \
+                                    "the entry's color; omitted with hide_icon or colorless entries"
+
+        # The config: option wrapped as a {Poetry::Charts::Config}.
+        # @api private
+        def chart_config
+          @chart_config ||= Poetry::Charts::Config.wrap(config)
+        end
+
+        # The resolved entries: explicit items:, else the config's
+        # colored entries in config order.
+        # @api private
+        def rows
+          @rows ||= if items.present?
+                      Array(items).map { |item| resolve(item.symbolize_keys) }
+                    else
+                      chart_config.color_entries.map do |entry|
+                        { key: entry.key, name: entry.label || entry.key,
+                          color: entry.color_for(:light) ? swatch_color(entry) : nil }
+                      end
+                    end
+        end
+
+        # The toggle buttons speak straight to the live controller on the
+        # chart frame (Stimulus action params carry the series key).
+        # @api private
+        def toggle_attributes(row)
+          {
+            type: "button",
+            data: {
+              slot: "chart-legend-item",
+              key: row[:key],
+              action: "click->poetry--charts--live#toggleSeries",
+              "poetry--charts--live-key-param": row[:key]
+            },
+            class: "#{css(:item)} #{css(:toggle)}"
+          }
+        end
+
+        # The legend row's attributes with the part self-identification.
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            { "data-slot" => "chart-legend-content" }.merge(component_data_attributes)
+          )
+        end
+
+        # A swatch's guarded inline background (colors reaching a style
+        # attribute must be CSS-safe).
+        # @api private
+        def swatch_style(color)
+          return nil unless color
+          raise ArgumentError, "legend color #{color.inspect} is not CSS-safe" unless color.match?(Config::COLOR)
+
+          "background-color: #{color};"
+        end
+
+        private
+
+        # Themed entries swatch through var(--color-<key>) (the container's
+        # emission), so the swatch follows dark mode; flat colors inline.
+        def swatch_color(entry)
+          entry.theme ? "var(--color-#{entry.key})" : entry.color
+        end
+
+        def resolve(item)
+          key = (item[:key] || item[:name]).to_s
+          entry = chart_config[key]
+          {
+            key: key,
+            name: chart_config.label_for(key, item[:name]),
+            color: item[:color] || (entry && swatch_color(entry))
+          }
+        end
+
+        private :chart_config, :rows, :toggle_attributes, :root_attributes, :swatch_style
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    module LegendContent
+      # The legend chrome: config-derived (the default) and explicit items.
+      class Preview < Poetry::Core::Preview::Base
+        CONFIG = {
+          desktop: { label: "Desktop", color: "var(--chart-1)" },
+          mobile: { label: "Mobile", color: "var(--chart-2)" }
+        }.freeze
+
+        def default
+          render_component(config: CONFIG)
+        end
+
+        def top_aligned
+          render_component(config: CONFIG, align: :top)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    module LegendContent
+      # Re-expressed through the cn-* theme layer. flex-wrap stays
+      # poetry's one structural addition (long lists wrap in the real flex
+      # column); order-first stays inline in the top align (layout
+      # mechanism - the padding rides the theme rule). The toggle's
+      # data-hidden dim is live-controller state, inline.
+      class Style < Poetry::Core::Style
+        base "cn-chart-legend flex flex-wrap items-center justify-center"
+
+        variant :align, {
+          top: "cn-chart-legend-align-top order-first",
+          bottom: "cn-chart-legend-align-bottom"
+        }
+        element :item, "cn-chart-legend-item flex items-center"
+        element :swatch, "cn-chart-legend-swatch shrink-0"
+        # Toggle buttons dim when their series hides (the live controller
+        # stamps data-hidden).
+        element :toggle, "cursor-pointer data-hidden:opacity-40"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+<%= 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 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 %>
+      </g>
+    <% end %>
+    <%= cursor_svg(:line) %>
+    <g data-slot="chart-lines">
+      <% series_entries.each do |entry| %>
+        <% if (d = series_path(entry)) %>
+          <%# pathLength="1" normalizes the path to unit length - the motion stylesheet's dash draw-in needs no measurement. %>
+          <path data-slot="chart-line" data-key="<%= entry.key %>" d="<%= d %>" fill="none" stroke="var(--color-<%= entry.key %>)" stroke-width="<%= entry.stroke_width %>"<% if animate? %> pathLength="1"<% end %> />
+        <% end %>
+        <% if entry.dots %>
+          <g data-slot="chart-dots" data-key="<%= entry.key %>">
+            <% markers(entry).each do |marker| %>
+              <circle data-slot="chart-dot" cx="<%= fnum(marker[:x]) %>" cy="<%= fnum(marker[:y]) %>" r="<%= entry.dot_radius %>" fill="<%= dot_fill(entry, marker) %>" />
+            <% end %>
+          </g>
+        <% end %>
+        <% if entry.error_key %>
+          <g data-slot="chart-error-bars" data-key="<%= entry.key %>" aria-hidden="true">
+            <% markers(entry).each do |marker| %>
+              <% range = error_range(marker[:row], entry.error_key, marker[:value]) %>
+              <% if range %>
+                <path class="<%= css(:error_bar) %>" d="<%= error_bar_path(marker[:x], 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 %>">
+            <% markers(entry).each do |marker| %>
+              <text class="<%= css(:label) %>" x="<%= fnum(marker[:x]) %>" y="<%= fnum(marker[:y] - 12) %>" text-anchor="middle"><%= marker_label(marker) %></text>
+            <% end %>
+          </g>
+        <% end %>
+      <% end %>
+    </g>
+    <%= reference_marks_svg %>
+<% if tooltip? %>
+  <g data-slot="chart-active-dots" aria-hidden="true">
+    <% series_entries.each do |entry| %>
+      <% active_dot_markers(entry).each do |marker| %>
+        <circle data-slot="chart-active-dot" data-key="<%= entry.key %>" data-index="<%= marker[:index] %>" cx="<%= fnum(marker[:x]) %>" cy="<%= fnum(marker[:y]) %>" r="4" fill="var(--color-<%= entry.key %>)" display="none" />
+      <% end %>
+    <% end %>
+  </g>
+<% end %>
+    <% 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 %>
+    <%= 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 %>

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

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    # The line chart family.
+    module LineChart
+      # Renders a line chart - one stroked curve per series, no fills -
+      # through the cartesian pipeline. Adds dot variants (solid
+      # series-colored dots, or per-point colors read from a data key),
+      # value labels stamped above the points, and error whiskers.
+      #
+      # @example Two series over a formatted month axis
+      #   <%= poetry_chart :line, 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_line data_key: :desktop %>
+      #     <% c.with_line data_key: :mobile %>
+      #   <% end %>
+      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
+        include Poetry::Charts::ErrorBars
+
+        # Projected into the registry and agent surface.
+        AGENT_RULES = [
+          "Compose from slots: with_grid / with_x_axis(data_key:) / with_line(data_key:) / with_legend.",
+          "Lines default to stroke-width 2 and NO dots (the ported block look); dots: true adds them.",
+          "dot_color_key: reads a per-row data key for per-point dot colors (the dots-colors block).",
+          "labels: true stamps each value above its point; give the chart margin top when using it.",
+          "Colors come from the config - never set stroke on a line directly.",
+          "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_line call's captured series config.
+        Series = Data.define(:key, :curve, :stroke_width, :dots, :dot_radius, :dot_color_key, :labels,
+                             :error_key, :error_width) do
+          # The cartesian pipeline contract (lines never stack).
+          def stack = nil
+        end
+
+        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 :label, :string,
+               doc: "Accessible name for the chart SVG; defaults to one built from the configured series."
+
+        motion_options
+        live_option
+
+        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-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-lines", "The line-mark group - each series' curve plus its companion marks"
+        part "chart-line", "One series' stroked curve - pathLength=1 when animating so the " \
+                           "dash draw-in needs no measurement",
+             states: { "data-key" => "the series key" }
+        part "chart-dots", "One series' point-dot group (dots: true)",
+             states: { "data-key" => "the series key" }
+        part "chart-dot", "One point dot (<circle>)"
+        part "chart-error-bars", "One series' error-whisker group (error_key:) - cap-stem-cap " \
+                                 "paths in the foreground color",
+             states: { "data-key" => "the series key" }
+        part "chart-labels", "One series' value-label group (labels: true)",
+             states: { "data-key" => "the series key" }
+        part "chart-reference", "The reference-mark group (with_reference_line/_area/_dot), " \
+                                "painted above the series"
+        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-coordinates", "The embedded per-index geometry payload " \
+                                  "(<script type=application/json>) the tooltip controller " \
+                                  "reads - zero chart math in the browser"
+
+        renders_many :lines,
+                     doc: "A line series bound to data_key:. dots: marks each point; dot_color_key: reads per-point " \
+                          "dot colors from the row; labels: stamps each value above its point; error_key: adds " \
+                          "error whiskers.",
+                     renders: lambda { |data_key:, curve: :natural, stroke_width: 2, dots: false,
+                                       dot_radius: 3, dot_color_key: nil, labels: false, error_key: nil, error_width: 5|
+                       raise ArgumentError, "unknown curve #{curve.inspect}" unless CURVES.include?(curve.to_sym)
+
+                       (@series_entries ||= []) << Series.new(key: data_key.to_s, curve: curve.to_sym, stroke_width:,
+                                                              dots:, dot_radius:, dot_color_key: dot_color_key&.to_s,
+                                                              labels:, error_key: error_key&.to_s, error_width:)
+                       nil
+                     }
+
+        include Poetry::Charts::CartesianFamily
+
+        # The captured Series configs, forcing lazy slot evaluation.
+        # @api private
+        def series_entries
+          lines? # force slot evaluation (slots evaluate lazily)
+          @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?,
+            y_tick_count: y_axis_config&.tick_count || 5
+          )
+        end
+
+        # One series' stroked curve path.
+        # @api private
+        def series_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
+
+        # The visible points for dots/labels (NaN values render nothing).
+        # @api private
+        def markers(entry)
+          cartesian.points(entry).each_with_index.filter_map do |point, i|
+            next if point[:value].nan?
+
+            { x: point[:x], y: point[:y1], value: point[:value], row: data[i] }
+          end
+        end
+
+        # Per-point dot color: the dot_color_key row value (CSS-validated),
+        # else the series color.
+        # @api private
+        def dot_fill(entry, marker)
+          if entry.dot_color_key
+            color = marker[:row].to_h.transform_keys(&:to_s)[entry.dot_color_key].to_s
+            raise ArgumentError, "dot color #{color.inspect} is not CSS-safe" unless color.match?(Config::COLOR)
+
+            color
+          else
+            "var(--color-#{entry.key})"
+          end
+        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
+
+        # A point's value label, integers shown bare.
+        # @api private
+        def marker_label(marker)
+          value = marker[:value]
+          value == value.to_i ? value.to_i.to_s : value.to_s
+        end
+
+        # ChartFamily#svg_label's chart-type lead-in.
+        # @api private
+        def svg_label_prefix = "Line 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 = :line
+
+        # The series list serialized into the live spec.
+        # @api private
+        def live_series
+          series_entries.map { |e| { data_key: e.key, curve: e.curve } }
+        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, :markers, :dot_fill, :x_tick_label, :y_tick_label
+        private :marker_label, :svg_label_prefix, :coordinates_json, :live_type, :live_series, :live_axes
+        private :live_x_scale_type, :live_category_axis?
+      end
+    end
+  end
+end