velo-circuit

Framework-agnostic SVG circuit editor for Boukamp DSL circuits used in electrochemical impedance spectroscopy (EIS).

Documentation: jigonzalez930209.github.io/velo-circuit

Why velo-circuit

• Unified circuit model from DSL parsing to rendered SVG output
• Pure TypeScript core with no runtime UI framework dependency
• Official adapters for React, Vue, Svelte, Angular, Astro and Vanilla
• Built-in editor interactions: zoom, pan, drag, diagnostics, undo/redo
• Static SVG preview for docs and thumbnails — no editor chrome required
• Parameterized DSL: R0{50}-Q1{5e-5,0.8} with strict validation mode
• SVG-first canvas with world-space infinite grid
• createCircuitGrid() catalog view (DSL + SVG columns) and editor grid mode
• Full parity with velo-spectroz circuit elements (11 types including CC, HN)
• Designed to integrate with scientific tooling such as velo-spectroz
• Sidebar export (extended preset): SVG with/without parameters, full DSL download, optional dark export theme; transparent SVG background by default

Element types (11)

Circuit symbols use the outline symbol design system: outline-only glyphs, 2.0 px base stroke, and per-kind stroke colors. Parameter counts and DSL syntax are documented in Element Types.

| Code | Element | Params | |------|---------|--------| | R | Resistor | 1 | | C | Capacitor | 1 | | L | Inductor | 1 | | Q | CPE | 2 | | W | Warburg Infinite | 1 | | Ws | Warburg Short | 2 | | Wo | Warburg Open | 2 | | G | Gerischer | 2 | | Pdw | Parallel Diffusion Warburg | 4 | | CC | Cole-Cole | 3 | | HN | Havriliak-Negami | 4 |

Install

pnpm add velo-circuit

or:

npm install velo-circuit

Quick Usage (Vanilla)

import { createEditor } from 'velo-circuit';

const editor = createEditor();

editor.mount(document.getElementById('canvas'), {
  initialDsl: 'R0-p(R1,C1)-Wo2',
  width: 900,
  height: 560,
});

editor.on('ast-changed', () => {
  console.log(editor.getValue());
});

Circuit grid catalog

import { createCircuitGrid } from 'velo-circuit';

const grid = createCircuitGrid({
  height: 480,
  rowHeight: 120,
  strict: true,
  columns: [
    { id: 'dsl', label: 'Linear DSL', type: 'dsl', width: 320 },
    { id: 'svg', label: 'Circuit', type: 'svg', width: 220 },
    { id: 'params', label: 'Parameters', type: 'params', width: 200 },
  ],
  initialRows: [
    { id: 'r1', dsl: 'R0{50}-p(R1{100},C1{1e-5})' },
    { id: 'r2', dsl: 'R0{10}-CC1{50,1e-3,0.8}' },
  ],
});

grid.mount(document.getElementById('grid')!);
grid.on('row-double-click', (row) => console.log(row));

Static SVG preview

Render read-only circuit diagrams without mounting the editor:

import { renderDslPreviewSvg } from 'velo-circuit';

const svg = renderDslPreviewSvg('R0-p(R1,C1)-Wo2', {
  themeMode: 'dark',
  colorMode: 'multicolor',
  connectionStyle: 'curved',
});
// → standalone <svg class="circuit-preview">…</svg> with embedded CSS

See the Static SVG Rendering guide for export patterns and theme options.

Local Development

pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm docs:dev

Release Workflow

CI runs in GitHub Actions on Node 22 and 24. npm publish is triggered by pushing a tag like v1.0.0.

You can prepare and dispatch a release with:

pnpm release:prepare -- 1.0.0

What it does:

• runs typecheck, test, and build
• bumps package.json (and lockfile) to the provided version, or skips if already set
• creates commit chore(release): vX.Y.Z
• creates tag vX.Y.Z
• pushes branch and tag to GitHub

Required GitHub secret for publish workflow: NPM_TOKEN.

License

MIT