poetry-charts 0.0.2

data/lib/poetry/charts/spec.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    # The chart-spec: the CLOSED, VERSIONED description every poetry chart
+    # compiles to. The server engine consumes it Ruby-side; swappable
+    # adapters consume the same spec JSON-side through the duck-typed
+    # protocol (render(el, spec) / update / destroy). No engine-specific key
+    # ever enters this schema - engine styling lives in the adapter,
+    # declared; a pass-through options bag would tie call sites to one
+    # engine and the spec could never close.
+    #
+    # Keys ride the wire camelCased (dataKey, stackId) - one vocabulary
+    # on both sides of the seam.
+    #
+    # @example Compile a spec and serialize it for an adapter
+    #   Poetry::Charts::Spec.new(
+    #     type: :bar, data: rows, series: [{ data_key: :revenue }]
+    #   ).to_json
+    class Spec
+      # The spec schema version stamped into every payload.
+      VERSION = 1
+
+      # The chart types the spec can describe.
+      TYPES = %i[area bar line pie radar radial].freeze
+
+      # The closed key set a series entry may carry.
+      SERIES_KEYS = %i[key data_key name_key stack curve].freeze
+      # The closed key set an axis entry may carry.
+      AXIS_KEYS = %i[data_key hide tick_count format].freeze
+
+      attr_reader :type, :data, :series, :axes, :config
+
+      # @param type [Symbol, String] one of TYPES
+      # @param data [Array<Hash>] the rows, one hash per data point
+      # @param series [Array<Hash>] series entries; data_key: is required
+      # @param axes [Hash] per-axis settings (SERIES_KEYS/AXIS_KEYS closed sets)
+      # @param config [Config, Hash, nil] label/color config, wrapped via Config.wrap
+      def initialize(type:, data:, series:, axes: {}, config: nil)
+        @type = type.to_sym
+        unless TYPES.include?(@type)
+          raise ArgumentError,
+                "unknown chart type #{type.inspect} (one of #{TYPES.join(", ")})"
+        end
+
+        @data = Array(data)
+        @series = normalize_series(series)
+        @axes = normalize_axes(axes)
+        @config = Config.wrap(config)
+      end
+
+      # The wire form: string keys, camelCased entry keys, the version
+      # stamped in.
+      #
+      # @return [Hash]
+      def to_h
+        {
+          "version" => VERSION,
+          "type" => type.to_s,
+          "data" => data.map { |row| row.to_h.transform_keys(&:to_s) },
+          "series" => series.map { |entry| camelize_keys(entry) },
+          "axes" => axes.to_h { |name, axis| [name.to_s, camelize_keys(axis)] },
+          "config" => config.to_h.transform_values { |value| camelize_keys(value) }
+        }
+      end
+
+      # The wire form serialized - what the spec <script> embeds.
+      #
+      # @return [String]
+      def to_json(...)
+        to_h.to_json(...)
+      end
+
+      private
+
+      def normalize_series(series)
+        Array(series).map do |entry|
+          entry = entry.symbolize_keys
+          raise ArgumentError, "a series entry requires data_key: (got #{entry.inspect})" unless entry[:data_key]
+
+          unknown = entry.keys - SERIES_KEYS
+          raise ArgumentError, "unknown series keys #{unknown.inspect} (the spec is closed)" if unknown.any?
+
+          { key: entry[:data_key].to_s }.merge(entry).compact
+        end
+      end
+
+      def normalize_axes(axes)
+        axes.symbolize_keys.to_h do |name, axis|
+          axis = axis.symbolize_keys
+          unknown = axis.keys - AXIS_KEYS
+          raise ArgumentError, "unknown axis keys #{unknown.inspect} on #{name} (the spec is closed)" if unknown.any?
+
+          [name, axis]
+        end
+      end
+
+      # snake_case Ruby -> camelCase wire (dataKey, stackId-style).
+      # Symbol values (data keys, curve names) become strings on the
+      # wire.
+      def camelize_keys(hash)
+        hash.to_h do |key, value|
+          [key.to_s.camelize(:lower), value.is_a?(Symbol) ? value.to_s : value]
+        end
+      end
+    end
+  end
+end

