poetry-charts 0.0.2

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

@@ -0,0 +1,318 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    # The bar chart family.
+    module BarChart
+      # Renders a bar chart, vertical columns by default
+      # (orientation: :horizontal flips them): band-scale positioning - a
+      # 10% category gap trims each side of the band, a 4px gap separates
+      # side-by-side groups, stacked bars share a slot. Rounded corners
+      # are per-corner (radius: 8 or [tl, tr, br, bl] - stacked segments
+      # round only their outer edge), negatives drop below the zero
+      # baseline, and per-cell fills come from a data key or a guarded
+      # proc (sign-based coloring).
+      #
+      # @example Columns with rounded corners
+      #   <%= poetry_chart :bar, data:, config: do |c| %>
+      #     <% c.with_grid %>
+      #     <% c.with_x_axis data_key: :month, tick_formatter: ->(v) { v[0, 3] } %>
+      #     <% c.with_bar data_key: :desktop, radius: 8 %>
+      #   <% 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::BarMath
+        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_bar(data_key:) / with_legend.",
+          "radius: 8 rounds all corners; stacked bars use arrays - [0,0,4,4] bottom bar, [4,4,0,0] top bar.",
+          "Stack bars with the same stack: id; negatives automatically drop below the zero line.",
+          "cell_fill: ->(row, value) { ... } colors bars per datum (validated CSS-safe); color_key: reads a row key.",
+          "active_index: highlights one bar (fill-opacity 0.8 + dashed stroke - the active block look).",
+          "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_bar call's captured series config.
+        Series = Data.define(:key, :stack, :radius, :labels, :label_key, :color_key,
+                             :cell_fill, :active_index, :stroke_width, :error_key, :error_width) 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 category."
+        option :config, ActiveModel::Type::Value.new, required: true,
+                                                      doc: "The series config - key => { label:, color: } - naming " \
+                                                           "and coloring every series."
+        option :id, :string,
+               doc: "Explicit DOM id token, stable across renders; otherwise the chart gets a unique per-render id."
+        option :width, :integer, default: 640,
+                                 doc: "ViewBox width in pixels; the rendered chart scales to its container."
+        option :height, :integer, default: 360, doc: "ViewBox height in pixels."
+        option :margin, ActiveModel::Type::Value.new,
+               doc: "Plot margin overrides ({ top:, right:, bottom:, left: }), merged over the defaults."
+        option :offset, :symbol, default: :none,
+                                 doc: "Stack baseline mode - :expand normalizes each stack to percentages."
+        option :label, :string,
+               doc: "Accessible name for the chart SVG; defaults to one built from the configured series."
+
+        motion_options(duration: 400)
+        live_option
+        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."
+        option :orientation, :symbol, default: :vertical,
+                                      doc: ":vertical = columns (the default); :horizontal = bars growing rightward " \
+                                           "- the category axis moves to the Y side (with_y_axis data_key:) and the " \
+                                           "numeric axis hides."
+
+        validates :offset, inclusion: { in: Cartesian::OFFSETS }
+        validates :orientation, inclusion: { in: Cartesian::LAYOUTS }
+
+        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-bars", "The bar-mark group wrapping every series"
+        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" => "the highlighted cell - server-rendered from active_index:, " \
+                                "and the tooltip controller marks the hovered index at runtime",
+               "data-motion-origin" => { condition: "when animate - the zero edge the entrance " \
+                                                    "grows from",
+                                         values: %w[bottom top left right] }
+             }
+        part "chart-labels", "One series' value-label group (labels: true)",
+             states: { "data-key" => "the series key" }
+        part "chart-x-axis", "The x-axis tick-label group (with_x_axis)"
+        part "chart-y-axis", "The y-axis tick-label group (with_y_axis)"
+        part "chart-coordinates", "The embedded per-index geometry payload " \
+                                  "(<script type=application/json>) the tooltip controller " \
+                                  "reads - zero chart math in the browser"
+
+        renders_many :bars,
+                     doc: "A bar series bound to data_key:. Bars sharing a stack: id pile up; radius: rounds " \
+                          "corners; labels:/label_key: stamp values; color_key:/cell_fill: color per cell; " \
+                          "active_index: highlights one bar; error_key: adds whiskers.",
+                     renders: lambda { |data_key:, stack: nil, radius: 0, labels: false, label_key: nil,
+                                      color_key: nil, cell_fill: nil, active_index: nil, stroke_width: 2,
+                                      error_key: nil, error_width: 5|
+                       (@series_entries ||= []) << Series.new(key: data_key.to_s, stack:, radius:, labels:,
+                                                              label_key: label_key&.to_s, color_key: color_key&.to_s,
+                                                              cell_fill:, active_index:, stroke_width:,
+                                                              error_key: error_key&.to_s, error_width:)
+                       nil
+                     }
+
+        # In the horizontal orientation the Y axis IS the category axis -
+        # give it the data_key. The CartesianFamily value-axis hook, so
+        # the include below declares this shape between x_axis and grid.
+        def self.value_axis_slot
+          renders_one :y_axis,
+                      doc: "The y axis: data_key: makes it the category axis (horizontal orientation); " \
+                           "tick_count:/tick_formatter:/tick_margin: as on the x axis.",
+                      renders: lambda { |data_key: nil, tick_count: 3, tick_formatter: nil, tick_margin: 8|
+                        @y_axis_config = AxisConfig.new(data_key: data_key&.to_s, tick_formatter:,
+                                                        tick_margin:, tick_count:)
+                        nil
+                      }
+        end
+
+        include Poetry::Charts::CartesianFamily
+
+        # The captured Series configs, forcing lazy slot evaluation.
+        # @api private
+        def series_entries
+          bars? # force slot evaluation (slots evaluate lazily)
+          @series_entries ||= []
+        end
+
+        # Whether bars grow rightward from a Y-side category axis.
+        # @api private
+        def horizontal?
+          orientation == :horizontal
+        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: horizontal? ? y_axis_config&.data_key : x_axis_config&.data_key,
+            margin: live_margin,
+            category_axis: horizontal? ? y_axis? : x_axis?,
+            value_axis: !horizontal? && y_axis?,
+            # Horizontal charts hide the numeric axis (implicit tickCount 5);
+            # vertical ones take the visible Y axis's count when present.
+            y_tick_count: horizontal? ? 5 : (y_axis_config&.tick_count || 5),
+            offset: offset,
+            x_scale_type: :band,
+            layout: orientation
+          )
+        end
+
+        # The per-group band slots: stacked bars share a slot; groups sit
+        # side by side inside the band (no explicit bar size).
+        # @api private
+        def bar_slots
+          @bar_slots ||= bar_slots_for(series_entries)
+        end
+
+        # One series' bar 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
+
+        # Fill resolution: cell_fill proc, else color_key row value, else
+        # the series color - everything reaching the attribute is guarded.
+        # @api private
+        def cell_fill(entry, cell)
+          color = if entry.cell_fill
+                    entry.cell_fill.call(cell[:row], cell[:value]).to_s
+                  elsif entry.color_key
+                    cell[:row].to_h.transform_keys(&:to_s)[entry.color_key].to_s
+                  else
+                    return "var(--color-#{entry.key})"
+                  end
+          raise ArgumentError, "bar fill #{color.inspect} is not CSS-safe" unless color.match?(Config::COLOR)
+
+          color
+        end
+
+        # Whether this cell is the series' highlighted active_index.
+        # @api private
+        def active?(entry, cell)
+          entry.active_index == cell[:index]
+        end
+
+        # A cell's value label: the label_key row value, else the value
+        # with integers shown bare.
+        # @api private
+        def cell_label(entry, cell)
+          if entry.label_key
+            cell[:row].to_h.transform_keys(&:to_s)[entry.label_key].to_s
+          else
+            value = cell[:value]
+            value == value.to_i ? value.to_i.to_s : value.to_s
+          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
+
+        # The horizontal layout's category labels (the Y side).
+        # @api private
+        def category_tick_label(category)
+          formatter = y_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
+
+        # ChartFamily#svg_label's chart-type lead-in.
+        # @api private
+        def svg_label_prefix = "Bar 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 = :bar
+
+        # The series list serialized into the live spec.
+        # @api private
+        def live_series
+          series_entries.map { |e| { data_key: e.key, stack: e.stack }.compact }
+        end
+
+        # The axis config serialized into the live spec.
+        # @api private
+        def live_axes
+          axes = {}
+          if horizontal?
+            axes[:y] = { data_key: y_axis_config.data_key } if y_axis_config&.data_key
+          else
+            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
+          end
+          axes
+        end
+
+        # The x scale kind the live renderer rebuilds.
+        # @api private
+        def live_x_scale_type = :band
+        # Whether the live frame renders a category axis.
+        # @api private
+        def live_category_axis? = horizontal? ? y_axis? : x_axis?
+
+        # Bar-specific geometry knobs merged into the frame envelope.
+        # @api private
+        def live_frame_extras
+          {
+            "barGap" => bar_gap,
+            "barCategoryGap" => bar_category_gap,
+            "series" => series_entries.to_h { |e| [e.key, { "radius" => e.radius }] }
+          }
+        end
+
+        private :cartesian, :bar_slots, :cells, :bar_path, :cell_fill, :active?
+        private :cell_label, :x_tick_label, :category_tick_label, :y_tick_label, :svg_label_prefix, :coordinates_json
+        private :live_type, :live_series, :live_axes, :live_x_scale_type, :live_category_axis?, :live_frame_extras
+      end
+    end
+  end
+end

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

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    module BarChart
+      # The bar family (vertical) across its variants: default
+      # (radius 8), multiple, stacked (outer-edge radius arrays), negative
+      # (sign-colored cells + month labels), value labels, the active
+      # highlight, and the horizontal + mixed layouts.
+      class Preview < Poetry::Core::Preview::Base
+        DATA = AreaChart::Preview::DATA
+        ONE = AreaChart::Preview::ONE
+        TWO = AreaChart::Preview::TWO
+
+        NEGATIVE_DATA = [
+          { month: "January", visitors: 186 },
+          { month: "February", visitors: 205 },
+          { month: "March", visitors: -207 },
+          { month: "April", visitors: 173 },
+          { month: "May", visitors: -209 },
+          { month: "June", visitors: 214 }
+        ].freeze
+
+        VISITORS = { visitors: { label: "Visitors" } }.freeze
+
+        BROWSER_DATA = LineChart::Preview::BROWSER_DATA
+        BROWSER_CONFIG = LineChart::Preview::BROWSER_CONFIG
+
+        def default
+          render_component(data: DATA, config: ONE, id: "bar-default") do |chart|
+            chart.with_grid
+            chart.with_x_axis(data_key: :month, tick_formatter: ->(v) { v[0, 3] })
+            chart.with_bar(data_key: :desktop, radius: 8)
+            chart.with_tooltip(hide_label: true)
+          end
+        end
+
+        def multiple
+          render_component(data: DATA, config: TWO, id: "bar-multiple") do |chart|
+            chart.with_grid
+            chart.with_x_axis(data_key: :month, tick_formatter: ->(v) { v[0, 3] })
+            chart.with_bar(data_key: :desktop, radius: 4)
+            chart.with_bar(data_key: :mobile, radius: 4)
+          end
+        end
+
+        def stacked
+          render_component(data: DATA, config: TWO, id: "bar-stacked") do |chart|
+            chart.with_grid
+            chart.with_x_axis(data_key: :month, tick_formatter: ->(v) { v[0, 3] })
+            chart.with_bar(data_key: :desktop, stack: :a, radius: [0, 0, 4, 4])
+            chart.with_bar(data_key: :mobile, stack: :a, radius: [4, 4, 0, 0])
+            chart.with_legend
+          end
+        end
+
+        def negative
+          render_component(data: NEGATIVE_DATA, config: VISITORS, id: "bar-negative") do |chart|
+            chart.with_grid
+            chart.with_bar(data_key: :visitors, labels: true, label_key: :month,
+                           cell_fill: ->(_row, value) { value.positive? ? "var(--chart-1)" : "var(--chart-2)" })
+          end
+        end
+
+        def label
+          render_component(data: DATA, config: ONE, id: "bar-label", margin: { top: 20 }) do |chart|
+            chart.with_grid
+            chart.with_x_axis(data_key: :month, tick_formatter: ->(v) { v[0, 3] })
+            chart.with_bar(data_key: :desktop, radius: 8, labels: true)
+          end
+        end
+
+        def active
+          render_component(data: BROWSER_DATA, config: BROWSER_CONFIG, id: "bar-active") do |chart|
+            chart.with_grid
+            chart.with_x_axis(data_key: :browser, tick_formatter: ->(v) { BROWSER_CONFIG[v.to_sym][:label] })
+            chart.with_bar(data_key: :visitors, radius: 8, color_key: :fill, active_index: 2)
+          end
+        end
+
+        def horizontal
+          render_component(data: DATA, config: ONE, id: "bar-horizontal",
+                           orientation: :horizontal, margin: { left: -20 }) do |chart|
+            chart.with_y_axis(data_key: :month, tick_formatter: ->(v) { v[0, 3] }, tick_margin: 10)
+            chart.with_bar(data_key: :desktop, radius: 5)
+          end
+        end
+
+        def mixed
+          render_component(data: BROWSER_DATA, config: BROWSER_CONFIG, id: "bar-mixed",
+                           orientation: :horizontal, margin: { left: 0 }) do |chart|
+            chart.with_y_axis(data_key: :browser, tick_margin: 10,
+                              tick_formatter: ->(v) { BROWSER_CONFIG[v.to_sym][:label] })
+            chart.with_bar(data_key: :visitors, radius: 5, color_key: :fill)
+          end
+        end
+
+        # The full live-window surface in one frame - the client renderer
+        # (live:), the zoom drag, the brush strip, and a sync group: the
+        # wiring the stimulus contract holds to the DOM. No tick_formatter
+        # (lambdas cannot ride the live payload).
+        def live_window
+          render_component(data: DATA, config: ONE, id: "bar-live", live: true, zoom: true,
+                           sync: "bar-demo") do |chart|
+            chart.with_grid
+            chart.with_x_axis(data_key: :month)
+            chart.with_bar(data_key: :desktop, radius: 8)
+            chart.with_tooltip(hide_label: true)
+            chart.with_brush
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    module BarChart
+      # The cartesian chrome on the shared cn-chart-* theme rules
+      # + the bar 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/bar_math.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    # The bar geometry shared by BarChart and ComposedChart: the slot
+    # math dividing each category band (no explicit bar size - stacked
+    # bars share a slot, groups sit side by side inside the band), the
+    # per-corner rounded rect path, and the entrance origin. Hosts
+    # provide cartesian, data, horizontal?, fnum, bar_gap, and
+    # bar_category_gap.
+    # @api private
+    module BarMath
+      # One {offset, size} slot per stack group, laid out inside the
+      # category band.
+      def bar_slots_for(entries)
+        groups = entries.map(&:stack_or_self).uniq
+        band = cartesian.band_width
+        gap = bar_gap.to_f
+        trim = bar_percent_value(bar_category_gap, band)
+        gap = 0.0 if band - (2 * trim) - ((groups.length - 1) * gap) <= 0
+
+        size = (band - (2 * trim) - ((groups.length - 1) * gap)) / groups.length
+        size = Geometry.js_round(size).to_f if size > 1
+
+        groups.each_with_index.to_h do |group, i|
+          [group, { offset: trim + ((size + gap) * i), size: size }]
+        end
+      end
+
+      # One rect per category for a series: band position + slot offset
+      # along the category side, the value span on the other, normalized
+      # so width/height stay positive (negatives keep the zero edge).
+      def bar_cells(entry, slot)
+        points = cartesian.points(entry)
+
+        points.each_with_index.filter_map do |point, i|
+          next if point[:value].nan?
+
+          base = { index: i, value: point[:value], row: data[i] }
+          if horizontal?
+            left = [point[:x0], point[:x1]].min
+            right = [point[:x0], point[:x1]].max
+            base.merge(x: left, y: cartesian.x_positions[i] + slot[:offset],
+                       width: right - left, height: slot[:size])
+          else
+            top = [point[:y0], point[:y1]].min
+            bottom = [point[:y0], point[:y1]].max
+            base.merge(x: cartesian.x_positions[i] + slot[:offset], y: top,
+                       width: slot[:size], height: bottom - top)
+          end
+        end
+      end
+
+      # The zero edge the entrance animation grows from: sign x
+      # orientation - stacked segments grow from their own zero-side
+      # edge, not the axis baseline.
+      def motion_origin(cell)
+        if horizontal?
+          cell[:value].negative? ? "right" : "left"
+        else
+          cell[:value].negative? ? "top" : "bottom"
+        end
+      end
+
+      # radius: Integer (all corners) or [tl, tr, br, bl] (the stacked
+      # blocks). Clamped to half the rect so corners never cross.
+      def bar_path_for(radius, cell)
+        radii = radius.is_a?(Array) ? radius.map(&:to_f) : Array.new(4, radius.to_f)
+        max = [cell[:width] / 2.0, cell[:height] / 2.0].min
+        tl, tr, br, bl = radii.map { |r| r.clamp(0.0, max) }
+        x = cell[:x]
+        y = cell[:y]
+        w = cell[:width]
+        h = cell[:height]
+        f = ->(v) { fnum(v) }
+
+        "M#{f.call(x)},#{f.call(y + tl)}" \
+          "#{"A#{f.call(tl)},#{f.call(tl)},0,0,1,#{f.call(x + tl)},#{f.call(y)}" if tl.positive?}" \
+          "L#{f.call(x + w - tr)},#{f.call(y)}" \
+          "#{"A#{f.call(tr)},#{f.call(tr)},0,0,1,#{f.call(x + w)},#{f.call(y + tr)}" if tr.positive?}" \
+          "L#{f.call(x + w)},#{f.call(y + h - br)}" \
+          "#{"A#{f.call(br)},#{f.call(br)},0,0,1,#{f.call(x + w - br)},#{f.call(y + h)}" if br.positive?}" \
+          "L#{f.call(x + bl)},#{f.call(y + h)}" \
+          "#{"A#{f.call(bl)},#{f.call(bl)},0,0,1,#{f.call(x)},#{f.call(y + h - bl)}" if bl.positive?}Z"
+      end
+
+      # Percent-or-pixels: "10%" resolves against the total, a bare
+      # number is pixels.
+      def bar_percent_value(value, total)
+        text = value.to_s
+        text.end_with?("%") ? total * (text.to_f / 100.0) : text.to_f
+      end
+    end
+  end
+end

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    # The shared cartesian slot grammar (area/line/bar/composed): the
+    # axis/grid/legend/tooltip slots plus the readers that force their
+    # lazy evaluation. Lambda slots accumulate config into ivars and
+    # return nil (the breadcrumb pattern - slot wrappers do not delegate
+    # to lambda return values); readers force evaluation via the slot
+    # predicate (slots evaluate lazily).
+    #
+    # Slots register at the include site because declaration order IS the
+    # registry's slot order - include this AFTER the family's mark slots.
+    # The value axis is a class-method hook: a family whose Y side
+    # diverges (bar - the horizontal orientation moves the category axis
+    # there) defines its own value_axis_slot before including.
+    #
+    # @example Adding the cartesian slot grammar to a family
+    #   class StepChart::Component < Poetry::Core::Component
+    #     include Poetry::Charts::ChartFamily
+    #
+    #     # Mark slots first - declaration order is the registry's slot order.
+    #     renders_many :steps, lambda { |data_key:| ... }
+    #
+    #     include Poetry::Charts::CartesianFamily
+    #   end
+    module CartesianFamily
+      def self.included(base)
+        base.extend(ClassMethods)
+
+        # The category axis: data_key: names the field ticks label;
+        # tick_formatter: reshapes each label; tick_margin: pads it from
+        # the plot.
+        base.renders_one :x_axis, lambda { |data_key:, tick_formatter: nil, tick_margin: 8|
+          @x_axis_config = AxisConfig.new(data_key: data_key.to_s, tick_formatter:, tick_margin:, tick_count: nil)
+          nil
+        }
+
+        base.value_axis_slot
+
+        # The gridlines: horizontal rules by default; vertical: true adds
+        # column rules.
+        base.renders_one :grid, lambda { |vertical: false, horizontal: true|
+          @grid_config = GridConfig.new(vertical:, horizontal:)
+          nil
+        }
+
+        # The legend row under the plot: align:, items:, hide_icon:, and
+        # toggle: (live charts only - clicking an entry hides its series).
+        base.renders_one :legend, lambda { |**options|
+          @legend_config = options
+          nil
+        }
+
+        # The hover tooltip: indicator:, hide_label:, hide_indicator:, and
+        # cursor: (the hover rule/band, on by default). The slot captures
+        # options only; the tooltip layer itself (controller + chrome
+        # wiring) is declared by TooltipWiring.
+        base.renders_one :tooltip, lambda { |**options|
+          @tooltip_config = options
+          nil
+        }
+      end
+
+      # The class-level hooks the include site drives.
+      module ClassMethods
+        # Declares the default numeric Y axis slot (tick count 3, no data
+        # key). Families whose value axis diverges override this before
+        # including the concern.
+        def value_axis_slot
+          renders_one :y_axis,
+                      doc: "The value axis: tick_count: sets how many ticks show; tick_formatter: reshapes each " \
+                           "label; tick_margin: pads it.",
+                      renders: lambda { |tick_count: 3, tick_formatter: nil, tick_margin: 8|
+                        @y_axis_config = AxisConfig.new(data_key: nil, tick_formatter:, tick_margin:, tick_count:)
+                        nil
+                      }
+        end
+      end
+
+      # The x-axis slot's captured config, forcing lazy slot evaluation.
+      # @api private
+      def x_axis_config
+        x_axis?
+        @x_axis_config
+      end
+
+      # The y-axis slot's captured config, forcing lazy slot evaluation.
+      # @api private
+      def y_axis_config
+        y_axis?
+        @y_axis_config
+      end
+
+      # The grid slot's captured config, forcing lazy slot evaluation.
+      # @api private
+      def grid_config
+        grid?
+        @grid_config
+      end
+
+      private :x_axis_config, :y_axis_config, :grid_config
+    end
+  end
+end