railsui_charts 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 90aab15c8c1ef133527f757c7e24344da84a62a190825a13decee8979cf79892
-  data.tar.gz: db6626712782f3a93d92ea8c149d9fbe27cece328b1cfca4b611269dd06a8c0b
+  metadata.gz: f3fa00b0555667e87a913c0341ac9efcff529d54d4eb3b7e6a70fbe12167d1a1
+  data.tar.gz: 47b6cc37a82c21c1ccbc1213a8876fa37fa8a2573ef6663629d4e1d09d4cb7fc
 SHA512:
-  metadata.gz: 94345b1a73e7cdd1e2760ee58462f6af60396019295cb0a05a5f300120c2d5ed192d64770cb38254abfa959e94ca5ab51ed9353107163e5f2eb75a22e42611a9
-  data.tar.gz: e89fad7105008595f9de2070044287e1c193a09ab83dd327492a794106259d24783fc30ed580e19c07a40c8a7ea06ed2fbb7ac5780d620af0eafe7ce643da9d8
+  metadata.gz: c5140c807d377faf06d02f1da3b1807d71bf023e3551ba74429ad5bc26aed89e8b19746570337b004080e881beced4cb76a7234c486bf1b28cd6b0810eed423c
+  data.tar.gz: a38ce24f9ba774e6532df52c87e8c71c6260c2103e679702ecb85e50f06d37b40aa09a7d4b3efd1a6cf74eeaa199b48f00708cc76d90b6eaf1fb2a61789904c0

data/CHANGELOG.md

@@ -6,6 +6,49 @@ public API may change between minor versions.
 
 ## [Unreleased]
 
+## [0.2.0]
+
+The JavaScript now comes from the gem instead of being copied into the
+application. This is a breaking change to how it is installed; the helpers, the
+chart API and the CSS are untouched.
+
+### Added
+
+- An npm package, `@getrailsui/charts`, for applications that bundle their
+  JavaScript. It carries the Stimulus controllers and a
+  `registerRailsuiCharts(application)` helper that registers each one under the
+  identifier the Ruby helpers emit.
+- Importmap support. The engine adds its own pins to the host application's
+  importmap and serves a prebuilt, self-contained build, so an importmap app
+  needs no package and no copied files. Both worlds use the same import line.
+- `@hotwired/stimulus` and `apexcharts` are declared as peer dependencies rather
+  than bundled, so an application keeps one copy of each.
+
+### Changed
+
+- **`rails g railsui_charts:install` no longer copies the controllers.** It adds
+  the stylesheet import and prints the right next step for a bundled or an
+  importmap app.
+- The install generator writes through its own file actions rather than
+  `Rails.root`, so it respects `destination_root` — which is also what made the
+  generators testable.
+
+### Removed
+
+- The duplicate controllers under `lib/generators/.../templates`. They had to be
+  kept in sync with the engine's own copies by hand, and had already drifted.
+
+### Upgrading
+
+Delete the copied controllers from `app/javascript/controllers` and follow the
+README. Left in place they register the same identifiers a second time, and
+Stimulus keeps the last one without complaint.
+
+This is why it changed: a copy is frozen at the version that installed it.
+`bundle update` moved the Ruby and left the JavaScript alone, so 0.1.2's fix for
+empty tooltips on pie, donut and polar area charts reached nobody who did not
+also know to re-copy a file nothing told them about.
+
 ## [0.1.2]
 
 ### Fixed
@@ -67,7 +110,8 @@ First release.
   reachable only by hovering a mark
 - Animation stops when the reader has asked for reduced motion
 
-[Unreleased]: https://github.com/getrailsui/railsui_charts/compare/v0.1.2...HEAD
+[Unreleased]: https://github.com/getrailsui/railsui_charts/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/getrailsui/railsui_charts/compare/v0.1.2...v0.2.0
 [0.1.2]: https://github.com/getrailsui/railsui_charts/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/getrailsui/railsui_charts/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/getrailsui/railsui_charts/releases/tag/v0.1.0

