poetry-charts 0.0.2

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    module ScatterChart
+      # The scatter family: simple, two series, and z-sized bubbles.
+      class Preview < Poetry::Core::Preview::Base
+        SAMPLE = [
+          { height: 161, weight: 51, bmi: 19.7 },
+          { height: 167, weight: 59, bmi: 21.2 },
+          { height: 170, weight: 68, bmi: 23.5 },
+          { height: 174, weight: 66, bmi: 21.8 },
+          { height: 178, weight: 79, bmi: 24.9 },
+          { height: 183, weight: 84, bmi: 25.1 },
+          { height: 189, weight: 95, bmi: 26.6 }
+        ].freeze
+
+        CONTROL = [
+          { height: 158, weight: 62, bmi: 24.8 },
+          { height: 165, weight: 71, bmi: 26.1 },
+          { height: 172, weight: 60, bmi: 20.3 },
+          { height: 180, weight: 88, bmi: 27.2 },
+          { height: 186, weight: 77, bmi: 22.3 }
+        ].freeze
+
+        ONE = { sample: { label: "Sample", color: "var(--chart-1)" } }.freeze
+        TWO = ONE.merge(control: { label: "Control", color: "var(--chart-2)" }).freeze
+
+        def default
+          render_component(data: SAMPLE, config: ONE, id: "scatter-default",
+                           margin: { left: 12, right: 12 }) do |chart|
+            chart.with_grid
+            chart.with_x_axis(data_key: :height, name: "Height")
+            chart.with_y_axis(data_key: :weight, name: "Weight")
+            chart.with_scatter(key: :sample)
+            chart.with_tooltip
+          end
+        end
+
+        def multiple
+          render_component(data: SAMPLE, config: TWO, id: "scatter-multiple",
+                           margin: { left: 12, right: 12 }) do |chart|
+            chart.with_grid
+            chart.with_x_axis(data_key: :height, name: "Height")
+            chart.with_y_axis(data_key: :weight, name: "Weight")
+            chart.with_scatter(key: :sample)
+            chart.with_scatter(key: :control, data: CONTROL)
+            chart.with_legend
+            chart.with_tooltip
+          end
+        end
+
+        def bubbles
+          render_component(data: SAMPLE, config: ONE, id: "scatter-bubbles",
+                           margin: { left: 12, right: 12 }) do |chart|
+            chart.with_grid
+            chart.with_x_axis(data_key: :height, name: "Height")
+            chart.with_y_axis(data_key: :weight, name: "Weight")
+            chart.with_z_axis(data_key: :bmi, range: [64, 400])
+            chart.with_scatter(key: :sample)
+            chart.with_tooltip
+          end
+        end
+
+        def reference_zones
+          render_component(data: SAMPLE, config: ONE, id: "scatter-refs",
+                           margin: { left: 12, right: 12 }) do |chart|
+            chart.with_grid
+            chart.with_x_axis(data_key: :height, name: "Height")
+            chart.with_y_axis(data_key: :weight, name: "Weight")
+            chart.with_scatter(key: :sample, error_key: :werr)
+            chart.with_reference_area(y1: 60, y2: 80, label: "target band")
+            chart.with_reference_line(x: 175)
+            chart.with_reference_dot(x: 172, y: 70, r: 10, label: "median")
+            chart.with_tooltip
+          end
+        end
+
+        # A sync group member: the sync value the stimulus contract
+        # holds to the DOM.
+        def synced
+          render_component(data: SAMPLE, config: ONE, id: "scatter-synced",
+                           margin: { left: 12, right: 12 }, sync: "scatter-demo") do |chart|
+            chart.with_x_axis(data_key: :height, name: "Height")
+            chart.with_y_axis(data_key: :weight, name: "Weight")
+            chart.with_scatter(key: :sample)
+            chart.with_tooltip
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    module ScatterChart
+      # The scatter chrome on the shared cn-chart-* theme rules.
+      # Point fills 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 :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/tooltip_content/component.html.erb