data/lib/poetry/charts/theme_style.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    # Turns a chart's Config into the scoped per-series custom
+    # properties, one block per theme -
+    #
+    #   [data-chart=chart-revenue] { --color-desktop: var(--chart-1); }
+    #   .dark [data-chart=chart-revenue] { --color-desktop: oklch(...); }
+    #
+    # so series markup (SVG fills, tooltip indicators, legend swatches) can
+    # reference var(--color-<key>) and follow theme flips with ZERO
+    # re-render. Emission is safe by construction: Config validated every
+    # key and color at wrap time.
+    #
+    # @example
+    #   Poetry::Charts::ThemeStyle.new(id: "chart-revenue", config: config).css
+    class ThemeStyle
+      # Theme name -> selector prefix (the .dark class convention).
+      THEMES = { light: "", dark: ".dark " }.freeze
+
+      # @param id [String] the container's data-chart identifier
+      # @param config [Config, Hash] the chart config the colors come from
+      def initialize(id:, config:)
+        @id = id
+        @config = Config.wrap(config)
+      end
+
+      # The stylesheet text, or nil when no entry carries a color - a
+      # colorless config renders no <style> element at all.
+      #
+      # @return [String, nil]
+      def css
+        entries = @config.color_entries
+        return nil if entries.empty?
+
+        THEMES.filter_map { |theme, prefix| theme_block(theme, prefix, entries) }.join("\n")
+      end
+
+      private
+
+      def theme_block(theme, prefix, entries)
+        declarations = entries.filter_map do |entry|
+          color = entry.color_for(theme)
+          "  --color-#{entry.key}: #{color};" if color
+        end
+        return nil if declarations.empty?
+
+        "#{prefix}[data-chart=#{@id}] {\n#{declarations.join("\n")}\n}"
+      end
+    end
+  end
+end

data/lib/poetry/charts/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    # The gem version.
+    VERSION = "0.0.2"
+  end
+end

data/lib/poetry/charts.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "poetry/core"
+require "yaml"
+require_relative "charts/version"
+require_relative "charts/config"
+require_relative "charts/theme_style"
+require_relative "charts/spec"
+require_relative "charts/geometry"
+require_relative "charts/cartesian"
+require_relative "charts/polar"
+
+# The poetry component family's shared root namespace.
+module Poetry
+  # poetry's chart tier: charts as server-rendered SVG. Ruby runs the
+  # whole geometry pipeline - data -> domains -> scales -> ticks ->
+  # points -> paths, with decimal-exact nice ticks - and the finished
+  # chart ships in the initial HTML: no-JS/print/email valid, themed by
+  # CSS variables (--chart-1..5 + per-chart --color-<key>), dark mode
+  # with zero re-render. Stimulus chrome adds tooltip/legend/active
+  # interactivity by reading SERVER-EMBEDDED coordinates - no chart math
+  # in the browser.
+  #
+  # Engines stay swappable (three doors): the container contract is
+  # engine-agnostic; every chart also compiles to a closed, VERSIONED
+  # chart-spec consumed by duck-typed adapters (render/update/destroy -
+  # a canvas adapter ships as the reference); client-rendered chart
+  # libraries remain reachable through a Stimulus-mounted island.
+  #
+  # @example Render a chart through the dispatcher helper
+  #   poetry_chart :bar, data: rows, series: [{ data_key: :revenue }]
+  module Charts
+    # The curve interpolation whitelist every series slot validates
+    # against.
+    CURVES = %i[natural linear step step_before step_after monotone_x].freeze
+    # The axis capture shape the cartesian family slots accumulate into
+    # (scatter carries its own - both axes numeric, different fields).
+    AxisConfig = Data.define(:data_key, :tick_formatter, :tick_margin, :tick_count)
+    # The grid capture shape - which rule directions render (radar
+    # carries its own, with polygon/circle rings).
+    GridConfig = Data.define(:vertical, :horizontal)
+
+    class << self
+      # Gem root (the directory containing lib/, app/, config/).
+      def root
+        @root ||= Pathname.new(File.expand_path("../..", __dir__))
+      end
+
+      # The registry builder this gem commits from (the poetry-ui shared-
+      # builder rule: rake registry:generate/verify and the sync test share
+      # ONE construction). helper_args carries each poetry_* helper's max
+      # positional arity from its real signature - poetry_chart(type, ...)
+      # legitimately takes one, which is exactly why arity is an emitted
+      # per-helper fact and never a convention.
+      def registry
+        # The helpers section carries the dispatcher's yields declaration:
+        # poetry_chart(type) routes to a component that yields its slot
+        # builder, so its block param is legitimate - the one exception to
+        # the no-wrapper-yields invariant.
+        Poetry::Core::Registry.new(
+          source_root: root, helper_args: registry_helper_args,
+          helpers: { "poetry_chart" => { "yields" => "the dispatched chart component" } },
+          descriptions: registry_descriptions
+        )
+      end
+
+      # The editorial per-chart descriptions merged into the registry
+      # (component_path => one-liner, from config/component_descriptions.yml).
+      # Absent file -> nil, so the registry stays lint-identical without it.
+      def registry_descriptions
+        path = root.join("config/component_descriptions.yml")
+        path.exist? ? YAML.safe_load_file(path) : nil
+      end
+
+      # The installable-item projection, boot-free from the COMMITTED
+      # registry - the docs site aggregates this with poetry-ui's for
+      # /r/*.json.
+      def registry_items
+        Poetry::Core::RegistryItems.new(
+          registry: YAML.safe_load_file(root.join(Poetry::Core::Registry::RELATIVE_PATH)),
+          root: root, gem_name: "poetry-charts", gem_version: VERSION
+        )
+      end
+
+      # Parameter kinds that count toward a helper's positional arity.
+      POSITIONAL_PARAM_KINDS = %i[req opt].freeze
+
+      # Each poetry_* helper's max positional arity, read from its real
+      # signature.
+      # @api private
+      def registry_helper_args
+        require root.join("app/helpers/poetry/charts/components_helper.rb")
+        ComponentsHelper.public_instance_methods(false).grep(/\Apoetry_/).sort.filter_map do |name|
+          params = ComponentsHelper.instance_method(name).parameters
+          next if params.any? { |kind, _param| kind == :rest }
+
+          [name.to_s, params.count { |kind, _param| POSITIONAL_PARAM_KINDS.include?(kind) }]
+        end.to_h
+      end
+
+      # The tooltip display string shared by every chart family (matches
+      # TooltipContent's Row: delimited numerics from RAW values so
+      # integers stay integers, verbatim strings, nil for missing).
+      def display_value(value)
+        return nil if value.nil?
+        return ActiveSupport::NumberHelper.number_to_delimited(value) if value.is_a?(Numeric)
+
+        value.to_s
+      end
+    end
+  end
+end
+
+require_relative "charts/engine"

