cordova-plugin-ra-chart 1.0.0

package/ionic/ra-chart.component.ts

@@ -0,0 +1,254 @@
+import {
+  AfterViewInit, ChangeDetectionStrategy, ChangeDetectorRef, Component, ElementRef,
+  EventEmitter, Inject, Input, NgZone, OnChanges, OnDestroy, Output, SimpleChanges, ViewChild
+} from '@angular/core';
+import { CommonModule } from '@angular/common';
+
+import { RA_CHART_SCRIPT_URL, ensureRaChart } from './ra-chart.loader';
+import type {
+  RaAnimation, RaBand, RaChartInstance, RaChartOptions, RaChartType,
+  RaFieldMap, RaSelectEvent, RaSeries, RaToggleEvent, RaZoomEvent
+} from './ra-chart.types';
+
+/**
+ * `<ra-chart>` — Ionic/Angular wrapper around the raChart engine.
+ *
+ *   <ra-chart type="column" category="month"
+ *             [series]="series" [data]="rows" [zoom]="true"
+ *             (select)="onSelect($event)"></ra-chart>
+ *
+ * The engine runs entirely outside Angular's zone, so touch scrubbing and
+ * entrance animations never trigger change detection. Events are re-entered
+ * into the zone before they reach your handlers.
+ */
+@Component({
+  selector: 'ra-chart',
+  standalone: true,
+  imports: [CommonModule],
+  templateUrl: './ra-chart.component.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  styles: [`
+    :host { display: block; position: relative; }
+    :host .ra-chart--busy { display: none; }
+  `]
+})
+export class RaChartComponent implements AfterViewInit, OnChanges, OnDestroy {
+  @ViewChild('host', { static: true }) hostRef!: ElementRef<HTMLDivElement>;
+
+  // ---- data ----
+  @Input() type: RaChartType = 'column';
+  @Input() data: any[] = [];
+  @Input() category = 'category';
+  @Input() series: RaSeries[] = [];
+  @Input() colors: string[] | null = null;
+
+  // ---- shape ----
+  @Input() stacked = false;
+  @Input() fullStacked = false;
+  @Input() smooth = false;
+  @Input() stepped = false;
+  @Input() semi = false;
+  @Input() depth = 0;
+
+  // ---- field mapping ----
+  @Input() fields: RaFieldMap | null = null;
+  @Input() xField = 'x';
+  @Input() sizeField = 'size';
+
+  // ---- scale ----
+  @Input() min = 0;
+  @Input() max: number | null = null;
+  @Input() bands: RaBand[] | null = null;
+  @Input() upColor?: string;
+  @Input() downColor?: string;
+
+  // ---- interaction ----
+  @Input() zoom = false;
+  @Input() pinchZoom = true;
+  @Input() legend = true;
+  @Input() haptics = true;
+  @Input() sheetTooltip: boolean | 'auto' = 'auto';
+  @Input() tooltipHold = 2600;
+
+  // ---- presentation ----
+  @Input() height = 260;
+  @Input() animation: RaAnimation = { duration: 800, delay: 70 };
+  @Input() loading = false;
+  @Input() emptyText = 'No data to display';
+  @Input() loadingText = 'Loading…';
+
+  // ---- events ----
+  @Output() select = new EventEmitter<RaSelectEvent>();
+  @Output() zoomChange = new EventEmitter<RaZoomEvent>();
+  @Output() toggle = new EventEmitter<RaToggleEvent>();
+  @Output() ready = new EventEmitter<RaChartInstance>();
+
+  /** Set when the engine script cannot be loaded, so the template can say so. */
+  error: string | null = null;
+
+  private chart: RaChartInstance | null = null;
+  private booted = false;
+  private listeners: Array<[string, EventListener]> = [];
+
+  constructor(
+    private zone: NgZone,
+    private cdr: ChangeDetectorRef,
+    @Inject(RA_CHART_SCRIPT_URL) private scriptUrl: string
+  ) { }
+
+  /** True when the current type has nothing to draw. */
+  get isEmpty(): boolean {
+    if (this.loading || this.error) return false;
+    if (!this.data || this.data.length === 0) return true;
+    // sankey carries its own from/to/value rows; every other type needs a series
+    if (this.type === 'sankey') return false;
+    return this.series.length === 0;
+  }
+
+  ngAfterViewInit(): void {
+    this.boot();
+  }
+
+  ngOnChanges(changes: SimpleChanges): void {
+    if (!this.chart) return;
+
+    // data-only change on a stable shape → let the engine morph the values
+    const keys = Object.keys(changes);
+    if (keys.length === 1 && keys[0] === 'data' && !changes['data'].firstChange) {
+      if (this.isEmpty) { this.teardownChart(); this.cdr.markForCheck(); return; }
+      this.zone.runOutsideAngular(() => this.chart!.setData(this.data || []));
+      return;
+    }
+    if (keys.length === 1 && keys[0] === 'loading') { this.cdr.markForCheck(); return; }
+
+    if (this.isEmpty) { this.teardownChart(); this.cdr.markForCheck(); return; }
+    this.zone.runOutsideAngular(() => this.chart!.update(this.buildOptions()));
+  }
+
+  ngOnDestroy(): void {
+    this.teardownChart();
+  }
+
+  // ---------------------------------------------------------------
+  // imperative API — grab the component with @ViewChild and call these
+  // ---------------------------------------------------------------
+
+  /** The live engine instance, or null before first render. */
+  get instance(): RaChartInstance | null {
+    return this.chart;
+  }
+
+  replay(): void {
+    this.zone.runOutsideAngular(() => this.chart?.replay());
+  }
+
+  resize(): void {
+    this.zone.runOutsideAngular(() => this.chart?.resize());
+  }
+
+  zoomTo(from: number, to: number): void {
+    this.zone.runOutsideAngular(() => this.chart?.zoomTo(from, to));
+  }
+
+  resetZoom(): void {
+    this.zone.runOutsideAngular(() => this.chart?.resetZoom());
+  }
+
+  toggleSeries(index: number, hidden?: boolean): void {
+    this.zone.runOutsideAngular(() => this.chart?.toggleSeries(index, hidden));
+  }
+
+  /** SVG markup of the current chart — handy for share sheets and exports. */
+  toSVG(): string {
+    return this.chart ? this.chart.toSVG() : '';
+  }
+
+  // ---------------------------------------------------------------
+  // internals
+  // ---------------------------------------------------------------
+
+  private buildOptions(): RaChartOptions {
+    const o: RaChartOptions = {
+      type: this.type,
+      data: this.data || [],
+      category: this.category,
+      series: this.series || [],
+      colors: this.colors,
+      stacked: this.stacked,
+      fullStacked: this.fullStacked,
+      smooth: this.smooth,
+      stepped: this.stepped,
+      semi: this.semi,
+      depth: this.depth,
+      fields: this.fields,
+      xField: this.xField,
+      sizeField: this.sizeField,
+      min: this.min,
+      max: this.max,
+      bands: this.bands,
+      zoom: this.zoom,
+      pinchZoom: this.pinchZoom,
+      legend: this.legend,
+      height: this.height,
+      haptics: this.haptics,
+      sheetTooltip: this.sheetTooltip,
+      tooltipHold: this.tooltipHold,
+      animation: this.animation
+    };
+    if (this.upColor) o.upColor = this.upColor;
+    if (this.downColor) o.downColor = this.downColor;
+    return o;
+  }
+
+  private boot(): void {
+    if (this.booted || this.isEmpty) return;
+    this.booted = true;
+
+    ensureRaChart(this.scriptUrl).then(Ctor => {
+      if (!this.hostRef) return;
+      this.zone.runOutsideAngular(() => {
+        this.bindEvents();
+        this.chart = new Ctor(this.hostRef.nativeElement, this.buildOptions());
+      });
+      this.zone.run(() => {
+        this.error = null;
+        this.ready.emit(this.chart!);
+        this.cdr.markForCheck();
+      });
+    }).catch((err: Error) => {
+      this.zone.run(() => {
+        this.error = 'Chart engine failed to load';
+        this.booted = false;
+        this.cdr.markForCheck();
+      });
+      console.error('[ra-chart]', err.message, '— expected at:', this.scriptUrl);
+    });
+  }
+
+  private bindEvents(): void {
+    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;
+        this.zone.run(() => out.emit(e.detail));
+      }) as EventListener;
+      host.addEventListener(name, fn);
+      this.listeners.push([name, fn]);
+    };
+    bridge('raChartSelect', this.select);
+    bridge('raChartZoom', this.zoomChange);
+    bridge('raChartToggle', this.toggle);
+  }
+
+  private teardownChart(): void {
+    const host = this.hostRef?.nativeElement;
+    if (host) {
+      this.listeners.forEach(([name, fn]) => host.removeEventListener(name, fn));
+    }
+    this.listeners = [];
+    this.chart?.destroy();
+    this.chart = null;
+    this.booted = false;
+  }
+}

package/ionic/ra-chart.loader.ts

@@ -0,0 +1,63 @@
+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:
+ *
+ *   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', {
+  providedIn: 'root',
+  factory: () => 'assets/ra-chart/ra-chart.js'
+});
+
+let pending: Promise<RaChartConstructor> | null = null;
+
+/** The engine attaches itself to `window`; grab it if it is already there. */
+function fromWindow(): RaChartConstructor | null {
+  const w = window as any;
+  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 = () => {
+      const ctor = fromWindow();
+      if (ctor) resolve(ctor);
+      else reject(new Error('ra-chart.js loaded but window.RaChart is missing'));
+    };
+
+    if (tag) {
+      tag.addEventListener('load', done);
+      tag.addEventListener('error', () => reject(new Error('Failed to load ' + scriptUrl)));
+      return;
+    }
+
+    tag = document.createElement('script');
+    tag.src = scriptUrl;
+    tag.async = true;
+    tag.dataset['raChart'] = '1';
+    tag.onload = done;
+    tag.onerror = () => {
+      pending = null;
+      reject(new Error('Failed to load ' + scriptUrl));
+    };
+    document.head.appendChild(tag);
+  });
+
+  return pending;
+}

package/ionic/ra-chart.module.ts

@@ -0,0 +1,23 @@
+import { NgModule, ModuleWithProviders } from '@angular/core';
+import { RaChartComponent } from './ra-chart.component';
+import { RA_CHART_SCRIPT_URL } from './ra-chart.loader';
+
+/**
+ * Compatibility module for apps that are not on standalone components yet.
+ * Standalone apps can import `RaChartComponent` directly instead.
+ */
+@NgModule({
+  imports: [RaChartComponent],
+  exports: [RaChartComponent]
+})
+export class RaChartModule {
+  /** Point the lazy loader at a custom script path. */
+  static forRoot(config: { scriptUrl?: string } = {}): ModuleWithProviders<RaChartModule> {
+    return {
+      ngModule: RaChartModule,
+      providers: config.scriptUrl
+        ? [{ provide: RA_CHART_SCRIPT_URL, useValue: config.scriptUrl }]
+        : []
+    };
+  }
+}

package/ionic/ra-chart.types.ts

@@ -0,0 +1,136 @@
+/**
+ * raChart Cordova — types re-exported for Ionic/Angular consumers.
+ *
+ * These mirror `types/index.d.ts`; they live here as plain source so the
+ * Ionic app can import them without a package build step.
+ */
+
+export type RaChartType =
+  | 'column' | 'bar' | 'line' | 'area' | 'lollipop'
+  | 'pie' | 'donut' | 'radar'
+  | 'treemap' | 'sankey' | 'wordcloud' | 'venn'
+  | 'candlestick' | 'timeline' | 'gantt'
+  | 'scatter' | 'bubble'
+  | 'funnel' | 'pyramid'
+  | 'gauge' | 'heatmap';
+
+export interface RaSeries {
+  name: string;
+  field: string;
+}
+
+export interface RaFieldMap {
+  open?: string;
+  high?: string;
+  low?: string;
+  close?: string;
+  start?: string;
+  end?: string;
+  progress?: string;
+  from?: string;
+  to?: string;
+  value?: string;
+}
+
+export interface RaBand {
+  from?: number;
+  to?: number;
+  color?: string;
+}
+
+export interface RaAnimation {
+  duration?: number;
+  delay?: number;
+}
+
+export interface RaChartOptions {
+  type?: RaChartType;
+  data?: any[];
+  category?: string;
+  series?: RaSeries[];
+  colors?: string[] | null;
+  stacked?: boolean;
+  fullStacked?: boolean;
+  smooth?: boolean;
+  stepped?: boolean;
+  semi?: boolean;
+  depth?: number;
+  fields?: RaFieldMap | null;
+  xField?: string;
+  sizeField?: string;
+  min?: number;
+  max?: number | null;
+  bands?: RaBand[] | null;
+  upColor?: string;
+  downColor?: string;
+  zoom?: boolean;
+  pinchZoom?: boolean;
+  legend?: boolean;
+  height?: number;
+  haptics?: boolean;
+  sheetTooltip?: boolean | 'auto';
+  tooltipHold?: number;
+  animation?: RaAnimation;
+}
+
+export interface RaSelectEvent {
+  seriesIndex?: number;
+  categoryIndex?: number;
+  index?: number;
+  series?: string;
+  category?: string;
+  value?: number;
+  percent?: number;
+  x?: number;
+  y?: number;
+  size?: number;
+  ohlc?: { o: number; h: number; l: number; c: number };
+  start?: number;
+  end?: number;
+  progress?: number | null;
+  kind?: 'link' | 'node';
+  from?: string;
+  to?: string;
+  name?: string;
+  row?: any;
+  col?: number;
+  [key: string]: any;
+}
+
+export interface RaZoomEvent {
+  from: number;
+  to: number;
+  startIndex: number;
+  endIndex: number;
+}
+
+export interface RaToggleEvent {
+  index: number;
+  name: string;
+  hidden: boolean;
+}
+
+/** Runtime handle returned by the engine. */
+export interface RaChartInstance {
+  setData(data: any[]): RaChartInstance;
+  setType(type: RaChartType): RaChartInstance;
+  update(partial: RaChartOptions): RaChartInstance;
+  replay(): RaChartInstance;
+  resize(): RaChartInstance;
+  zoomTo(from: number, to: number): RaChartInstance;
+  resetZoom(): RaChartInstance;
+  getZoom(): RaZoomEvent;
+  toggleSeries(index: number, hidden?: boolean): RaChartInstance;
+  toSVG(): string;
+  destroy(): void;
+}
+
+export interface RaChartConstructor {
+  new(host: HTMLElement | string, options?: RaChartOptions): RaChartInstance;
+  version: string;
+  defaults: RaChartOptions;
+  palette: string[];
+  paletteDark: string[];
+  types: RaChartType[];
+  create(host: HTMLElement | string, options?: RaChartOptions): RaChartInstance;
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "cordova-plugin-ra-chart",
+  "version": "1.0.0",
+  "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",
+  "license": "MIT",
+  "author": "RemoteApps",
+  "cordova": {
+    "id": "cordova-plugin-ra-chart",
+    "platforms": [
+      "android",
+      "ios",
+      "browser",
+      "electron"
+    ]
+  },
+  "keywords": [
+    "ecosystem:cordova",
+    "cordova-android",
+    "cordova-ios",
+    "cordova-browser",
+    "ionic",
+    "angular",
+    "chart",
+    "charts",
+    "svg",
+    "graph",
+    "dashboard",
+    "mobile",
+    "offline",
+    "no-dependencies"
+  ],
+  "files": [
+    "www/",
+    "types/",
+    "ionic/",
+    "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

@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  raChart Cordova plugin descriptor.
+
+  Install:  cordova plugin add ./ra-chart-cordova
+  After install, `window.RaChart` is available on deviceready.
+
+  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.
+-->
+<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
+        id="cordova-plugin-ra-chart"
+        version="1.0.0">
+
+  <name>raChart</name>
+  <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.
+  </description>
+  <license>MIT</license>
+  <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.
+  -->
+  <asset src="www/ra-chart.css" target="css/ra-chart.css" />
+
+  <platform name="android" />
+  <platform name="ios" />
+  <platform name="browser" />
+  <platform name="electron" />
+
+</plugin>