cordova-plugin-ra-chart 1.0.0 → 1.0.2

package/README.md

@@ -44,8 +44,14 @@ ra-chart-cordova/
 
 ## Install
 
+> **Ionic/Angular app? Use Option B.** The Cordova plugin route only exposes
+> `window.RaChart` after `deviceready`, so charts stay blank under `ionic serve`.
+> raChart has no native code, so the plugin buys you nothing there.
+
 ### Option A — Cordova plugin
 
+Run from your Cordova project root, pointing at the folder that contains `plugin.xml`:
+
 ```bash
 cordova plugin add ./ra-chart-cordova
 ```
@@ -518,7 +524,59 @@ ready(chart: RaChartInstance) {
 
 ## Troubleshooting
 
-**"Chart engine failed to load"** — `ra-chart.js` is not at the loader's path. Confirm it sits in `src/assets/ra-chart/`, that `angular.json` copies `src/assets`, and override `RA_CHART_SCRIPT_URL` if you keep it elsewhere.
+### Install errors
+
+**`Failed to fetch plugin cordova-plugin-ra-chart via registry`** — the plugin is not published to npm. Install from the local folder instead, with a path (the leading `./` matters):
+
+```bash
+cordova plugin add ./ra-chart-cordova
+```
+
+Run it from your Cordova project root, and point at wherever the folder actually lives, e.g. `cordova plugin add C:/Users/You/Desktop/AI/ra-chart-cordova`.
+
+**`Cannot find plugin.xml for plugin "..."`** — the path is wrong or points one level off. It must be the folder that directly contains `plugin.xml`, not its parent and not `www/`.
+
+**`Plugin doesn't support this project's cordova version`** — this came from a version requirement that v1.0.1 removed. Update to v1.0.1, or delete the `<engines>` block from `plugin.xml`.
+
+**`npm ERR! code ENOLOCAL` / `Could not install from "ra-chart-cordova"`** — you ran `npm install` instead of `cordova plugin add`. This is a Cordova plugin, not an npm package.
+
+**Using Capacitor, not Cordova?** `cordova plugin add` does not exist there. Skip the plugin entirely and use Option B — copy the two files into `src/assets/` and use the `<ra-chart>` component. Nothing in raChart needs a native bridge.
+
+**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.
 
 **Chart is blank but no error** — the host had zero width at build time (a hidden tab, a collapsed accordion). Call `chart.resize()` or the component's `resize()` when the container becomes visible.
 

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);
@@ -229,8 +240,12 @@ export class RaChartComponent implements AfterViewInit, OnChanges, OnDestroy {
     const host = this.hostRef.nativeElement;
     const bridge = (name: string, out: EventEmitter<any>) => {
       const fn = ((e: CustomEvent) => {
-        // only surface to Angular if somebody is actually listening
-        if (out.observers.length === 0) return;
+        // Skip the zone re-entry when nobody is bound, so touch scrubbing stays
+        // cheap. `observed` is RxJS 7+; `observers` is the older spelling and is
+        // gone in RxJS 8 — feature-detect rather than pin to either.
+        const subj = out as unknown as { observed?: boolean; observers?: unknown[] };
+        if (subj.observed === false) return;
+        if (subj.observed === undefined && subj.observers && subj.observers.length === 0) return;
         this.zone.run(() => out.emit(e.detail));
       }) as EventListener;
       host.addEventListener(name, fn);

package/ionic/ra-chart.loader.ts

@@ -2,9 +2,9 @@ import { InjectionToken } from '@angular/core';
 import type { RaChartConstructor } from './ra-chart.types';
 
 /**
- * Where `ra-chart.js` lives when it is NOT bundled via angular.json "scripts".
- * Override in your app config to change the path:
+ * Where `ra-chart.js` lives when it is NOT already on `window`.
  *
+ * Override in your app config to pin an exact path:
  *   providers: [{ provide: RA_CHART_SCRIPT_URL, useValue: 'assets/vendor/ra-chart.js' }]
  */
 export const RA_CHART_SCRIPT_URL = new InjectionToken<string>('RA_CHART_SCRIPT_URL', {
@@ -12,6 +12,18 @@ export const RA_CHART_SCRIPT_URL = new InjectionToken<string>('RA_CHART_SCRIPT_U
   factory: () => 'assets/ra-chart/ra-chart.js'
 });
 
+/**
+ * Paths tried after the configured one, so a copy that landed in a slightly
+ * different place still works instead of failing the whole chart. Covers the
+ * Cordova plugin install location and the usual assets spellings.
+ */
+const FALLBACK_URLS = [
+  'assets/ra-chart/ra-chart.js',
+  'assets/js/ra-chart.js',
+  'assets/ra-chart.js',
+  'plugins/cordova-plugin-ra-chart/www/ra-chart.js'
+];
+
 let pending: Promise<RaChartConstructor> | null = null;
 
 /** The engine attaches itself to `window`; grab it if it is already there. */
@@ -20,44 +32,64 @@ function fromWindow(): RaChartConstructor | null {
   return w && w.RaChart ? (w.RaChart as RaChartConstructor) : null;
 }
 
-/**
- * Resolve the engine, lazy-injecting the script the first time if needed.
- * Repeat calls share one in-flight promise, so many charts on one page
- * trigger exactly one network request.
- */
-export function ensureRaChart(scriptUrl: string): Promise<RaChartConstructor> {
-  const existing = fromWindow();
-  if (existing) return Promise.resolve(existing);
-  if (pending) return pending;
-
-  pending = new Promise<RaChartConstructor>((resolve, reject) => {
-    // another loader may have injected the same tag already
-    const selector = `script[data-ra-chart="1"]`;
-    let tag = document.querySelector<HTMLScriptElement>(selector);
-
-    const done = () => {
+function injectOnce(url: string): Promise<RaChartConstructor> {
+  return new Promise<RaChartConstructor>((resolve, reject) => {
+    const existing = document.querySelector<HTMLScriptElement>(
+      `script[data-ra-chart="${CSS && CSS.escape ? CSS.escape(url) : url}"]`
+    );
+    const settle = () => {
       const ctor = fromWindow();
       if (ctor) resolve(ctor);
-      else reject(new Error('ra-chart.js loaded but window.RaChart is missing'));
+      else reject(new Error(`Loaded ${url} but window.RaChart is missing`));
     };
 
-    if (tag) {
-      tag.addEventListener('load', done);
-      tag.addEventListener('error', () => reject(new Error('Failed to load ' + scriptUrl)));
+    if (existing) {
+      existing.addEventListener('load', settle);
+      existing.addEventListener('error', () => reject(new Error(`Failed to load ${url}`)));
       return;
     }
 
-    tag = document.createElement('script');
-    tag.src = scriptUrl;
+    const tag = document.createElement('script');
+    tag.src = url;
     tag.async = true;
-    tag.dataset['raChart'] = '1';
-    tag.onload = done;
-    tag.onerror = () => {
-      pending = null;
-      reject(new Error('Failed to load ' + scriptUrl));
-    };
+    tag.dataset['raChart'] = url;
+    tag.onload = settle;
+    tag.onerror = () => reject(new Error(`Failed to load ${url}`));
     document.head.appendChild(tag);
   });
+}
+
+/**
+ * Resolve the engine, lazy-injecting the script the first time if needed.
+ * Repeat calls share one in-flight promise, so many charts on one page trigger
+ * a single load. Tries `scriptUrl` first, then the well-known fallbacks.
+ */
+export function ensureRaChart(scriptUrl: string): Promise<RaChartConstructor> {
+  const already = fromWindow();
+  if (already) return Promise.resolve(already);
+  if (pending) return pending;
+
+  const candidates = [scriptUrl, ...FALLBACK_URLS.filter(u => u !== scriptUrl)];
+
+  pending = candidates
+    .reduce<Promise<RaChartConstructor | null>>(
+      (chain, url) => chain.then(found => (found ? found : injectOnce(url).catch(() => null))),
+      Promise.resolve(null)
+    )
+    .then(found => {
+      if (found) return found;
+      pending = null;                 // let a later call retry after a fix
+      throw new Error(
+        'ra-chart.js not found. Tried: ' + candidates.join(', ') +
+        '. Copy www/ra-chart.js into src/assets/ra-chart/, or provide ' +
+        'RA_CHART_SCRIPT_URL with the correct path.'
+      );
+    });
 
   return pending;
 }
+
+/** Test seam — forget any cached load so the next call re-resolves. */
+export function resetRaChartLoader(): void {
+  pending = null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cordova-plugin-ra-chart",
-  "version": "1.0.0",
+  "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",
@@ -8,12 +8,7 @@
   "author": "RemoteApps",
   "cordova": {
     "id": "cordova-plugin-ra-chart",
-    "platforms": [
-      "android",
-      "ios",
-      "browser",
-      "electron"
-    ]
+    "platforms": []
   },
   "keywords": [
     "ecosystem:cordova",
@@ -38,17 +33,10 @@
     "plugin.xml",
     "README.md"
   ],
-  "engines": {
-    "cordovaDependencies": {
-      "1.0.0": {
-        "cordova": ">=9.0.0"
-      }
-    }
-  },
   "dependencies": {},
   "peerDependencies": {},
   "sideEffects": [
     "www/ra-chart.js",
     "www/ra-chart.css"
   ]
-}
+}

package/plugin.xml

@@ -3,14 +3,19 @@
   raChart Cordova plugin descriptor.
 
   Install:  cordova plugin add ./ra-chart-cordova
-  After install, `window.RaChart` is available on deviceready.
+  After install, `window.RaChart` is available once deviceready fires.
 
-  This is a pure web-asset plugin: it ships JS + CSS only, so it works on
-  every Cordova platform (and in the browser) with no native compilation.
+  This is a pure web-asset plugin: JS + CSS only, no native code and no
+  compilation, so it installs on every Cordova platform. Deliberately declares
+  no <engine> requirement and no <platform> filters — adding either only makes
+  the install fail on setups the plugin actually supports fine.
+
+  Cordova does not inject stylesheets. Link the CSS yourself in index.html:
+    <link rel="stylesheet" href="plugins/cordova-plugin-ra-chart/www/ra-chart.css">
 -->
 <plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
         id="cordova-plugin-ra-chart"
-        version="1.0.0">
+        version="1.0.1">
 
   <name>raChart</name>
   <description>
@@ -21,25 +26,27 @@
   <keywords>cordova,ionic,chart,charts,svg,graph,dashboard,mobile,offline</keywords>
   <author>RemoteApps</author>
 
-  <engines>
-    <engine name="cordova" version=">=9.0.0" />
-  </engines>
-
   <!-- window.RaChart -->
   <js-module src="www/ra-chart.js" name="RaChart">
     <clobbers target="RaChart" />
   </js-module>
 
-  <!--
-    Cordova does not inject stylesheets, so link the CSS yourself in index.html:
-      <link rel="stylesheet" href="plugins/cordova-plugin-ra-chart/www/ra-chart.css">
-    Ionic apps normally add it to angular.json "styles" instead.
-  -->
+  <!-- copied to www/css/ra-chart.css in the built app -->
   <asset src="www/ra-chart.css" target="css/ra-chart.css" />
 
-  <platform name="android" />
-  <platform name="ios" />
-  <platform name="browser" />
-  <platform name="electron" />
+  <info>
+raChart installed.
+
+Add the stylesheet to your index.html:
+  &lt;link rel="stylesheet" href="css/ra-chart.css"&gt;
+
+Then, after deviceready:
+  new RaChart('#myChart', { type: 'column', category: 'month',
+    series: [{ name: 'Revenue', field: 'revenue' }], data: rows });
+
+Ionic/Angular apps do not need this plugin — copy www/ra-chart.js and
+www/ra-chart.css into src/assets/ra-chart/ and use the &lt;ra-chart&gt;
+component in ionic/ instead. See README.md.
+  </info>
 
 </plugin>

package/www/ra-chart.js

@@ -1,5 +1,5 @@
 /*!
- * raChart Cordova v1.0.0 — mobile SVG chart engine
+ * raChart Cordova v1.0.1 — mobile SVG chart engine
  * RemoteApps UI Components
  *
  * Zero dependencies. No jQuery, no chart library, no build step.
@@ -20,7 +20,7 @@
   "use strict";
 
   var NS = "http://www.w3.org/2000/svg";
-  var VERSION = "1.0.0";
+  var VERSION = "1.0.1";
 
   /* ============================================================
      Palettes — CVD-validated order, do not shuffle
@@ -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;