railsui_charts 0.1.0

data/lib/railsui_charts/chart_helper.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+module RailsuiCharts
+  module ChartHelper
+    # Forms whose placeholder should be a disc rather than a plotting area.
+    CIRCULAR_TYPES = %i[pie donut polar_area radar].freeze
+
+    def railsui_chart(data, type: :line, **options)
+      # An empty dataset is a normal day one, not an error. Rendering axes
+      # around nothing looks like a chart that failed rather than a chart with
+      # nothing to show yet.
+      return railsui_chart_empty(**empty_options(options)) if ApexOptionsBuilder.blank?(data)
+
+      config = ApexOptionsBuilder.new(data, type: type, **options).build
+      id = options[:id] || "rui-chart-#{SecureRandom.hex(4)}"
+
+      table = options[:accessible] != false ? accessibility_table(config, id: id) : nil
+
+      content_tag(:div,
+                  id: id,
+                  class: "railsui-chart",
+                  # Charts draw when they scroll into view, so the space has to
+                  # be held from the start. Without it the page is short on
+                  # load and grows under the reader as they scroll.
+                  style: reserved_height(config),
+                  data: { controller: "railsui-chart", "railsui-chart-options-value": config.to_json }) do
+        table
+      end
+    end
+
+    # One small chart per series, sharing a y-scale.
+    #
+    # This is the honest answer when there are more categories than a single
+    # chart can hold. Eight lines on one axis is a plate of spaghetti, and a
+    # ninth colour is not distinguishable from the others anyway — facets scale
+    # where colour does not.
+    #
+    #   <%= railsui_small_multiples @plans, type: :area, columns: 3 %>
+    def railsui_small_multiples(series, type: :line, height: 120, columns: 3, **options)
+      return railsui_chart_empty(**empty_options(options)) if ApexOptionsBuilder.blank?(series)
+
+      entries = Array(series)
+      shared = shared_scale(entries)
+
+      content_tag(:div, class: "railsui-small-multiples", style: "--rui-small-multiple-columns: #{columns.to_i}") do
+        safe_join(entries.each_with_index.map do |entry, index|
+          content_tag(:div, class: "railsui-small-multiple") do
+            safe_join([
+              content_tag(:p, entry[:name] || entry["name"] || "Series #{index + 1}", class: "railsui-small-multiple__title"),
+              # Every facet takes the same colour. The title carries identity
+              # here, so spending a hue on it would say nothing extra.
+              railsui_chart(entry[:data] || entry["data"], type: type, height: height,
+                                                           yaxis: shared.merge(tickAmount: 3), **options)
+            ])
+          end
+        end)
+      end
+    end
+
+    # Facets only compare if they share a scale. Left to themselves each one
+    # would fit its own data and a small series would look like a large one.
+    def shared_scale(entries)
+      values = entries.flat_map { |entry| Array(entry[:data] || entry["data"]).map { |point| ApexOptionsBuilder.value_of(point) } }.compact
+      return {} if values.empty?
+
+      min, max = values.minmax
+      return {} if min == max
+
+      { min: min, max: max }
+    end
+
+    # Holds the chart's footprint so a card keeps its shape whether or not the
+    # query came back with anything.
+    def railsui_chart_empty(title: nil, description: nil, height: nil)
+      chart_state(:empty, title: title || "No data", description: description, height: height)
+    end
+
+    def railsui_chart_error(title: nil, description: nil, height: nil)
+      chart_state(:error, title: title || "Couldn't load this chart", description: description, height: height)
+    end
+
+    # Server-rendered placeholder for a chart whose data has not arrived yet —
+    # the thing a Turbo frame shows before it swaps in the real one. Pass the
+    # `type:` it will become so the placeholder is the shape being waited on.
+    def railsui_chart_skeleton(height: nil, type: :line, label: "Loading chart")
+      classes = ["railsui-chart-skeleton"]
+      classes << "railsui-chart-skeleton--circular" if CIRCULAR_TYPES.include?(type.to_sym)
+
+      content_tag(:div,
+                  class: "railsui-chart-state railsui-chart-state--loading",
+                  style: state_height(height),
+                  role: "status",
+                  aria: { label: label, busy: true }) do
+        content_tag(:span, "", class: classes.join(" "), aria: { hidden: true })
+      end
+    end
+
+    private
+
+    def chart_state(kind, title:, description:, height:)
+      content_tag(:div,
+                  class: "railsui-chart-state railsui-chart-state--#{kind}",
+                  style: state_height(height),
+                  role: "status") do
+        content_tag(:div, class: "railsui-chart-state__body") do
+          safe_join([
+            content_tag(:p, title, class: "railsui-chart-state__title"),
+            description.present? ? content_tag(:p, description, class: "railsui-chart-state__description") : nil
+          ].compact)
+        end
+      end
+    end
+
+    def reserved_height(config)
+      height = config.dig(:chart, :height)
+      return if height.blank?
+
+      "min-height: #{height.to_i}px"
+    end
+
+    def state_height(height)
+      height ||= RailsuiCharts.config.default_height
+      "min-height: #{height.to_i}px"
+    end
+
+    # `empty:` takes a string for the headline, or a hash to say more.
+    def empty_options(options)
+      given = options[:empty]
+      base = { height: options[:height] }
+
+      case given
+      when String then base.merge(title: given)
+      when Hash then base.merge(given.symbolize_keys)
+      else base
+      end
+    end
+
+    # Every chart ships a visually hidden table so no value is reachable only by
+    # hovering a mark.
+    def accessibility_table(config, id:)
+      series = config[:series]
+      return if series.blank?
+
+      if series.is_a?(Array) && series.first.is_a?(Numeric)
+        # Pie / donut / polar area: a flat array of values with separate labels.
+        columns = [{ name: "Value", data: series }]
+        categories = config[:labels] || []
+      else
+        columns = Array(series).map { |s| { name: s[:name] || "Value", data: s[:data] } }
+        categories = config.dig(:xaxis, :categories) || []
+      end
+
+      rows = columns.first&.dig(:data)
+      return if rows.blank?
+
+      content_tag(:table, class: "sr-only", aria: { label: "Chart data" }) do
+        safe_join([
+          content_tag(:caption, "Data for chart #{id}"),
+          content_tag(:thead) do
+            content_tag(:tr) do
+              safe_join(
+                [content_tag(:th, "Category")] +
+                  columns.map { |column| content_tag(:th, column[:name]) }
+              )
+            end
+          end,
+          content_tag(:tbody) do
+            safe_join(
+              rows.each_with_index.map do |_, index|
+                content_tag(:tr) do
+                  safe_join(
+                    [content_tag(:td, categories[index] || index + 1)] +
+                      columns.map { |column| content_tag(:td, cell_value(column[:data][index])) }
+                  )
+                end
+              end
+            )
+          end
+        ])
+      end
+    end
+
+    def cell_value(value)
+      case value
+      when Array then value.join(", ")
+      when Hash
+        # A bubble carries three numbers that all mean something here. Anything
+        # else keeps its label in the category column already, so repeating it
+        # beside the value just reads as "A, 6" to a screen reader.
+        value.key?(:z) ? value.values_at(:x, :y, :z).compact.join(", ") : value[:y]
+      else value
+      end
+    end
+  end
+end