@@ -0,0 +1,19 @@
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <% if label_text && !nest_label? %><div data-slot="chart-tooltip-label" class="<%= css(:label) %>"><%= label_text %></div><% end %>
+  <div class="<%= css(:inner) %>">
+    <% rows.each do |row| %>
+      <div data-slot="chart-tooltip-item" data-key="<%= row.key %>" class="<%= row_classes %>">
+        <% unless hide_indicator %>
+          <div data-slot="chart-tooltip-indicator" class="<%= indicator_classes(nested: nest_label?) %>"<% if row.indicator_style %> style="<%= row.indicator_style %>"<% end %>></div>
+        <% end %>
+        <div class="<%= value_wrap_classes %>">
+          <div class="<%= css(:inner) %>">
+            <% if label_text && nest_label? %><div data-slot="chart-tooltip-label" class="<%= css(:label) %>"><%= label_text %></div><% end %>
+            <span data-slot="chart-tooltip-name" class="<%= css(:name) %>"><%= row.name %></span>
+          </div>
+          <% if row.formatted_value %><span data-slot="chart-tooltip-value" class="<%= css(:value) %>"><%= row.formatted_value %></span><% end %>
+        </div>
+      </div>
+    <% end %>
+  </div>
+<% end %>

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

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    # The chart tooltip chrome.
+    module TooltipContent
+      # The tooltip chrome - the styled info box: optional label, then
+      # one row per series item (indicator + name + tabular value). Pure
+      # server-rendered markup; the tooltip controller positions and
+      # repopulates it from server-embedded coordinates. Indicator colors
+      # ride the --color-bg/--color-border inline custom properties, so a
+      # row's swatch follows its series.
+      #
+      # @example
+      #   <%= poetry_chart_tooltip_content(config: config,
+      #                                    items: [{ key: :desktop, value: 186 }]) %>
+      #
+      # Items are `{ key:, name:, value:, color: }` hashes; names resolve
+      # through the config (config label, else the item name, else the
+      # key) and colors fall back to the config entry's color, all
+      # server-side.
+      class Component < Poetry::Core::Component
+        # Projected into the registry and agent surface.
+        AGENT_RULES = [
+          "Tooltip rows resolve names/colors through the chart config - pass key:, not a display string.",
+          "indicator: :dot (default) | :line | :dashed matches the ported variants.",
+          "Numeric values render delimited (1,234) in the mono tabular column automatically."
+        ].freeze
+
+        option :config, ActiveModel::Type::Value.new, required: true,
+                                                      doc: "The series config - key => { label:, color: } - " \
+                                                           "resolving row names and colors."
+        option :items, ActiveModel::Type::Value.new, required: true,
+                                                     doc: "The rows: [{ key:, name:, value:, color: }] hashes, one " \
+                                                          "per series."
+        option :indicator, :symbol, default: :dot, doc: "The row swatch shape."
+        option :label, :string, doc: "The category label above the rows, resolved through the config."
+        option :hide_label, :boolean, default: false, doc: "Hides the category label."
+        option :hide_indicator, :boolean, default: false, doc: "Hides the row swatches."
+
+        validates :indicator, inclusion: { in: %i[dot line dashed] }
+
+        part "chart-tooltip-content", "The tooltip box (<div>) - the styled chrome the chart's " \
+                                      "tooltip controller positions and text-swaps"
+        part "chart-tooltip-label", "The category label (<div>) - above the rows, or nested " \
+                                    "inside the single row for line/dashed indicators"
+        part "chart-tooltip-item", "One series row (<div>) - indicator + name + value",
+             states: { "data-key" => "always - the series key the controller matches values by" }
+        part "chart-tooltip-indicator", "The row's swatch (<div>) - dot/line/dashed per " \
+                                        "indicator:, hidden with hide_indicator",
+             vars: {
+               "--color-bg" => "the swatch fill - carries the row's series color (inline; polar " \
+                               "charts retint it to the hovered slice's color at runtime)",
+               "--color-border" => "the swatch border - the same series color as the fill"
+             }
+        part "chart-tooltip-name", "The series name (<span>) - resolved through the chart config"
+        part "chart-tooltip-value", "The formatted value (<span>) - the mono tabular column, " \
+                                    "numbers delimited"
+
+        # The config: option wrapped as a {Poetry::Charts::Config}.
+        # @api private
+        def chart_config
+          @chart_config ||= Poetry::Charts::Config.wrap(config)
+        end
+
+        # The items resolved into Row objects.
+        # @api private
+        def rows
+          @rows ||= Array(items).map { |item| Row.new(item.symbolize_keys, chart_config) }
+        end
+
+        # The label nests inside the single row for line/dashed
+        # indicators - the layout that makes the 1-series line-indicator
+        # tooltip read as one unit.
+        # @api private
+        def nest_label?
+          rows.length == 1 && indicator != :dot
+        end
+
+        # Label resolution: config label for the key when one matches,
+        # else the given string.
+        # @api private
+        def label_text
+          return nil if hide_label || label.blank?
+
+          chart_config.label_for(label, label)
+        end
+
+        # A row's classes, with the dot layout when the indicator is one.
+        # @api private
+        def row_classes
+          classes = css(:row)
+          classes = "#{classes} #{css(:row_dot)}" if indicator == :dot
+          classes
+        end
+
+        # The swatch's classes for the indicator shape (nested dashes get
+        # their own alignment).
+        # @api private
+        def indicator_classes(nested: false)
+          classes = "#{css(:indicator)} #{css(:"indicator_#{indicator}")}"
+          classes = "#{classes} #{css(:indicator_dashed_nested)}" if nested && indicator == :dashed
+          classes
+        end
+
+        # The value column's alignment classes (nested labels bottom-align).
+        # @api private
+        def value_wrap_classes
+          "#{css(:value_wrap)} #{nest_label? ? css(:value_wrap_end) : css(:value_wrap_center)}"
+        end
+
+        # The box's attributes with the part self-identification.
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            { "data-slot" => "chart-tooltip-content" }.merge(component_data_attributes)
+          )
+        end
+
+        # One resolved tooltip row: name via config, color via item-else-config.
+        # @api private
+        class Row
+          def initialize(item, config)
+            @item = item
+            @config = config
+          end
+
+          def key
+            (@item[:key] || @item[:name] || "value").to_s
+          end
+
+          def name
+            @config.label_for(key, @item[:name])
+          end
+
+          def color
+            @item[:color] || @config[key]&.color
+          end
+
+          def value
+            @item[:value]
+          end
+
+          def formatted_value
+            return nil if value.nil?
+            return ActiveSupport::NumberHelper.number_to_delimited(value) if value.is_a?(Numeric)
+
+            value.to_s
+          end
+
+          # Guarded inline style: colors reaching a style attribute must be
+          # CSS-safe (config colors already are; item colors get the same rule).
+          def indicator_style
+            return nil unless color
+            unless color.match?(Config::COLOR)
+              raise ArgumentError, "tooltip item color #{color.inspect} is not CSS-safe"
+            end
+
+            "--color-bg: #{color}; --color-border: #{color};"
+          end
+        end
+
+        private :chart_config, :rows, :nest_label?, :label_text, :row_classes, :indicator_classes, :value_wrap_classes
+        private :root_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    module TooltipContent
+      # The tooltip chrome across its three indicator variants - every
+      # chart tooltip composes from exactly these pieces.
+      class Preview < Poetry::Core::Preview::Base
+        CONFIG = {
+          desktop: { label: "Desktop", color: "var(--chart-1)" },
+          mobile: { label: "Mobile", color: "var(--chart-2)" }
+        }.freeze
+
+        ITEMS = [
+          { key: "desktop", value: 1260 },
+          { key: "mobile", value: 570 }
+        ].freeze
+
+        def default
+          render_component(config: CONFIG, items: ITEMS, label: "January")
+        end
+
+        def line_indicator
+          render_component(config: CONFIG, items: [{ key: "desktop", value: 1260 }],
+                           label: "January", indicator: :line)
+        end
+
+        def dashed_indicator
+          render_component(config: CONFIG, items: [{ key: "desktop", value: 1260 }],
+                           label: "January", indicator: :dashed)
+        end
+
+        def no_label
+          render_component(config: CONFIG, items: ITEMS, hide_label: true)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    module TooltipContent
+      # Re-expressed through the cn-* theme layer: the box, type,
+      # and row treatments ride cn-chart-tooltip-* rules. The indicator's
+      # border-(--color-border)/bg-(--color-bg) arbitrary properties stay
+      # inline - they read the per-row inline custom properties the
+      # component sets to the series color (mechanism).
+      class Style < Poetry::Core::Style
+        base "cn-chart-tooltip grid min-w-[8rem] items-start"
+
+        element :label, "cn-chart-tooltip-label"
+        element :inner, "grid gap-1.5"
+        element :row, "cn-chart-tooltip-row flex w-full flex-wrap items-stretch"
+        element :row_dot, "items-center"
+        element :indicator, "shrink-0 rounded-[2px] border-(--color-border) bg-(--color-bg)"
+        element :indicator_dot, "h-2.5 w-2.5"
+        element :indicator_line, "w-1"
+        element :indicator_dashed, "w-0 border-[1.5px] border-dashed bg-transparent"
+        element :indicator_dashed_nested, "my-0.5"
+        element :value_wrap, "flex flex-1 justify-between leading-none"
+        element :value_wrap_center, "items-center"
+        element :value_wrap_end, "items-end"
+        element :name, "cn-chart-tooltip-name"
+        element :value, "cn-chart-tooltip-value"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,6 @@
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <%= render Poetry::Charts::TooltipContent::Component.new(
+        config: chart_config, items: items, label: hide_label ? nil : "…",
+        indicator: indicator, hide_label: hide_label, hide_indicator: hide_indicator
+      ) %>
+<% end %>

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    # The chart families' internal hover-tooltip mount.
+    module TooltipLayer
+      # The hidden tooltip box a chart family renders when with_tooltip is
+      # set: the TooltipContent chrome pre-rendered with one row per series
+      # (names and indicator colors resolved server-side), positioned and
+      # text-swapped by the tooltip controller. Rendered by the chart
+      # families, never composed directly.
+      # @api private
+      class Component < Poetry::Core::Component
+        # The box is the parent frame controller's tooltip target - no
+        # registration here (TooltipWiring registers on the chart frame).
+        use_stimulus do
+          on :root do
+            controller(TooltipWiring::CONTROLLER) { target :tooltip }
+          end
+        end
+
+        option :config, ActiveModel::Type::Value.new, required: true,
+                                                      doc: "The series config - key => { label:, color: } - " \
+                                                           "resolving row names and colors."
+        option :series_keys, ActiveModel::Type::Value.new, required: true,
+                                                           doc: "The series keys to pre-render rows for."
+        option :indicator, :symbol, default: :dot, doc: "The row swatch shape."
+        option :hide_label, :boolean, default: false, doc: "Hides the category label."
+        option :hide_indicator, :boolean, default: false, doc: "Hides the row swatches."
+
+        # The config: option wrapped as a {Poetry::Charts::Config}.
+        # @api private
+        def chart_config
+          @chart_config ||= Poetry::Charts::Config.wrap(config)
+        end
+
+        # Placeholder rows: value 0 guarantees the value span exists for
+        # the controller to swap; the box is hidden until a point is active.
+        # @api private
+        def items
+          series_keys.map { |key| { key: key, value: 0 } }
+        end
+
+        # The hidden box's attributes: part self-identification plus the
+        # parent frame controller's tooltip target.
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            {
+              "data-slot" => "chart-tooltip",
+              "hidden" => ""
+            }.merge(stimulus_attributes_for(:root))
+              .merge(component_data_attributes)
+          )
+        end
+
+        private :chart_config, :items, :root_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    module TooltipLayer
+      # The floating box: absolute within the relative Container, above the
+      # SVG, never intercepting the pointer (the SVG owns the events).
+      class Style < Poetry::Core::Style
+        base "pointer-events-none absolute z-10 w-max"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    # Shared tooltip wiring for the chart families: the frame
+    # wrapper carries the controller, the SVG carries targets/actions plus
+    # the accessibilityLayer floor (focusable, role=application, arrows walk
+    # categories), and the hidden chrome pre-renders per-series rows the
+    # controller text-swaps - zero chart math in the browser.
+    module TooltipWiring
+      # Full-string controller identifier - the bare :tooltip shorthand
+      # would be ambiguous with the core tooltip controller.
+      CONTROLLER = "poetry--charts--tooltip"
+
+      # The wiring is declared, not hand-built: the frame carries the
+      # controller + sync value, the SVG carries the target and the
+      # pointer/keyboard actions (the accessibilityLayer floor), and the
+      # coordinates <script> is the data target the controller reads.
+      def self.included(base)
+        # Sync-group id: charts sharing the same sync: broadcast and
+        # receive each other's active index.
+        base.option :sync, :string
+
+        base.use_stimulus do
+          on :frame do
+            controller CONTROLLER, if: :tooltip? do
+              register
+              value :sync, if: -> { sync.present? }
+            end
+          end
+          on :svg do
+            controller CONTROLLER, if: :tooltip? do
+              target :svg
+              action :move, on: :pointermove
+              action :leave, on: :pointerleave
+              action :focus, on: :focus
+              action :blur, on: :blur
+              action :keydown, on: :keydown
+            end
+          end
+          on :coordinates do
+            controller CONTROLLER, if: :tooltip? do
+              target :data
+            end
+          end
+          # Rendered BY the TooltipLayer child inside the frame - mirrored
+          # here so the family's contract owns its full anatomy (the gate
+          # flags phantom if the layer ever stops rendering it).
+          on :tooltip_layer do
+            controller CONTROLLER, if: :tooltip? do
+              target :tooltip
+            end
+          end
+        end
+      end
+
+      # The tooltip slot's captured options, forcing lazy slot evaluation.
+      # @api private
+      def tooltip_config
+        tooltip?
+        @tooltip_config || {}
+      end
+
+      # The legend slot's options, guarded: toggle needs the live renderer
+      # (hiding a series recomputes the domain client-side).
+      # @api private
+      def legend_config
+        legend?
+        config = @legend_config || {}
+        if config[:toggle] && !(respond_to?(:live?) && live?)
+          raise ArgumentError, "with_legend toggle: true needs live: true - " \
+                               "the toggle recomputes the domain client-side"
+        end
+        config
+      end
+
+      # The with_legend options forwarded to the LegendContent child.
+      LEGEND_OPTIONS = %i[align items hide_icon toggle].freeze
+
+      # The LegendContent child built from the chart's config and legend
+      # options.
+      # @api private
+      def legend_component
+        LegendContent::Component.new(config: chart_config, **legend_config.slice(*LEGEND_OPTIONS))
+      end
+
+      # The hover cursor, on by default when a tooltip attaches: bars get
+      # a translucent band rect, line/area/composed a vertical rule -
+      # hidden until the tooltip controller positions it at the active
+      # index. Renders UNDER the series (after the grid) so marks stay
+      # on top.
+      # @api private
+      def cursor_svg(kind)
+        return unless tooltip? && tooltip_config.fetch(:cursor, true)
+
+        case kind
+        when :band
+          if respond_to?(:horizontal?) && horizontal?
+            tag.rect("data-slot": "chart-cursor", "aria-hidden": true, class: css(:cursor_band),
+                     x: fnum(cartesian.plot_left), y: 0,
+                     width: fnum(cartesian.plot_right - cartesian.plot_left), height: 0,
+                     display: "none")
+          else
+            tag.rect("data-slot": "chart-cursor", "aria-hidden": true, class: css(:cursor_band),
+                     x: fnum(cartesian.plot_left), y: fnum(cartesian.plot_top),
+                     width: 0, height: fnum(cartesian.plot_bottom - cartesian.plot_top),
+                     display: "none")
+          end
+        when :line
+          tag.line("data-slot": "chart-cursor", "aria-hidden": true, class: css(:cursor_line),
+                   x1: 0, x2: 0, y1: fnum(cartesian.plot_top), y2: fnum(cartesian.plot_bottom),
+                   display: "none")
+        end
+      end
+
+      # Attributes for the frame div (display: contents) wrapping svg +
+      # chrome + coordinates: the declared frame wiring - tooltip
+      # registration + sync here, whichever of motion/live/window the
+      # family mixes in declared by those modules - plus the part-contract
+      # self-identification: the frame is the chart type's own root (the
+      # Container wrapper self-ids as "container", so without this the
+      # SVG anatomy would have no owner in the part contract).
+      # @api private
+      def frame_attributes
+        { "data-component" => self.class.component_title }.merge(stimulus_attributes_for(:frame))
+      end
+
+      # role=img for static charts; when the tooltip attaches the SVG
+      # becomes the focusable accessibility layer (role=application +
+      # tabindex) so arrow keys walk the categories. Motion rides the
+      # same tag: data-animate + the --poetry-motion-* knobs.
+      # @api private
+      def svg_interaction_attributes
+        base = tooltip? ? { "role" => "application", "tabindex" => "0" } : { "role" => "img" }
+        base.merge!(stimulus_attributes_for(:svg))
+        respond_to?(:motion_svg_attributes) ? base.merge(motion_svg_attributes) : base
+      end
+
+      # The TooltipLayer child built from the chart's config and tooltip
+      # options.
+      # @api private
+      def tooltip_layer_component
+        TooltipLayer::Component.new(
+          config: chart_config,
+          series_keys: series_entries.map(&:key),
+          indicator: tooltip_config.fetch(:indicator, :dot),
+          hide_label: tooltip_config.fetch(:hide_label, false),
+          hide_indicator: tooltip_config.fetch(:hide_indicator, false)
+        )
+      end
+
+      # The hover markers lines/areas show at the active index -
+      # server-rendered hidden circles the controller toggles.
+      # @api private
+      def active_dot_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
+
+      private :tooltip_config, :legend_config, :legend_component, :cursor_svg, :frame_attributes
+      private :svg_interaction_attributes, :tooltip_layer_component, :active_dot_markers
+    end
+  end
+end