cordova-plugin-ra-chart 1.0.2 → 1.0.4

package/README.md

@@ -82,6 +82,14 @@ Add the stylesheet to `angular.json`:
 ]
 ```
 
+> **`ra-chart.css` must be global — never a component's `styleUrls`.** Angular's
+> view encapsulation scopes those rules to `[_ngcontent-*]`, which never matches
+> the legend, tooltip and zoom bar because the engine creates them at runtime.
+> The classic symptom is a legend that reads `RevenueTarget` with no colour
+> swatches. Since v1.0.3 the engine injects its own structural styles so this
+> renders correctly regardless, and `ra-chart.css` is optional — it only supplies
+> theming. Load it globally to theme; skip it entirely and charts still look right.
+
 The component lazy-loads `ra-chart.js` from `assets/ra-chart/ra-chart.js` on first use. To bundle it eagerly instead, add it to `angular.json` → `"scripts"`; the loader will detect `window.RaChart` and skip the fetch.
 
 To load it from somewhere else:
@@ -104,6 +112,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 +210,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 +598,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. Mutating the array instead of replacing it.** The component is `OnPush`, so `push()` is invisible to it:
+**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.
+
+**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;`
 
@@ -586,6 +629,8 @@ To silence the diagnostics in production: `RaChart.warnings = false;`
 
 **Labels are cut off** — increase `height`, or shorten category labels. Horizontal `bar` and `gantt` cap the label gutter at about a third of the width.
 
