@vanduo-oss/vd3-cbun

The Vanduo components bundle for the vd3 line: Vue3-only charts, flowchart, hex-grid, and music-player consolidated into ONE package with tree-shakeable subpath exports. It replaces the four per-repo publishes (@vanduo-oss/charts, @vanduo-oss/flowchart, @vanduo-oss/hex-grid, @vanduo-oss/music-player) of the old line.

Status: 1.0.0 — first public release. All four component families are consolidated Vue3-only (vanilla auto-init/window-global layers excised), each on its own tree-shakeable subpath, with the esbuild metafile isolation guard in place.

Install

pnpm add @vanduo-oss/vd3-cbun

vue >=3.3.0 is a required peer dependency (the only runtime dep) — install it alongside if your project does not already depend on Vue. For correct theming, also provide the Vanduo --vd-* design tokens (see Theming).

Subpath-import model

Each component lives on its own subpath — importing one never pulls in another:

import { VdChart } from '@vanduo-oss/vd3-cbun/charts';
import '@vanduo-oss/vd3-cbun/charts/css';

import { VdFlowchart } from '@vanduo-oss/vd3-cbun/flowchart';
import '@vanduo-oss/vd3-cbun/flowchart/css';

import { VdHexGrid } from '@vanduo-oss/vd3-cbun/hex-grid';
import { hexToPixel } from '@vanduo-oss/vd3-cbun/hex-grid/hex-math';

import { VdMusicPlayer } from '@vanduo-oss/vd3-cbun/music-player';
import '@vanduo-oss/vd3-cbun/music-player/css';

The root import exposes only the per-component VERSION-constants map:

import { VD3_CBUN_VERSIONS } from '@vanduo-oss/vd3-cbun';

Each subpath entry (dist/<component>/index.js) re-exports both the Vue component and its framework-agnostic core (the core aliased with a Core suffix where the names collide — VdFlowchartCore, VdHexGridCore). Isolation is not a convention but a build guard: scripts/build.js bundles every entry separately with vue external, emits an esbuild metafile (dist/meta.json), and fails the build if any component entry's inputs reach outside its own src/<component>/ directory or if anything but vue is externalized. The package declares sideEffects: ["**/*.css"], so bundlers may drop any unused JS export while preserving the CSS side-effect imports. Inspect dist/meta.json to confirm tree-shaking downstream.

Notes:

• vue >=3.3.0 is a required peer dependency (the only runtime dep; never bundled — it stays external in both the esm and cjs outputs).
• Named exports only — no default exports on any subpath.
• No IIFE builds and no ./vue subpaths — the Vue bindings ARE the subpath exports; framework-agnostic cores stay exported alongside them.
• hex-grid ships no CSS (canvas-based; it reads --vd-* tokens via getComputedStyle).

Per-component version policy

The bundle's own semver (package.json version) is decoupled from the components inside it. Each component carries a VERSION constant tracked in component-versions.json at the repo root and asserted in tests against the exported VD3_CBUN_VERSIONS map. At bundle launch, charts, hex-grid, and music-player reset to 1.0.0; flowchart continues its old-line lineage at 1.2.0 because VD_FLOWCHART_VERSION is load-bearing — it is serialized into user documents via toJSON().version.

Theming

All four components render against Vanduo's --vd-* design tokens — the same tokens @vanduo-oss/vd3 defines. charts, flowchart, and hex-grid carry built-in fallbacks and degrade gracefully without them; music-player expects the tokens and renders with unset colors/backgrounds if none are provided. For correct theming, supply the tokens on an ancestor element — the simplest way is to ship the vd3 stylesheet:

import '@vanduo-oss/vd3/css'; // full tokens + component CSS
// …or the tokens-only layer:
import '@vanduo-oss/vd3/css/core';

The tokens consumed include --vd-bg-primary, --vd-bg-secondary, --vd-text-primary, --vd-text-muted, --vd-border-color, and --vd-color-primary. hex-grid reads them off the host element via getComputedStyle; the CSS-based components resolve them through var(--vd-*). (vd3 is not a package dependency of the bundle — any provider of the --vd-* tokens works — but it is the canonical source.)

Security

• One runtime dependency — the vue >=3.3.0 peer; nothing else is bundled or required (vue stays external in every esm/cjs output, and the build fails if any other module is externalized or any node_modules input is bundled).
• Hardened .npmrc: ignore-scripts, minimum-release-age, save-exact, strict-peer-dependencies, trust-policy=no-downgrade, block-exotic-subdeps, and an explicit registry.
• MIT licensed (LICENSE); the bundle vendors no third-party runtime code.

Exports

| Export | Contents | | ----------------------------------------- | ------------------------------------------------------------ | | @vanduo-oss/vd3-cbun | Root — the VD3_CBUN_VERSIONS per-component version map | | @vanduo-oss/vd3-cbun/charts | VdChart + typed chart wrappers, factories, scales, resolveTheme | | @vanduo-oss/vd3-cbun/charts/css | Charts stylesheet (dist/charts/vd3-charts.css) | | @vanduo-oss/vd3-cbun/flowchart | VdFlowchart + VdFlowchartCore, computeLayout, FLOWCHART_* | | @vanduo-oss/vd3-cbun/flowchart/css | Flowchart stylesheet (dist/flowchart/vd3-flowchart.css) | | @vanduo-oss/vd3-cbun/hex-grid | VdHexGrid + VdHexGridCore, VD_HEX_VERSION | | @vanduo-oss/vd3-cbun/hex-grid/hex-math | Pure coordinate/terrain math (hexToPixel, TerrainType, …) | | @vanduo-oss/vd3-cbun/music-player | VdMusicPlayer + MusicPlayer core | | @vanduo-oss/vd3-cbun/music-player/css | Music-player stylesheet (dist/music-player/vd3-music-player.css) |

Development

pnpm install
pnpm lint          # eslint
pnpm format:check  # prettier
pnpm test          # vitest unit/wrapper suites (jsdom + node)
pnpm build         # esbuild harness → dist/
pnpm test:types    # tsc --noEmit over tests/types (needs dist/ — run build first)
pnpm test:e2e      # Playwright canvas smoke, Chromium (needs dist/ — run build first)

test:types and test:e2e both consume the built dist/ output, so run pnpm build first (CI orders them after the build step). The type harness type-checks the shipped declarations by resolving the package's own exports map (self-reference → dist/<component>/*.d.ts); the Playwright fixtures (tests/e2e/fixtures/*.html) import the built ESM entries directly and are served over a dependency-free python3 -m http.server (the vue external is resolved to the locally installed browser build via an import map). Chromium must be installed once: pnpm exec playwright install chromium.

The published package declares a consumer-friendly engines.node >=20.19.0; the dev/CI toolchain pins Node 24 via packageManager + .github/workflows/ci.yml.

Documentation

• Agent / LLM reference — SKILL.md
• Changelog — CHANGELOG.md

License

MIT © Vanduo Open Source Foundation