@revolist/svelte-charts 0.0.0-stage → 3.0.2

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# RevoGrid Svelte 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/svelte-charts@workspace:*" "@revolist/charts@workspace:*"
+pnpm build
+```
+
+Source: `packages/charts/packages/svelte-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/svelte-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/svelte-charts/-/svelte-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.
+
+```svelte
+<script lang="ts">
+  import { RevoChart, type ChartComponentOptions } from '@revolist/svelte-charts';
+  let options = $state.raw<ChartComponentOptions>({
+    chartType: 'line',
+    data: [{ month: 'Jan', revenue: 120 }, { month: 'Feb', revenue: 180 }],
+    mapping: { category: { field: 'month' }, series: [{ field: 'revenue' }] },
+  });
+</script>
+<RevoChart {options} onReady={chart => console.log(chart.model)}
+  style="height:400px" class="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/RevoChart.svelte

@@ -0,0 +1,23 @@
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import type { HTMLAttributes } from 'svelte/elements';
+  import { createChartComponentController } from '@revolist/charts/framework';
+  import type { ChartComponentController, ChartComponentOptions } from '@revolist/charts/framework';
+  import type { ChartRef } from '@revolist/charts';
+
+  interface Props extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    options: ChartComponentOptions;
+    onReady?: (chart: ChartRef) => void;
+  }
+  let { options, onReady, style = '', ...attributes }: Props = $props();
+  let host: HTMLDivElement;
+  let controller: ChartComponentController | undefined;
+  onMount(() => {
+    controller = createChartComponentController(host, chart => onReady?.(chart));
+    void controller.setOptions(options);
+    return () => { controller?.destroy(); controller = undefined; };
+  });
+  $effect(() => { const next = options; void controller?.setOptions(next); });
+</script>
+
+<div {...attributes} bind:this={host} style={`width:100%;height:300px;${style}`}></div>

package/dist/RevoChart.svelte.d.ts

@@ -0,0 +1,10 @@
+import type { HTMLAttributes } from 'svelte/elements';
+import type { ChartComponentOptions } from '@revolist/charts/framework';
+import type { ChartRef } from '@revolist/charts';
+interface Props extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    options: ChartComponentOptions;
+    onReady?: (chart: ChartRef) => void;
+}
+declare const RevoChart: import("svelte").Component<Props, {}, "">;
+type RevoChart = ReturnType<typeof RevoChart>;
+export default RevoChart;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { default as RevoChart } from './RevoChart.svelte';
+export type { ChartComponentOptions } from '@revolist/charts/framework';
+export type { ChartRef } from '@revolist/charts';

package/dist/index.js

@@ -0,0 +1 @@
+export { default as RevoChart } from './RevoChart.svelte';

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@revolist/svelte-charts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "3.0.2",
+  "description": "Svelte 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",
+      "svelte": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@revolist/charts": "3.0.2"
+  },
+  "peerDependencies": {
+    "svelte": "^5.55.0"
+  },
+  "devDependencies": {
+    "svelte": "^5.55.0",
+    "typescript": "~6.0.3",
+    "@sveltejs/package": "^2.5.0",
+    "svelte-check": "^4.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/revolist/revogrid-pro.git",
+    "directory": "packages/charts/packages/svelte-charts"
+  },
+  "svelte": "./dist/index.js",
+  "scripts": {
+    "build": "svelte-package -i src -o dist",
+    "lint": "svelte-check --tsconfig ./tsconfig.json",
+    "test": "node --test --test-name-pattern=\"^svelte charts\" ../../../../.github/workflows/chart-frameworks.test.mjs"
+  }
 }