@vmz/plugin-echarts 0.0.0 → 0.0.2

package/README.md

@@ -1,3 +1,28 @@
 # @vmz/plugin-echarts
 
-Placeholder package (0.0.0). Reserved for the VMZ project.
+## Turn product data into an interactive view 📈
+
+Tables are excellent for exact values, but they are poor at revealing a trend, an outlier, a changing distribution, or the relationship between several metrics. `@vmz/plugin-echarts` brings Apache ECharts to VMZ applications for the moments when users need to explore data rather than merely read it.
+
+ECharts is a mature choice for dashboards, analytics panels, monitoring surfaces, reports, and embedded product insights. It offers a broad chart vocabulary and rich interaction without asking the surrounding VMZ page to become a chart-specific application.
+
+## Where it fits
+
+| Scenario | What ECharts adds |
+|---|---|
+| Operational dashboard | Dense, interactive views over changing metrics |
+| Product analytics | Trends, comparisons, filters, and drill-down behavior |
+| Technical documentation | Live visual examples when a static diagram is not enough |
+| Existing ECharts product | A native VMZ boundary around familiar chart options |
+
+## ECharts or Mermaid?
+
+- Choose **ECharts** when the visualization is driven by data and users need tooltips, zooming, filtering, or exploration.
+- Choose **Mermaid** when the visual explains a process, architecture, state machine, or sequence authored as text.
+- Use ordinary content and tables when exact values matter more than visual exploration.
+
+## Keep the chart in its place
+
+ECharts owns drawing and interaction inside its host region. VMZ owns the page, data boundary, Island/client placement, lifetime, SSR fallback, tests, and delivery decision.
+
+That separation matters on real dashboards: a powerful chart should become interactive when useful without forcing navigation, surrounding content, and every other panel into one eager browser runtime. ✨

package/components/Echarts.vmz

@@ -0,0 +1,34 @@
+<template>
+  <div class="echarts-host" data-vmz-echarts style="min-height: 320px; width: 100%"></div>
+</template>
+
+<script client>
+import { mountEcharts } from '@vmz/plugin-echarts/runtime';
+
+export default class Echarts {
+  public option: any = null;
+  public theme: string | null = null;
+  public renderer: string = 'canvas';
+
+  #api: { setOption: (o: any, notMerge?: boolean) => void; dispose: () => void } | null = null;
+
+  async onMount() {
+    const root = this.__vmzDomRoot;
+    const el =
+      (root && root.nodeType === 1 && root.matches?.('[data-vmz-echarts]') && root) ||
+      root?.querySelector?.('[data-vmz-echarts]') ||
+      root;
+    if (!el || el.nodeType !== 1) return;
+    this.#api = await mountEcharts(el, {
+      option: this.option,
+      theme: this.theme,
+      renderer: this.renderer === 'svg' ? 'svg' : 'canvas',
+    });
+  }
+
+  onDestroy() {
+    this.#api?.dispose();
+    this.#api = null;
+  }
+}
+</script>

package/package.json

@@ -1,10 +1,38 @@
 {
   "name": "@vmz/plugin-echarts",
-  "version": "0.0.0",
-  "description": "VMZ placeholder — not for production use.",
+  "version": "0.0.2",
+  "type": "module",
+  "description": "VMZ ECharts chart adapter - <Echarts>",
   "license": "MIT",
-  "private": false,
-  "files": [
-    "README.md"
-  ]
+  "main": "./vmz.plugin.ts",
+  "types": "./vmz.plugin.ts",
+  "exports": {
+    ".": {
+      "types": "./vmz.plugin.ts",
+      "default": "./vmz.plugin.ts"
+    },
+    "./runtime": {
+      "types": "./runtime.ts",
+      "default": "./runtime.ts"
+    }
+  },
+  "dependencies": {
+    "@vmz/plugin": "0.0.2"
+  },
+  "peerDependencies": {
+    "echarts": ">=5"
+  },
+  "keywords": [
+    "vmz",
+    "plugin",
+    "echarts",
+    "chart"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/doki-land/vmz-framework.git"
+  }
 }

package/runtime.ts

@@ -0,0 +1,52 @@
+/**
+ * ECharts mount helper (browser). Peer: echarts.
+ * Parallel to DaVinci (declarative track); prefer for production charts while DaVinci matures.
+ */
+
+export type MountEchartsOptions = {
+    option?: Record<string, unknown> | null;
+    theme?: string | object | null;
+    renderer?: 'canvas' | 'svg';
+};
+
+export async function mountEcharts(el: HTMLElement, opts: MountEchartsOptions = {}) {
+    const echarts = await import('echarts');
+    const chart = echarts.init(el, opts.theme ?? undefined, {
+        renderer: opts.renderer ?? 'canvas',
+    });
+    if (opts.option) {
+        chart.setOption(opts.option);
+    }
+    const onResize = () => {
+        chart.resize();
+    };
+    if (typeof ResizeObserver !== 'undefined') {
+        const ro = new ResizeObserver(onResize);
+        ro.observe(el);
+        return {
+            chart,
+            setOption: (option: Record<string, unknown>, notMerge?: boolean) => {
+                chart.setOption(option, notMerge);
+            },
+            dispose: () => {
+                ro.disconnect();
+                chart.dispose();
+            },
+        };
+    }
+    if (typeof window !== 'undefined') {
+        window.addEventListener('resize', onResize);
+    }
+    return {
+        chart,
+        setOption: (option: Record<string, unknown>, notMerge?: boolean) => {
+            chart.setOption(option, notMerge);
+        },
+        dispose: () => {
+            if (typeof window !== 'undefined') {
+                window.removeEventListener('resize', onResize);
+            }
+            chart.dispose();
+        },
+    };
+}

package/vmz.plugin.ts

@@ -0,0 +1,46 @@
+import { definePlugin, loadPluginSource } from '@vmz/plugin';
+
+const source = loadPluginSource(import.meta.url, 'components/Echarts.vmz');
+
+export default definePlugin({
+    name: '@vmz/plugin-echarts',
+    version: '0.1.0',
+    protocol: '0.1.0',
+    stages: ['workspace_resolve', 'analyzer'],
+    deterministic: true,
+    async contribute(ctx) {
+        if (ctx.stage === 'workspace_resolve') {
+            return {
+                stage: 'workspace_resolve',
+                cacheKey: `@vmz/plugin-echarts:Echarts.vmz:${source.contentHash.slice(0, 12)}`,
+                items: [
+                    {
+                        id: 'component-echarts',
+                        kind: 'source',
+                        path: 'src/components/Echarts.vmz',
+                        content: source.content,
+                        contentHash: source.contentHash,
+                        materialize: true,
+                    },
+                ],
+            };
+        }
+        if (ctx.stage === 'analyzer') {
+            return {
+                stage: 'analyzer',
+                cacheKey: '@vmz/plugin-echarts:analyzer',
+                items: [
+                    {
+                        id: 'component-echarts-online',
+                        kind: 'analyzer',
+                        path: 'src/components/Echarts.vmz',
+                        severity: 'advice',
+                        message: 'Echarts component online',
+                        code: 'vmz.plugin.echarts',
+                    },
+                ],
+            };
+        }
+        return { stage: ctx.stage, items: [] };
+    },
+});