An open source design system that's fully customizable and agent ready
TypeScript
docs(vega): document that specs are programs, with the untrusted-spec wiring (#5530)
Baraa Hamodi2bf24da207bb
diff --git a/packages/vega/README.md b/packages/vega/README.mdindex f8c488ec51..9010a460cf 100644--- a/packages/vega/README.md+++ b/packages/vega/README.md@@ -156,6 +156,43 @@ To update data dynamically after render, use `onReady` to get the live View and/>```+### Untrusted specs++A Vega/Vega-Lite spec is a program, not just data: Vega evaluates the+expression strings inside it (signals, event streams, encodings, filters)+and, by default, compiles them to JavaScript with the Function constructor.+A spec's `data` entries can also name URLs — including signal-built dynamic+ones — that the default loader will fetch with the page's credentials.++`<VegaChart>` renders the spec you give it with Vega's defaults, so those+defaults define the trust boundary: **only pass specs you author or+review.** If specs come from users, stored documents, or model output, wire+the safe evaluation mode through the existing pass-through options — Vega's+own guidance for untrusted specs:++```tsx+import {expressionInterpreter} from 'vega-interpreter';+import {loader} from 'vega';++<VegaChart+ spec={untrustedSpec}+ // Retain the expression AST and evaluate it interpreted (no Function+ // constructor). Slower, and a small subset of expressions is unsupported —+ // see the vega-interpreter README.+ parseOptions={{ast: true}}+ viewOptions={{+ expr: expressionInterpreter,+ // Restrict (or disable) what a spec may load. `mode: 'file'` with no+ // baseURL rejects everything; supply your own loader to allowlist hosts.+ loader: loader({mode: 'file'}),+ }}+/>;+```++`vega-interpreter` is a separate package (`npm install vega-interpreter`);+pair it with a `Content-Security-Policy` that omits `'unsafe-eval'` so the+boundary is enforced by the platform, not only by configuration.+### `parseSchema(schema)` (exported utility)Parses and validates a Vega `$schema` URL. Returns:diff --git a/packages/vega/src/types.ts b/packages/vega/src/types.tsindex 95ab8a6775..40023bc879 100644--- a/packages/vega/src/types.ts+++ b/packages/vega/src/types.ts@@ -12,9 +12,19 @@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';+import type {+ TopLevelSpec as VegaLiteSpec,+ Config as VegaLiteConfig,+} from 'vega-lite';-export type {VegaSpec, VegaLiteSpec, Config, View, ViewOptions, LoggerInterface};+export type {+ VegaSpec,+ VegaLiteSpec,+ Config,+ View,+ ViewOptions,+ LoggerInterface,+};/*** Options for the Vega-Lite `compile()` function.@@ -58,8 +68,12 @@ export type AnySpec = (VegaSpec | VegaLiteSpec) & {$schema: string};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`.+ * Vega expressions in the runtime instead of compiling them with the+ * Function constructor. Pair it with `viewOptions.expr` set to+ * `vega-interpreter`'s evaluator to run spec expressions interpreted —+ * the required configuration for specs you didn't author (see+ * "Untrusted specs" in the README). Also useful for introspection and+ * tooling. Defaults to `false`.*/ast?: boolean;}@@ -118,8 +132,18 @@ export interface VegaChartProps extends Omit<* - `vega-lite` -> compiled to Vega via `vega-lite`'s `compile()`, then rendered* - `vega` -> rendered directly without compilation*+ * **A spec is a program, not just data.** Vega evaluates the expression+ * strings inside a spec (signals, event streams, encodings, filters) and,+ * by default, compiles them with the Function constructor; a spec's data+ * sources can also name URLs the default loader will fetch, including+ * signal-built ones. Only render specs you author or review. For specs+ * from users, documents, or model output, wire the interpreter and a+ * restricted loader — see "Untrusted specs" in the README — and treat that+ * configuration as required, not optional.+ ** @see https://vega.github.io/vega/docs/specification/* @see https://vega.github.io/vega-lite/docs/spec.html+ * @see https://vega.github.io/vega/usage/interpreter/*/spec: AnySpec;/**