+**Legend reads "RevenueTarget" with no colour swatches** — the legend HTML is unstyled, meaning `ra-chart.css` did not reach it. Almost always because it was added to a component's `styleUrls` instead of `angular.json` → `styles`; view encapsulation scopes it to `[_ngcontent-*]` and the runtime-created legend has no such attribute. Fixed by default in v1.0.3 (the engine injects its own structural CSS), so updating the engine resolves it. To theme, move `ra-chart.css` to the global styles array.
+
 **Tooltip is clipped inside `ion-card`** — the tooltip is absolutely positioned inside the chart element; give the card content enough padding, or set `sheetTooltip: true` to dock it.
 
 **No haptics on device** — install `@capacitor/haptics`, or rely on the `navigator.vibrate` fallback (Android only; iOS Safari does not support it).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cordova-plugin-ra-chart",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "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.3">
 
   <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.3 — 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.3";
 
   /* ============================================================
      Palettes — CVD-validated order, do not shuffle
@@ -351,6 +351,60 @@
     gauge: "gauge", heatmap: "heat"
   };
 
+  /* ============================================================
+     Base stylesheet
+
+     The SVG gets its colours from inline attributes, but the legend, tooltip
+     and zoom bar are real HTML and would collapse into unstyled inline text
+     without CSS — the classic "legend reads RevenueTarget" symptom. Angular
+     makes that easy to hit: ra-chart.css dropped into a component's styleUrls
+     is scoped to [_ngcontent-*], which never matches nodes the engine creates
+     at runtime.
+
+     So the structural rules ship in JS and are injected once, at the TOP of
+     <head>, leaving ra-chart.css (and any app CSS) free to override them.
+     Colours defer to the same custom properties, with fallbacks.
+     ============================================================ */
+
+  var BASE_STYLE_ID = "ra-chart-base-styles";
+  var BASE_CSS = [
+    'ra-chart{display:block;position:relative;width:100%}',
+    '.ra-chart{position:relative;display:block;width:100%;font-family:system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;-webkit-tap-highlight-color:transparent}',
+    '.ra-chart__stage{position:relative;width:100%;overflow:hidden}',
+    '.ra-chart__stage svg{display:block;width:100%;height:100%;overflow:visible;user-select:none;-webkit-user-select:none}',
+    '.ra-chart .ra-hit{cursor:pointer}',
+    '.ra-chart__legend{display:flex;flex-wrap:wrap;justify-content:center;align-items:center;gap:4px 14px;padding-top:10px;font-size:13px;font-weight:700;line-height:1.4;color:var(--ra-chart-body,#4b5563)}',
+    '.ra-chart__legend-item{display:inline-flex;align-items:center;gap:7px;padding:7px 2px;cursor:pointer;user-select:none;-webkit-user-select:none;transition:opacity .18s}',
+    '.ra-chart__legend-item.is-off{opacity:.38}',
+    '.ra-chart__legend-item.is-off .ra-chart__legend-label{text-decoration:line-through}',
+    '.ra-chart__legend-swatch{display:inline-block;width:11px;height:11px;border-radius:4px;flex:0 0 auto}',
+    '.ra-chart__legend-value{color:var(--ra-chart-muted,#9ca3af);font-weight:600}',
+    '.ra-chart__tip{position:absolute;z-index:5;pointer-events:none;max-width:88%;background:var(--ra-chart-tip-bg,#1f2937);color:var(--ra-chart-tip-text,#f9fafb);font-size:12px;font-weight:600;line-height:1.5;border-radius:10px;padding:8px 12px;box-shadow:0 6px 20px rgba(15,23,42,.28);opacity:0;transform:translate(-50%,-112%) scale(.96);transition:opacity .15s,transform .15s;white-space:nowrap}',
+    '.ra-chart__tip.is-on{opacity:1;transform:translate(-50%,-112%) scale(1)}',
+    '.ra-chart__tip--sheet{left:50%!important;top:auto!important;bottom:6px;transform:translate(-50%,8px);white-space:normal;text-align:center;padding:10px 16px;border-radius:12px;font-size:13px}',
+    '.ra-chart__tip--sheet.is-on{transform:translate(-50%,0)}',
+    '.ra-chart__tip-dot{display:inline-block;width:8px;height:8px;border-radius:50%;margin-right:6px}',
+    '.ra-chart__tip-cat{display:block;color:var(--ra-chart-tip-muted,#9ca3af);font-weight:500;margin-bottom:2px}',
+    '.ra-chart__tip-muted{color:var(--ra-chart-tip-muted,#9ca3af);font-weight:500}',
+    '.ra-chart__zoom{padding:6px 0 14px;touch-action:none}',
+    '.ra-chart__zoom-track{position:relative;height:8px;background:var(--ra-chart-zoom-track,#eceff3);border-radius:999px;margin:0 13px}',
+    '.ra-chart__zoom-sel{position:absolute;top:0;height:100%;background:var(--ra-chart-zoom-sel,#c7c2ee);border-radius:999px;cursor:grab}',
+    '.ra-chart__zoom-handle{position:absolute;top:50%;width:26px;height:26px;border-radius:50%;background:var(--ra-chart-zoom-handle,#fff);border:2px solid var(--ra-chart-zoom-handle-border,#534ab7);box-shadow:0 1px 5px rgba(15,23,42,.28);transform:translate(-50%,-50%);cursor:ew-resize;touch-action:none}',
+    '@media (pointer:fine){.ra-chart__zoom-handle{width:18px;height:18px}}'
+  ].join("");
+
+  function ensureBaseStyles() {
+    if (typeof document === "undefined") return;
+    if (document.getElementById(BASE_STYLE_ID)) return;
+    var head = document.head || document.getElementsByTagName("head")[0];
+    if (!head) return;
+    var st = document.createElement("style");
+    st.id = BASE_STYLE_ID;
+    st.appendChild(document.createTextNode(BASE_CSS));
+    // first in <head> so ra-chart.css and app styles win on equal specificity
+    head.insertBefore(st, head.firstChild);
+  }
+
   var UID = 0;
 
   /* ============================================================
@@ -362,6 +416,7 @@
     if (typeof host === "string") host = document.querySelector(host);
     if (!host) throw new Error("raChart: host element not found");
 
+    ensureBaseStyles();
     this.el = host;
     this.uid = ++UID;
     this.opts = merge(merge({}, DEFAULTS), options || {});
@@ -2855,6 +2910,176 @@
   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;
+  /** Inject the built-in structural stylesheet (called automatically). */
+  RaChart.injectStyles = ensureBaseStyles;
+
+  // 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 ($) {