data/lib/railsui_charts/configuration.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module RailsuiCharts
+  class Configuration
+    attr_accessor :default_height, :default_currency, :colors, :series_colors, :theme_css_prefix, :extra_types
+    attr_accessor :labelled_point_types, :typography, :geometry
+
+    # Categorical hues carry identity, so the order is the colourblind-safety
+    # mechanism rather than a style choice — it was picked by validating every
+    # ordering of these hues and keeping one that clears the lightness band,
+    # chroma floor, CVD separation, normal-vision floor, and 3:1 contrast in
+    # both light and dark. Reorder it and those guarantees go with it.
+    #
+    # Forms where any two marks can sit side by side (pie, donut, polar area,
+    # scatter, bubble) hold to a stricter all-pairs test, which these hues clear
+    # for the first four slots. Past four, fold the tail into "Other".
+    SERIES_COUNT = 8
+
+    SERIES_FALLBACKS = %w[
+      #6366f1 #ea580c #db2777 #c026d3
+      #65a30d #0284c7 #dc2626 #0d9488
+    ].freeze
+
+    def initialize
+      @default_height = 250
+      @default_currency = "$"
+      # Chart types registered by an extension, such as Rails UI Charts Pro.
+      @extra_types = []
+      @labelled_point_types = []
+      @theme_css_prefix = "--rui-chart"
+      @series_colors = (1..SERIES_COUNT).map { |i| "var(--rui-chart-series-#{i}, #{SERIES_FALLBACKS[i - 1]})" }
+      @colors = {
+        primary: "var(--rui-chart-primary, #4f46e5)",
+        secondary: "var(--rui-chart-secondary, #0ea5e9)",
+        accent: "var(--rui-chart-accent, #10b981)",
+        muted: "var(--rui-chart-muted, #94a3b8)",
+        grid: "var(--rui-chart-grid, rgba(148, 163, 184, 0.2))",
+        text: "var(--rui-chart-text, #64748b)",
+        # The card colour behind a chart. Touching marks separate with a gap in
+        # this colour rather than a stroke drawn around them.
+        surface: "var(--rui-chart-surface, #ffffff)"
+      }
+
+      # Type rides the same channel the colours do, because Apex takes these as
+      # CSS strings and the controller resolves `var()` against the chart's own
+      # computed style before handing the options over. That is worth more than
+      # a Ruby setting here: a dense card can shrink the type on its own charts
+      # without a second configuration, and a media query can do it per theme.
+      #
+      # The defaults are the sizes that were hardcoded before, so nothing moves
+      # until someone sets a variable.
+      @typography = {
+        family: "var(--rui-chart-font-family, inherit)",
+        size: "var(--rui-chart-font-size, 12px)",
+        # Legend, annotation labels, and the compact breakpoint under 640px.
+        size_sm: "var(--rui-chart-font-size-sm, 11px)"
+      }
+
+      # Numbers, and that is the whole reason they are here rather than in the
+      # CSS. A resolved CSS variable arrives as a string, and Apex does
+      # arithmetic on these — "4" + 1 is "41", so a radius set that way would
+      # silently produce a chart with corners nobody asked for.
+      @geometry = {
+        bar_radius: 4,
+        stroke_width: 2,
+        marker_size: 0,
+        marker_hover_size: 6
+      }
+    end
+    # Register a chart type this gem does not ship, so it passes validation and
+    # is drawn through the same options builder as everything else rather than
+    # around it.
+    #
+    #   RailsuiCharts.config.register_type :treemap, points: :labelled
+    #
+    # `points: :labelled` keeps each point as {x:, y:}. Most types put the label
+    # on the axis and send bare values, but a treemap draws its labels inside
+    # the rectangles, so they have to stay in the data.
+    def register_type(type, points: :values)
+      type = type.to_sym
+
+      @extra_types |= [type]
+      @labelled_point_types |= [type] if points == :labelled
+
+      type
+    end
+
+  end
+end

