@revolist/react-charts 0.0.0-stage → 3.0.2

package/README.md

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+# RevoGrid React Charts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+One generic `RevoChart` component backed by the standalone chart engine.
+
+## Installation: public wrapper, private engine
+
+The four wrapper packages are configured for public npm publishing. `@revolist/charts` remains a
+private commercial package on GitHub Packages; you need licensed access to
+install and use it. The wrapper imports the engine and does not bundle it.
+
+### Before the first release
+
+The wrappers are not published yet; registry install commands below apply after
+publication. In this monorepo, replace `your-app` with your consumer workspace
+name and use the local package:
+
+```sh
+pnpm --filter your-app add "@revolist/react-charts@workspace:*" "@revolist/charts@workspace:*"
+pnpm build
+```
+
+Source: `packages/charts/packages/react-charts`. The public import name is unchanged.
+
+### Registry installation after publication
+
+Configure your project's `.npmrc` for the engine, keeping credentials in your
+environment:
+
+```ini
+@revolist:registry=https://npm.pkg.github.com/
+//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}
+```
+
+Both registries use the `@revolist` scope. Install the public wrapper by its
+explicit npm tarball URL so the scope mapping continues to send the engine to
+GitHub Packages. A plain `pnpm add @revolist/react-charts` with that mapping
+would look for the wrapper on GitHub instead. Changing only the default
+`--registry` does not override the scope mapping.
+
+```sh
+pnpm add @revolist/charts@3.0.0
+pnpm add https://registry.npmjs.org/@revolist/react-charts/-/react-charts-3.0.0.tgz
+```
+
+Use matching released wrapper and engine versions; replace `3.0.0` in these
+examples when upgrading. Commit your lockfile so CI retains both registries'
+resolved tarball URLs, and provide `GITHUB_PACKAGES_TOKEN` during CI installs.
+Missing or unauthorized engine access causes installation to fail. No separate
+wrapper trial package is published.
+
+Define your chart configuration:
+
+```ts
+const options = {
+  chartType: 'line',
+  data: [{ month: 'Jan', revenue: 120 }, { month: 'Feb', revenue: 180 }],
+  mapping: {
+    category: { field: 'month' },
+    series: [{ field: 'revenue', label: 'Revenue' }],
+  },
+} satisfies ChartComponentOptions;
+```
+
+```tsx
+import { RevoChart, type ChartComponentOptions } from '@revolist/react-charts';
+// Use the options above in your component:
+<RevoChart options={options} onReady={chart => console.log(chart.model)}
+  style={{ height: 400 }} className="sales-chart" />
+```
+
+## Updates and lifecycle
+
+`options` has type `Omit<ChartOptions, 'container'>`. It accepts the same rows and
+mapping, dataset, saved model, renderer, data source and chart settings as
+`@revolist/charts`. Existing callbacks such as `onNodeClick`, `onChange` and
+`onError` belong inside `options`. Callback replacements take effect without
+recreating a chart.
+
+Replace `options` and changed nested values to update the chart; do not mutate
+nested objects in place. In Vue, replace the ref value; in Svelte, prefer
+`$state.raw` for chart configuration. Ordinary data/settings changes update the
+current chart. Source replacements use `setDataSource`. Initialization settings,
+input-mode changes and removed settings recreate it to restore engine defaults.
+
+The host defaults to width `100%` and height `300px`. Override its dimensions with
+framework styles. The engine observes resizing. No stylesheet, element
+registration or manual mount call is needed.
+
+The readiness callback/event receives `ChartRef` for `download`, `getCSV`,
+`getImageDataURL`, selection and transactions. It fires again after recreation;
+replace any stored ref on each readiness event. The component owns destruction,
+so do not destroy its ref yourself.
+
+Creation and updates are asynchronous. Pending work is cancelled on unmount or
+superseding configuration, and stale results are destroyed. Failures call
+`options.onError`, or `console.error` when no error handler is supplied. Server
+rendering produces an empty host; chart creation starts after client mounting.
+
+## Building and distribution
+
+The package compiles with the monorepo's root `pnpm build`. Framework runtimes and
+`@revolist/charts` stay external. Install the framework peers listed in
+`package.json`; the engine version follows the wrapper version.
+
+The normal charts release publishes this wrapper to public npmjs using the
+repository's `NPM_TOKEN` secret. The private engine is published separately to
+GitHub Packages using GitHub credentials. No wrapper `build:trial` or trial
+publication is needed.

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import type { HTMLAttributes, ReactElement } from 'react';
+import type { ChartComponentOptions } from '@revolist/charts/framework';
+import type { ChartRef } from '@revolist/charts';
+export type { ChartComponentOptions, ChartRef };
+export interface RevoChartProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    options: ChartComponentOptions;
+    onReady?: (chart: ChartRef) => void;
+}
+export declare function RevoChart({ options, onReady, style, ...attributes }: RevoChartProps): ReactElement;

package/dist/index.js

@@ -0,0 +1,19 @@
+import { createElement, useEffect, useRef } from 'react';
+import { createChartComponentController } from '@revolist/charts/framework';
+export function RevoChart({ options, onReady, style, ...attributes }) {
+    const host = useRef(null);
+    const controller = useRef(undefined);
+    const ready = useRef(onReady);
+    // Update callbacks only after commit; abandoned concurrent renders stay invisible.
+    useEffect(() => { ready.current = onReady; }, [onReady]);
+    useEffect(() => {
+        const instance = createChartComponentController(host.current, chart => ready.current?.(chart));
+        controller.current = instance;
+        return () => {
+            instance.destroy();
+            controller.current = undefined;
+        };
+    }, []);
+    useEffect(() => { void controller.current?.setOptions(options); }, [options]);
+    return createElement('div', { ...attributes, ref: host, style: { width: '100%', height: '300px', ...style } });
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@revolist/react-charts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "3.0.2",
+  "description": "React components for RevoGrid Charts",
+  "type": "module",
+  "license": "Commercial",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@revolist/charts": "3.0.2"
+  },
+  "peerDependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "~6.0.3",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.1"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/revolist/revogrid-pro.git",
+    "directory": "packages/charts/packages/react-charts"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test --test-name-pattern=\"^react charts\" ../../../../.github/workflows/chart-frameworks.test.mjs"
+  }
 }