diff --git a/CHANGELOG.md b/CHANGELOG.md index 663252f..f06a023 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,18 @@ # Changelog +## 0.3.1 + +Aligned with **@chartgpu/chartgpu ^0.3.9**. + +### Dependencies + +- Peer / dev: `@chartgpu/chartgpu` **^0.3.9** (was ^0.3.6) + +### Docs + +- README redesigned to match the ChartGPU core repository layout (cleaner header, overview, install, features, browser support tables) +- Version pins updated in getting started, examples, and source comments + ## 0.3.0 Aligned with **@chartgpu/chartgpu ^0.3.6** and modern React/TypeScript tooling. diff --git a/README.md b/README.md index 9a05d80..0bdde62 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,42 @@ -

- ChartGPU +

+ ChartGPU

-

- React bindings for ChartGPU: MIT-licensed WebGPU charts for dense real-time, multi-series and multi-panel dashboards. +

+ React bindings for ChartGPU — + WebGPU charts for large datasets, real-time streaming, multi-chart dashboards, and 3D series. + MIT licensed.

-
+

+ npm + MIT + docs + demo + Featured in Awesome WebGPU +

-[Powered by WebGPU](#browser-support-webgpu-required) -[![npm version](https://img.shields.io/npm/v/chartgpu-react?style=for-the-badge&color=blue)](https://www.npmjs.com/package/chartgpu-react) -[![NPM Downloads](https://img.shields.io/npm/dm/chartgpu-react?style=for-the-badge&color=%2368cc49)](https://www.npmjs.com/package/chartgpu-react) -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://github.com/ChartGPU/chartgpu-react/blob/main/LICENSE) -[![Live Demo](https://img.shields.io/badge/demo-live-brightgreen?style=for-the-badge)](https://chartgpu.io) -[![Documentation](https://img.shields.io/badge/Documentation-Getting%20Started-blue?style=for-the-badge)](https://chartgpu.io/docs/getting-started/) -[![API Reference](https://img.shields.io/badge/API-Reference-blue?style=for-the-badge)](./docs/API.md) +

+ Live demo · + Docs · + React API · + Core library +

-[Featured on Hacker News](https://news.ycombinator.com/item?id=46706528) +--- -[Featured in Awesome WebGPU](https://github.com/mikbry/awesome-webgpu) +## Overview -
+`chartgpu-react` is a thin React + TypeScript wrapper around [`@chartgpu/chartgpu`](https://www.npmjs.com/package/@chartgpu/chartgpu). Core charting stays in ChartGPU; this package handles: -`chartgpu-react` is a thin React + TypeScript wrapper around [`@chartgpu/chartgpu`](https://www.npmjs.com/package/@chartgpu/chartgpu): lifecycle, resize, events, refs, and multi-chart GPU sharing in React. Core charting stays in ChartGPU (MIT commercial embed, zero npm runtime dependencies in core, WebGPU required, no WebGL fallback). +- Async create/dispose lifecycle and debounced resize +- Declarative event props and imperative `ChartGPUHandle` ref +- Shared-device multi-chart via `useGPUContext` / `gpuContext` +- Chart sync via `useConnectCharts` / `connectCharts` -Use it when Chart.js, ECharts, or uPlot hit streaming or multi-panel walls. Commercial GPU seats often ship WebGL fallback and broader catalog; ChartGPU is the open WebGPU-only embed. +ChartGPU renders with **WebGPU** (not Canvas2D or WebGL). There is **no WebGL/Canvas fallback**. Unsupported browsers must be gated by the host app. -Demo and docs: [chartgpu.io](https://chartgpu.io) · [docs](https://chartgpu.io/docs/) · [streaming dashboards](https://chartgpu.io/docs/streaming-dashboards/) · [core repo](https://github.com/ChartGPU/ChartGPU) +Demo and product docs: [chartgpu.io](https://chartgpu.io) · [streaming dashboards](https://chartgpu.io/docs/streaming-dashboards/) --- @@ -36,11 +46,9 @@ Demo and docs: [chartgpu.io](https://chartgpu.io) · [docs](https://chartgpu.io/ npm install chartgpu-react @chartgpu/chartgpu react react-dom ``` -Peer dependency: **`@chartgpu/chartgpu` ^0.3.6** (aligned with this package’s 0.3.x line). React 18 or 19. - ---- +Peer dependency: **`@chartgpu/chartgpu` ^0.3.9**. React 18 or 19. -## Quick start +### Minimal example ```tsx import { ChartGPU } from 'chartgpu-react'; @@ -48,39 +56,34 @@ import type { ChartGPUOptions } from 'chartgpu-react'; function MyChart() { const options: ChartGPUOptions = { - series: [ - { - type: 'line', - data: { - x: new Float64Array([0, 1, 2, 3]), - y: new Float64Array([0, 1, 4, 9]), - }, - lineStyle: { width: 2, color: '#667eea' }, + series: [{ + type: 'line', + data: { + x: new Float64Array([0, 1, 2]), + y: new Float64Array([1, 3, 2]), }, - ], - xAxis: { type: 'value' }, - yAxis: { type: 'value' }, + }], }; - return ; + return ; } ``` -Object / `[x,y]` tuples are fine for tiny demos; prefer typed-array columns at scale. +Prefer column-shaped x/y at scale; object / `[x,y]` tuples are fine for small demos. Requires a WebGPU-capable browser (see [Browser support](#browser-support)). --- -## Why chartgpu-react +## Features -| | | -|---|---| -| **React lifecycle** | Async create/dispose, debounced `ResizeObserver` sizing | -| **Dense real-time jobs** | Multi-series streaming, multi-panel dashboards, finance, heatmaps (via core) | -| **Shared-device multi-panel** | `useGPUContext` / `gpuContext` prop (recommended for ≥3 charts); `useConnectCharts` / `connectCharts` | -| **Ring FIFO streaming** | `ref.appendData(..., { maxPoints })`; heatmap/surface stream APIs on core | -| **Events and refs** | `onClick`, `onCrosshairMove`, `onZoomChange`, `onDataAppend`, `onDeviceLost`, …; `ChartGPUHandle` imperative API | -| **MIT commercial embed** | MIT wrapper; core density stays free under MIT with no feature gates on FIFO, zoom, multi-chart, or finance series | -| **WebGPU-only** | Same browser gate as core; no WebGL fallback | +- **React lifecycle** — async create/dispose, StrictMode-safe, debounced `ResizeObserver` sizing +- **Streaming** — `ref.appendData(..., { maxPoints })` FIFO ring; heatmap/surface stream APIs on core (`updateHeatmap`, `updateSurface3D`) +- **Multi-chart** — `useGPUContext` + `gpuContext` prop (≥3 charts recommended); zoom sync via `useConnectCharts` / `connectCharts` +- **Events and refs** — `onClick`, `onCrosshairMove`, `onZoomChange`, `onDataAppend`, `onDeviceLost`, …; full `ChartGPUHandle` imperative API +- **External render mode** — app-owned rAF with `renderMode: 'external'`, `needsRender()`, `renderFrame()` +- **Series via core** — line, area, bar, scatter, pie, candlestick, ohlc, heatmap, band, errorBar, impulse, step, stacked mountain, 3D (`pointCloud3d`, `surface3d`) +- **MIT commercial embed** — wrapper and core density (FIFO, zoom, multi-chart, finance series) stay open under MIT + +Core architecture: [ChartGPU ARCHITECTURE](https://github.com/ChartGPU/ChartGPU/blob/main/docs/ARCHITECTURE.md). Performance: [chartgpu.io/docs/performance](https://chartgpu.io/docs/performance/). --- @@ -110,9 +113,12 @@ function StreamingChart() { const id = window.setInterval(() => { const x0 = t.current; const x = new Float64Array([x0, x0 + 1, x0 + 2]); - const y = new Float64Array([Math.sin(x0 * 0.05), Math.sin((x0 + 1) * 0.05), Math.sin((x0 + 2) * 0.05)]); + const y = new Float64Array([ + Math.sin(x0 * 0.05), + Math.sin((x0 + 1) * 0.05), + Math.sin((x0 + 2) * 0.05), + ]); t.current += 3; - // Density path: column payload + fixed-capacity ring ref.current?.appendData(0, { x, y }, { maxPoints: 50_000 }); }, 16); return () => window.clearInterval(id); @@ -123,15 +129,10 @@ function StreamingChart() { ref={ref} options={{ autoScroll: true, - series: [ - { - type: 'line', - data: { x: new Float64Array(0), y: new Float64Array(0) }, - lineStyle: { width: 2, color: '#4facfe' }, - }, - ], - xAxis: { type: 'value' }, - yAxis: { type: 'value' }, + series: [{ + type: 'line', + data: { x: new Float64Array(0), y: new Float64Array(0) }, + }], }} style={{ width: '100%', height: 320 }} /> @@ -141,7 +142,9 @@ function StreamingChart() { --- -## Multi-chart dashboards (shared GPU device) +## Multi-chart (shared device) + +For three or more charts on one page, create a single adapter/device/pipeline cache and pass it into each chart. Charts do not destroy a shared device on dispose. ```tsx import { ChartGPU, useGPUContext } from 'chartgpu-react'; @@ -166,11 +169,11 @@ function Dashboard() { } ``` -Recommended for ≥3 charts. Full recipes: [streaming dashboards](https://chartgpu.io/docs/streaming-dashboards/) · [chart-sync recipe](./docs/recipes/chart-sync.md) · [core multi-chart cookbook](https://github.com/ChartGPU/ChartGPU/blob/main/docs/guides/multichart-dashboard-cookbook.md) +Recipes: [streaming dashboards](https://chartgpu.io/docs/streaming-dashboards/) · [chart-sync](./docs/recipes/chart-sync.md) · [core multi-chart cookbook](https://github.com/ChartGPU/ChartGPU/blob/main/docs/guides/multichart-dashboard-cookbook.md) --- -## More feature snippets +## More snippets ### Crosshair / interaction X @@ -284,29 +287,49 @@ function CandlestickStreaming() { --- +## Browser support + +WebGPU only. No WebGL path. + +| Browser | Support | +|---------|---------| +| Chrome / Edge | 113+ | +| Safari | 18+ | +| Firefox | Windows 114+; macOS 145+; Linux incomplete — see [gpuweb status](https://github.com/gpuweb/gpuweb/wiki/Implementation-Status) | + +Detect `navigator.gpu` before creating charts. Do not leave an unsupported user on a blank canvas without UI. + +```ts +if (!navigator.gpu) { + // fail closed: show UI, do not leave an empty chart +} +``` + +If you need Canvas/SVG or dual WebGL+WebGPU backends, use a library that ships those fallbacks. + +--- + ## Documentation ### chartgpu.io (core product) -| | | -|---|---| +| Resource | Description | +|----------|-------------| | [Docs hub](https://chartgpu.io/docs/) | Guides and series docs | | [Getting started](https://chartgpu.io/docs/getting-started/) | Install and first chart | +| [API reference](https://chartgpu.io/docs/api/) | `create`, options, streaming, interaction, 3D | | [Streaming dashboards](https://chartgpu.io/docs/streaming-dashboards/) | Shared device, multi-chart | | [Performance](https://chartgpu.io/docs/performance/) | Density, sampling, GPU sharing | +| [Theming](https://chartgpu.io/docs/theming/) | Dark / light / custom | ### This repository (React) -| | | -|---|---| +| Resource | Description | +|----------|-------------| | [Getting started](./docs/GETTING_STARTED.md) | React install and first component | | [API](./docs/API.md) | Component, hooks, handle | | [Recipes](./docs/recipes/) | Crosshair, sync, streaming, annotations, dataZoom | ---- - -## Examples - ```bash npm install npm run dev @@ -317,32 +340,13 @@ See [`examples/main.tsx`](./examples/main.tsx). --- -## Browser support (WebGPU required) - -No WebGL fallback. Gate unsupported browsers in your app (capability detect; never a blank canvas). - -| Browser | Notes | -|---------|--------| -| Chrome / Edge | 113+ | -| Safari | 18+ | -| Firefox | Windows 114+, macOS 145+, Linux still incomplete on [gpuweb status](https://github.com/gpuweb/gpuweb/wiki/Implementation-Status) | - -```ts -if (!navigator.gpu) { - // fail closed: show UI, do not leave an empty chart -} -``` - -WebGPU-only is intentional. Need Canvas/SVG or dual WebGL+WebGPU? Use a stack that ships a fallback. - ---- - ## Development ```bash npm install npm run typecheck npm run build +npm run test npm run dev ``` @@ -401,7 +405,7 @@ Issues and pull requests welcome. For larger changes, open an issue first. ## License -[MIT](LICENSE). Free for commercial embedding. ChartGPU core keeps density, FIFO, multi-chart, and finance series in the open core. +[MIT](LICENSE). Free for commercial use. ChartGPU core keeps density, FIFO, multi-chart, and finance series in the open core. ## Related diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index 02df990..a210998 100644 --- a/docs/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -10,7 +10,7 @@ npm install chartgpu-react @chartgpu/chartgpu react react-dom ## Requirements -- **@chartgpu/chartgpu**: ^0.3.6 (peer) +- **@chartgpu/chartgpu**: ^0.3.9 (peer) - **React**: 18 or 19 - **WebGPU**: a browser with `navigator.gpu` support (Chrome/Edge 113+, Safari 18+, modern Firefox) diff --git a/examples/index.html b/examples/index.html index 0723917..1916436 100644 --- a/examples/index.html +++ b/examples/index.html @@ -55,7 +55,7 @@

Examples

- Interactive demos for chartgpu-react on @chartgpu/chartgpu@^0.3.6. + Interactive demos for chartgpu-react on @chartgpu/chartgpu@^0.3.9. Source: examples/main.tsx.

diff --git a/package-lock.json b/package-lock.json index 62798e5..5f5ed11 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,15 +1,15 @@ { "name": "chartgpu-react", - "version": "0.3.0", + "version": "0.3.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "chartgpu-react", - "version": "0.3.0", + "version": "0.3.1", "license": "MIT", "devDependencies": { - "@chartgpu/chartgpu": "^0.3.6", + "@chartgpu/chartgpu": "^0.3.9", "@testing-library/jest-dom": "^6.9.1", "@testing-library/react": "^16.3.2", "@types/react": "^19.2.17", @@ -27,7 +27,7 @@ "node": ">=20" }, "peerDependencies": { - "@chartgpu/chartgpu": "^0.3.6", + "@chartgpu/chartgpu": "^0.3.9", "react": ">=18.0.0", "react-dom": ">=18.0.0" }, @@ -411,9 +411,9 @@ } }, "node_modules/@chartgpu/chartgpu": { - "version": "0.3.6", - "resolved": "https://registry.npmjs.org/@chartgpu/chartgpu/-/chartgpu-0.3.6.tgz", - "integrity": "sha512-YLHpU4mCduWN/LiLdI64qy1SOOFAVlTEbxtDDVBK4fX/npAzkzIXj2dK9dfcWxGA7V4miMjTOhqqk8S8m3gfsA==", + "version": "0.3.9", + "resolved": "https://registry.npmjs.org/@chartgpu/chartgpu/-/chartgpu-0.3.9.tgz", + "integrity": "sha512-oEYpzQrFtA756miSM8khPHBmqWPTgUYHDzIAcziCaAZlu39lWCnWJQ5Qvb3urbh9bFJhV1DJTJ0gZvaA2pBYmw==", "dev": true, "license": "MIT" }, diff --git a/package.json b/package.json index 31a5765..8b12655 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "chartgpu-react", - "version": "0.3.0", + "version": "0.3.1", "description": "React bindings for ChartGPU — WebGPU-powered high-performance charts", "license": "MIT", "author": "", @@ -42,7 +42,7 @@ "test:watch": "vitest" }, "peerDependencies": { - "@chartgpu/chartgpu": "^0.3.6", + "@chartgpu/chartgpu": "^0.3.9", "react": ">=18.0.0", "react-dom": ">=18.0.0" }, @@ -52,7 +52,7 @@ } }, "devDependencies": { - "@chartgpu/chartgpu": "^0.3.6", + "@chartgpu/chartgpu": "^0.3.9", "@testing-library/jest-dom": "^6.9.1", "@testing-library/react": "^16.3.2", "@types/react": "^19.2.17", diff --git a/src/index.ts b/src/index.ts index 97bcec6..805cb75 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,7 +1,7 @@ /** * chartgpu-react * React bindings for ChartGPU — WebGPU-powered high-performance charts - * Compatible with @chartgpu/chartgpu ^0.3.6 + * Compatible with @chartgpu/chartgpu ^0.3.9 */ // Primary ChartGPU component diff --git a/src/types.ts b/src/types.ts index aea31ac..cf09048 100644 --- a/src/types.ts +++ b/src/types.ts @@ -1,6 +1,6 @@ /** * Type definitions for ChartGPU React wrapper. - * Aligned with @chartgpu/chartgpu ^0.3.6. + * Aligned with @chartgpu/chartgpu ^0.3.9. */ import type { CSSProperties } from 'react';