cordova-plugin-ra-chart 1.0.2 → 1.0.3

package/README.md

@@ -104,6 +104,31 @@ bootstrapApplication(AppComponent, {
 <script src="ra-chart.js"></script>
 ```
 
+### The `<ra-chart>` custom element
+
+Loading `ra-chart.js` registers `<ra-chart>` as a real custom element, so the tag
+works with no framework at all:
+
+```html
+<ra-chart type="column" category="month"></ra-chart>
+<script>
+  document.querySelector('ra-chart').data = rows;
+  document.querySelector('ra-chart').series = [{ name: 'Revenue', field: 'revenue' }];
+</script>
+```
+
+Scalar options are attributes (`type`, `category`, `height`, `zoom`, `stacked`,
+`smooth`, `semi`, `depth`, `min`, `max`, `x-field`, `size-field`, …; dash-case maps
+to camelCase). Object options are properties (`data`, `series`, `colors`, `bands`,
+`fields`, `animation`).
+
+This also acts as a safety net in Angular: if `RaChartComponent` is missing from
+`imports`, the element still renders rather than failing silently. When the Angular
+component *is* present it renders its own child first and the custom element stands
+down, so the two never double-render. Disable with
+`RaChart.defineElement = function () { return false; }` before load, or register
+under a different tag with `RaChart.defineElement('my-chart')`.
+
 ---
 
 ## Quick start
@@ -177,6 +202,14 @@ export class SalesPage {
 </ra-chart>
 ```
 
+> **`imports: [RaChartComponent]` is required.** Leave it out and Angular treats
+> `<ra-chart>` as an unknown element. Ionic projects usually include
+> `CUSTOM_ELEMENTS_SCHEMA`, which suppresses the error that would tell you —
+> so the tag appears in the DOM, `@Output()`s never fire, and you get a blank
+> box with a clean console. Since v1.0.2 the built-in custom element renders a
+> chart anyway (see below), but you lose the Angular outputs and inputs typing,
+> so add the import.
+
 ### NgModule apps
 
 ```ts
@@ -557,20 +590,22 @@ Your rows have: month, total. Check the `field`/`category` names against your da
 
 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.
+**2. `RaChartComponent` missing from `imports`** — the single most common cause in Ionic. Symptoms: the tag is in the DOM, no console error, and you had to add `display: block` yourself to see it. That last one is the giveaway — the component sets `:host { display: block }`, so if you needed to add it manually, the component was never attached. Add it to `imports: []`. Since v1.0.2 the custom element renders anyway and logs an actionable error, but the Angular `@Input()`/`@Output()` API only works with the import.
+
+**3. 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:
+**4. 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. 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. 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.
+**7. 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;`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cordova-plugin-ra-chart",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "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",

package/plugin.xml

@@ -15,7 +15,7 @@
 -->
 <plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
         id="cordova-plugin-ra-chart"
-        version="1.0.1">
+        version="1.0.2">
 
   <name>raChart</name>
   <description>

package/www/ra-chart.css

@@ -7,6 +7,14 @@
  * reads these same variables at build time for SVG fills.
  */
 
+/* The custom element / Angular host. Without this the tag is inline and
+   collapses to zero height, which reads as "the chart did not render". */
+ra-chart {
+  display: block;
+  position: relative;
+  width: 100%;
+}
+
 .ra-chart {
   /* ---- palette hooks (override in your theme) ---- */
   --ra-chart-scheme: light;

package/www/ra-chart.js

@@ -1,5 +1,5 @@
 /*!
- * raChart Cordova v1.0.1 — mobile SVG chart engine
+ * raChart Cordova v1.0.2 — 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.1";
+  var VERSION = "1.0.2";
 
   /* ============================================================
      Palettes — CVD-validated order, do not shuffle
@@ -2855,6 +2855,174 @@
   RaChart.types = Object.keys(KINDS);
   RaChart.create = function (host, options) { return new RaChart(host, options); };
 
+  /* ============================================================
+     <ra-chart> custom element
+
+     Makes the tag work on its own, so a chart still renders when the Angular
+     component was never instantiated — the silent-blank-chart case, which
+     `CUSTOM_ELEMENTS_SCHEMA` hides by suppressing Angular's unknown-element
+     error. Angular property bindings ([data]="rows") land on the element as
+     plain DOM properties, which the accessors below pick up.
+
+     If the Angular component IS attached it renders its own child div first;
+     the element sees that and stands down, so the two never double-render.
+     ============================================================ */
+
+  var EL_ATTRS = [
+    "type", "category", "height", "min", "max", "depth",
+    "x-field", "size-field", "up-color", "down-color", "tooltip-hold",
+    "zoom", "pinch-zoom", "stacked", "full-stacked", "smooth", "stepped",
+    "semi", "legend", "haptics", "sheet-tooltip"
+  ];
+  var EL_PROPS = ["data", "series", "colors", "bands", "fields", "animation"];
+
+  function camel(s) {
+    return s.replace(/-([a-z])/g, function (_, c) { return c.toUpperCase(); });
+  }
+
+  function coerceAttr(v) {
+    if (v === null) return undefined;
+    if (v === "" || v === "true") return true;
+    if (v === "false") return false;
+    if (v === "auto") return "auto";
+    var n = parseFloat(v);
+    return (!isNaN(n) && String(n) === String(v).trim()) ? n : v;
+  }
+
+  function defineElement(tag) {
+    tag = tag || "ra-chart";
+    if (typeof customElements === "undefined" ||
+      typeof Reflect === "undefined" || !Reflect.construct) return false;
+    if (customElements.get(tag)) return false;
+
+    // ES5-compatible subclassing so the file still parses on old WebViews;
+    // the body only ever runs where custom elements exist.
+    function RaChartElement() {
+      return Reflect.construct(HTMLElement, [], Object.getPrototypeOf(this).constructor);
+    }
+    RaChartElement.prototype = Object.create(HTMLElement.prototype);
+    RaChartElement.prototype.constructor = RaChartElement;
+    Object.setPrototypeOf(RaChartElement, HTMLElement);
+
+    Object.defineProperty(RaChartElement, "observedAttributes", {
+      get: function () { return EL_ATTRS; }
+    });
+
+    // object-valued inputs arrive as properties, not attributes
+    EL_PROPS.forEach(function (name) {
+      Object.defineProperty(RaChartElement.prototype, name, {
+        configurable: true,
+        get: function () { return this["_" + name]; },
+        set: function (v) {
+          this["_" + name] = v;
+          this._raSchedule();
+        }
+      });
+    });
+
+    RaChartElement.prototype.connectedCallback = function () {
+      this._raSchedule();
+    };
+
+    RaChartElement.prototype.disconnectedCallback = function () {
+      if (this._raChart) { this._raChart.destroy(); this._raChart = null; }
+      this._raMount = null;
+    };
+
+    RaChartElement.prototype.attributeChangedCallback = function () {
+      this._raSchedule();
+    };
+
+    /** Coalesce the burst of attribute/property writes into one render. */
+    RaChartElement.prototype._raSchedule = function () {
+      var self = this;
+      if (this._raPending) return;
+      this._raPending = true;
+      var run = function () {
+        self._raPending = false;
+        self._raRender();
+      };
+      // a macrotask lets a framework finish rendering its own children first
+      if (typeof setTimeout === "function") setTimeout(run, 0);
+      else run();
+    };
+
+    RaChartElement.prototype._raOptions = function () {
+      var o = {};
+      for (var i = 0; i < EL_ATTRS.length; i++) {
+        var a = EL_ATTRS[i];
+        if (!this.hasAttribute(a)) continue;
+        var v = coerceAttr(this.getAttribute(a));
+        if (v !== undefined) o[camel(a)] = v;
+      }
+      for (var j = 0; j < EL_PROPS.length; j++) {
+        var p = EL_PROPS[j];
+        if (this["_" + p] !== undefined) o[p] = this["_" + p];
+      }
+      return o;
+    };
+
+    RaChartElement.prototype._raRender = function () {
+      if (!this.isConnected) return;
+
+      // Stand down if a framework component owns this element: it renders its
+      // own .ra-chart child and drives the engine itself.
+      var owned = this.querySelector("div.ra-chart");
+      if (owned && owned !== this._raMount) {
+        this._raClaimed = true;
+        return;
+      }
+      if (this._raClaimed) return;
+
+      var o = this._raOptions();
+      var rows = o.data;
+      if (!rows || !rows.length) {
+        // Nothing to draw yet. Only complain once the page has settled, so an
+        // async load in flight does not produce a false alarm.
+        this._raWarnEmpty();
+        return;
+      }
+
+      if (!this._raMount) {
+        this._raMount = document.createElement("div");
+        this._raMount.className = "ra-chart";
+        this.appendChild(this._raMount);
+      }
+      if (this._raChart) this._raChart.destroy();
+      this._raChart = new RaChart(this._raMount, o);
+      this._raWarned = true;   // it rendered; nothing to report
+    };
+
+    RaChartElement.prototype._raWarnEmpty = function () {
+      var self = this;
+      if (this._raWarned || this._raWarnTimer) return;
+      this._raWarnTimer = setTimeout(function () {
+        self._raWarnTimer = null;
+        if (self._raChart || self._raClaimed || self._raWarned) return;
+        if (!RaChart.warnings) return;
+        self._raWarned = true;
+        console.error(
+          "[raChart] <ra-chart> is in the DOM but has no data, so nothing was drawn.\n" +
+          "  • Angular/Ionic: add RaChartComponent to your component's `imports: []` " +
+          "(or RaChartModule for NgModule apps). Without it, CUSTOM_ELEMENTS_SCHEMA " +
+          "silently swallows the unknown-element error and [data] never reaches the chart.\n" +
+          "  • Plain HTML: set the data property, e.g. " +
+          "document.querySelector('ra-chart').data = rows;",
+          self
+        );
+      }, 3000);
+    };
+
+    customElements.define(tag, RaChartElement);
+    return true;
+  }
+
+  RaChart.defineElement = defineElement;
+
+  // Auto-register so the tag works with no setup. Harmless when a framework
+  // component already owns the element — the stand-down guard handles it.
+  try { defineElement("ra-chart"); } catch (e) { /* non-fatal */ }
+
   /** Optional jQuery bridge — only if jQuery happens to be present. */
   if (typeof window !== "undefined" && window.jQuery) {
     (function ($) {