tessl/npm-vega-embed

Publish Vega visualizations as embedded web components.

—

Pending

Overview

Eval results

Files

Utilities and Helpers

Name: tessl/npm-vega-embed
Author: tessl

Utility functions for mode detection, URL validation, and configuration merging to support the core embedding functionality. These helpers provide common functionality used throughout the vega-embed library.

Capabilities

Mode Detection

Automatically determine whether a specification is Vega or Vega-Lite format.

/**
 * Guess the mode (vega or vega-lite) of a specification
 * @param spec - The visualization specification to analyze
 * @param providedMode - Optional mode override
 * @returns The detected or provided mode
 */
function guessMode(spec: VisualizationSpec, providedMode?: Mode): Mode;

type Mode = 'vega' | 'vega-lite';

Usage Examples:

import { guessMode } from "vega-embed";

// Detect mode from spec
const vlSpec = {
  mark: "bar",
  data: { values: [{ a: "A", b: 28 }] },
  encoding: { x: { field: "a" }, y: { field: "b" } }
};

const mode = guessMode(vlSpec); // Returns 'vega-lite'

// With $schema, mode is detected from schema URL
const specWithSchema = {
  $schema: "https://vega.github.io/schema/vega-lite/v5.json",
  mark: "point",
  // ...
};

const detectedMode = guessMode(specWithSchema); // Returns 'vega-lite'

// Override mode detection
const forcedMode = guessMode(vlSpec, 'vega'); // Returns 'vega' (with warning)

Mode Detection Logic

The function uses several strategies to determine the specification format:

Schema Analysis: If $schema is present, parses the URL to determine format
Vega-Lite Indicators: Looks for mark, encoding, layer, hconcat, vconcat, repeat, facet properties
Fallback: Defaults to 'vega' if no clear indicators are found

URL Validation

Check if a string represents a valid URL for loading specifications.

/**
 * Check if a string is a URL
 * @param s - String to test
 * @returns True if the string appears to be a URL
 */
function isURL(s: string): boolean;

Usage Examples:

import { isURL } from "vega-embed";

// Valid URLs
console.log(isURL("https://example.com/spec.json")); // true
console.log(isURL("http://localhost:3000/data.json")); // true
console.log(isURL("//cdn.example.com/chart.vg.json")); // true

// Not URLs
console.log(isURL("spec.json")); // false
console.log(isURL("{ mark: 'bar' }")); // false
console.log(isURL("/local/path.json")); // false

Deep Configuration Merging

Merge configuration objects recursively for options composition.

/**
 * Deep merge configuration objects
 * @param dest - Destination object to merge into
 * @param src - Source objects to merge from
 * @returns The merged destination object
 */
function mergeDeep<T>(dest: T, ...src: readonly DeepPartial<T>[]): T;

type DeepPartial<T> = {
  [P in keyof T]?: P extends unknown ? unknown : DeepPartial<T[P]>;
};

Usage Examples:

import { mergeDeep } from "vega-embed";

const baseConfig = {
  actions: { export: true, source: false },
  renderer: "canvas",
  theme: "default"
};

const userConfig = {
  actions: { source: true },
  width: 400
};

const merged = mergeDeep(baseConfig, userConfig);
// Result: {
//   actions: { export: true, source: true },
//   renderer: "canvas",
//   theme: "default",
//   width: 400
// }

Type Definitions

Core type definitions used throughout the utility functions.

type Mode = 'vega' | 'vega-lite';

type Config = VlConfig | VgConfig;

type ExpressionFunction = Record<string, any | { fn: any; visitor?: any }>;

type DeepPartial<T> = {
  [P in keyof T]?: P extends unknown ? unknown : DeepPartial<T[P]>;
};

Message Data Structure

Data structure for communication with external editors and tools.

interface MessageData {
  /** Specification as JSON string */
  spec: string;
  
  /** Optional file data */
  file?: unknown;
  
  /** Configuration object */
  config?: Config;
  
  /** Visualization mode */
  mode: Mode;
  
  /** Rendering backend */
  renderer?: Renderers;
}

This interface is used when communicating with the Vega Editor or other external tools through the post message system.

Version Information

Access to package version information.

/** Current version of vega-embed package */
const version: string;

Usage Examples:

import { version } from "vega-embed";

console.log(`Using vega-embed version ${version}`);

Re-exported Libraries

Access to the underlying Vega and Vega-Lite libraries.

/** Vega library re-export */
const vega: typeof vegaImport;

/** Vega-Lite library re-export with backwards compatibility */
let vegaLite: typeof vegaLiteImport;

Usage Examples:

import { vega, vegaLite } from "vega-embed";

// Access Vega functions directly
const view = new vega.View(vega.parse(spec));

// Access Vega-Lite compilation
const compiled = vegaLite.compile(vlSpec);

The vegaLite export includes backwards compatibility logic for older versions of Vega-Lite and browser environments.

Install with Tessl CLI