medicine-wheel

@medicine-wheel/graph-viz

Medicine Wheel graph visualization — circular layout with four-direction node positioning, ceremony-aware edges, and OCAP® indicators.

[!WARNING] Experimental alpha. Part of the Medicine Wheel Developer Suite, which is under active development. APIs change between patch versions and all packages move in lockstep — pin exact versions. See ALPHA.md.

Features

Circular medicine wheel layout — nodes positioned by direction (East/South/West/North)
Direction quadrant backgrounds with Ojibwe names
Ceremony-aware edges — gold dashed lines for honored relations
OCAP® indicators — red/green dots showing compliance status
Wilson alignment halos — color-coded rings showing relational accountability
Hover highlighting — dims unconnected nodes, highlights neighbors
Pure SVG React — no D3 runtime dependency, SSR-compatible
Dark mode by default

Installation

npm install @medicine-wheel/graph-viz @medicine-wheel/ontology-core

Usage

import { MedicineWheelGraph, buildGraphData } from '@medicine-wheel/graph-viz';

// From ontology-core data
const graphData = buildGraphData(relationalNodes, relationalEdges);

<MedicineWheelGraph
  data={graphData}
  width={600}
  height={600}
  showDirectionLabels
  showQuadrants
  showNodeLabels
  darkMode
  onNodeClick={(node) => console.log('Clicked:', node.label)}
/>

Manual data

const data = {
  nodes: [
    { id: 'n1', label: 'Ceremony', type: 'spirit', direction: 'east' },
    { id: 'n2', label: 'Elder', type: 'human', direction: 'north' },
  ],
  links: [
    { source: 'n1', target: 'n2', label: 'guides', ceremonyHonored: true },
  ],
};

<MedicineWheelGraph data={data} />

API

`<MedicineWheelGraph>` Props

Prop	Type	Default	Description
`data`	`MWGraphData`	required	Nodes and links
`width`	`number`	600	SVG width
`height`	`number`	600	SVG height
`layout`	`Partial<WheelLayoutConfig>`	auto	Layout configuration
`showDirectionLabels`	`boolean`	true	Show direction labels
`showQuadrants`	`boolean`	true	Show quadrant backgrounds
`showNodeLabels`	`boolean`	true	Show node labels
`showLinkLabels`	`boolean`	false	Show link labels
`showOcapIndicators`	`boolean`	false	Show OCAP® compliance dots
`showWilsonHalos`	`boolean`	false	Show Wilson alignment halos
`darkMode`	`boolean`	true	Dark background
`onNodeClick`	`(node) => void`	-	Node click handler
`onNodeHover`	`(node\\|null) => void`	-	Node hover handler
`onLinkClick`	`(link) => void`	-	Link click handler

Layout Engine (headless)

import { applyWheelLayout, getQuadrantGeometries } from '@medicine-wheel/graph-viz';

const positioned = applyWheelLayout(data, { radius: 300, centerX: 400, centerY: 400 });

Data Converters

import { buildGraphData, nodesToGraphNodes, edgesToGraphLinks } from '@medicine-wheel/graph-viz';

`<LineageWeb>`: episodes and their relations

Episodes sit on a spine in chronicle order, each in its direction’s band. Continuation arcs bow above and relation arcs bow below, rising with the square root of their length and staying inside the canvas. Hover or select an episode to light its arcs. A tap selects and a second tap calls onOpen. The wheel’s Episodes tab and the Miadi chronicle both draw it (jgwill/medicine-wheel#162).

import { LineageWeb } from '@medicine-wheel/graph-viz';

<LineageWeb
  episodes={[{ id: 'ep044', label: 'E044', title: 'Teaching…', direction: 'east', date: '2026-06-10', thread: 'portal' }]}
  edges={[{ from: 'ep044', to: 'ep001', kind: 'continuation', words: 'grounds the ceremony of seeing' }]}
  matches={query ? new Set(found) : null}   // keeps what a search found and, as rings, its relatives
  onOpen={(id) => router.push(`/episodes/${id}`)}
/>

Prop	Default
`episodes`, `edges`		Episodes oldest first; edges `continuation` or `relation`, with optional `words`
`selected` / `onSelect`	held by the web	Controlled selection
`onOpen`		Called on a second tap of the selected episode
`matches`, `matchMode`	`null`, `'kin'`	`kin` keeps the matches and their relatives; `fade` dims the rest
`view` / `defaultView` / `onViewChange`	whole chronicle, depth 1, both kinds, threads on	`scope: 'all' \\| 'around'`, `depth: 1 \\| 2`, `kinds`, `threads`
`controls`	`true`	The options bar: whole chronicle or around the selected episode, depth, kinds, threads
`colors`, `threadColors`, `bandLabels`	`--mw-*` tokens
`layout`	`DEFAULT_LINEAGE_WEB_LAYOUT`	Margins, band gap, head and foot room for arcs, minimum step and width
`startAt`	`'start'`	`'end'` opens scrolled to the newest episodes

Moving and reading it by hand (jgwill/medicine-wheel#163):

Gesture	What it does
Drag the empty canvas (mouse)	Moves along time; a finger scrolls natively. A press without a drag clears the selection
− + Fit, Ctrl/⌘ + wheel, pinch	Zoom, keeping the moment under the pointer in place; Fit puts the whole span in the box
Hover or tap an arc	Lights it and its two ends; the strip names both episodes and shows the relation’s words. A tap pins it
← →	Step along time
↑ ↓	Choose one of the selected episode’s relations; its words show and its other end scrolls into view
Enter	Follow the chosen relation, or open the selected episode
Esc	Let the relation go, then the selection
− + 0	Zoom out, in, fit

A new selection scrolls into view, the episode in focus and its relatives are labelled at any size, and the band names stay at the left edge.

The geometry is exported without React: visibleLineage, lineageNeighbourhood, layoutLineageWeb, lineageArcPath, threadChains, lineageWebWidth, fitZoom, zoomScrollLeft, stepAlongSpine, relationsAround, lineageEdgeKey.

License

MIT — IAIP Collaborative, Shawinigan, QC

This site is open source. Improve this page.