An open source design system that's fully customizable and agent ready
TypeScript
feat(vega): add @xds/vega subpackage — Vega-Lite chart wrapper (#1096)
L Reis79f5c5ed7ac5
diff --git a/apps/storybook/package.json b/apps/storybook/package.jsonindex 7364674e00..62b304e346 100644--- a/apps/storybook/package.json+++ b/apps/storybook/package.json@@ -12,7 +12,10 @@"@xds/theme-neutral": "*","react": "^19.2.5","react-dom": "^19.2.5",- "unplugin": "^2.3.11"+ "unplugin": "^2.3.11",+ "@xds/vega": "*",+ "vega": "^6.2.0",+ "vega-lite": "^6.4.2"},"devDependencies": {"@storybook/addon-essentials": "^8.6.17",diff --git a/apps/storybook/stories/VegaChart.stories.tsx b/apps/storybook/stories/VegaChart.stories.tsxnew file mode 100644index 0000000000..24153da93d--- /dev/null+++ b/apps/storybook/stories/VegaChart.stories.tsx@@ -0,0 +1,98 @@+import type {Meta, StoryObj} from '@storybook/react';+import {XDSVegaChart} from '@xds/vega';+import type {AnySpec} from '@xds/vega';++/**+ * Radial plot from the official Vega example gallery.+ * Encodes two values as the angle and radius of an arc.+ *+ * @see https://github.com/vega/vega/blob/main/docs/examples/radial-plot.vg.json+ */+const radialPlotSpec: AnySpec = {+ $schema: 'https://vega.github.io/schema/vega/v6.json',+ description:+ 'A basic radial plot that encodes two values as the angle and radius of an arc.',+ width: 200,+ height: 200,+ data: [+ {+ name: 'table',+ values: [12, 23, 47, 6, 52, 19],+ transform: [{type: 'pie', field: 'data'}],+ },+ ],+ scales: [+ {+ name: 'r',+ type: 'sqrt',+ domain: {data: 'table', field: 'data'},+ zero: true,+ range: [20, 100],+ },+ ],+ marks: [+ {+ type: 'arc',+ from: {data: 'table'},+ encode: {+ enter: {+ x: {field: {group: 'width'}, mult: 0.5},+ y: {field: {group: 'height'}, mult: 0.5},+ startAngle: {field: 'startAngle'},+ endAngle: {field: 'endAngle'},+ innerRadius: {value: 20},+ outerRadius: {scale: 'r', field: 'data'},+ stroke: {value: '#fff'},+ },+ update: {+ fill: {value: '#ccc'},+ },+ hover: {+ fill: {value: 'pink'},+ },+ },+ },+ {+ type: 'text',+ from: {data: 'table'},+ encode: {+ enter: {+ x: {field: {group: 'width'}, mult: 0.5},+ y: {field: {group: 'height'}, mult: 0.5},+ radius: {scale: 'r', field: 'data', offset: 8},+ theta: {signal: '(datum.startAngle + datum.endAngle)/2'},+ fill: {value: '#000'},+ align: {value: 'center'},+ baseline: {value: 'middle'},+ text: {field: 'data'},+ },+ },+ },+ ],+};++const meta: Meta<typeof XDSVegaChart> = {+ title: 'Vega/XDSVegaChart',+ component: XDSVegaChart,+ tags: ['autodocs'],+ parameters: {+ layout: 'centered',+ },+ argTypes: {+ renderer: {+ control: 'radio',+ options: ['svg', 'canvas'],+ description: 'Vega rendering backend',+ },+ },+};++export default meta;+type Story = StoryObj<typeof XDSVegaChart>;++export const RadialPlot: Story = {+ name: 'Radial Plot',+ args: {+ spec: radialPlotSpec,+ },+};diff --git a/package.json b/package.jsonindex 5035de6479..a4b7642fc3 100644--- a/package.json+++ b/package.json@@ -9,7 +9,7 @@"internal/*"],"scripts": {- "build": "yarn workspace @xds/core build && yarn workspace @xds/theme-default build && yarn workspace @xds/theme-neutral build && yarn workspace @xds/theme-brutalist build && yarn workspace @xds/theme-daily build && yarn workspace @xds/theme-whatsapp build && yarn workspace @xds/theme-meta build",+ "build": "yarn workspace @xds/core build && yarn workspace @xds/vega build && yarn workspace @xds/theme-default build && yarn workspace @xds/theme-neutral build && yarn workspace @xds/theme-brutalist build && yarn workspace @xds/theme-daily build && yarn workspace @xds/theme-whatsapp build && yarn workspace @xds/theme-meta build","dev": "yarn workspace @xds/storybook dev","test": "vitest run","test:watch": "vitest",diff --git a/packages/README.md b/packages/README.mdindex 2f516e4fa5..f94443a098 100644--- a/packages/README.md+++ b/packages/README.md@@ -4,6 +4,7 @@ Published npm packages for the XDS design system.<!-- SYNC: When files in this directory change, update this document. -->-| Directory | Role | Purpose |-| --------- | ------- | ---------------------------------------- |-| `core/` | Primary | Core UI components library (`@xds/core`) |+| Directory | Role | Purpose |+| --------- | ------- | ------------------------------------------------- |+| `core/` | Primary | Core UI components library (`@xds/core`) |+| `vega/` | Add-on | Vega-Lite chart wrapper components (`@xds/vega`) |diff --git a/packages/vega/README.md b/packages/vega/README.mdnew file mode 100644index 0000000000..ece952c75b--- /dev/null+++ b/packages/vega/README.md@@ -0,0 +1,161 @@+# @xds/vega++XDS Vega wrapper -- chart and data visualization components.++Renders [Vega](https://vega.github.io/vega/) and [Vega-Lite](https://vega.github.io/vega-lite/) specifications via the Vega runtime. The component inspects `$schema` to decide whether to compile (Vega-Lite) or render directly (Vega), validates the schema URL before doing either, and exposes the full Vega `parse()` and `View` construction APIs as props.++<!-- SYNC: When files in this directory change, update this document. -->++## File Manifest++| File | Role | Purpose |+|------|------|---------|+| `package.json` | Config | Package metadata, deps, build scripts |+| `tsconfig.json` | Config | TypeScript compiler config (extends root) |+| `tsup.config.ts` | Config | Build config -- CJS + ESM + `.d.ts` outputs |+| `src/index.ts` | Barrel | Public API surface |+| `src/XDSVegaChart.tsx` | Component | Inspects `$schema`, compiles or renders, owns View lifecycle |+| `src/schema.ts` | Utility | Parses and validates Vega/Vega-Lite `$schema` URLs |+| `src/types.ts` | Types | Shared TypeScript types for this package |++## Installation++```bash+yarn add @xds/vega vega vega-lite+```++## Usage++### Vega-Lite spec (compiled automatically)++```tsx+import {XDSVegaChart} from '@xds/vega';++<XDSVegaChart+ spec={{+ $schema: 'https://vega.github.io/schema/vega-lite/v5.json',+ mark: 'bar',+ data: {values: [{a: 'A', b: 28}, {a: 'B', b: 55}]},+ encoding: {+ x: {field: 'a', type: 'ordinal'},+ y: {field: 'b', type: 'quantitative'},+ },+ }}+/>+```++### Vega spec (rendered directly, no compilation)++```tsx+<XDSVegaChart+ spec={{+ $schema: 'https://vega.github.io/schema/vega/v5.json',+ marks: [...],+ }}+/>+```++### Full configuration++```tsx+<XDSVegaChart+ spec={spec}+ parseConfig={{background: '#1a1a1a'}}+ parseOptions={{ast: true}}+ viewOptions={{+ renderer: 'canvas',+ logLevel: 1,+ tooltip: myTooltipHandler,+ locale: myLocale,+ loader: myLoader,+ }}+ onReady={view => {+ view.addSignalListener('highlight', (name, value) => {+ console.log('signal:', name, value);+ });+ }}+ onError={err => console.error('Chart error:', err.message)}+/>+```++## API++### `<XDSVegaChart>`++| Prop | Type | Default | Description |+|------|------|---------|-------------|+| `spec` | `AnySpec` | -- | Vega or Vega-Lite spec with `$schema` (required) |+| `data` | `ViewData` | -- | Initial dataset values — `{datasetName: tuples[]}` |+| `compileOptions` | `CompileOptions` | -- | Options passed to `compile(spec, options)` — Vega-Lite only |+| `parseConfig` | `Config` | -- | Vega config passed to `parse(spec, config)` |+| `parseOptions` | `ParseOptions` | -- | Options passed to `parse(spec, config, options)` |+| `viewOptions` | `Omit<ViewOptions, 'container'>` | -- | Options passed to `new View(runtime, options)` |+| `className` | `string` | -- | CSS class on the container div |+| `style` | `CSSProperties` | -- | Inline styles on the container div |+| `onReady` | `(view: View) => void` | -- | Called with the live Vega View when ready |+| `onError` | `(err: Error) => void` | -- | Called on schema error, compile failure, or render failure |++`viewOptions` maps directly to [`ViewOptions`](https://vega.github.io/vega/docs/api/view/) with `container` omitted (always set by the component). Notable fields:++| `viewOptions` field | Type | Description |+|---|---|---|+| `renderer` | `'svg' \| 'canvas'` | Rendering backend (default: `'svg'`) |+| `hover` | `boolean` | Enable hover encoding (default: `true`) |+| `logLevel` | `number` | Vega log verbosity |+| `logger` | `LoggerInterface` | Custom logger |+| `tooltip` | `TooltipHandler` | Custom tooltip handler |+| `locale` | `LocaleFormatters` | Number and time format locale |+| `loader` | `Loader` | Custom data loader |+| `background` | `Color` | Chart background color |++`compileOptions` fields (Vega-Lite specs only, ignored otherwise):++| `compileOptions` field | Type | Description |+|---|---|---|+| `config` | `VegaLiteConfig` | Vega-Lite config merged on top of the spec's config |+| `logger` | `LoggerInterface` | Custom logger used during compilation |+| `fieldTitle` | `(fieldDef, config) => string` | Custom field title formatter |++`parseOptions` fields:++| `parseOptions` field | Type | Description |+|---|---|---|+| `ast` | `boolean` | Retain expression AST in the runtime (useful for tooling) |++### Data loading++`data` maps dataset names to tuple arrays and is applied via `view.data(name, tuples)` during View initialization, before the first render. It is *not reactive* — changes after mount are ignored.++To update data dynamically after render, use `onReady` to get the live View and drive it yourself:++```tsx+<XDSVegaChart+ spec={spec}+ data={{table: [{category: 'A', value: 28}, {category: 'B', value: 55}]}}+ onReady={view => {+ // Later, update data dynamically:+ view.data('table', newRows);+ view.runAsync();+ }}+/>+```++### `parseSchema(schema)` (exported utility)++Parses and validates a Vega `$schema` URL. Returns:+- `{ok: true, library: 'vega' | 'vega-lite', version: string}` on success+- `{ok: false, error: string}` if the URL is missing, malformed, or names an unknown library++## Schema validation++`XDSVegaChart` validates `spec.$schema` before doing any work. It will call `onError` (and render nothing) if:++- `$schema` is missing or not a string+- The URL doesn't match the expected format (`schema/{library}/{version}.json`)+- The library name is not `vega` or `vega-lite`++## Build++```bash+yarn workspace @xds/vega build+```diff --git a/packages/vega/package.json b/packages/vega/package.jsonnew file mode 100644index 0000000000..ea96331bb7--- /dev/null+++ b/packages/vega/package.json@@ -0,0 +1,39 @@+{+ "name": "@xds/vega",+ "version": "0.0.12",+ "description": "XDS Vega wrapper \u2014 chart and data visualization components",+ "main": "./dist/index.js",+ "module": "./dist/index.mjs",+ "types": "./dist/index.d.ts",+ "exports": {+ ".": {+ "source": "./src/index.ts",+ "types": "./dist/index.d.ts",+ "import": "./dist/index.mjs",+ "require": "./dist/index.js"+ }+ },+ "files": [+ "dist",+ "src"+ ],+ "scripts": {+ "build": "tsup",+ "dev": "tsup --watch",+ "typecheck": "tsc --noEmit"+ },+ "peerDependencies": {+ "react": ">=19.0.0",+ "react-dom": ">=19.0.0",+ "vega": ">=6.0.0",+ "vega-lite": ">=6.0.0"+ },+ "devDependencies": {+ "@types/react": "^19.2.14",+ "tsup": "^8.3.0",+ "typescript": "^5.7.0",+ "vega": "^6.2.0",+ "vega-lite": "^6.4.2",+ "vega-util": "^1.17.2"+ }+}diff --git a/packages/vega/src/XDSVegaChart.tsx b/packages/vega/src/XDSVegaChart.tsxnew file mode 100644index 0000000000..0a8bec6799--- /dev/null+++ b/packages/vega/src/XDSVegaChart.tsx@@ -0,0 +1,172 @@+/**+ * @file XDSVegaChart.tsx+ * @input A Vega or Vega-Lite spec (distinguished by $schema), parse config/options, view options, and data+ * @output A React component that renders the spec via the Vega runtime+ * @position Primary component in @xds/vega; owns the Vega View lifecycle+ *+ * SYNC: When modified, update /packages/vega/README.md+ */++import React, {useEffect, useRef} from 'react';+import {parse, View} from 'vega';+import {compile} from 'vega-lite';+import {parseSchema} from './schema';+import type {XDSVegaChartProps, VegaSpec, VegaLiteSpec} from './types';++/**+ * `XDSVegaChart` renders a Vega or Vega-Lite specification using the Vega runtime.+ *+ * The component inspects `spec.$schema` to determine how to handle the spec:+ * - `vega-lite` schema -> compiled to Vega via `vega-lite`'s `compile()`, then rendered+ * - `vega` schema -> rendered directly without compilation+ * - Invalid / missing `$schema` -> calls `onError` and renders nothing+ *+ * Parse and view construction are fully configurable via `parseConfig`,+ * `parseOptions`, and `viewOptions`, which map directly to the Vega API:+ *+ * vega.parse(spec, parseConfig, parseOptions)+ * new vega.View(runtime, { ...viewOptions, container })+ *+ * Initial dataset values can be provided via `data`. They are loaded once+ * during View initialization, before the first render, and are not reactive.+ *+ * It owns the full `View` lifecycle: creates the view on mount, re-creates+ * it when `spec`, `parseConfig`, `parseOptions`, or `viewOptions` changes,+ * and calls `view.finalize()` on cleanup to release all runtime resources.+ *+ * Callbacks (`onReady`, `onError`) are stable across renders via refs --+ * you don't need to memoize them. Pass stable references (or `useMemo`)+ * for `parseConfig`, `parseOptions`, `viewOptions`, and `data` to avoid+ * unnecessary re-renders.+ *+ * Note: this component does not accept `xstyle` because `@xds/vega` does not+ * depend on StyleX. Use `className` or `style` for layout overrides.+ *+ * @example+ * ```+ * import {XDSVegaChart} from '@xds/vega';+ *+ * // Vega-Lite spec -- compiled automatically+ * <XDSVegaChart+ * spec={{+ * $schema: 'https://vega.github.io/schema/vega-lite/v5.json',+ * mark: 'bar',+ * data: {name: 'table'},+ * encoding: {+ * x: {field: 'a', type: 'ordinal'},+ * y: {field: 'b', type: 'quantitative'},+ * },+ * }}+ * data={{table: [{a: 'A', b: 28}, {a: 'B', b: 55}]}}+ * />+ *+ * // Vega spec -- rendered directly+ * <XDSVegaChart+ * spec={{$schema: 'https://vega.github.io/schema/vega/v5.json', marks: []}}+ * parseConfig={{background: '#1a1a1a'}}+ * viewOptions={{logLevel: 1, tooltip: myTooltipHandler}}+ * />+ * ```+ */+export function XDSVegaChart({+ spec,+ data,+ compileOptions,+ parseConfig,+ parseOptions,+ viewOptions,+ className,+ style,+ ref,+ onReady,+ onError,+ ...props+}: XDSVegaChartProps) {+ const containerRef = useRef<HTMLDivElement>(null);++ // Keep callbacks in refs so they don't need to be in the dep array.+ const onReadyRef = useRef(onReady);+ const onErrorRef = useRef(onError);+ onReadyRef.current = onReady;+ onErrorRef.current = onError;++ useEffect(() => {+ const container = containerRef.current;+ if (!container) return;++ let cancelled = false;+ let view: View | null = null;++ const fail = (err: unknown) => {+ if (!cancelled) {+ onErrorRef.current?.(err instanceof Error ? err : new Error(String(err)));+ }+ };++ try {+ // Validate $schema and resolve the library kind.+ const schemaResult = parseSchema(spec.$schema);+ if (!schemaResult.ok) {+ fail(new Error(schemaResult.error));+ return;+ }++ // Compile Vega-Lite -> Vega if needed; otherwise use the spec directly.+ const vegaSpec: VegaSpec =+ schemaResult.library === 'vega-lite'+ ? compile(spec as VegaLiteSpec, compileOptions).spec+ : (spec as VegaSpec);++ // parse(spec, config?, options?) -> Runtime+ const runtime = parse(vegaSpec, parseConfig, parseOptions);++ // new View(runtime, viewOptions) -- container is always injected by us.+ view = new View(runtime, {+ hover: true,+ ...viewOptions,+ container,+ });++ // Load initial data into named datasets before the first render.+ // data is not reactive -- changes after mount are ignored.+ if (data) {+ for (const [name, tuples] of Object.entries(data)) {+ view.data(name, tuples);+ }+ }++ view+ .runAsync()+ .then(() => {+ if (cancelled) {+ view?.finalize();+ return;+ }+ onReadyRef.current?.(view!);+ })+ .catch(fail);+ } catch (err) {+ fail(err);+ }++ return () => {+ cancelled = true;+ view?.finalize();+ };+ }, [spec, data, compileOptions, parseConfig, parseOptions, viewOptions]);++ return (+ <div+ ref={node => {+ containerRef.current = node;+ if (typeof ref === 'function') ref(node);+ else if (ref) (ref as React.MutableRefObject<HTMLDivElement | null>).current = node;+ }}+ className={className}+ style={style}+ {...props}+ />+ );+}++XDSVegaChart.displayName = 'XDSVegaChart';diff --git a/packages/vega/src/index.ts b/packages/vega/src/index.tsnew file mode 100644index 0000000000..e28b54855a--- /dev/null+++ b/packages/vega/src/index.ts@@ -0,0 +1,23 @@+/**+ * @file index.ts+ * @input All public exports for @xds/vega+ * @output Public API surface for the XDS Vega wrapper package+ * @position Barrel export; entry point for consumers of @xds/vega+ *+ * SYNC: When modified, update /packages/vega/README.md+ */++/**+ * @file index.ts+ * @input All public exports for @xds/vega+ * @output Public API surface for the XDS Vega wrapper package+ * @position Barrel export; entry point for consumers of @xds/vega+ *+ * SYNC: When modified, update /packages/vega/README.md+ */++export {XDSVegaChart} from './XDSVegaChart';+export {parseSchema} from './schema';+export type {XDSVegaChartProps, AnySpec, ViewData, VegaSpec, VegaLiteSpec, CompileOptions, ParseOptions, Config, ViewOptions, LoggerInterface} from './types';+export type {SchemaLibrary, SchemaResult} from './schema';+diff --git a/packages/vega/src/schema.ts b/packages/vega/src/schema.tsnew file mode 100644index 0000000000..9a94844b02--- /dev/null+++ b/packages/vega/src/schema.ts@@ -0,0 +1,61 @@+/**+ * @file schema.ts+ * @input A spec object (Vega or Vega-Lite)+ * @output The resolved schema kind: 'vega', 'vega-lite', or an error+ * @position Utility; consumed by XDSVegaChart to decide whether to compile+ *+ * SYNC: When modified, update /packages/vega/README.md+ */++/** Known libraries in the Vega schema URL namespace. */+export type SchemaLibrary = 'vega' | 'vega-lite';++/** Result of parsing a $schema URL. */+export type SchemaResult =+ | {ok: true; library: SchemaLibrary; version: string}+ | {ok: false; error: string};++/**+ * Pattern matching the official Vega schema URL format:+ * https://vega.github.io/schema/{library}/{version}.json+ * Also tolerates proxy-prefixed URLs (anything before "schema/").+ *+ * @see https://github.com/vega/schema+ */+const SCHEMA_RE = /schema\/([\w-]+)\/([\w.-]+)\.json$/;++/**+ * Parse a Vega or Vega-Lite `$schema` URL.+ *+ * Returns `{ ok: true, library, version }` on success, or+ * `{ ok: false, error }` if the URL is missing, not a string,+ * doesn't match the expected format, or names an unknown library.+ */+export function parseSchema(schema: unknown): SchemaResult {+ if (schema === undefined || schema === null) {+ return {ok: false, error: 'Spec is missing a $schema field. Add "$schema": "https://vega.github.io/schema/vega/v5.json" or the vega-lite equivalent.'};+ }++ if (typeof schema !== 'string') {+ return {ok: false, error: `$schema must be a string, got ${typeof schema}.`};+ }++ const match = SCHEMA_RE.exec(schema);+ if (!match) {+ return {+ ok: false,+ error: `Unrecognized $schema URL: "${schema}". Expected format: https://vega.github.io/schema/{vega|vega-lite}/{version}.json`,+ };+ }++ const [, library, version] = match;++ if (library !== 'vega' && library !== 'vega-lite') {+ return {+ ok: false,+ error: `Unknown schema library "${library}". Must be "vega" or "vega-lite".`,+ };+ }++ return {ok: true, library, version};+}diff --git a/packages/vega/src/types.ts b/packages/vega/src/types.tsnew file mode 100644index 0000000000..8057721939--- /dev/null+++ b/packages/vega/src/types.ts@@ -0,0 +1,176 @@+/**+ * @file types.ts+ * @input Vega and Vega-Lite spec types, and the XDS Vega wrapper API surface+ * @output Shared TypeScript types for @xds/vega+ * @position Type definitions; imported by all components in this package+ *+ * SYNC: When modified, update /packages/vega/README.md+ */++import type React from 'react';+import type {Spec as VegaSpec, Config, View, ViewOptions} from 'vega';+import type {LoggerInterface} from 'vega-util';+import type {TopLevelSpec as VegaLiteSpec, Config as VegaLiteConfig} from 'vega-lite';++export type {VegaSpec, VegaLiteSpec, Config, View, ViewOptions, LoggerInterface};++/**+ * Options for the Vega-Lite `compile()` function.+ *+ * Mirrors `CompileOptions` from `vega-lite/src/compile/compile.ts`, which is+ * not part of the public vega-lite export surface, so we redeclare it here.+ *+ * @see https://github.com/vega/vega-lite/blob/main/src/compile/compile.ts+ */+export interface CompileOptions {+ /**+ * Vega-Lite config merged on top of the spec's own config before compilation.+ */+ config?: VegaLiteConfig;+ /**+ * Custom logger used during compilation.+ * @see https://github.com/vega/vega/blob/main/packages/vega-util/src/logger.ts+ */+ logger?: LoggerInterface;+ /**+ * Custom field title formatter. Overrides the global singleton used by+ * vega-lite to produce axis/legend/header titles from field definitions.+ *+ * Typed loosely to avoid coupling to vega-lite's unexported internal types.+ */+ // Typed loosely to avoid coupling to vega-lite's unexported internal types.+ fieldTitle?: (...args: unknown[]) => string;+}++/**+ * A spec accepted by `<XDSVegaChart>`. Must include a `$schema` field --+ * the component uses it to decide whether to compile (Vega-Lite) or+ * render directly (Vega).+ */+export type AnySpec = (VegaSpec | VegaLiteSpec) & {$schema: string};++/**+ * Options forwarded to `vega.parse(spec, config, parseOptions)`.+ * @see https://vega.github.io/vega/docs/api/view/#view_parse+ */+export interface ParseOptions {+ /**+ * When `true`, the parser retains the abstract syntax tree (AST) of+ * Vega expressions in the runtime. Useful for introspection and tooling.+ * Defaults to `false`.+ */+ ast?: boolean;+}++/**+ * Initial data to load into named Vega datasets after the View is created,+ * before the first render.+ *+ * Each key is a dataset name matching a `data` entry in the Vega spec.+ * Each value is the array of tuples passed to `view.data(name, tuples)`.+ *+ * This mirrors the setter overload of the View data API:+ * `view.data(name: string, tuples: any[]): this`+ *+ * @see https://vega.github.io/vega/docs/api/view/#view_data+ *+ * @example+ * ```+ * data={{+ * table: [{category: 'A', value: 28}, {category: 'B', value: 55}],+ * }}+ * ```+ */+export type ViewData = Record<string, unknown[]>;++/**+ * Props for the `<XDSVegaChart>` component.+ *+ * Extends `React.HTMLAttributes<HTMLDivElement>` (minus `contentEditable`,+ * `dangerouslySetInnerHTML`) for full DOM event passthrough — drag, pointer,+ * keyboard, clipboard, `data-testid`, etc.+ *+ * Note: unlike other XDS components, this component does not accept `xstyle`+ * because `@xds/vega` does not depend on StyleX. Use `className` or `style`+ * for layout overrides instead.+ */+export interface XDSVegaChartProps extends Omit<+ React.HTMLAttributes<HTMLDivElement>,+ | 'contentEditable'+ | 'dangerouslySetInnerHTML'+ | 'suppressContentEditableWarning'+ | 'suppressHydrationWarning'+ | 'onError'+> {+ /**+ * Ref forwarded to the root container div.+ */+ ref?: React.Ref<HTMLDivElement>;+ /**+ * A Vega or Vega-Lite specification object.+ *+ * Must include a `$schema` field matching the official Vega schema URL+ * format: `https://vega.github.io/schema/{vega|vega-lite}/{version}.json`+ *+ * The component inspects `$schema` to determine how to handle the spec:+ * - `vega-lite` -> compiled to Vega via `vega-lite`'s `compile()`, then rendered+ * - `vega` -> rendered directly without compilation+ *+ * @see https://vega.github.io/vega/docs/specification/+ * @see https://vega.github.io/vega-lite/docs/spec.html+ */+ spec: AnySpec;+ /**+ * Initial data for named Vega datasets, applied via `view.data(name, tuples)`+ * after the View is created and before the first render.+ *+ * This prop is *not reactive* — it is only read during View initialization.+ * Changes after mount are ignored. To update data dynamically, use `onReady`+ * to access the live View and call `view.data(name, tuples)` + `view.runAsync()`+ * directly.+ *+ * Each key must match a dataset name defined in the spec's `data` array.+ *+ * @see https://vega.github.io/vega/docs/api/view/#view_data+ */+ data?: ViewData;+ /**+ * Options passed to `vega-lite`'s `compile()` function.+ * Only applied when `spec.$schema` identifies a `vega-lite` spec.+ * Ignored for native Vega specs.+ * @see https://github.com/vega/vega-lite/blob/main/src/compile/compile.ts+ */+ compileOptions?: CompileOptions;+ /**+ * Vega config object passed as the second argument to `vega.parse()`.+ * Overrides config values embedded in the spec.+ * @see https://vega.github.io/vega/docs/config/+ */+ parseConfig?: Config;+ /**+ * Options passed as the third argument to `vega.parse()`.+ * Currently only supports `{ ast: boolean }`.+ * @see https://vega.github.io/vega/docs/api/view/#view_parse+ */+ parseOptions?: ParseOptions;+ /**+ * Options passed directly to `new vega.View(runtime, viewOptions)`.+ * Controls renderer backend, logger, tooltip handler, locale, loader,+ * background color, hover behavior, and more.+ *+ * Note: `container` is always set by the component and will be overridden.+ *+ * @see https://vega.github.io/vega/docs/api/view/+ */+ viewOptions?: Omit<ViewOptions, 'container'>;+ /**+ * Called with the live Vega `View` once the chart has rendered.+ * Use this to attach signal listeners, stream data, or drive animations.+ */+ onReady?: (view: View) => void;+ /**+ * Called when the `$schema` is invalid, compilation fails, or the+ * Vega runtime throws during rendering.+ */+ onError?: (error: Error) => void;+}diff --git a/packages/vega/tsconfig.json b/packages/vega/tsconfig.jsonnew file mode 100644index 0000000000..49e05cea1e--- /dev/null+++ b/packages/vega/tsconfig.json@@ -0,0 +1,8 @@+{+ "extends": "../../tsconfig.json",+ "compilerOptions": {+ "outDir": "./dist",+ "rootDir": "./src"+ },+ "include": ["src"]+}diff --git a/packages/vega/tsup.config.ts b/packages/vega/tsup.config.tsnew file mode 100644index 0000000000..6e66510412--- /dev/null+++ b/packages/vega/tsup.config.ts@@ -0,0 +1,19 @@+/**+ * @file tsup.config.ts+ * @input Uses tsup+ * @output Bundle configuration for CJS/ESM outputs with TypeScript declarations+ * @position Build config; defines entry points and output formats for @xds/vega+ *+ * SYNC: When modified, update this header and /packages/vega/README.md+ */++import {defineConfig} from 'tsup';++export default defineConfig({+ entry: ['src/index.ts'],+ format: ['cjs', 'esm'],+ dts: true,+ splitting: true,+ clean: true,+ external: ['react', 'react-dom', 'vega', 'vega-lite'],+});