railsui_charts 0.1.0

data/lib/railsui_charts/metric_helper.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+module RailsuiCharts
+  module MetricHelper
+    # A compact label / value / delta stack with an optional sparkline.
+    def railsui_metric(label:, value:, change: nil, comparison: nil, history: nil, format: :number, **options)
+      change ||= comparison
+      sparkline = metric_sparkline(history, options)
+
+      content_tag(:div, class: "railsui-metric") do
+        safe_join([
+          content_tag(:p, label, class: "railsui-metric-label"),
+          content_tag(:div, class: "railsui-metric-value-row") do
+            safe_join([
+              content_tag(:span, format_metric_value(value, format), class: "railsui-metric-value"),
+              change ? metric_delta(change) : nil
+            ].compact)
+          end,
+          sparkline
+        ].compact)
+      end
+    end
+
+    # The full dashboard card: label, value, delta, previous-period line, a
+    # comparison chart, and a footer. This is the piece a Rails app actually
+    # drops into a dashboard — the chart alone is rarely the whole job.
+    # `expand: true` turns the footer link into an expanded view of the same
+    # series — a card chart is 180px tall, which is enough to read a trend and
+    # not enough to read a value. Takes precedence over `details_path`.
+    def railsui_metric_card(label:, value:, previous: nil, change: nil, history: nil, compare: nil,
+                            format: :number, updated_at: nil, details_path: nil,
+                            details_label: "More details", positive_is_good: true,
+                            chart_height: 180, expand: false, **options)
+      change ||= percentage_change(value, previous)
+      expand &&= history.present?
+      # The chart cannot know that a falling churn rate is a win, so the card
+      # tells it — the tooltip colours its delta the same way the value does.
+      chart_options = options.merge(label: options[:label] || label, trend_up_is_good: positive_is_good)
+
+      card = content_tag(:div, class: "railsui-metric-card", data: expand ? { controller: "railsui-metric-dialog" } : {}) do
+        safe_join([
+          metric_card_head(label, value, change, previous, format, positive_is_good),
+          metric_card_chart(history, compare, format, chart_height, chart_options),
+          metric_card_footer(updated_at, details_path, details_label, expand: expand),
+          expand ? metric_dialog(label, value, change, previous, history, compare, format, positive_is_good, chart_options) : nil
+        ].compact)
+      end
+
+      card
+    end
+
+    # The card's own placeholder. It stands in for the text that is coming and
+    # leaves the plot area empty: a grey slab where the chart goes claims more
+    # about the shape of the data than a loading state can know.
+    def railsui_metric_card_skeleton(chart_height: 180, footer: true, label: "Loading metric")
+      content_tag(:div, class: "railsui-metric-card", role: "status", aria: { busy: true, label: label }) do
+        safe_join([
+          content_tag(:div, class: "railsui-metric-card__head") do
+            safe_join(%w[label value meta].map do |part|
+              content_tag(:span, "", class: "railsui-skeleton-bar railsui-skeleton-bar--#{part}", aria: { hidden: true })
+            end)
+          end,
+          content_tag(:div, "", class: "railsui-metric-card__chart", style: "min-height: #{chart_height.to_i}px"),
+          footer ? content_tag(:div, class: "railsui-metric-card__footer") do
+            content_tag(:span, "", class: "railsui-skeleton-bar railsui-skeleton-bar--footer", aria: { hidden: true })
+          end : nil
+        ].compact)
+      end
+    end
+
+    private
+
+    def metric_card_head(label, value, change, previous, format, positive_is_good)
+      content_tag(:div, class: "railsui-metric-card__head") do
+        safe_join([
+          content_tag(:p, label, class: "railsui-metric-card__label"),
+          content_tag(:div, class: "railsui-metric-card__value-row") do
+            safe_join([
+              content_tag(:span, format_metric_value(value, format), class: "railsui-metric-card__value"),
+              change ? metric_delta(change, positive_is_good: positive_is_good) : nil
+            ].compact)
+          end,
+          previous ? content_tag(:p, "#{format_metric_value(previous, format)} previous period", class: "railsui-metric-card__previous") : nil
+        ].compact)
+      end
+    end
+
+    def metric_card_chart(history, compare, format, height, options)
+      # No early return on blank history: railsui_chart renders its empty panel
+      # at the same height, so a card with nothing to plot keeps its shape
+      # instead of collapsing and shuffling the grid around it.
+      content_tag(:div, class: "railsui-metric-card__chart") do
+        safe_join([
+          railsui_chart(
+            history,
+            type: :line,
+            compare: compare,
+            # The value above is already spelled out in full, so the axis takes
+            # the compact form: $19K rather than $19,000.00.
+            format: format == :currency ? :short_currency : format,
+            height: height,
+            # The end labels are rendered below as plain text instead. Apex
+            # centres a label on its data point and clips at the canvas edge, so
+            # an edge label either loses its first characters or has to be
+            # bought with padding that eats into the plot.
+            xaxis: { labels: { show: false } },
+            grid: { padding: { left: 0, right: 4, top: 0, bottom: 0 } },
+            # Scale on the right, so the plot starts flush with the card edge.
+            axis: :right,
+            # The "previous period" line above already names the comparison, so a
+            # legend box would only restate it and eat the card's height.
+            legend: { show: false },
+            **options
+          ),
+          metric_card_axis(history)
+        ].compact)
+      end
+    end
+
+    # First and last labels, flush to the card edges. Nothing to clip, and the
+    # plot keeps its full width.
+    def metric_card_axis(history)
+      labels = Array(history).filter_map { |point| point[:x] || point["x"] if point.is_a?(Hash) }
+      return if labels.length < 2
+
+      content_tag(:div, class: "railsui-metric-card__axis") do
+        safe_join([content_tag(:span, labels.first), content_tag(:span, labels.last)])
+      end
+    end
+
+    def metric_card_footer(updated_at, details_path, details_label, expand: false)
+      return if updated_at.blank? && details_path.blank? && !expand
+
+      action = if expand
+                 content_tag(:button, details_label, type: "button", class: "railsui-metric-card__details",
+                                                     data: { action: "railsui-metric-dialog#open" })
+               elsif details_path.present?
+                 link_to(details_label, details_path, class: "railsui-metric-card__details")
+               end
+
+      content_tag(:div, class: "railsui-metric-card__footer") do
+        safe_join([content_tag(:span, updated_at, class: "railsui-metric-card__updated"), action].compact)
+      end
+    end
+
+    def metric_dialog(label, value, change, previous, history, compare, format, positive_is_good, options)
+      content_tag(:dialog,
+                  class: "railsui-metric-dialog",
+                  data: { "railsui-metric-dialog-target": "dialog", action: "click->railsui-metric-dialog#closeOnBackdrop" }) do
+        content_tag(:div, class: "railsui-metric-dialog__panel") do
+          safe_join([
+            content_tag(:div, class: "railsui-metric-dialog__head") do
+              safe_join([
+                metric_card_head(label, value, change, previous, format, positive_is_good),
+                content_tag(:button, "&times;".html_safe, type: "button", class: "railsui-metric-dialog__close",
+                                                          aria: { label: "Close" }, data: { action: "railsui-metric-dialog#close" })
+              ])
+            end,
+            # Room to read values rather than just a trend, so the axis labels
+            # the card suppresses come back. They centre on their data point,
+            # so the outermost two need room or Apex clips them at the canvas.
+            railsui_chart(history, type: :line, compare: compare, format: format, height: 420,
+                                   axis: :right, legend: { show: compare.present? },
+                                   grid: { padding: { left: 28, right: 12 } }, **options)
+          ])
+        end
+      end
+    end
+
+    def format_metric_value(value, format)
+      case format
+      when :currency, :short_currency
+        number_to_currency(value)
+      when :percentage
+        number_to_percentage(value, precision: 1)
+      when :human
+        number_to_human(value, units: { thousand: "K", million: "M", billion: "B" }, format: "%n%u", precision: 3)
+      else
+        number_with_delimiter(value)
+      end
+    end
+
+    # Plain coloured text, not a pill. A filled badge competes with the value
+    # it is annotating.
+    def metric_delta(change, positive_is_good: true)
+      return if change.nil?
+
+      trend = trend_direction(change, positive_is_good: positive_is_good)
+      sign = change.to_f.positive? ? "+" : ""
+
+      content_tag(:span, "#{sign}#{format_change(change)}%", class: "railsui-metric-delta railsui-metric-delta--#{trend}")
+    end
+
+    def format_change(change)
+      rounded = change.to_f.round(2)
+      rounded == rounded.to_i ? rounded.to_i : rounded
+    end
+
+    # Direction and goodness are separate: a falling churn rate is a win, so the
+    # colour follows meaning rather than the sign.
+    def trend_direction(change, positive_is_good: true)
+      return "neutral" if change.nil? || change.to_f.zero?
+
+      change.to_f.positive? == positive_is_good ? "positive" : "negative"
+    end
+
+    def percentage_change(value, previous)
+      return if value.nil? || previous.nil? || previous.to_f.zero?
+
+      ((value.to_f - previous.to_f) / previous.to_f * 100).round(2)
+    end
+
+    def metric_sparkline(history, options)
+      return if history.blank?
+
+      railsui_chart(history, type: :sparkline, height: 40, accessible: false, **options.except(:id))
+    end
+  end
+end

