railsui_charts 0.1.0

data/app/controllers/railsui_charts/demo_controller.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RailsuiCharts
+  class DemoController < ::ActionController::Base
+    layout false
+
+    def index
+      @monthly_revenue = [
+        { x: "Jan", y: 32_000 },
+        { x: "Feb", y: 35_000 },
+        { x: "Mar", y: 42_000 },
+        { x: "Apr", y: 38_000 },
+        { x: "May", y: 48_290 },
+        { x: "Jun", y: 52_000 }
+      ]
+
+      @daily_signups = [12, 19, 15, 25, 22, 30, 28]
+      @plan_distribution = [
+        { x: "Starter", y: 120 },
+        { x: "Pro", y: 85 },
+        { x: "Enterprise", y: 32 }
+      ]
+
+      @page_views = [120, 132, 101, 134, 190, 230, 210, 180, 250, 280]
+    end
+  end
+end

data/app/javascript/controllers/railsui_chart_controller.js

@@ -0,0 +1,438 @@
+import { Controller } from "@hotwired/stimulus"
+import ApexCharts from "apexcharts"
+
+export default class extends Controller {
+  static values = { options: Object }
+
+  connect() {
+    // Bind before the first render: the theme getter reads the media query, so
+    // rendering first paints every chart light on a dark OS.
+    this.bindThemeListeners()
+
+    // Apex measures the element as it renders. Anything hidden at connect — a
+    // closed dialog, a collapsed panel — measures zero and draws nothing, so
+    // there is no point building it yet. Whatever reveals it says so, and the
+    // chart lays itself out then.
+    this.refresh = this.refresh.bind(this)
+    this.element.addEventListener("railsui-chart:refresh", this.refresh)
+
+    this.watchViewport()
+  }
+
+  disconnect() {
+    this.unwatchViewport()
+    this.element.removeEventListener("railsui-chart:refresh", this.refresh)
+    this.destroy()
+    this.unbindThemeListeners()
+  }
+
+  // Building every chart at once is work the reader has not asked for, and a
+  // page carrying a dozen of them spends the first seconds laying out charts
+  // nobody is looking at. Each one waits until it is nearly on screen; the
+  // server reserves its height so nothing shifts when it arrives.
+  watchViewport() {
+    if (!("IntersectionObserver" in window)) {
+      if (this.measurable) this.render()
+      return
+    }
+
+    this.viewportObserver = new IntersectionObserver(
+      (entries) => {
+        if (!entries.some((entry) => entry.isIntersecting)) return
+
+        this.unwatchViewport()
+        if (this.measurable) this.render()
+      },
+      // Start early enough that it is drawn by the time it is scrolled to.
+      { rootMargin: "300px 0px" }
+    )
+
+    this.viewportObserver.observe(this.element)
+  }
+
+  unwatchViewport() {
+    this.viewportObserver?.disconnect()
+    this.viewportObserver = null
+  }
+
+  // An explicit reveal outranks the viewport check — a dialog opening means
+  // draw it now.
+  refresh() {
+    this.unwatchViewport()
+    if (this.measurable) this.render()
+  }
+
+  rerender() {
+    if (this.chart) this.render()
+  }
+
+  // Anything inside a `display: none` subtree — a closed <dialog>, a hidden
+  // tab panel — reports no client rects.
+  get measurable() {
+    return this.element.getClientRects().length > 0
+  }
+
+  render() {
+    this.destroy()
+    this.chart = new ApexCharts(this.element, this.resolvedOptions())
+    this.chart.render()
+  }
+
+  destroy() {
+    if (this.chart) {
+      this.chart.destroy()
+      this.chart = null
+    }
+  }
+
+  resolvedOptions() {
+    const options = this.resolveCssVariables({
+      ...this.optionsValue,
+      chart: {
+        ...(this.optionsValue.chart || {}),
+        animations: {
+          ...(this.optionsValue.chart?.animations || {}),
+          enabled: this.animationsEnabled
+        }
+      },
+      theme: {
+        ...this.optionsValue.theme,
+        // Last word: the server ships a static `light` default it cannot know
+        // better than, so spreading it after would pin every chart to light.
+        mode: this.darkMode ? "dark" : "light"
+      }
+    })
+
+    return this.applyTooltip(this.applyEdgeLabels(this.applyFormatters(options)))
+  }
+
+  // Apex's stock tooltip is a dark slab whatever the page is doing. This one is
+  // built from the same CSS variables as everything else, so it follows the
+  // theme, and it leads with what changed rather than with the date.
+  applyTooltip(options) {
+    // `tooltip_style: false` hands the tooltip back to Apex; passing your own
+    // `tooltip.custom` also wins.
+    if (options.tooltip_style === false) return options
+    if (options.tooltip?.custom || options.chart?.sparkline?.enabled) return options
+
+    const format = this.formatterFor(options.format || "number", options.currency)
+    // One formatter per series on a combo, so a currency row and a percentage
+    // row in the same tooltip each read in their own units.
+    const rowFormats = (options.series_formats || []).map((name) => this.formatterFor(name, options.currency))
+    const comparedDates = options.compare_categories || []
+    const upIsGood = options.trend_up_is_good !== false
+    const showDelta = options.tooltip_delta !== false
+    const headingMode = options.tooltip_heading
+
+    return {
+      ...options,
+      tooltip: {
+        ...(options.tooltip || {}),
+        custom: ({ series, dataPointIndex, w }) => {
+          const labels = w.globals.categoryLabels?.length ? w.globals.categoryLabels : w.globals.labels
+          const point = (index) => series[index]?.[dataPointIndex]
+          const comparing = series.length === 2 && comparedDates.length > 0
+
+          const rows = series.map((_, index) => ({
+            // In a comparison the two rows are the same metric at different
+            // dates, so the date identifies them. Otherwise the name does.
+            label: comparing
+              ? (index === 0 ? labels?.[dataPointIndex] : comparedDates[dataPointIndex])
+              : w.globals.seriesNames[index],
+            value: point(index),
+            color: w.globals.colors[index],
+            format: rowFormats[index] || null
+          }))
+
+          // Auto: a comparison leads with the metric, since the rows carry the
+          // dates. Anything else leads with the point being hovered.
+          const leadsWithSeries = headingMode ? headingMode === "series" : comparing
+          const heading = leadsWithSeries ? w.globals.seriesNames[0] : labels?.[dataPointIndex]
+          const delta = showDelta && comparing ? this.tooltipDelta(point(0), point(1), upIsGood) : null
+
+          return this.tooltipMarkup(heading, rows, delta, format)
+        }
+      }
+    }
+  }
+
+  tooltipDelta(current, previous, upIsGood) {
+    if (![current, previous].every((n) => typeof n === "number") || previous === 0) return null
+
+    const change = ((current - previous) / Math.abs(previous)) * 100
+    if (!isFinite(change)) return null
+
+    const rounded = Math.round(change * 100) / 100
+    return {
+      text: `${rounded > 0 ? "+" : ""}${rounded}%`,
+      tone: rounded === 0 ? "neutral" : (rounded > 0) === upIsGood ? "positive" : "negative"
+    }
+  }
+
+  tooltipMarkup(heading, rows, delta, format) {
+    const cells = rows
+      .filter((row) => row.value !== null && row.value !== undefined)
+      .map(
+        (row) => `
+          <tr>
+            <th scope="row">
+              <span class="railsui-chart-tooltip__key" style="background:${this.escape(row.color)}"></span>
+              ${this.escape(row.label)}
+            </th>
+            <td>${this.escape(this.formatRow(row, format))}</td>
+          </tr>`
+      )
+      .join("")
+
+    const badge = delta
+      ? `<span class="railsui-chart-tooltip__delta railsui-chart-tooltip__delta--${delta.tone}">${this.escape(delta.text)}</span>`
+      : ""
+
+    return `
+      <div class="railsui-chart-tooltip">
+        <div class="railsui-chart-tooltip__head">
+          <span class="railsui-chart-tooltip__title">${this.escape(heading)}</span>${badge}
+        </div>
+        <table class="railsui-chart-tooltip__rows">${cells}</table>
+      </div>`
+  }
+
+  // A row's own formatter when it has one, the chart's otherwise.
+  formatRow(row, fallback) {
+    const format = row.format || fallback
+    return format ? format(row.value) : row.value
+  }
+
+  // Series names and category labels come from application data.
+  escape(value) {
+    return String(value ?? "").replace(/[&<>"']/g, (char) => {
+      return { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[char]
+    })
+  }
+
+  // Stripe-style cards label only the first and last tick, so the axis reads as
+  // a range rather than a row of collided, rotated dates.
+  applyEdgeLabels(options) {
+    if (!options.edge_labels) return options
+
+    const categories = options.xaxis?.categories || []
+    const last = categories.length - 1
+
+    return {
+      ...options,
+      xaxis: {
+        ...(options.xaxis || {}),
+        labels: {
+          ...(options.xaxis?.labels || {}),
+          formatter: (value, _timestamp, opts) => {
+            const index = typeof opts?.i === "number" ? opts.i : categories.indexOf(value)
+            return index === 0 || index === last ? value : ""
+          }
+        }
+      },
+      // Apex reuses the axis formatter for the tooltip title, which would blank
+      // out every point between the two edges.
+      tooltip: {
+        ...(options.tooltip || {}),
+        x: {
+          ...(options.tooltip?.x || {}),
+          formatter: (value, opts) => categories[opts?.dataPointIndex] ?? value
+        }
+      }
+    }
+  }
+
+  applyFormatters(options) {
+    const formatter = this.formatterFor(options.format || "number", options.currency)
+    if (!formatter) return options
+
+    const withFormatter = (axis) => {
+      if (Array.isArray(axis)) return axis.map(withFormatter)
+
+      // An axis may name its own format. A combo measures money on one side
+      // and a percentage on the other, and one formatter across both dresses
+      // one of the two scales in the wrong units.
+      const own = axis?.format ? this.formatterFor(axis.format, options.currency) : null
+
+      return { ...(axis || {}), labels: { ...(axis?.labels || {}), formatter: own || formatter } }
+    }
+
+    // A horizontal bar puts its values along x and its categories up y, so
+    // formatting the y-axis there would dress the labels and leave the numbers
+    // bare.
+    if (options.plotOptions?.bar?.horizontal) {
+      // Unless it is a time axis. A timeline's x values are milliseconds, and a
+      // number formatter over the top turns every tick into "1,786,380,000,000"
+      // where a date belongs. Apex formats a datetime axis from the date
+      // itself, so the right move is to leave it alone.
+      const timeAxis = options.xaxis?.type === "datetime"
+
+      return {
+        ...options,
+        ...(timeAxis ? {} : { xaxis: withFormatter(options.xaxis) }),
+        tooltip: { ...(options.tooltip || {}), y: { ...(options.tooltip?.y || {}), formatter: formatter } }
+      }
+    }
+
+    const formatted = {
+      ...options,
+      yaxis: withFormatter(options.yaxis),
+      tooltip: {
+        ...(options.tooltip || {}),
+        y: {
+          ...(options.tooltip?.y || {}),
+          formatter: formatter
+        }
+      }
+    }
+
+    // Only when there is one. Apex reads `responsive` as a list, and writing
+    // the key back as undefined is not the same as leaving it out — it finds
+    // the key, walks it, and throws before anything is drawn. A sparkline
+    // never gets breakpoints, so every one of them hit this and rendered as
+    // an empty element with no error in the console.
+    if (Array.isArray(options.responsive)) {
+      // Breakpoint overrides replace the axis rather than merging into it, so
+      // an unformatted mobile axis is the default unless the formatter is
+      // planted in each one too.
+      formatted.responsive = options.responsive.map((entry) => ({
+        ...entry,
+        options: {
+          ...(entry.options || {}),
+          ...(entry.options?.yaxis ? { yaxis: withFormatter(entry.options.yaxis) } : {})
+        }
+      }))
+    }
+
+    return formatted
+  }
+
+  formatterFor(format, currency = "$") {
+    switch (format) {
+      case "currency":
+        return (value) => {
+          if (value === null || value === undefined || isNaN(value)) return value
+          return `${currency}${Number(value).toLocaleString("en-US", { minimumFractionDigits: 0, maximumFractionDigits: 2 })}`
+        }
+      case "percentage":
+        return (value) => {
+          if (value === null || value === undefined || isNaN(value)) return value
+          return `${Number(value).toFixed(1)}%`
+        }
+      case "human":
+        return (value) => {
+          if (value === null || value === undefined || isNaN(value)) return value
+          return this.humanFormat(Number(value))
+        }
+      case "short_currency":
+        return (value) => {
+          if (value === null || value === undefined || isNaN(value)) return value
+          return `${currency}${this.humanFormat(Number(value))}`
+        }
+      case "number":
+        // Computed series arrive as floats, so an unformatted axis renders
+        // "860.0000000000000". Delimited and trimmed by default.
+        return (value) => {
+          if (value === null || value === undefined || isNaN(value)) return value
+          return Number(value).toLocaleString("en-US", { maximumFractionDigits: 2 })
+        }
+      default:
+        return null
+    }
+  }
+
+  humanFormat(value) {
+    if (value === 0) return "0"
+
+    const suffixes = ["", "K", "M", "B", "T"]
+    const tier = Math.log10(Math.abs(value)) / 3 | 0
+    if (tier === 0) return `${Math.round(value * 100) / 100}`
+
+    const scaled = value / Math.pow(10, tier * 3)
+    // 2.0K reads worse than 2K; only keep the decimal when it carries meaning.
+    const rounded = Math.round(scaled * 10) / 10
+    return `${Number.isInteger(rounded) ? rounded : rounded.toFixed(1)}${suffixes[tier]}`
+  }
+
+  resolveCssVariables(value) {
+    if (typeof value === "string") {
+      return this.resolveCssVariable(value)
+    }
+
+    if (Array.isArray(value)) {
+      return value.map((item) => this.resolveCssVariables(item))
+    }
+
+    if (value !== null && typeof value === "object") {
+      return Object.entries(value).reduce((result, [key, val]) => {
+        result[key] = this.resolveCssVariables(val)
+        return result
+      }, {})
+    }
+
+    return value
+  }
+
+  resolveCssVariable(value) {
+    const match = value.match(/^var\((--[^,]+)(?:,\s*(.+))?\)$/)
+    if (!match) return value
+
+    const variableName = match[1]
+    const fallback = match[2]
+    // Read from the chart's own element so a scoped theme (a dark panel inside
+    // a light page) resolves against the surface it actually sits on.
+    const computed = getComputedStyle(this.element).getPropertyValue(variableName).trim()
+
+    return computed || fallback || value
+  }
+
+  bindThemeListeners() {
+    this.darkModeMediaQuery = window.matchMedia("(prefers-color-scheme: dark)")
+    this.motionMediaQuery = window.matchMedia("(prefers-reduced-motion: reduce)")
+    // Only redraw what is already drawn. A chart still waiting for the
+    // viewport should keep waiting rather than be pulled forward by a theme
+    // change it is not on screen for.
+    this.themeHandler = () => this.rerender()
+
+    this.darkModeMediaQuery.addEventListener("change", this.themeHandler)
+    this.motionMediaQuery.addEventListener("change", this.themeHandler)
+
+    // Class- and attribute-based theme toggles never fire a media query event,
+    // so watch the root element for the swap too.
+    this.renderedDarkMode = this.darkMode
+    this.themeObserver = new MutationObserver(() => {
+      const dark = this.darkMode
+      if (dark === this.renderedDarkMode) return
+
+      this.renderedDarkMode = dark
+      this.rerender()
+    })
+    this.themeObserver.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ["class", "data-theme"]
+    })
+  }
+
+  unbindThemeListeners() {
+    if (this.themeHandler) {
+      this.darkModeMediaQuery?.removeEventListener("change", this.themeHandler)
+      this.motionMediaQuery?.removeEventListener("change", this.themeHandler)
+    }
+    this.themeObserver?.disconnect()
+  }
+
+  get animationsEnabled() {
+    return !(this.motionMediaQuery && this.motionMediaQuery.matches)
+  }
+
+  get darkMode() {
+    const root = document.documentElement
+    const explicit = root.getAttribute("data-theme")
+
+    if (explicit === "dark") return true
+    if (explicit === "light") return false
+    if (root.classList.contains("dark")) return true
+
+    return this.darkModeMediaQuery ? this.darkModeMediaQuery.matches : false
+  }
+}