data/lib/railsui_charts/engine.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RailsuiCharts
+  class Engine < ::Rails::Engine
+    isolate_namespace RailsuiCharts
+
+    initializer "railsui_charts.helpers" do
+      ActiveSupport.on_load :action_controller do
+        helper RailsuiCharts::ChartHelper
+        helper RailsuiCharts::MetricHelper
+        helper RailsuiCharts::FilterHelper
+      end
+    end
+
+    initializer "railsui_charts.assets" do |app|
+      app.config.assets.precompile << "railsui_charts.css"
+    end
+  end
+end

data/lib/railsui_charts/filter_helper.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module RailsuiCharts
+  module FilterHelper
+    # Renders the single filter row that scopes every chart below it.
+    #
+    #   <%= railsui_chart_filters @filters, url: dashboard_path %>
+    #
+    # Submits as a plain GET form, so it works without JavaScript and each
+    # slice gets a shareable URL. With Turbo, the controller submits on change
+    # and only the frame re-renders.
+    #
+    # The controls are deliberately bare — text and a chevron, with the pill
+    # only appearing on hover. Filter chrome sits above the data all day, so it
+    # earns its weight only while someone is reaching for it.
+    #
+    # An app that would rather use its own form styles passes them in. Doing so
+    # drops the built-in chevron and switch, since those belong to this
+    # treatment:
+    #
+    #   <%= railsui_chart_filters @filters, url: dashboard_path,
+    #         select_class: "form-select w-auto", checkbox_class: "form-input-checkbox" %>
+    def railsui_chart_filters(filters, url: nil, frame: nil, select_class: nil, checkbox_class: nil)
+      bare_selects = select_class.nil?
+      switch = checkbox_class.nil?
+      select_class ||= "railsui-chart-filters__select"
+      checkbox_class ||= "railsui-chart-filters__checkbox"
+
+      form_tag(url, method: :get, class: "railsui-chart-filters", data: filter_form_data(frame)) do
+        safe_join([
+          filter_field("Date range",
+                       select_tag(:range, options_for_select(filters.presets.map { |preset| [preset.label, preset.key] }, filters.preset.key), **filter_select_options(select_class)),
+                       chevron: bare_selects),
+          filter_field("Interval",
+                       select_tag(:interval, options_for_select(filters.intervals, filters.interval.to_s), **filter_select_options(select_class)),
+                       chevron: bare_selects),
+          filter_compare(filters, checkbox_class, switch: switch),
+          # Without Turbo or Stimulus the selects still need a way to apply.
+          content_tag(:noscript, submit_tag("Apply", class: "railsui-chart-filters__apply", data: { disable_with: nil }))
+        ])
+      end
+    end
+
+    private
+
+    def filter_form_data(frame)
+      data = { controller: "railsui-chart-filters" }
+      data[:turbo_frame] = frame if frame.present?
+      data
+    end
+
+    def filter_field(label, control, chevron:)
+      content_tag(:div, class: "railsui-chart-filters__field") do
+        safe_join([
+          content_tag(:span, label, class: "railsui-chart-filters__label"),
+          # The chevron rides a wrapper rather than a background image on the
+          # select, so it inherits currentColor and follows the theme.
+          chevron ? content_tag(:span, control, class: "railsui-chart-filters__control") : control
+        ])
+      end
+    end
+
+    def filter_select_options(select_class)
+      {
+        class: select_class,
+        data: { action: "change->railsui-chart-filters#submit" }
+      }
+    end
+
+    def filter_compare(filters, checkbox_class, switch:)
+      classes = ["railsui-chart-filters__compare"]
+      classes << "railsui-chart-filters__compare--switch" if switch
+
+      content_tag(:label, class: classes.join(" ")) do
+        safe_join([
+          # Paired hidden field so unchecking sends an explicit value rather
+          # than dropping the param and falling back to the default.
+          hidden_field_tag(:compare, "0", id: nil),
+          check_box_tag(:compare, "1", filters.compare?,
+                        class: switch ? "railsui-chart-filters__switch" : checkbox_class,
+                        data: { action: "change->railsui-chart-filters#submit" }),
+          # Adjacent sibling of the input, which is what drives the checked and
+          # focus states.
+          switch ? content_tag(:span, "", class: "railsui-chart-filters__track", aria: { hidden: true }) : nil,
+          content_tag(:span, "Compare to previous period")
+        ].compact)
+      end
+    end
+  end
+end

