Skip to content

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.json
index 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.tsx
new file mode 100644
index 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.json
index 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.md
index 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.md
new file mode 100644
index 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.json
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.json
new file mode 100644
index 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.ts
new file mode 100644
index 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'],
+});