data/app/javascript/controllers/railsui_chart_filters_controller.js

@@ -0,0 +1,14 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Submits the filter row as soon as a control changes, so the whole view
+// re-renders against one slice. The form is a plain GET, so every slice stays
+// linkable and the page still works with this controller absent.
+export default class extends Controller {
+  submit() {
+    if (this.element.requestSubmit) {
+      this.element.requestSubmit()
+    } else {
+      this.element.submit()
+    }
+  }
+}

data/app/javascript/controllers/railsui_metric_dialog_controller.js

@@ -0,0 +1,27 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Opens a metric card's expanded view: the same series with room to read it.
+// A native <dialog> handles focus trapping, Escape, and inertness for us.
+export default class extends Controller {
+  static targets = ["dialog"]
+
+  open() {
+    this.dialogTarget.showModal()
+
+    // The chart inside was laid out while the dialog was closed, which means
+    // it measured zero and drew nothing. Now that it has a size, tell it.
+    this.dialogTarget.querySelectorAll(".railsui-chart").forEach((chart) => {
+      chart.dispatchEvent(new CustomEvent("railsui-chart:refresh"))
+    })
+  }
+
+  close() {
+    this.dialogTarget.close()
+  }
+
+  // Clicking the backdrop lands on the dialog element itself; a click anywhere
+  // inside lands on a child.
+  closeOnBackdrop(event) {
+    if (event.target === this.dialogTarget) this.dialogTarget.close()
+  }
+}

