poetry-charts 0.0.2

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    # The identity chassis every chart family shares: the data-chart id
+    # scope, the wrapped config, the accessible SVG name, and the SVG
+    # number formatter. Families supply svg_label_prefix (the accessible
+    # name's chart-type lead-in); a family whose default name reads from a
+    # different surface (scatter: series keys through the config) overrides
+    # svg_label itself.
+    #
+    # @example A minimal chart family
+    #   class Sparkline::Component < Poetry::Core::Component
+    #     include Poetry::Charts::ChartFamily
+    #
+    #     option :config, ActiveModel::Type::Value.new, required: true
+    #     option :id, :string
+    #     option :label, :string
+    #
+    #     # The accessible name's chart-type lead-in.
+    #     def svg_label_prefix = "Sparkline"
+    #   end
+    module ChartFamily
+      # The data-chart scope: explicit id when given (stable for tests /
+      # multiple charts), else unique per render.
+      #
+      # @return [String]
+      def chart_id
+        @chart_id ||= (dom_id_token(id) ? "chart-#{dom_id_token(id)}" : poetry_instance_id("chart"))
+      end
+
+      # The config: option wrapped as a {Poetry::Charts::Config} - series
+      # entries with labels and colors.
+      #
+      # @return [Poetry::Charts::Config]
+      def chart_config
+        @chart_config ||= Poetry::Charts::Config.wrap(config)
+      end
+
+      # The accessible name for the role=img SVG: explicit label: or a
+      # sensible default from the configured series.
+      #
+      # @return [String]
+      def svg_label
+        label.presence || "#{svg_label_prefix}: #{chart_config.entries.map { |e| e.label || e.key }.join(", ")}"
+      end
+
+      # SVG attribute numbers: 2-decimal rounding, script-style formatting
+      # (bare integers) - keeps the markup compact and stable.
+      # @api private
+      def fnum(value)
+        Geometry.js_number((value * 100).round / 100.0)
+      end
+
+      private :fnum
+    end
+  end
+end

data/app/components/poetry/charts/composed_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) %>>
+    <% area_entries = series_entries.select { |e| e.mark == :area } %>
+    <% if area_entries.any?(&:gradient) || (animate? && area_entries.any?) %>
+      <defs>
+        <% area_entries.select(&:gradient).each do |entry| %>
+          <linearGradient id="<%= gradient_id(entry) %>" x1="0" y1="0" x2="0" y2="1">
+            <stop offset="5%" stop-color="var(--color-<%= entry.key %>)" stop-opacity="0.8" />
+            <stop offset="95%" stop-color="var(--color-<%= entry.key %>)" stop-opacity="0.1" />
+          </linearGradient>
+        <% end %>
+        <% if animate? && area_entries.any? %>
+          <clipPath id="<%= chart_id %>-reveal"><rect data-slot="chart-motion-reveal" x="0" y="0" width="<%= width %>" height="<%= height %>" /></clipPath>
+        <% end %>
+      </defs>
+    <% end %>
+    <% 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) %>
+    <%# Declaration order IS paint order. %>
+    <% series_entries.each do |entry| %>
+      <% case entry.mark %>
+      <% when :area %>
+        <g data-slot="chart-areas"<% if animate? %> clip-path="url(#<%= chart_id %>-reveal)"<% end %>>
+          <% if (d = area_path(entry)) %>
+            <path data-slot="chart-area" data-key="<%= entry.key %>" d="<%= d %>" fill="<%= area_fill(entry) %>" fill-opacity="<%= entry.fill_opacity %>" stroke="none" />
+            <path data-slot="chart-area-stroke" data-key="<%= entry.key %>" d="<%= top_line_path(entry) %>" fill="none" stroke="var(--color-<%= entry.key %>)" stroke-width="<%= entry.stroke_width %>" />
+          <% end %>
+        </g>
+      <% when :bar %>
+        <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="var(--color-<%= entry.key %>)"<% if animate? %> data-motion-origin="<%= motion_origin(cell) %>"<% end %> />
+          <% end %>
+        </g>
+      <% when :line %>
+        <g data-slot="chart-lines">
+          <% if (d = top_line_path(entry)) %>
+            <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 %>">
+              <% line_markers(entry).each do |marker| %>
+                <circle data-slot="chart-dot" cx="<%= fnum(marker[:x]) %>" cy="<%= fnum(marker[:y]) %>" r="<%= entry.dot_radius %>" fill="var(--color-<%= entry.key %>)" />
+              <% end %>
+            </g>
+          <% end %>
+        </g>
+      <% end %>
+    <% end %>
+    <%= 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 %>
+  </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 %>

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

