@chartml/react 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alytic Pty Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,437 @@
+# @chartml/react
+
+React wrapper component for ChartML - render beautiful data visualizations in React with ease.
+
+## Features
+
+- ✅ **React Component** - Clean, idiomatic React API
+- ✅ **useChartML Hook** - Manage ChartML instances with React hooks
+- ✅ **Auto-Cleanup** - Automatic cleanup on unmount
+- ✅ **Plugin Support** - Register custom chart renderers and data sources
+- ✅ **Event Callbacks** - Progress, cache hit/miss, and error events
+- ✅ **TypeScript Ready** - Includes TypeScript definitions
+- ✅ **All Chart Types** - Includes pie, scatter, and metric chart plugins
+- ✅ **Zero Config** - Works out of the box with sensible defaults
+
+## Installation
+
+```bash
+npm install @chartml/react
+```
+
+**Peer Dependencies:**
+- `react` ^18.0.0
+- `react-dom` ^18.0.0
+
+The core ChartML library is included automatically.
+
+## Quick Start
+
+### Basic Usage
+
+```jsx
+import { ChartMLChart } from '@chartml/react';
+
+function SalesChart() {
+  const spec = `
+type: chart
+version: 1
+
+data:
+  - month: "Jan"
+    revenue: 45000
+  - month: "Feb"
+    revenue: 52000
+  - month: "Mar"
+    revenue: 48000
+
+visualize:
+  type: bar
+  columns: month
+  rows: revenue
+  style:
+    title: "Monthly Revenue"
+  `;
+
+  return <ChartMLChart spec={spec} />;
+}
+```
+
+### With Styling
+
+```jsx
+<ChartMLChart
+  spec={spec}
+  className="my-chart"
+  style={{ maxWidth: '800px', margin: '0 auto' }}
+/>
+```
+
+### With Event Callbacks
+
+```jsx
+import { ChartMLChart } from '@chartml/react';
+import { useState } from 'react';
+
+function ChartWithStatus() {
+  const [status, setStatus] = useState('idle');
+
+  return (
+    <div>
+      <p>Status: {status}</p>
+      <ChartMLChart
+        spec={spec}
+        options={{
+          onProgress: (e) => setStatus(`Loading: ${e.percent}%`),
+          onCacheHit: () => setStatus('Loaded from cache'),
+          onCacheMiss: () => setStatus('Fetching data'),
+          onError: (err) => setStatus(`Error: ${err.message}`)
+        }}
+      />
+    </div>
+  );
+}
+```
+
+## Advanced Usage
+
+### Using the useChartML Hook
+
+For more control, use the `useChartML` hook to manage your own ChartML instance:
+
+```jsx
+import { ChartMLChart, useChartML } from '@chartml/react';
+import { useEffect } from 'react';
+
+function CustomChart() {
+  const chartml = useChartML({
+    onProgress: (e) => console.log(`Progress: ${e.percent}%`),
+    palettes: {
+      custom: ['#ff0000', '#00ff00', '#0000ff']
+    }
+  });
+
+  // Register custom renderers if needed
+  useEffect(() => {
+    // Custom plugins would be registered here
+    // chartml.registerChartRenderer('custom', myRenderer);
+  }, [chartml]);
+
+  return <ChartMLChart spec={spec} chartml={chartml} />;
+}
+```
+
+### Dynamic Specs with State
+
+```jsx
+import { ChartMLChart } from '@chartml/react';
+import { useState } from 'react';
+
+function DynamicChart() {
+  const [chartType, setChartType] = useState('bar');
+
+  const spec = `
+type: chart
+version: 1
+
+data:
+  - month: "Jan"
+    revenue: 45000
+  - month: "Feb"
+    revenue: 52000
+
+visualize:
+  type: ${chartType}
+  columns: month
+  rows: revenue
+  `;
+
+  return (
+    <div>
+      <button onClick={() => setChartType('bar')}>Bar</button>
+      <button onClick={() => setChartType('line')}>Line</button>
+      <button onClick={() => setChartType('area')}>Area</button>
+      <ChartMLChart spec={spec} />
+    </div>
+  );
+}
+```
+
+### Fetching Data from API
+
+```jsx
+import { ChartMLChart } from '@chartml/react';
+import { useState, useEffect } from 'react';
+
+function APIChart() {
+  const [chartData, setChartData] = useState(null);
+
+  useEffect(() => {
+    fetch('/api/sales-data')
+      .then(res => res.json())
+      .then(data => {
+        const spec = {
+          type: 'chart',
+          version: 1,
+          data: data,
+          visualize: {
+            type: 'bar',
+            columns: 'month',
+            rows: 'revenue'
+          }
+        };
+        setChartData(spec);
+      });
+  }, []);
+
+  if (!chartData) return <div>Loading...</div>;
+
+  return <ChartMLChart spec={chartData} />;
+}
+```
+
+## All Chart Types Available
+
+This package includes all ChartML chart plugins by default:
+
+### Built-in Chart Types
+- `bar` - Vertical and horizontal bar charts
+- `line` - Single and multi-series line charts
+- `area` - Stacked and normalized area charts
+
+### Included Plugins
+- `pie` - Pie charts (from @chartml/chart-pie)
+- `doughnut` - Doughnut charts (from @chartml/chart-pie)
+- `scatter` - Scatter plots and bubble charts (from @chartml/chart-scatter)
+- `metric` - Metric cards for KPIs (from @chartml/chart-metric)
+
+All types work out of the box - no additional imports needed!
+
+## API Reference
+
+### `<ChartMLChart>` Component
+
+**Props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `spec` | `string \| object` | ChartML specification (YAML string or object) |
+| `chartml` | `ChartML` | Optional ChartML instance (for custom plugins) |
+| `options` | `object` | Options for ChartML instance |
+| `options.onProgress` | `function` | Progress callback: `(event) => void` |
+| `options.onCacheHit` | `function` | Cache hit callback: `(event) => void` |
+| `options.onCacheMiss` | `function` | Cache miss callback: `(event) => void` |
+| `options.onError` | `function` | Error callback: `(error) => void` |
+| `options.palettes` | `object` | Custom color palettes |
+| `className` | `string` | CSS class for container |
+| `style` | `object` | Inline styles for container |
+
+**Example:**
+
+```jsx
+<ChartMLChart
+  spec={mySpec}
+  className="chart-container"
+  style={{ maxWidth: '100%' }}
+  options={{
+    onProgress: (e) => console.log(e.percent),
+    onError: (err) => console.error(err)
+  }}
+/>
+```
+
+### `useChartML()` Hook
+
+Creates and manages a ChartML instance with React hooks.
+
+**Parameters:**
+- `options` (object, optional) - ChartML options
+
+**Returns:** `ChartML` instance
+
+**Example:**
+
+```jsx
+const chartml = useChartML({
+  onProgress: (e) => console.log(`Loading: ${e.percent}%`),
+  palettes: {
+    custom: ['#ff0000', '#00ff00', '#0000ff']
+  }
+});
+```
+
+## Examples
+
+### Pie Chart
+
+```jsx
+const pieSpec = `
+type: chart
+version: 1
+
+data:
+  - category: "Product A"
+    sales: 1200
+  - category: "Product B"
+    sales: 850
+  - category: "Product C"
+    sales: 1450
+
+visualize:
+  type: pie
+  columns: category
+  rows: sales
+  style:
+    title: "Sales by Product"
+`;
+
+<ChartMLChart spec={pieSpec} />
+```
+
+### Scatter Plot
+
+```jsx
+const scatterSpec = `
+type: chart
+version: 1
+
+data:
+  - temperature: 65
+    sales: 120
+  - temperature: 70
+    sales: 140
+  - temperature: 75
+    sales: 180
+
+visualize:
+  type: scatter
+  columns: temperature
+  rows: sales
+  style:
+    title: "Sales vs Temperature"
+`;
+
+<ChartMLChart spec={scatterSpec} />
+```
+
+### Metric Card
+
+```jsx
+const metricSpec = `
+type: chart
+version: 1
+
+data:
+  - value: 1234
+
+visualize:
+  type: metric
+  rows: value
+  style:
+    title: "Total Revenue"
+    format: "$,.0f"
+`;
+
+<ChartMLChart spec={metricSpec} />
+```
+
+## TypeScript Support
+
+Type definitions are included:
+
+```tsx
+import { ChartMLChart, useChartML } from '@chartml/react';
+import type { ChartML } from '@chartml/core';
+
+interface ChartProps {
+  data: any[];
+}
+
+function TypedChart({ data }: ChartProps) {
+  const chartml: ChartML = useChartML();
+
+  const spec = {
+    type: 'chart' as const,
+    version: 1,
+    data,
+    visualize: {
+      type: 'bar' as const,
+      columns: 'month',
+      rows: 'revenue'
+    }
+  };
+
+  return <ChartMLChart spec={spec} chartml={chartml} />;
+}
+```
+
+## Best Practices
+
+### 1. Memoize Spec Objects
+
+If passing spec as an object (not string), memoize it to prevent unnecessary re-renders:
+
+```jsx
+import { useMemo } from 'react';
+
+const spec = useMemo(() => ({
+  type: 'chart',
+  version: 1,
+  data: chartData,
+  visualize: { type: 'bar', columns: 'x', rows: 'y' }
+}), [chartData]);
+
+<ChartMLChart spec={spec} />
+```
+
+### 2. Use String Specs for Static Charts
+
+For static charts, YAML strings are more readable:
+
+```jsx
+const spec = `
+type: chart
+version: 1
+data: [...]
+visualize: { type: bar }
+`;
+```
+
+### 3. Handle Loading States
+
+Always handle loading states for async data:
+
+```jsx
+if (!data) return <div>Loading chart...</div>;
+return <ChartMLChart spec={buildSpec(data)} />;
+```
+
+### 4. Error Boundaries
+
+Wrap charts in error boundaries for production:
+
+```jsx
+<ErrorBoundary fallback={<div>Chart failed to load</div>}>
+  <ChartMLChart spec={spec} />
+</ErrorBoundary>
+```
+
+## Browser Support
+
+- React 18+
+- Modern browsers with SVG support
+- IE11+ (with polyfills)
+
+## Documentation
+
+- **ChartML Specification**: https://chartml.org/spec
+- **Examples**: https://chartml.org/examples
+- **API Reference**: https://chartml.org/api
+
+## License
+
+MIT © 2025 Alytic Pty Ltd
+
+## Powered By
+
+ChartML is maintained by the team at [Kyomi](https://kyomi.ai) and is the visualization engine that powers the platform.

package/dist/index.js

@@ -0,0 +1,25 @@
+import { useRef as u, useEffect as l } from "react";
+import { ChartML as f } from "@chartml/core";
+function R({ spec: e, chartml: r, options: n = {}, className: o = "", style: i = {} }) {
+  const t = u(null), c = u(null);
+  return l(() => (c.current || (c.current = r || new f(n)), (async () => {
+    if (t.current && e)
+      try {
+        await c.current.render(e, t.current);
+      } catch (a) {
+        console.error("[ChartML React] Render failed:", a), n.onError && n.onError(a);
+      }
+  })(), () => {
+    t.current && (t.current.innerHTML = "");
+  }), [e, r, n]), /* @__PURE__ */ React.createElement("div", { ref: t, className: o, style: i });
+}
+function m(e = {}) {
+  const r = u(null);
+  return r.current || (r.current = new f(e)), r.current;
+}
+export {
+  R as ChartMLChart,
+  R as default,
+  m as useChartML
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/index.jsx"],"sourcesContent":["/**\n * @chartml/react\n *\n * React wrapper component for ChartML\n * Provides a convenient React API for rendering ChartML specifications\n *\n * @example\n * import { ChartMLChart } from '@chartml/react';\n * import { ChartML } from '@chartml/core';\n *\n * function MyComponent() {\n *   const spec = `\n *     data:\n *       - month: Jan\n *         revenue: 45000\n *       - month: Feb\n *         revenue: 52000\n *\n *     visualize:\n *       type: bar\n *       columns: month\n *       rows: revenue\n *       style:\n *         title: \"Monthly Revenue\"\n *   `;\n *\n *   return <ChartMLChart spec={spec} />;\n * }\n */\n\nimport { useEffect, useRef } from 'react';\nimport { ChartML } from '@chartml/core';\n\n/**\n * ChartMLChart Component\n *\n * @param {Object} props\n * @param {string|object} props.spec - ChartML specification (YAML string or object)\n * @param {ChartML} [props.chartml] - Optional ChartML instance (for custom plugins)\n * @param {Object} [props.options] - Options for ChartML instance (if not providing instance)\n * @param {Function} [props.options.onProgress] - Progress callback\n * @param {Function} [props.options.onCacheHit] - Cache hit callback\n * @param {Function} [props.options.onCacheMiss] - Cache miss callback\n * @param {Function} [props.options.onError] - Error callback\n * @param {Object} [props.options.palettes] - Custom color palettes\n * @param {string} [props.className] - CSS class for container\n * @param {Object} [props.style] - Inline styles for container\n *\n * @example\n * // Basic usage\n * <ChartMLChart spec={yamlSpec} />\n *\n * @example\n * // With custom ChartML instance (for plugins)\n * const chartml = new ChartML();\n * chartml.registerChartRenderer('pie', pieRenderer);\n * <ChartMLChart spec={spec} chartml={chartml} />\n *\n * @example\n * // With hooks\n * <ChartMLChart\n *   spec={spec}\n *   options={{\n *     onProgress: (event) => console.log(`Progress: ${event.percent}%`),\n *     onCacheHit: (event) => console.log('Cache hit!'),\n *     palettes: { myPalette: ['#ff0000', '#00ff00', '#0000ff'] }\n *   }}\n * />\n */\nexport function ChartMLChart({ spec, chartml, options = {}, className = '', style = {} }) {\n  const containerRef = useRef(null);\n  const chartmlRef = useRef(null);\n\n  useEffect(() => {\n    // Create or use provided ChartML instance\n    if (!chartmlRef.current) {\n      chartmlRef.current = chartml || new ChartML(options);\n    }\n\n    // Render chart\n    const renderChart = async () => {\n      if (containerRef.current && spec) {\n        try {\n          await chartmlRef.current.render(spec, containerRef.current);\n        } catch (error) {\n          console.error('[ChartML React] Render failed:', error);\n          if (options.onError) {\n            options.onError(error);\n          }\n        }\n      }\n    };\n\n    renderChart();\n\n    // Cleanup function\n    return () => {\n      // Clear container on unmount\n      if (containerRef.current) {\n        containerRef.current.innerHTML = '';\n      }\n    };\n  }, [spec, chartml, options]);\n\n  return <div ref={containerRef} className={className} style={style} />;\n}\n\n/**\n * useChartML Hook\n *\n * Creates and manages a ChartML instance with plugins\n *\n * @param {Object} options - ChartML options\n * @returns {ChartML} ChartML instance\n *\n * @example\n * import { useChartML } from '@chartml/react';\n * import { createPieChartRenderer } from '@chartml/chart-pie';\n *\n * function MyComponent() {\n *   const chartml = useChartML({\n *     onProgress: (e) => console.log(`Progress: ${e.percent}%`)\n *   });\n *\n *   useEffect(() => {\n *     chartml.registerChartRenderer('pie', createPieChartRenderer());\n *   }, [chartml]);\n *\n *   return <ChartMLChart spec={spec} chartml={chartml} />;\n * }\n */\nexport function useChartML(options = {}) {\n  const chartmlRef = useRef(null);\n\n  if (!chartmlRef.current) {\n    chartmlRef.current = new ChartML(options);\n  }\n\n  return chartmlRef.current;\n}\n\nexport default ChartMLChart;\n"],"names":["ChartMLChart","spec","chartml","options","className","style","containerRef","useRef","chartmlRef","useEffect","ChartML","error","useChartML"],"mappings":";;AAqEO,SAASA,EAAa,EAAE,MAAAC,GAAM,SAAAC,GAAS,SAAAC,IAAU,IAAI,WAAAC,IAAY,IAAI,OAAAC,IAAQ,CAAA,KAAM;AACxF,QAAMC,IAAeC,EAAO,IAAI,GAC1BC,IAAaD,EAAO,IAAI;AAE9B,SAAAE,EAAU,OAEHD,EAAW,YACdA,EAAW,UAAUN,KAAW,IAAIQ,EAAQP,CAAO,KAIjC,YAAY;AAC9B,QAAIG,EAAa,WAAWL;AAC1B,UAAI;AACF,cAAMO,EAAW,QAAQ,OAAOP,GAAMK,EAAa,OAAO;AAAA,MAC5D,SAASK,GAAO;AACd,gBAAQ,MAAM,kCAAkCA,CAAK,GACjDR,EAAQ,WACVA,EAAQ,QAAQQ,CAAK;AAAA,MAEzB;AAAA,EAEJ,GAEA,GAGO,MAAM;AAEX,IAAIL,EAAa,YACfA,EAAa,QAAQ,YAAY;AAAA,EAErC,IACC,CAACL,GAAMC,GAASC,CAAO,CAAC,GAEpB,sBAAA,cAAC,OAAA,EAAI,KAAKG,GAAc,WAAAF,GAAsB,OAAAC,GAAc;AACrE;AA0BO,SAASO,EAAWT,IAAU,IAAI;AACvC,QAAMK,IAAaD,EAAO,IAAI;AAE9B,SAAKC,EAAW,YACdA,EAAW,UAAU,IAAIE,EAAQP,CAAO,IAGnCK,EAAW;AACpB;"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@chartml/react",
+  "version": "1.0.0",
+  "description": "React wrapper component for ChartML",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch"
+  },
+  "keywords": [
+    "chartml",
+    "react",
+    "chart",
+    "visualization",
+    "wrapper"
+  ],
+  "author": "Jason Adams",
+  "license": "MIT",
+  "dependencies": {
+    "@chartml/core": "^1.0.0",
+    "@chartml/chart-pie": "^1.0.0",
+    "@chartml/chart-scatter": "^1.0.0",
+    "@chartml/chart-metric": "^1.0.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "devDependencies": {
+    "vite": "^5.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chartml/chartml.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://chartml.org"
+}