data/lib/railsui_charts/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailsuiCharts
+  VERSION = "0.1.0"
+end

data/lib/railsui_charts.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "railsui_charts/version"
+require "active_support/core_ext/object/json"
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/date/calculations"
+require "active_support/core_ext/time/calculations"
+
+module RailsuiCharts
+  autoload :Configuration, "railsui_charts/configuration"
+  autoload :ApexOptionsBuilder, "railsui_charts/apex_options_builder"
+  autoload :ChartHelper, "railsui_charts/chart_helper"
+  autoload :MetricHelper, "railsui_charts/metric_helper"
+  autoload :FilterHelper, "railsui_charts/filter_helper"
+  autoload :Filters, "railsui_charts/filters"
+  autoload :Interval, "railsui_charts/interval"
+
+  mattr_accessor :config
+  @@config = RailsuiCharts::Configuration.new
+
+  def self.configure
+    yield(config)
+  end
+end
+
+require "railsui_charts/engine" if defined?(Rails)

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: railsui_charts
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andy Leverenz
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: Production-ready chart and metric components for Rails, built on ApexCharts.
+  Server-rendered, accessible, and designed for Tailwind CSS.
+email:
+- railsui@justalever.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.md
+- README.md
+- Rakefile
+- app/assets/stylesheets/railsui_charts.css
+- app/controllers/railsui_charts/demo_controller.rb
+- app/javascript/controllers/railsui_chart_controller.js
+- app/javascript/controllers/railsui_chart_filters_controller.js
+- app/javascript/controllers/railsui_metric_dialog_controller.js
+- app/views/railsui_charts/demo/index.html.erb
+- config/routes.rb
+- lib/generators/railsui_charts/install/install_generator.rb
+- lib/generators/railsui_charts/install/templates/railsui_chart_controller.js
+- lib/generators/railsui_charts/install/templates/railsui_chart_filters_controller.js
+- lib/generators/railsui_charts/install/templates/railsui_metric_dialog_controller.js
+- lib/railsui_charts.rb
+- lib/railsui_charts/apex_options_builder.rb
+- lib/railsui_charts/chart_helper.rb
+- lib/railsui_charts/configuration.rb
+- lib/railsui_charts/engine.rb
+- lib/railsui_charts/filter_helper.rb
+- lib/railsui_charts/filters.rb
+- lib/railsui_charts/interval.rb
+- lib/railsui_charts/metric_helper.rb
+- lib/railsui_charts/version.rb
+homepage: https://railsui.com/charts
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://railsui.com/charts
+  documentation_uri: https://railsui.com/docs/charts
+  source_code_uri: https://github.com/getrailsui/railsui_charts
+  changelog_uri: https://github.com/getrailsui/railsui_charts/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/getrailsui/railsui_charts/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Rails-native chart components for RailsUI
+test_files: []