data/lib/poetry-charts.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Bundler auto-require entrypoint for the hyphenated gem name.
+require "poetry/charts"

data/themes/default.css

@@ -0,0 +1,146 @@
+/* poetry-charts default theme — the cn-* named-class layer.
+ *
+ * Same contract as poetry-ui's themes/default.css: imported layer(base),
+ * dictionaries emit the names + structural classes, this file carries the
+ * design. The chart chrome names are SHARED across families (one
+ * .cn-chart-grid-line serves every cartesian family) — the equivalent of
+ * upstream's [&_.recharts-*] override chains, landed on parts poetry owns.
+ * Series fills/strokes stay var(--color-<key>) ATTRIBUTES, never classes;
+ * the --chart-1..5 palette rides tokens, not this file.
+ */
+
+/* MARK: Tooltip */
+.cn-chart-tooltip {
+  @apply gap-1.5 rounded-lg border border-border/50 bg-background px-2.5 py-1.5 text-xs shadow-xl;
+}
+
+.cn-chart-tooltip-label {
+  @apply font-medium;
+}
+
+.cn-chart-tooltip-row {
+  @apply gap-2 [&>svg]:h-2.5 [&>svg]:w-2.5 [&>svg]:text-muted-foreground;
+}
+
+.cn-chart-tooltip-name {
+  @apply text-muted-foreground;
+}
+
+.cn-chart-tooltip-value {
+  @apply font-mono font-medium text-foreground tabular-nums;
+}
+
+/* MARK: Legend */
+.cn-chart-legend {
+  @apply gap-4;
+}
+
+.cn-chart-legend-align-top {
+  @apply pb-3;
+}
+
+.cn-chart-legend-align-bottom {
+  @apply pt-3;
+}
+
+.cn-chart-legend-item {
+  @apply gap-1.5 [&>svg]:h-3 [&>svg]:w-3 [&>svg]:text-muted-foreground;
+}
+
+.cn-chart-legend-swatch {
+  @apply h-2 w-2 rounded-[2px];
+}
+
+/* MARK: Cartesian chrome (shared across families) */
+.cn-chart-grid-line {
+  @apply stroke-border/50;
+}
+
+.cn-chart-tick {
+  @apply fill-muted-foreground;
+}
+
+.cn-chart-cursor-line {
+  @apply stroke-border;
+}
+
+.cn-chart-cursor-band {
+  @apply fill-muted;
+}
+
+.cn-chart-reference-line {
+  @apply stroke-muted-foreground;
+}
+
+.cn-chart-reference-area {
+  @apply fill-muted-foreground;
+}
+
+.cn-chart-reference-dot {
+  @apply fill-background stroke-muted-foreground;
+}
+
+.cn-chart-error-bar {
+  @apply stroke-foreground;
+}
+
+.cn-chart-brush-track {
+  @apply fill-muted;
+}
+
+.cn-chart-brush-window {
+  @apply fill-foreground/10 stroke-border;
+}
+
+.cn-chart-brush-handle {
+  @apply fill-muted-foreground;
+}
+
+.cn-chart-label {
+  @apply fill-foreground;
+}
+
+/* MARK: Polar chrome */
+.cn-chart-polar-grid-line {
+  @apply fill-none stroke-border;
+}
+
+.cn-chart-polar-grid-circle {
+  @apply fill-none stroke-border/50;
+}
+
+.cn-chart-radial-track {
+  @apply fill-muted;
+}
+
+.cn-chart-radial-disc-muted {
+  @apply fill-muted;
+}
+
+.cn-chart-radial-disc-background {
+  @apply fill-background;
+}
+
+.cn-chart-inside-label {
+  @apply fill-background text-xs;
+}
+
+.cn-chart-radial-inside-label {
+  @apply fill-white capitalize mix-blend-luminosity text-[11px];
+}
+
+.cn-chart-center-title {
+  @apply fill-foreground text-3xl font-bold;
+}
+
+.cn-chart-center-title-radial {
+  @apply fill-foreground text-4xl font-bold;
+}
+
+.cn-chart-center-title-compact {
+  @apply fill-foreground text-2xl font-bold;
+}
+
+.cn-chart-center-subtitle {
+  @apply fill-muted-foreground;
+}