data/lib/railsui_charts/filters.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module RailsuiCharts
+  # Resolves request params into the window every chart on a page shares.
+  #
+  # Filters belong above the charts, not inside them: one row scopes the whole
+  # view so every chart re-renders against the same slice. A per-card date
+  # picker invites two cards to disagree about what "this week" means.
+  #
+  #   filters = RailsuiCharts::Filters.new(params)
+  #   filters.range           # => Mon, 06 Aug..Mon, 12 Aug
+  #   filters.interval        # => :day
+  #   filters.previous_range  # => the preceding 7 days, when comparing
+  class Filters
+    Preset = Struct.new(:key, :label, :length, :interval, :unit, keyword_init: true)
+
+    PRESETS = [
+      Preset.new(key: "24h", label: "Last 24 hours", length: 24, interval: :hour, unit: :hour),
+      Preset.new(key: "7d", label: "Last 7 days", length: 7, interval: :day, unit: :day),
+      Preset.new(key: "30d", label: "Last 30 days", length: 30, interval: :day, unit: :day),
+      Preset.new(key: "90d", label: "Last 90 days", length: 13, interval: :week, unit: :week),
+      Preset.new(key: "12m", label: "Last 12 months", length: 12, interval: :month, unit: :month),
+      Preset.new(key: "mtd", label: "Month to date", length: nil, interval: :day, unit: :day)
+    ].freeze
+
+    DEFAULT_PRESET = "7d"
+
+    INTERVAL_LABELS = { hour: "Hourly", day: "Daily", week: "Weekly", month: "Monthly" }.freeze
+
+    attr_reader :preset
+
+    def initialize(params = {}, today: nil)
+      params = params.respond_to?(:to_unsafe_h) ? params.to_unsafe_h : params.to_h
+      params = params.transform_keys(&:to_s)
+
+      @today = today || current_date
+      @preset = find_preset(params["range"])
+      @interval = coerce_interval(params["interval"])
+      @compare = compare_param?(params["compare"])
+    end
+
+    def range
+      @range ||= @preset.key == "mtd" ? (@today.beginning_of_month..@today) : trailing_range
+    end
+
+    def interval
+      @interval || @preset.interval
+    end
+
+    def compare?
+      @compare
+    end
+
+    def previous_range
+      return unless compare?
+
+      Interval.preceding(range, interval: interval)
+    end
+
+    def presets
+      PRESETS
+    end
+
+    def intervals
+      available = case @preset.unit
+                  when :hour then %i[hour day]
+                  when :month then %i[month]
+                  when :week then %i[week month]
+                  else %i[day week month]
+                  end
+
+      available.map { |key| [INTERVAL_LABELS.fetch(key), key.to_s] }
+    end
+
+    def label
+      @preset.label
+    end
+
+    def interval_label
+      INTERVAL_LABELS.fetch(interval)
+    end
+
+    def summary
+      parts = [label, interval_label]
+      parts << "Compared to previous period" if compare?
+      parts
+    end
+
+    def to_params
+      { range: @preset.key, interval: interval.to_s, compare: compare? ? "1" : "0" }
+    end
+
+    private
+
+    def trailing_range
+      finish = @preset.unit == :hour ? current_time : @today
+      start = (@preset.length - 1).times.inject(finish) { |value, _| Interval.step_back(value, @preset.interval) }
+
+      start..finish
+    end
+
+    def find_preset(key)
+      PRESETS.find { |preset| preset.key == key.to_s } || PRESETS.find { |preset| preset.key == DEFAULT_PRESET }
+    end
+
+    # An explicit interval only sticks if it makes sense for the window: hourly
+    # buckets across twelve months is 8,760 points nobody can read.
+    def coerce_interval(value)
+      return if value.blank?
+
+      candidate = value.to_sym
+      allowed = intervals.map { |(_, key)| key.to_sym }
+      allowed.include?(candidate) ? candidate : nil
+    end
+
+    def compare_param?(value)
+      return true if value.nil?
+
+      %w[1 true yes on].include?(value.to_s.downcase)
+    end
+
+    def current_date
+      Time.respond_to?(:zone) && Time.zone ? Time.zone.today : Date.today
+    end
+
+    def current_time
+      Time.respond_to?(:zone) && Time.zone ? Time.zone.now : Time.now
+    end
+  end
+end

