cordova-plugin-ra-chart 1.0.0

package/README.md

@@ -0,0 +1,543 @@
+# raChart Cordova
+
+A dependency-free SVG chart engine for **Cordova** and **Ionic**. 21 chart types, built for touch: tap to inspect, drag to scrub, pinch to zoom, with haptics, dark mode and offline rendering.
+
+No jQuery. No chart library. No native code. No build step. One 60 KB JS file and one CSS file.
+
+```
+ra-chart-cordova/
+├── plugin.xml                      Cordova plugin descriptor
+├── package.json
+├── www/
+│   ├── ra-chart.js                 the engine (window.RaChart)
+│   └── ra-chart.css                styles + theme variables
+├── types/index.d.ts                TypeScript definitions
+├── ionic/                          Angular wrapper
+│   ├── ra-chart.component.ts/.html  <ra-chart>
+│   ├── ra-chart.module.ts          NgModule for non-standalone apps
+│   ├── ra-chart.loader.ts          lazy script loader
+│   ├── ra-chart.types.ts
+│   └── index.ts
+└── demo/
+    ├── index.html                  plain mobile demo (open in a browser)
+    └── dashboard.page.ts/.html     Ionic page example
+```
+
+---
+
+## Table of contents
+
+1. [Install](#install)
+2. [Quick start](#quick-start)
+3. [Ionic / Angular usage](#ionic--angular-usage)
+4. [Chart types](#chart-types)
+5. [Data shapes](#data-shapes)
+6. [Options](#options)
+7. [Methods](#methods)
+8. [Events](#events)
+9. [Mobile behaviour](#mobile-behaviour)
+10. [Theming and dark mode](#theming-and-dark-mode)
+11. [Recipes](#recipes)
+12. [Troubleshooting](#troubleshooting)
+
+---
+
+## Install
+
+### Option A — Cordova plugin
+
+```bash
+cordova plugin add ./ra-chart-cordova
+```
+
+`window.RaChart` is available once `deviceready` fires. Cordova does not inject CSS, so link it yourself in `index.html`:
+
+```html
+<link rel="stylesheet" href="plugins/cordova-plugin-ra-chart/www/ra-chart.css">
+```
+
+### Option B — Ionic app (recommended)
+
+Copy the two runtime files into your assets and the wrapper into your source tree:
+
+```
+src/assets/ra-chart/ra-chart.js      ← from www/
+src/assets/ra-chart/ra-chart.css     ← from www/
+src/app/shared/ra-chart/             ← the whole ionic/ folder
+```
+
+Add the stylesheet to `angular.json`:
+
+```json
+"styles": [
+  "src/theme/variables.scss",
+  "src/global.scss",
+  "src/assets/ra-chart/ra-chart.css"
+]
+```
+
+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:
+
+```ts
+// main.ts
+import { RA_CHART_SCRIPT_URL } from './app/shared/ra-chart';
+
+bootstrapApplication(AppComponent, {
+  providers: [
+    { provide: RA_CHART_SCRIPT_URL, useValue: 'assets/vendor/ra-chart.js' }
+  ]
+});
+```
+
+### Option C — plain browser
+
+```html
+<link rel="stylesheet" href="ra-chart.css">
+<script src="ra-chart.js"></script>
+```
+
+---
+
+## Quick start
+
+```html
+<div id="sales"></div>
+```
+
+```js
+var chart = new RaChart('#sales', {
+  type: 'column',
+  category: 'month',
+  series: [
+    { name: 'Revenue', field: 'revenue' },
+    { name: 'Target',  field: 'target'  }
+  ],
+  data: [
+    { month: 'Jan', revenue: 42, target: 38 },
+    { month: 'Feb', revenue: 55, target: 45 }
+  ],
+  height: 240
+});
+
+chart.setData(newRows);   // animates to the new values
+chart.destroy();          // always clean up
+```
+
+In Cordova, wait for the platform first:
+
+```js
+document.addEventListener('deviceready', function () {
+  new RaChart('#sales', { /* ... */ });
+});
+```
+
+---
+
+## Ionic / Angular usage
+
+### Standalone component (Angular 16+)
+
+```ts
+import { Component } from '@angular/core';
+import { RaChartComponent } from '../shared/ra-chart';
+import type { RaSeries, RaSelectEvent } from '../shared/ra-chart';
+
+@Component({
+  selector: 'app-sales',
+  standalone: true,
+  imports: [RaChartComponent],
+  templateUrl: './sales.page.html'
+})
+export class SalesPage {
+  series: RaSeries[] = [{ name: 'Revenue', field: 'revenue' }];
+  rows = [{ month: 'Jan', revenue: 42 }, { month: 'Feb', revenue: 55 }];
+
+  onSelect(e: RaSelectEvent) {
+    console.log(e.category, e.value);
+  }
+}
+```
+
+```html
+<ra-chart type="column"
+          category="month"
+          [series]="series"
+          [data]="rows"
+          [zoom]="true"
+          [height]="240"
+          (select)="onSelect($event)">
+</ra-chart>
+```
+
+### NgModule apps
+
+```ts
+import { RaChartModule } from './shared/ra-chart';
+
+@NgModule({
+  imports: [RaChartModule]              // or RaChartModule.forRoot({ scriptUrl: '...' })
+})
+export class SalesPageModule {}
+```
+
+### Calling methods
+
+```ts
+@ViewChild('chart') chart?: RaChartComponent;
+```
+
+```html
+<ra-chart #chart ...></ra-chart>
+```
+
+```ts
+this.chart?.replay();
+this.chart?.zoomTo(0.5, 1);
+this.chart?.resetZoom();
+const svg = this.chart?.toSVG();
+this.chart?.instance?.setData(rows);   // raw engine handle
+```
+
+### Change detection
+
+The component is `OnPush` and the engine runs **outside** Angular's zone, so touch scrubbing and animations never trigger change detection. Replace arrays instead of mutating them so `ngOnChanges` fires:
+
+```ts
+this.rows = [...this.rows, newRow];    // ✅ detected
+this.rows.push(newRow);                // ❌ ignored
+```
+
+A change to `data` alone animates the values in place. Changing any other input rebuilds the chart.
+
+---
+
+## Chart types
+
+| `type` | Shape | Notes |
+|---|---|---|
+| `column` | vertical bars | `stacked`, `fullStacked`, `depth` |
+| `bar` | horizontal bars | same options |
+| `line` | line | `smooth`, `stepped` |
+| `area` | filled line | `smooth`, `stepped` |
+| `lollipop` | stem + dot | good for sparse mobile series |
+| `pie` | pie | `semi`, `depth` |
+| `donut` | donut with live centre total | `semi`, `depth` |
+| `radar` | multi-axis polygon | |
+| `treemap` | squarified hierarchy | |
+| `sankey` | flow diagram | uses `from`/`to`/`value` rows |
+| `wordcloud` | spiral-packed words | |
+| `venn` | up to 3 sets | |
+| `candlestick` | OHLC | `upColor`, `downColor`, `zoom` |
+| `timeline` | events on an axis | accepts dates |
+| `gantt` | task bars with progress | accepts dates |
+| `scatter` | numeric X/Y | `xField` |
+| `bubble` | X/Y + size | `xField`, `sizeField` |
+| `funnel` | conversion stages | |
+| `pyramid` | proportional triangle | |
+| `gauge` | needle + bands | `max`, `bands` |
+| `heatmap` | matrix on a sequential ramp | |
+
+`RaChart.types` returns this list at runtime.
+
+---
+
+## Data shapes
+
+Everything takes an **array of plain objects**. `category` names the label field; `series` maps display names to value fields.
+
+**Most types** — `column`, `bar`, `line`, `area`, `lollipop`, `radar`, `heatmap`:
+
+```js
+category: 'month',
+series: [{ name: 'Revenue', field: 'revenue' }, { name: 'Cost', field: 'cost' }],
+data: [{ month: 'Jan', revenue: 42, cost: 30 }]
+```
+
+**Single-value types** — `pie`, `donut`, `treemap`, `wordcloud`, `venn`, `funnel`, `pyramid`, `gauge` (first series only):
+
+```js
+category: 'source',
+series: [{ name: 'Share', field: 'value' }],
+data: [{ source: 'Direct', value: 42 }]
+```
+
+**Candlestick:**
+
+```js
+category: 'day',
+data: [{ day: '1', open: 102, high: 108, low: 100, close: 106 }]
+// rename columns: fields: { open: 'o', high: 'h', low: 'l', close: 'c' }
+```
+
+**Gantt** — dates or numbers, `progress` is optional (0–100):
+
+```js
+category: 'task',
+data: [{ task: 'Design', start: '2026-01-20', end: '2026-03-01', progress: 100 }]
+// fields: { start: 'from', end: 'until', progress: 'pct' }
+```
+
+**Timeline:**
+
+```js
+category: 'milestone',
+series: [{ name: 'Date', field: 'date' }],
+data: [{ milestone: 'Launch', date: '2026-07-01' }]
+```
+
+**Sankey** — no `category`/`series`, just links:
+
+```js
+data: [{ from: 'Solar', to: 'Grid', value: 30 }]
+// fields: { from: 'src', to: 'dst', value: 'amount' }
+```
+
+**Scatter / bubble:**
+
+```js
+xField: 'price', sizeField: 'reach',
+series: [{ name: 'Brand A', field: 'rating' }],
+data: [{ price: 12, rating: 3.8, reach: 20 }]
+```
+
+---
+
+## Options
+
+### Data
+
+| Option | Default | Description |
+|---|---|---|
+| `type` | `'column'` | Any type from the table above |
+| `data` | `[]` | Array of plain rows |
+| `category` | `'category'` | Row field used for labels |
+| `series` | `[]` | `[{ name, field }]` |
+| `colors` | `null` | Hex array; `null` picks the theme-aware palette |
+| `fields` | `null` | Rename columns per type (see above) |
+| `xField` / `sizeField` | `'x'` / `'size'` | Scatter and bubble |
+
+### Shape
+
+| Option | Default | Description |
+|---|---|---|
+| `stacked` | `false` | Stack column/bar series |
+| `fullStacked` | `false` | 100% stacked; tooltips switch to % |
+| `smooth` | `false` | Curved line/area |
+| `stepped` | `false` | Stepped line/area |
+| `semi` | `false` | Half-circle pie/donut |
+| `depth` | `0` | 3D extrusion px (column, bar, pie, donut) |
+
+### Scale
+
+| Option | Default | Description |
+|---|---|---|
+| `min` | `0` | Value-axis minimum |
+| `max` | `null` | Gauge maximum |
+| `bands` | `null` | Gauge zones `[{ from, to, color }]` |
+| `upColor` / `downColor` | green / red | Candlestick bull/bear |
+
+### Interaction
+
+| Option | Default | Description |
+|---|---|---|
+| `zoom` | `false` | Range slider (XY types + candlestick) |
+| `pinchZoom` | `true` | Pinch and pan when `zoom` is on |
+| `legend` | `true` | Tappable; auto-hidden for single-series XY |
+| `haptics` | `true` | Vibrate on touch-select |
+| `sheetTooltip` | `'auto'` | Dock tooltip to bottom; auto = touch device under 480px |
+| `tooltipHold` | `2600` | ms the tooltip stays after finger lift; `0` = until next tap |
+
+### Presentation
+
+| Option | Default | Description |
+|---|---|---|
+| `height` | `260` | Plot height px; legend and zoom bar sit outside it |
+| `animation` | `{duration: 800, delay: 70}` | Entrance timing; data changes morph over 550 ms |
+
+---
+
+## Methods
+
+```js
+chart.setData(rows)              // morph to new values (rebuilds if the shape changed)
+chart.setType('donut')           // switch type; resets zoom and hidden series
+chart.update({ depth: 12 })      // merge options and rebuild
+chart.replay()                   // replay the entrance animation
+chart.resize()                   // re-measure (automatic on rotate/resize)
+
+chart.zoomTo(0.25, 0.75)         // fraction window
+chart.zoomTo(5, 10)              // integers = data index range
+chart.resetZoom()
+chart.getZoom()                  // { from, to, startIndex, endIndex }
+
+chart.toggleSeries(1)            // hide/show series or slice by index
+chart.toggleSeries(1, true)      // explicitly hide
+
+chart.toSVG()                    // SVG string, background included — for share/export
+chart.destroy()                  // remove listeners and observers
+```
+
+Statics: `RaChart.version`, `RaChart.defaults`, `RaChart.palette`, `RaChart.paletteDark`, `RaChart.types`, `RaChart.create(el, opts)`.
+
+---
+
+## Events
+
+The engine dispatches **DOM CustomEvents** on the host element. The Angular component re-emits them as `@Output()`s.
+
+| DOM event | Angular output | Detail |
+|---|---|---|
+| `raChartReady` | `(ready)` | The chart instance |
+| `raChartSelect` | `(select)` | The tapped mark |
+| `raChartZoom` | `(zoomChange)` | `{ from, to, startIndex, endIndex }` |
+| `raChartToggle` | `(toggle)` | `{ index, name, hidden }` |
+
+```js
+document.getElementById('sales')
+  .addEventListener('raChartSelect', function (e) {
+    console.log(e.detail.category, e.detail.value);
+  });
+```
+
+`raChartSelect` detail varies by type — `category`/`series`/`value` for most, plus `ohlc` for candlestick, `start`/`end`/`progress` for gantt, `x`/`y`/`size` for scatter and bubble, `kind`/`from`/`to` for sankey. `row` carries the original data object.
+
+---
+
+## Mobile behaviour
+
+**Touch.** Tap any mark to open its tooltip; drag without lifting to scrub across marks, each one snapping the tooltip along. The tooltip stays `tooltipHold` ms after you lift so it is readable, then fades. Tapping empty space dismisses it.
+
+**Pinch and pan.** With `zoom: true`, two fingers on the plot zoom around the pinch midpoint and one finger pans once you are zoomed in. Panning only takes over the gesture after clearly horizontal movement, so vertical page scrolling still works. The range slider stays in sync.
+
+**Hit targets.** On coarse pointers, dots and points get invisible finger-sized hit rings, thin candlesticks get full-band hit columns, zoom handles grow to 26 px, and legend rows carry 44 px of padded height.
+
+**Haptics.** Selecting a mark or toggling a legend entry fires a light impact through Capacitor Haptics when available, falling back to `navigator.vibrate`, and silently doing nothing otherwise. Disable with `haptics: false`.
+
+**Bottom-sheet tooltips.** Under 480 px on touch devices the tooltip docks to the bottom edge instead of floating, so your thumb never covers the value.
+
+**Rotation.** A `ResizeObserver` on the host redraws after orientation changes, debounced 160 ms, without re-running entrance animations.
+
+**Backgrounding.** Browsers freeze `requestAnimationFrame` while a page is hidden, which would otherwise leave a chart stuck mid-animation when the user switches apps. Charts built while hidden skip straight to their final frame, and a tween interrupted by backgrounding settles on its last frame instead of resuming half-drawn.
+
+**Reduced motion.** With `prefers-reduced-motion: reduce`, animations resolve to their final frame immediately.
+
+**Offline.** Everything renders locally — no network, no fonts, no tiles.
+
+---
+
+## Theming and dark mode
+
+Every colour is a CSS custom property, and the engine reads the same variables when it paints SVG. Restyle from your Ionic theme file without touching JS:
+
+```css
+:root {
+  --ra-chart-surface: #ffffff;
+  --ra-chart-text:    #1f2937;
+  --ra-chart-label:   #898781;
+  --ra-chart-grid:    #e1e0d9;
+  --ra-chart-zoom-handle-border: #534ab7;
+}
+```
+
+Dark mode activates automatically from `prefers-color-scheme`, Ionic 8's `.ion-palette-dark`, or a legacy `body.dark`. The series palette swaps to steps validated against a dark surface — it is a re-stepped palette, not an inverted one.
+
+Force a mode per chart with a class:
+
+```html
+<div class="ra-chart ra-chart--light"></div>
+<div class="ra-chart ra-chart--dark"></div>
+```
+
+The default 8-colour palette is ordered so adjacent series stay distinguishable for colourblind viewers. If you pass your own `colors`, keep that in mind. Charts also carry non-colour cues — legends, direct labels, tooltips.
+
+---
+
+## Recipes
+
+**Live data**
+
+```ts
+this.sub = interval(5000).subscribe(() => {
+  this.rows = [...fetchLatest()];       // new array reference
+});
+```
+
+**Switch type from an ion-segment**
+
+```html
+<ion-segment [value]="type" (ionChange)="type = $any($event.detail.value)">
+  <ion-segment-button value="column"><ion-label>Bars</ion-label></ion-segment-button>
+  <ion-segment-button value="donut"><ion-label>Donut</ion-label></ion-segment-button>
+</ion-segment>
+
+<ra-chart [type]="type" ...></ra-chart>
+```
+
+**Share a chart as an image**
+
+```ts
+import { Share } from '@capacitor/share';
+import { Filesystem, Directory } from '@capacitor/filesystem';
+
+async share() {
+  const svg = this.chart!.toSVG();
+  const file = await Filesystem.writeFile({
+    path: 'chart.svg',
+    data: btoa(unescape(encodeURIComponent(svg))),
+    directory: Directory.Cache
+  });
+  await Share.share({ title: 'Chart', url: file.uri });
+}
+```
+
+**Brand colours**
+
+```ts
+colors = ['#534ab7', '#2196f3', '#f0334b', '#eda100'];
+```
+
+```html
+<ra-chart [colors]="colors" ...></ra-chart>
+```
+
+**Long series on a small screen** — show a window and let the user pinch:
+
+```ts
+ready(chart: RaChartInstance) {
+  chart.zoomTo(Math.max(0, this.rows.length - 12), this.rows.length);
+}
+```
+
+```html
+<ra-chart [zoom]="true" (ready)="ready($event)" ...></ra-chart>
+```
+
+---
+
+## 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.
+
+**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.
+
+**Nothing happens when data changes** — you mutated the array. Assign a new reference.
+
+**Page will not scroll over the chart** — only happens with `zoom: true`; vertical scrolling is preserved and horizontal drags pan. Set `pinchZoom: false` to disable gesture capture entirely.
+
+**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.
+
+**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).
+
+---
+
+## Browser and platform support
+
+Android WebView 60+ (Android 8+), iOS 12+, and all modern desktop browsers. `ResizeObserver` falls back to window resize/orientation listeners; `CustomEvent` falls back to `createEvent` for old WebViews.
+
+## Licence
+
+MIT — RemoteApps.

package/ionic/index.ts

@@ -0,0 +1,16 @@
+/**
+ * raChart Cordova — Ionic/Angular entry point.
+ *
+ * Standalone (Angular 16+):
+ *   import { RaChartComponent } from 'src/app/shared/ra-chart';
+ *   @Component({ imports: [RaChartComponent], ... })
+ *
+ * NgModule apps:
+ *   import { RaChartModule } from 'src/app/shared/ra-chart';
+ *   @NgModule({ imports: [RaChartModule], ... })
+ */
+
+export * from './ra-chart.types';
+export * from './ra-chart.loader';
+export * from './ra-chart.component';
+export * from './ra-chart.module';

package/ionic/ra-chart.component.html

@@ -0,0 +1,15 @@
+<!-- The engine renders into this element and adds its own .ra-chart class. -->
+<div #host class="ra-chart" [class.ra-chart--busy]="loading || isEmpty"></div>
+
+<div class="ra-chart__loading" *ngIf="loading" [style.height.px]="height">
+  <span class="ra-chart__spinner"></span>
+  <span>{{ loadingText }}</span>
+</div>
+
+<div class="ra-chart__empty" *ngIf="!loading && isEmpty" [style.height.px]="height">
+  <span>{{ emptyText }}</span>
+</div>
+
+<div class="ra-chart__empty" *ngIf="error" [style.height.px]="height">
+  <span>{{ error }}</span>
+</div>