vanduo-hex-grid

name	vanduo-hex-grid
description	Use when building interactive hex grids with @vanduo-oss/hex-grid — a standalone canvas VdHexGrid (axial math, pan/zoom, terrain, pathfinding) with an optional Vue 3 wrapper. Covers install, the class + hex-math API, events, security, and caveats.

@vanduo-oss/hex-grid

Standalone canvas hex-grid for the Vanduo design system: VdHexGrid with axial hex math, pan/zoom, terrain, and BFS pathfinding. Theme-aware (reads --vd-* tokens); framework-agnostic core with an optional Vue 3 wrapper at ./vue.

Install

pnpm add @vanduo-oss/hex-grid

import { VdHexGrid } from "@vanduo-oss/hex-grid";

const grid = new VdHexGrid({ element, canvas, size: 30, width: 15, height: 10 });
grid.on("select", (hex) => console.log(hex));

Pure math helpers: import { hexToPixel, hexDistance } from "@vanduo-oss/hex-grid/hex-math". Vue 3 (optional peer vue >=3.3): import { VdHexGrid } from "@vanduo-oss/hex-grid/vue".

Architecture

• 2D canvas rendering of flat-top hexagons with pointer/touch (pan, pinch-zoom); theme-aware via a MutationObserver on --vd-* tokens.
• Axial (q/r) coordinates; pixel conversion, distance, and adjacency are pure functions in the hex-math subpath.
• Terrain layer (8 types) with yields/movement costs + BFS pathfinding.
• Optional Vue wrapper is SSR-safe (grid created on client mount; prop changes go through setters, no recreate).

API

• Constructor: new VdHexGrid({ element, canvas?, size=30, width=10, height=10, rotation=0 }).
• Events: on(event, cb) for select, zoom, pan, ready.
• Grid: setSize, setDimensions, setRotation, resetView, zoomIn/zoomOut, reset, fillRandom, getTransform, getHexCount, hasHex.
• Hexes: getHex(q,r), getAllHexes(), setHexFill(q,r,color), setHexData/getHexData/clearHexData.
• Terrain & movement: setHexTerrain/getHexTerrain, generateRandomTerrain, getValidMoves(q,r,points), getPath(sq,sr,eq,er) (BFS), hexDistance, exportTerrainData/importTerrainData.
• Rendering: setCustomRender(cb)/clearCustomRender(). Lifecycle: destroy() (disconnects observers — call before discarding).
• hex-math exports: hexToPixel, pixelToHex, axialRound, rotatePoint/unrotatePoint, getHexCorners, getAdjacentHexes, hexDistance, isPassable, getMovementCost, getTerrainYields, getTerrainColor; TerrainType, TERRAIN_COLORS, TERRAIN_YIELDS, TERRAIN_MOVEMENT_COSTS, DEFAULT_TERRAIN_COLOR.
• Vue: <VdHexGrid :size :width :height :rotation @select @zoom @pan @ready>; template ref exposes getInstance().

Security

• No eval / dynamic script execution; rendering is sandboxed to a canvas context.
• DOM-bound: requires a real HTMLElement + canvas context.

Caveats

• Canvas/DOM required — the core can't run in SSR directly; the Vue component is SSR-safe (creates the grid on mount).
• Call destroy() before discarding instances (disconnects the theme MutationObserver + media-query listeners).
• vue is an optional peer (vanilla consumers unaffected). OCEAN and MOUNTAIN are impassable (movement cost 999).

Docs

Full documentation and live demos: https://vanduo.dev