data/lib/railsui_charts/interval.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module RailsuiCharts
+  # Date arithmetic for the supported bucket sizes: truncating a value to the
+  # bucket it belongs in, stepping between buckets, and finding the window
+  # before a window.
+  #
+  # This is plumbing rather than product. Filters needs it to resolve a preset
+  # into a range, so it stays here even though the bucketing that builds on it
+  # lives in Rails UI Charts Pro.
+  module Interval
+    SUPPORTED = %i[hour day week month].freeze
+
+    class << self
+      def validate!(interval)
+        interval = interval.to_sym
+        raise ArgumentError, "Unsupported interval: #{interval}. Supported: #{SUPPORTED.join(', ')}" unless SUPPORTED.include?(interval)
+
+        interval
+      end
+
+      def truncate(value, interval)
+        time = coerce(value)
+        return if time.nil?
+
+        case interval.to_sym
+        when :hour then time.change(min: 0, sec: 0)
+        when :week then time.to_date.beginning_of_week
+        when :month then time.to_date.beginning_of_month
+        else time.to_date
+        end
+      end
+
+      def coerce(value)
+        case value
+        when Time, DateTime then in_zone(value)
+        when Date then value
+        when String then parse(value)
+        when Numeric then in_zone(Time.at(value))
+        else value.respond_to?(:to_time) ? in_zone(value.to_time) : nil
+        end
+      end
+
+      # The equal-length window immediately before this one.
+      def preceding(range, interval: :day)
+        return if range.nil?
+
+        length = count(range, interval)
+        finish = step_back(range.first, interval)
+        start = length.pred.times.inject(finish) { |value, _| step_back(value, interval) }
+
+        start..finish
+      end
+
+      def count(range, interval)
+        total = 0
+        cursor = range.first
+
+        while cursor <= range.last
+          total += 1
+          cursor = step_forward(cursor, interval)
+        end
+
+        total
+      end
+
+      def step_forward(value, interval)
+        shift(value, interval, 1)
+      end
+
+      def step_back(value, interval)
+        shift(value, interval, -1)
+      end
+
+      # Every bucket start between the two ends, inclusive.
+      def each(range, interval)
+        return enum_for(:each, range, interval) unless block_given?
+
+        cursor = truncate(range.first, interval)
+        finish = truncate(range.last, interval)
+
+        while cursor <= finish
+          yield cursor
+          cursor = step_forward(cursor, interval)
+        end
+      end
+
+      private
+
+      def shift(value, interval, direction)
+        case interval.to_sym
+        when :hour then value + (direction * 3600)
+        when :week then value + (direction * 7)
+        when :month then value >> direction
+        else value + direction
+        end
+      end
+
+      def in_zone(time)
+        Time.respond_to?(:zone) && Time.zone ? time.in_time_zone : time
+      end
+
+      def parse(value)
+        Time.respond_to?(:zone) && Time.zone ? Time.zone.parse(value) : Time.parse(value)
+      rescue ArgumentError, TypeError
+        nil
+      end
+    end
+  end
+end