data/app/views/railsui_charts/demo/index.html.erb

@@ -0,0 +1,45 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>RailsUI Charts Demo</title>
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <%= stylesheet_link_tag "tailwind" if defined?(stylesheet_link_tag) %>
+  <%= stylesheet_link_tag "railsui_charts" %>
+</head>
+<body class="bg-slate-50 dark:bg-slate-900 text-slate-800 dark:text-slate-100 p-8">
+  <div class="max-w-5xl mx-auto space-y-8">
+    <div>
+      <h1 class="text-3xl font-bold tracking-tight">RailsUI Charts Demo</h1>
+      <p class="text-slate-600 dark:text-slate-400 mt-2">Server-rendered, accessible charts for Rails.</p>
+    </div>
+
+    <div class="grid grid-cols-1 md:grid-cols-3 gap-6">
+      <%= railsui_metric label: "Monthly revenue", value: 48_290, change: 12.4, format: :currency, history: @monthly_revenue.map { |d| d[:y] } %>
+      <%= railsui_metric label: "Daily signups", value: 28, change: -3.2, format: :number, history: @daily_signups %>
+      <%= railsui_metric label: "Page views", value: 1_827, change: 8.1, format: :human, history: @page_views %>
+    </div>
+
+    <div class="bg-white dark:bg-slate-800 rounded-xl border border-slate-200 dark:border-slate-700 p-6 shadow-sm">
+      <h2 class="text-lg font-semibold mb-4">Revenue over time</h2>
+      <%= railsui_chart @monthly_revenue, type: :area, label: "Revenue", height: 300 %>
+    </div>
+
+    <div class="grid grid-cols-1 md:grid-cols-2 gap-6">
+      <div class="bg-white dark:bg-slate-800 rounded-xl border border-slate-200 dark:border-slate-700 p-6 shadow-sm">
+        <h2 class="text-lg font-semibold mb-4">Plans</h2>
+        <%= railsui_chart @plan_distribution, type: :bar, label: "Customers", height: 250 %>
+      </div>
+
+      <div class="bg-white dark:bg-slate-800 rounded-xl border border-slate-200 dark:border-slate-700 p-6 shadow-sm">
+        <h2 class="text-lg font-semibold mb-4">Page view trend</h2>
+        <%= railsui_chart @page_views, type: :sparkline, height: 100 %>
+      </div>
+    </div>
+  </div>
+
+  <% if defined?(javascript_importmap_tags) %>
+    <%= javascript_importmap_tags %>
+  <% end %>
+  <%= javascript_include_tag "application" if defined?(javascript_include_tag) %>
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,4 @@
+RailsuiCharts::Engine.routes.draw do
+  get "/demo", to: "demo#index"
+  root to: "demo#index"
+end