data/README.md

@@ -35,28 +35,63 @@ Add to your Gemfile:
 gem "railsui_charts"
 ```
 
-Then run:
+Then:
 
 ```bash
 bundle install
 rails g railsui_charts:install
 ```
 
-The generator adds the CSS import and copies the Stimulus controller. You still need ApexCharts in your JavaScript:
+The generator adds the stylesheet import. The JavaScript is served from the gem
+rather than copied into your app, so `bundle update` moves all of it.
 
-**Build mode:**
+### Bundled apps (esbuild, bun, rollup, webpack)
 
 ```bash
-yarn add apexcharts
+yarn add @getrailsui/charts apexcharts
 ```
 
-**No-build (importmap):**
+```js
+// app/javascript/controllers/index.js
+import { registerRailsuiCharts } from "@getrailsui/charts"
+
+registerRailsuiCharts(application)
+```
+
+### Importmap
+
+Nothing to add for the controllers — the engine pins them. ApexCharts is a peer
+dependency, so pin that:
 
 ```ruby
 # config/importmap.rb
 pin "apexcharts", to: "https://esm.sh/apexcharts@3.45.2"
 ```
 
+```js
+// app/javascript/controllers/index.js
+import { registerRailsuiCharts } from "@getrailsui/charts"
+
+registerRailsuiCharts(application)
+```
+
+### Upgrading from 0.1.x
+
+0.1.x copied the controllers into `app/javascript/controllers`. Those copies are
+frozen at whatever version installed them — `bundle update` moved the Ruby and
+left them alone, which is the reason this changed. Delete them and follow one of
+the paths above:
+
+```bash
+rm app/javascript/controllers/railsui_chart_controller.js \
+   app/javascript/controllers/railsui_chart_filters_controller.js \
+   app/javascript/controllers/railsui_metric_dialog_controller.js
+```
+
+Leaving them in place registers the same identifiers twice. Stimulus keeps the
+last registration and says nothing about it, so the symptom is a chart behaving
+like an older version of itself.
+
 ## Usage
 
 All charts use the same `railsui_chart` helper. Change the `type:` to switch chart kinds.

data/app/assets/javascripts/railsui_charts.js

@@ -0,0 +1,388 @@
+// app/javascript/controllers/railsui_chart_controller.js
+import { Controller } from "@hotwired/stimulus";
+import ApexCharts from "apexcharts";
+var railsui_chart_controller_default = class extends Controller {
+  static values = { options: Object };
+  connect() {
+    this.bindThemeListeners();
+    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) {
+    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);
+    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, seriesIndex, dataPointIndex, w }) => {
+          const labels = w.globals.categoryLabels?.length ? w.globals.categoryLabels : w.globals.labels;
+          if (!Array.isArray(series[0])) {
+            const slice = seriesIndex ?? dataPointIndex;
+            const row = { label: "", value: series[slice], color: w.globals.colors[slice], format: rowFormats[slice] || null };
+            return this.tooltipMarkup(labels?.[slice], [row], null, format);
+          }
+          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
+          }));
+          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 !== void 0).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);
+      const own = axis?.format ? this.formatterFor(axis.format, options.currency) : null;
+      return { ...axis || {}, labels: { ...axis?.labels || {}, formatter: own || formatter } };
+    };
+    if (options.plotOptions?.bar?.horizontal) {
+      const timeAxis = options.xaxis?.type === "datetime";
+      return {
+        ...options,
+        ...timeAxis ? {} : { xaxis: withFormatter(options.xaxis) },
+        tooltip: { ...options.tooltip || {}, y: { ...options.tooltip?.y || {}, formatter } }
+      };
+    }
+    const formatted = {
+      ...options,
+      yaxis: withFormatter(options.yaxis),
+      tooltip: {
+        ...options.tooltip || {},
+        y: {
+          ...options.tooltip?.y || {},
+          formatter
+        }
+      }
+    };
+    if (Array.isArray(options.responsive)) {
+      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 === void 0 || isNaN(value)) return value;
+          return `${currency}${Number(value).toLocaleString("en-US", { minimumFractionDigits: 0, maximumFractionDigits: 2 })}`;
+        };
+      case "percentage":
+        return (value) => {
+          if (value === null || value === void 0 || isNaN(value)) return value;
+          return `${Number(value).toFixed(1)}%`;
+        };
+      case "human":
+        return (value) => {
+          if (value === null || value === void 0 || isNaN(value)) return value;
+          return this.humanFormat(Number(value));
+        };
+      case "short_currency":
+        return (value) => {
+          if (value === null || value === void 0 || isNaN(value)) return value;
+          return `${currency}${this.humanFormat(Number(value))}`;
+        };
+      case "number":
+        return (value) => {
+          if (value === null || value === void 0 || 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);
+    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];
+    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)");
+    this.themeHandler = () => this.rerender();
+    this.darkModeMediaQuery.addEventListener("change", this.themeHandler);
+    this.motionMediaQuery.addEventListener("change", this.themeHandler);
+    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;
+  }
+};
+
+// app/javascript/controllers/railsui_chart_filters_controller.js
+import { Controller as Controller2 } from "@hotwired/stimulus";
+var railsui_chart_filters_controller_default = class extends Controller2 {
+  submit() {
+    if (this.element.requestSubmit) {
+      this.element.requestSubmit();
+    } else {
+      this.element.submit();
+    }
+  }
+};
+
+// app/javascript/controllers/railsui_metric_dialog_controller.js
+import { Controller as Controller3 } from "@hotwired/stimulus";
+var railsui_metric_dialog_controller_default = class extends Controller3 {
+  static targets = ["dialog"];
+  open() {
+    this.dialogTarget.showModal();
+    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();
+  }
+};
+
+// app/javascript/railsui_charts/index.js
+var RAILSUI_CHART_CONTROLLERS = {
+  "railsui-chart": railsui_chart_controller_default,
+  "railsui-chart-filters": railsui_chart_filters_controller_default,
+  "railsui-metric-dialog": railsui_metric_dialog_controller_default
+};
+function registerRailsuiCharts(application) {
+  Object.entries(RAILSUI_CHART_CONTROLLERS).forEach(([identifier, controller]) => {
+    application.register(identifier, controller);
+  });
+  return application;
+}
+var index_default = registerRailsuiCharts;
+export {
+  RAILSUI_CHART_CONTROLLERS,
+  railsui_chart_controller_default as RailsuiChartController,
+  railsui_chart_filters_controller_default as RailsuiChartFiltersController,
+  railsui_metric_dialog_controller_default as RailsuiMetricDialogController,
+  index_default as default,
+  registerRailsuiCharts
+};

data/app/javascript/railsui_charts/index.js

@@ -0,0 +1,32 @@
+// The package entry point.
+//
+// The controllers used to be copied into each application by a generator, which
+// meant `bundle update` moved the Ruby and left the JavaScript on whatever
+// version was installed. Importing them from here — over npm for a bundled app,
+// over the asset pipeline for an importmap one — is what makes an upgrade
+// actually arrive.
+
+import RailsuiChartController from "../controllers/railsui_chart_controller.js"
+import RailsuiChartFiltersController from "../controllers/railsui_chart_filters_controller.js"
+import RailsuiMetricDialogController from "../controllers/railsui_metric_dialog_controller.js"
+
+export { RailsuiChartController, RailsuiChartFiltersController, RailsuiMetricDialogController }
+
+// The identifiers the Ruby helpers emit. Registering them by hand means three
+// chances to typo a name that fails silently — a chart simply never draws, with
+// nothing in the console to say why.
+export const RAILSUI_CHART_CONTROLLERS = {
+  "railsui-chart": RailsuiChartController,
+  "railsui-chart-filters": RailsuiChartFiltersController,
+  "railsui-metric-dialog": RailsuiMetricDialogController
+}
+
+export function registerRailsuiCharts(application) {
+  Object.entries(RAILSUI_CHART_CONTROLLERS).forEach(([identifier, controller]) => {
+    application.register(identifier, controller)
+  })
+
+  return application
+}
+
+export default registerRailsuiCharts

data/config/importmap.rb

@@ -0,0 +1,12 @@
+# Pins for applications using importmap-rails.
+#
+# The engine adds this file to the app's importmap paths, so an importmap app
+# gets the same bare specifier a bundled app uses:
+#
+#   import { registerRailsuiCharts } from "@getrailsui/charts"
+#
+# It points at a prebuilt, self-contained file rather than at the individual
+# controllers. Sprockets digests every asset separately, so the relative imports
+# between the source files would not resolve once served — the browser would ask
+# for an undigested path and get a 404 with the chart simply never appearing.
+pin "@getrailsui/charts", to: "railsui_charts.js", preload: true

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

@@ -3,50 +3,65 @@ require "rails/generators"
 module RailsuiCharts
   module Generators
     class InstallGenerator < Rails::Generators::Base
-      source_root File.expand_path("templates", __dir__)
-
+      # The JavaScript is no longer copied. It used to be, and that meant
+      # `bundle update` moved the Ruby while the controllers stayed on whatever
+      # version was installed — a fix could ship and reach nobody. Bundled apps
+      # take it from npm, importmap apps from the pin this engine adds, and both
+      # follow the gem from then on.
       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
+        path = "app/assets/tailwind/application.css"
+        import_statement = %q(@import "../../stylesheets/railsui_charts";)
+        full_path = File.join(destination_root, path)
+
+        unless File.exist?(full_path)
+          say "⚠️  #{path} not found. Add this import manually:", :yellow
+          say "  #{import_statement}"
+          return
+        end
+
+        if File.read(full_path).include?(import_statement)
+          say "✓ RailsUI Charts CSS import already present", :green
         else
-          say "⚠️ app/assets/tailwind/application.css not found. Add this import manually:", :yellow
-          say '  @import "../../stylesheets/railsui_charts";'
+          append_to_file path, "#{import_statement}\n"
+          say "✓ Added RailsUI Charts CSS import to #{path}", :green
         end
       end
 
-      CONTROLLERS = %w[
-        railsui_chart_controller.js
-        railsui_chart_filters_controller.js
-        railsui_metric_dialog_controller.js
-      ].freeze
+      def print_next_steps
+        say ""
+        say "RailsUI Charts #{RailsuiCharts::VERSION} installed.", :green
+        say ""
 
-      def copy_stimulus_controllers
-        CONTROLLERS.each do |controller|
-          copy_file controller, "app/javascript/controllers/#{controller}"
+        if importmap?
+          say "Your importmap already has the controllers — this engine pins them.", :cyan
+          say "Register them in app/javascript/controllers/index.js:", :cyan
+        else
+          say "Add the JavaScript package and ApexCharts:", :cyan
+          say "  yarn add @getrailsui/charts apexcharts", :cyan
+          say ""
+          say "Then register the controllers in app/javascript/controllers/index.js:", :cyan
         end
-      end
 
-      def print_next_steps
         say ""
-        say "RailsUI Charts installed.", :green
+        say '  import { registerRailsuiCharts } from "@getrailsui/charts"', :cyan
+        say "  registerRailsuiCharts(application)", :cyan
         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
+
+        if importmap?
+          say "ApexCharts is a peer dependency; pin it too:", :cyan
+          say '  pin "apexcharts", to: "https://esm.sh/apexcharts@3.45.2"', :cyan
+          say ""
+        end
+
+        say "Then use <%= railsui_chart data, type: :area %> in your views.", :cyan
         say ""
       end
+
+      private
+
+      def importmap?
+        File.exist?(File.join(destination_root, "config/importmap.rb"))
+      end
     end
   end
 end

data/lib/railsui_charts/engine.rb

@@ -13,7 +13,23 @@ module RailsuiCharts
     end
 
     initializer "railsui_charts.assets" do |app|
+      next unless app.config.respond_to?(:assets)
+
       app.config.assets.precompile << "railsui_charts.css"
+
+      # The built controllers, served from the gem so an importmap application
+      # can pin them instead of holding a copy that bundle update never moves.
+      app.config.assets.paths << root.join("app/assets/javascripts")
+      app.config.assets.precompile << "railsui_charts.js"
+    end
+
+    # Adds this gem's pins to the host app's importmap. `before` matters:
+    # importmap-rails reads the collected paths in its own initializer, and a
+    # pin added afterwards is simply never seen.
+    initializer "railsui_charts.importmap", before: "importmap" do |app|
+      next unless app.config.respond_to?(:importmap)
+
+      app.config.importmap.paths << root.join("config/importmap.rb")
     end
   end
 end

data/lib/railsui_charts/version.rb

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

data/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@getrailsui/charts",
+  "version": "0.2.0",
+  "description": "Rails-native chart components built on ApexCharts. Stimulus controllers for the railsui_charts gem.",
+  "author": "Andy Leverenz <railsui@justalever.com>",
+  "license": "MIT",
+  "homepage": "https://railsui.com/charts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getrailsui/railsui_charts.git"
+  },
+  "type": "module",
+  "main": "app/javascript/railsui_charts/index.js",
+  "module": "app/javascript/railsui_charts/index.js",
+  "exports": {
+    ".": "./app/javascript/railsui_charts/index.js",
+    "./controllers/*": "./app/javascript/controllers/*"
+  },
+  "files": [
+    "app/javascript",
+    "app/assets/javascripts",
+    "README.md",
+    "LICENSE.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "esbuild app/javascript/railsui_charts/index.js --bundle --format=esm --external:@hotwired/stimulus --external:apexcharts --outfile=app/assets/javascripts/railsui_charts.js"
+  },
+  "peerDependencies": {
+    "@hotwired/stimulus": ">=3.0.0",
+    "apexcharts": ">=3.45.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.0"
+  },
+  "sideEffects": false
+}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: railsui_charts
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Andy Leverenz
@@ -35,17 +35,17 @@ files:
 - LICENSE.md
 - README.md
 - Rakefile
+- app/assets/javascripts/railsui_charts.js
 - 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/javascript/railsui_charts/index.js
 - app/views/railsui_charts/demo/index.html.erb
+- config/importmap.rb
 - 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
@@ -56,6 +56,7 @@ files:
 - lib/railsui_charts/interval.rb
 - lib/railsui_charts/metric_helper.rb
 - lib/railsui_charts/version.rb
+- package.json
 homepage: https://railsui.com/charts
 licenses:
 - MIT

data/lib/generators/railsui_charts/install/templates/railsui_chart_controller.js

@@ -1,453 +0,0 @@
-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, seriesIndex, dataPointIndex, w }) => {
-          const labels = w.globals.categoryLabels?.length ? w.globals.categoryLabels : w.globals.labels
-
-          // A pie, donut or polar area hands back one number per slice rather
-          // than one array per series, and names the hovered slice with
-          // seriesIndex — dataPointIndex means nothing there. Read as a
-          // cartesian series, every value came out undefined, and since rows
-          // without a value are dropped the tooltip rendered as an empty box.
-          if (!Array.isArray(series[0])) {
-            const slice = seriesIndex ?? dataPointIndex
-            // No row label: the slice's name is already the heading, and
-            // printing it twice in a two-line tooltip reads as a mistake.
-            const row = { label: "", value: series[slice], color: w.globals.colors[slice], format: rowFormats[slice] || null }
-
-            return this.tooltipMarkup(labels?.[slice], [row], null, format)
-          }
-
-          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/lib/generators/railsui_charts/install/templates/railsui_chart_filters_controller.js

@@ -1,14 +0,0 @@
-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/lib/generators/railsui_charts/install/templates/railsui_metric_dialog_controller.js

@@ -1,27 +0,0 @@
-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()
-  }
-}