data/themes/luma.css

@@ -0,0 +1,139 @@
+/* poetry-charts luma theme - chart chrome under upstream
+ * style-luma.css (pinned clone 1773ecfe, the shadcn@4.19.0 release). Upstream ships ONE chart rule (cn-chart-tooltip); luma reskins it exactly as rhea does (popover surface, ring-for-border, rounded-xl) - everything else carries the default treatment.
+ * Same contract as default.css: imported layer(base) by the host entry;
+ * POETRY_THEME=luma drives the gates and golden set. */
+/* MARK: Tooltip */
+.cn-chart-tooltip {
+  @apply bg-popover text-popover-foreground ring-foreground/5 dark:ring-foreground/10 gap-1.5 rounded-xl px-2.5 py-1.5 text-xs shadow-lg ring-1;
+}
+
+.cn-chart-tooltip-label {
+  @apply font-medium;
+}
+
+.cn-chart-tooltip-row {
+  @apply gap-2 [&>svg]:h-2.5 [&>svg]:w-2.5 [&>svg]:text-muted-foreground;
+}
+
+.cn-chart-tooltip-name {
+  @apply text-muted-foreground;
+}
+
+.cn-chart-tooltip-value {
+  @apply font-mono font-medium text-foreground tabular-nums;
+}
+
+/* MARK: Legend */
+.cn-chart-legend {
+  @apply gap-4;
+}
+
+.cn-chart-legend-align-top {
+  @apply pb-3;
+}
+
+.cn-chart-legend-align-bottom {
+  @apply pt-3;
+}
+
+.cn-chart-legend-item {
+  @apply gap-1.5 [&>svg]:h-3 [&>svg]:w-3 [&>svg]:text-muted-foreground;
+}
+
+.cn-chart-legend-swatch {
+  @apply h-2 w-2 rounded-[2px];
+}
+
+/* MARK: Cartesian chrome (shared across families) */
+.cn-chart-grid-line {
+  @apply stroke-border/50;
+}
+
+.cn-chart-tick {
+  @apply fill-muted-foreground;
+}
+
+.cn-chart-cursor-line {
+  @apply stroke-border;
+}
+
+.cn-chart-cursor-band {
+  @apply fill-muted;
+}
+
+.cn-chart-reference-line {
+  @apply stroke-muted-foreground;
+}
+
+.cn-chart-reference-area {
+  @apply fill-muted-foreground;
+}
+
+.cn-chart-reference-dot {
+  @apply fill-background stroke-muted-foreground;
+}
+
+.cn-chart-error-bar {
+  @apply stroke-foreground;
+}
+
+.cn-chart-brush-track {
+  @apply fill-muted;
+}
+
+.cn-chart-brush-window {
+  @apply fill-foreground/10 stroke-border;
+}
+
+.cn-chart-brush-handle {
+  @apply fill-muted-foreground;
+}
+
+.cn-chart-label {
+  @apply fill-foreground;
+}
+
+/* MARK: Polar chrome */
+.cn-chart-polar-grid-line {
+  @apply fill-none stroke-border;
+}
+
+.cn-chart-polar-grid-circle {
+  @apply fill-none stroke-border/50;
+}
+
+.cn-chart-radial-track {
+  @apply fill-muted;
+}
+
+.cn-chart-radial-disc-muted {
+  @apply fill-muted;
+}
+
+.cn-chart-radial-disc-background {
+  @apply fill-background;
+}
+
+.cn-chart-inside-label {
+  @apply fill-background text-xs;
+}
+
+.cn-chart-radial-inside-label {
+  @apply fill-white capitalize mix-blend-luminosity text-[11px];
+}
+
+.cn-chart-center-title {
+  @apply fill-foreground text-3xl font-bold;
+}
+
+.cn-chart-center-title-radial {
+  @apply fill-foreground text-4xl font-bold;
+}
+
+.cn-chart-center-title-compact {
+  @apply fill-foreground text-2xl font-bold;
+}
+
+.cn-chart-center-subtitle {
+  @apply fill-muted-foreground;
+}