@revolist/vue-charts 0.0.0-stage → 3.0.2

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# RevoGrid Vue 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/vue-charts@workspace:*" "@revolist/charts@workspace:*"
+pnpm build
+```
+
+Source: `packages/charts/packages/vue-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/vue-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/vue-charts/-/vue-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.
+
+```vue
+<script setup lang="ts">
+import { shallowRef } from 'vue';
+import { RevoChart, type ChartComponentOptions } from '@revolist/vue-charts';
+const options = shallowRef<ChartComponentOptions>({
+  chartType: 'line',
+  data: [{ month: 'Jan', revenue: 120 }, { month: 'Feb', revenue: 180 }],
+  mapping: { category: { field: 'month' }, series: [{ field: 'revenue' }] },
+});
+</script>
+<template>
+  <RevoChart :options="options" @ready="chart => console.log(chart.model)"
+    style="height:400px" class="sales-chart" />
+</template>
+```
+
+## 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,21 @@
+import type { PropType } from 'vue';
+import type { ChartComponentOptions } from '@revolist/charts/framework';
+import type { ChartRef } from '@revolist/charts';
+export type { ChartComponentOptions, ChartRef };
+export declare const RevoChart: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    options: {
+        type: PropType<ChartComponentOptions>;
+        required: true;
+    };
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    ready: (_chart: ChartRef) => true;
+}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    options: {
+        type: PropType<ChartComponentOptions>;
+        required: true;
+    };
+}>> & Readonly<{
+    onReady?: ((_chart: ChartRef) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

package/dist/index.js

@@ -0,0 +1,19 @@
+import { defineComponent, h, mergeProps, onBeforeUnmount, onMounted, ref, toRaw, watch } from 'vue';
+import { createChartComponentController } from '@revolist/charts/framework';
+export const RevoChart = defineComponent({
+    name: 'RevoChart',
+    inheritAttrs: false,
+    props: { options: { type: Object, required: true } },
+    emits: { ready: (_chart) => true },
+    setup(props, { attrs, emit }) {
+        const host = ref();
+        let controller;
+        onMounted(() => {
+            controller = createChartComponentController(host.value, chart => emit('ready', chart));
+            void controller.setOptions(toRaw(props.options));
+        });
+        watch(() => props.options, options => { void controller?.setOptions(toRaw(options)); });
+        onBeforeUnmount(() => controller?.destroy());
+        return () => h('div', mergeProps({ style: { width: '100%', height: '300px' } }, attrs, { ref: host }));
+    },
+});

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@revolist/vue-charts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "3.0.2",
+  "description": "Vue 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": {
+    "vue": "^3.5.0"
+  },
+  "devDependencies": {
+    "vue": "^3.5.0",
+    "typescript": "~6.0.3"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/revolist/revogrid-pro.git",
+    "directory": "packages/charts/packages/vue-charts"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test --test-name-pattern=\"^vue charts\" ../../../../.github/workflows/chart-frameworks.test.mjs"
+  }
 }