@@ -0,0 +1,309 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    # The composed chart family.
+    module ComposedChart
+      # Renders a composed chart: area, bar, and line marks on ONE
+      # shared cartesian. All mark slots push into a single accumulator,
+      # so slot declaration order IS paint order. The x scale is always a
+      # band (bars need one; lines and areas ride the band centers), the
+      # y domain is shared across every mark, and stack ids are
+      # namespaced per mark type so an area stack can never co-stack
+      # with a bar stack by accident.
+      #
+      # @example Bars with a trend line on one plot
+      #   <%= poetry_chart :composed, data: data, config: config do |c| %>
+      #     <% c.with_grid %>
+      #     <% c.with_x_axis data_key: :month %>
+      #     <% c.with_bar data_key: :visitors, radius: 4 %>
+      #     <% c.with_line data_key: :trend, stroke_width: 2 %>
+      #     <% c.with_tooltip %>
+      #   <% end %>
+      class Component < Poetry::Core::Component
+        include Poetry::Charts::ChartFamily
+        include Poetry::Charts::TooltipWiring
+        include Poetry::Charts::Motion
+        include Poetry::Charts::BarMath
+        include Poetry::Charts::ReferenceMarks
+
+        # Projected into the registry and agent surface.
+        AGENT_RULES = [
+          "Mix marks freely: with_area / with_bar / with_line - declaration order is paint order.",
+          "All marks share the x band and ONE y domain; lines and areas ride the band centers.",
+          "stack: ids only combine within the same mark type (a bar stack never joins an area stack).",
+          "Colors come from the config - never set fill/stroke on a mark directly.",
+          "Entrance animation is on by default; each mark keeps its own reveal mechanism."
+        ].freeze
+
+        # One mark slot's captured series config, tagged by mark type.
+        Series = Data.define(:mark, :key, :stack, :curve, :fill_opacity, :gradient,
+                             :stroke_width, :dots, :dot_radius, :radius) do
+          # The band-slot group id: the stack, else the series' own key.
+          def stack_or_self = stack || key
+        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
+        option :bar_gap, :integer, default: 4, doc: "Pixels between side-by-side bars inside one category band."
+        option :bar_category_gap, :string, default: "10%",
+                                           doc: "Band trim on each side: a percent string of the band width, or a " \
+                                                "bare pixel number."
+
+        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-bar-series", "One series' bar group",
+             states: { "data-key" => "the series key" }
+        part "chart-bar", "One bar cell (a per-corner rounded-rect path)",
+             states: {
+               "data-key" => "the series key",
+               "data-index" => "the datum index",
+               "data-active" => "runtime - the tooltip controller marks the hovered index",
+               "data-motion-origin" => { condition: "when animate - the zero edge the entrance " \
+                                                    "grows from",
+                                         values: %w[bottom top] }
+             }
+        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-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 :areas,
+                     doc: "An area mark bound to data_key:; areas sharing a stack: id pile up (area stacks never " \
+                          "join bar stacks).",
+                     renders: lambda { |data_key:, stack: nil, curve: :natural, fill_opacity: 0.4,
+                                       gradient: false, stroke_width: 1|
+                       push_series(:area, key: data_key, stack: stack && "area-#{stack}",
+                                          curve: curve.to_sym, fill_opacity:, gradient:, stroke_width:)
+                     }
+
+        renders_many :bars,
+                     doc: "A bar mark bound to data_key:; radius: rounds corners; bars sharing a stack: id pile up " \
+                          "within the bar marks.",
+                     renders: lambda { |data_key:, stack: nil, radius: 0|
+                       push_series(:bar, key: data_key, stack: stack && "bar-#{stack}", radius: radius)
+                     }
+
+        renders_many :lines,
+                     doc: "A line mark bound to data_key:; dots: marks each point.",
+                     renders: lambda { |data_key:, curve: :natural, stroke_width: 2,
+                                       dots: false, dot_radius: 4|
+                       push_series(:line, key: data_key, curve: curve.to_sym, stroke_width:,
+                                          dots:, dot_radius:)
+                     }
+
+        include Poetry::Charts::CartesianFamily
+
+        # The captured Series configs in declaration order across every
+        # mark type.
+        # @api private
+        def series_entries
+          # Force every mark slot (slots evaluate lazily); the shared
+          # accumulator preserves declaration order across slot types.
+          areas?
+          bars?
+          lines?
+          @series_entries ||= []
+        end
+
+        # Just the bar-mark series, for the band slot math.
+        # @api private
+        def bar_entries = series_entries.select { |e| e.mark == :bar }
+
+        # The BarMath host contract: composed charts are vertical only.
+        # @api private
+        def horizontal? = false
+
+        # 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: margin || {},
+            category_axis: x_axis?,
+            value_axis: y_axis?,
+            y_tick_count: y_axis_config&.tick_count || 5,
+            x_scale_type: :band
+          )
+        end
+
+        # -- per-mark geometry -------------------------------------------------
+
+        # One area mark's fill path.
+        # @api private
+        def area_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
+
+        # A mark's top-curve stroke path (line marks, and area strokes).
+        # @api private
+        def top_line_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 per-group band slots for the bar marks.
+        # @api private
+        def bar_slots
+          @bar_slots ||= bar_slots_for(bar_entries)
+        end
+
+        # One bar series' rects, positioned in its band slot.
+        # @api private
+        def cells(entry)
+          bar_cells(entry, bar_slots.fetch(entry.stack_or_self))
+        end
+
+        # One bar cell's rounded-rect path.
+        # @api private
+        def bar_path(entry, cell)
+          bar_path_for(entry.radius, cell)
+        end
+
+        # The visible points for a line mark's dots (NaN renders nothing).
+        # @api private
+        def line_markers(entry)
+          cartesian.points(entry).each_with_index.filter_map do |point, i|
+            next if point[:value].nan?
+
+            { index: i, x: point[:x], y: point[:y1] }
+          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
+
+        # The per-series gradient def's id, scoped by the chart id.
+        # @api private
+        def gradient_id(entry)
+          "#{chart_id}-fill-#{entry.key}"
+        end
+
+        # An area mark's fill: its gradient url when gradient:, else its
+        # config color var.
+        # @api private
+        def area_fill(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 = "Composed chart"
+
+        # The embedded per-index geometry payload the tooltip controller
+        # reads.
+        # @api private
+        def coordinates_json
+          cartesian.coordinates.to_json
+        end
+
+        # Line and area marks show hover dots; bars reflect via data-index.
+        # @api private
+        def active_dot_markers(entry)
+          return [] if entry.mark == :bar
+
+          super
+        end
+
+        SERIES_DEFAULTS = { stack: nil, curve: nil, fill_opacity: nil, gradient: nil,
+                            stroke_width: nil, dots: nil, dot_radius: nil, radius: nil }.freeze
+        private_constant :SERIES_DEFAULTS
+
+        private
+
+        def push_series(mark, key:, **attrs)
+          attrs = SERIES_DEFAULTS.merge(attrs)
+          if attrs[:curve] && !CURVES.include?(attrs[:curve])
+            raise ArgumentError, "unknown curve #{attrs[:curve].inspect}"
+          end
+
+          (@series_entries ||= []) << Series.new(mark: mark, key: key.to_s, **attrs)
+          nil
+        end
+
+        private :bar_entries, :cartesian, :area_path, :top_line_path, :bar_slots, :cells
+        private :bar_path, :line_markers, :x_tick_label, :y_tick_label, :gradient_id, :area_fill, :svg_label_prefix
+        private :coordinates_json, :active_dot_markers
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    module ComposedChart
+      # The composed family: bars with a trend line, and the full
+      # area + bar + line mix.
+      class Preview < Poetry::Core::Preview::Base
+        DATA = [
+          { month: "January", visitors: 320, revenue: 214, trend: 240 },
+          { month: "February", visitors: 410, revenue: 305, trend: 290 },
+          { month: "March", visitors: 380, revenue: 237, trend: 320 },
+          { month: "April", visitors: 250, revenue: 173, trend: 300 },
+          { month: "May", visitors: 445, revenue: 209, trend: 340 },
+          { month: "June", visitors: 480, revenue: 264, trend: 390 }
+        ].freeze
+
+        CONFIG = {
+          visitors: { label: "Visitors", color: "var(--chart-1)" },
+          revenue: { label: "Revenue", color: "var(--chart-2)" },
+          trend: { label: "Trend", color: "var(--chart-3)" }
+        }.freeze
+
+        def bars_with_trend
+          render_component(data: DATA, config: CONFIG, id: "composed-trend") do |chart|
+            chart.with_grid
+            chart.with_x_axis(data_key: :month, tick_formatter: ->(v) { v[0, 3] })
+            chart.with_bar(data_key: :visitors, radius: 4)
+            chart.with_line(data_key: :trend, stroke_width: 2, dots: true)
+            chart.with_tooltip
+          end
+        end
+
+        def full_mix
+          render_component(data: DATA, config: CONFIG, id: "composed-mix") do |chart|
+            chart.with_grid
+            chart.with_x_axis(data_key: :month, tick_formatter: ->(v) { v[0, 3] })
+            chart.with_area(data_key: :revenue, fill_opacity: 0.25)
+            chart.with_bar(data_key: :visitors, radius: [4, 4, 0, 0])
+            chart.with_line(data_key: :trend, curve: :monotone_x, stroke_width: 2)
+            chart.with_legend
+            chart.with_tooltip
+          end
+        end
+
+        # A sync group member: charts sharing sync: broadcast/receive
+        # the active index - the sync value the stimulus contract holds
+        # to the DOM.
+        def synced
+          render_component(data: DATA, config: CONFIG, id: "composed-synced",
+                           sync: "composed-demo") do |chart|
+            chart.with_grid
+            chart.with_x_axis(data_key: :month, tick_formatter: ->(v) { v[0, 3] })
+            chart.with_bar(data_key: :visitors, radius: 4)
+            chart.with_line(data_key: :trend, stroke_width: 2, dots: true)
+            chart.with_tooltip
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    module ComposedChart
+      # The composed chrome on the shared cn-chart-* theme rules.
+      # Mark fills/strokes are var(--color-<key>) ATTRIBUTES.
+      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"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,4 @@
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <% if (css_text = theme_css) %><style><%= css_text.html_safe %></style><% end %>
+  <%= content %>
+<% end %>

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    # The chart container.
+    module Container
+      # The chart frame: the engine-agnostic outer layer every chart
+      # (poetry's own SVG engine, an adapter engine, or a
+      # Stimulus-mounted island) sits inside. It scopes the chart id, emits
+      # the per-series --color-<key> custom properties from the config
+      # (ThemeStyle, both themes), and carries the aspect-ratio sizing
+      # chrome. The content block is the chart body.
+      #
+      # @example
+      #   <%= poetry_chart_container(config: { desktop: { label: "Desktop", color: "var(--chart-1)" } }) do %>
+      #     ...the chart body...
+      #   <% end %>
+      class Component < Poetry::Core::Component
+        # Projected into the registry and agent surface.
+        AGENT_RULES = [
+          "Every chart lives inside poetry_chart_container(config:) - the config maps series keys to labels/colors.",
+          "Reference series colors as var(--color-<key>); never hard-code a color in chart markup.",
+          "Config colors point at theme tokens (var(--chart-1..5)) or use theme: { light:, dark: } maps.",
+          "Give charts an explicit id: when the page renders more than one of the same chart."
+        ].freeze
+
+        option :config, ActiveModel::Type::Value.new, required: true,
+                                                      doc: "The series config - key => { label:, color: } - driving " \
+                                                           "the per-series color emission."
+        option :id, :string,
+               doc: "Explicit DOM id token, stable across renders; otherwise the frame gets a unique per-render id."
+
+        part "chart", "The chart frame (<div>) - the aspect-video chrome, the tooltip layer's " \
+                      "positioning anchor, and the id scope the per-series colors are emitted for",
+             states: {
+               "data-chart" => "always - the chart instance id (explicit id: or unique per " \
+                               "render); the scoped color emission keys off it"
+             },
+             vars: {
+               "--color-*" => "per-series color, one entry per series key - the frame's " \
+                              "<style> block emits them for [data-chart=<id>] in both themes"
+             }
+
+        # The config: option wrapped as a {Poetry::Charts::Config}.
+        # @api private
+        def chart_config
+          @chart_config ||= Poetry::Charts::Config.wrap(config)
+        end
+
+        # The data-chart scope: explicit id when given (stable for tests /
+        # multiple charts), else unique per render.
+        # @api private
+        def chart_id
+          @chart_id ||= (dom_id_token(id) ? "chart-#{dom_id_token(id)}" : poetry_instance_id("chart"))
+        end
+
+        # The scoped per-series color declarations for the frame's
+        # <style> block, both themes.
+        # @api private
+        def theme_css
+          Poetry::Charts::ThemeStyle.new(id: chart_id, config: chart_config).css
+        end
+
+        # The frame div's attributes: part self-identification plus the
+        # data-chart scope.
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            {
+              "data-slot" => "chart",
+              "data-chart" => chart_id
+            }.merge(component_data_attributes)
+          )
+        end
+
+        private :chart_config, :chart_id, :theme_css, :root_attributes
+      end
+    end
+  end
+end