cordova-plugin-ra-chart 1.0.1 → 1.0.2

package/README.md

@@ -544,6 +544,36 @@ Run it from your Cordova project root, and point at wherever the folder actually
 
 **In an Ionic/Angular app, prefer Option B over the plugin.** The Cordova route only sets `window.RaChart` after `deviceready`, which means charts do not render in `ionic serve` or in unit tests. Copying to `src/assets/` works everywhere.
 
+### No data showing / blank chart
+
+Work down this list — the first two cover almost every case.
+
+**1. Check the console.** Since v1.0.1 the engine reports naming mismatches itself:
+
+```
+[raChart] nothing to plot — series "Revenue" field "revenue" not found in the data.
+Your rows have: month, total. Check the `field`/`category` names against your data keys.
+```
+
+That means `field: 'revenue'` does not match your rows, so every value read as 0. The `field` in `series` and the `category` string must match your data object keys **exactly**, including case. An API returning `Total` will not bind to `field: 'total'`.
+
+**2. Async data with `<ra-chart>`** — fixed in v1.0.1. On v1.0.0 a chart whose `data` was still `[]` when the view initialised never built once the API responded, leaving it permanently blank. Update to v1.0.1. There is no workaround on v1.0.0 other than `*ngIf`-ing the chart until data arrives.
+
+**3. Mutating the array instead of replacing it.** The component is `OnPush`, so `push()` is invisible to it:
+
+```ts
+this.rows = [...this.rows, row];   // ✅
+this.rows.push(row);               // ❌ nothing redraws
+```
+
+**4. Values are strings.** `"42"` from JSON coerces fine, but `"1,234"` or `"42%"` becomes 0. Parse before binding.
+
+**5. Zero-width container.** A chart built inside a hidden tab, collapsed accordion or `display:none` parent measures 0 and draws nothing. Call `resize()` when it becomes visible.
+
+**6. Plain Cordova: building before `deviceready`.** `window.RaChart` does not exist until the plugin bootstraps. Wrap construction in a `deviceready` listener.
+
+To silence the diagnostics in production: `RaChart.warnings = false;`
+
 ### Runtime issues
 
 **"Chart engine failed to load"** — `ra-chart.js` is not on any path the loader tries. It attempts your `RA_CHART_SCRIPT_URL` first, then `assets/ra-chart/ra-chart.js`, `assets/js/ra-chart.js`, `assets/ra-chart.js`, and `plugins/cordova-plugin-ra-chart/www/ra-chart.js`. Confirm the file is in one of those, that `angular.json` copies `src/assets`, and check the browser Network tab for a 404.

package/ionic/ra-chart.component.ts

@@ -88,6 +88,8 @@ export class RaChartComponent implements AfterViewInit, OnChanges, OnDestroy {
 
   private chart: RaChartInstance | null = null;
   private booted = false;
+  /** Guards against building before the host div has been measured. */
+  private viewReady = false;
   private listeners: Array<[string, EventListener]> = [];
 
   constructor(
@@ -106,11 +108,20 @@ export class RaChartComponent implements AfterViewInit, OnChanges, OnDestroy {
   }
 
   ngAfterViewInit(): void {
+    this.viewReady = true;
     this.boot();
   }
 
   ngOnChanges(changes: SimpleChanges): void {
-    if (!this.chart) return;
+    if (!this.chart) {
+      // No chart yet. This is the normal async case: the component rendered
+      // while `data` was still an empty array, so boot() bailed out as empty.
+      // Now that inputs have arrived, build it — otherwise the chart would
+      // stay blank forever.
+      if (this.viewReady && !this.isEmpty) this.boot();
+      else this.cdr.markForCheck();
+      return;
+    }
 
     // data-only change on a stable shape → let the engine morph the values
     const keys = Object.keys(changes);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cordova-plugin-ra-chart",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Dependency-free SVG chart engine for Cordova and Ionic — 21 chart types with touch gestures, pinch-to-zoom, haptics and dark-mode theming. No native code, no build step.",
   "main": "www/ra-chart.js",
   "types": "types/index.d.ts",
@@ -39,4 +39,4 @@
     "www/ra-chart.js",
     "www/ra-chart.css"
   ]
-}
+}

package/www/ra-chart.js

@@ -527,11 +527,54 @@
     this.kind = KINDS[o.type] || "xy";
     this.zoomable = !!o.zoom && (this.kind === "xy" || this.kind === "candle");
 
+    this._validate();
     if (this.zoomable) this._buildZoomBar();
     this._scaffoldBody();
     this._dispatchBuild(entrance);
   };
 
+  /**
+   * A blank chart is almost always a naming mismatch rather than a rendering
+   * fault: `field` or `category` pointing at keys the rows do not have reads
+   * every value as 0 and draws nothing. Say so instead of failing silently.
+   * Warns once per chart, and never in production-silent mode.
+   */
+  RaChart.prototype._validate = function () {
+    if (this._validated || !RaChart.warnings) return;
+    this._validated = true;
+
+    var o = this.opts;
+    var rows = o.data || [];
+    if (!rows.length || !rows[0] || typeof rows[0] !== "object") return;
+    var keys = Object.keys(rows[0]);
+    var problems = [];
+
+    if (this.kind === "sankey") {
+      var F = merge({ from: "from", to: "to", value: "value" }, o.fields || {});
+      ["from", "to", "value"].forEach(function (k) {
+        if (keys.indexOf(F[k]) < 0) problems.push('sankey ' + k + ' field "' + F[k] + '"');
+      });
+    } else {
+      (o.series || []).forEach(function (s) {
+        if (!s || !s.field) { problems.push("a series with no `field`"); return; }
+        var found = rows.some(function (r) { return r && r[s.field] !== undefined; });
+        if (!found) problems.push('series "' + (s.name || s.field) + '" field "' + s.field + '"');
+      });
+      if (this.kind !== "scatter" && this.kind !== "gauge" &&
+        rows[0][o.category] === undefined) {
+        problems.push('category "' + o.category + '"');
+      }
+    }
+
+    if (problems.length) {
+      console.warn(
+        "[raChart] nothing to plot — " + problems.join(", ") +
+        " not found in the data. Your rows have: " + keys.join(", ") +
+        ". Check the `field`/`category` names against your data keys."
+      );
+    }
+  };
+
   RaChart.prototype._scaffoldBody = function () {
     var o = this.opts;
     this.stage = el("div", "ra-chart__stage", this.el);
@@ -2804,6 +2847,8 @@
   /* ---------- statics ---------- */
 
   RaChart.version = VERSION;
+  /** Set false to silence the "nothing to plot" console diagnostics. */
+  RaChart.warnings = true;
   RaChart.defaults = DEFAULTS;
   RaChart.palette = PALETTE_LIGHT;
   RaChart.paletteDark = PALETTE_DARK;