data/lib/generators/railsui_charts/install/install_generator.rb

@@ -0,0 +1,52 @@
+require "rails/generators"
+
+module RailsuiCharts
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def add_css_import
+        application_css = Rails.root.join("app/assets/tailwind/application.css")
+
+        if File.exist?(application_css)
+          content = File.read(application_css)
+          import_statement = '@import "../../stylesheets/railsui_charts";'
+
+          unless content.include?(import_statement)
+            File.write(application_css, "#{content.strip}\n#{import_statement}\n")
+            say "✓ Added RailsUI Charts CSS import to app/assets/tailwind/application.css", :green
+          else
+            say "✓ RailsUI Charts CSS import already present", :green
+          end
+        else
+          say "⚠️ app/assets/tailwind/application.css not found. Add this import manually:", :yellow
+          say '  @import "../../stylesheets/railsui_charts";'
+        end
+      end
+
+      CONTROLLERS = %w[
+        railsui_chart_controller.js
+        railsui_chart_filters_controller.js
+        railsui_metric_dialog_controller.js
+      ].freeze
+
+      def copy_stimulus_controllers
+        CONTROLLERS.each do |controller|
+          copy_file controller, "app/javascript/controllers/#{controller}"
+        end
+      end
+
+      def print_next_steps
+        say ""
+        say "RailsUI Charts installed.", :green
+        say ""
+        say "Next steps:", :cyan
+        say "  1. Add the ApexCharts dependency for your JS setup:", :cyan
+        say "     Build mode:  yarn add apexcharts", :cyan
+        say "     No-build:    pin \"apexcharts\", to: \"https://esm.sh/apexcharts@3.45.2\"", :cyan
+        say "  2. Use <%= railsui_chart data, type: :area %> in your views.", :cyan
+        say ""
+      end
+    end
+  end
+end