@simplex-viz/svg 0.1.1 → 0.1.3

package/README.md

@@ -1,24 +1,90 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ghackenberg/simplex-viz/main/docs/assets/logo-svg.png" width="640" alt="SimplexViz / svg — @simplex-viz/svg" />
+</p>
+
 # @simplex-viz/svg
 
-Framework-agnostic SVG rendering engine and pluggable `SvgNodeView` architecture for `@simplex-viz/core`. Zero dependency on React—embeds cleanly into Vanilla TypeScript, Vue, Angular, Svelte, and Web Components.
+Framework-agnostic SVG rendering engine and pluggable `SvgNodeView` architecture for `@simplex-viz/core`. Zero dependency on React—embeds cleanly into Vanilla TypeScript, Vue, Angular, Svelte, Solid, and Web Components.
 
 - **Live Demo:** <https://hackenberg.tech/simplex-viz/>
 - **Source & Monorepo:** <https://github.com/ghackenberg/simplex-viz/tree/main/packages/svg>
+- **Companion Packages:** [`@simplex-viz/core`](https://www.npmjs.com/package/@simplex-viz/core) · [`@simplex-viz/react`](https://www.npmjs.com/package/@simplex-viz/react)
+
+## Visual Rendering Showcase
+
+While `@simplex-viz/core` computes pure spatial coordinates, `@simplex-viz/svg` turns each frame into live DOM `<svg>` elements inside any browser container or UI framework. The preview below renders its built-in views together in a single viewport:
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ghackenberg/simplex-viz/main/docs/assets/preview-svg.png" width="100%" alt="@simplex-viz/svg rendering showcase showing GeometricShapeSvgView, MultiSectorGlyphSvgView, ClusterAnchorSvgView, and BadgeClusterSvgView" />
+</p>
+
+*Figure: Visual showcase of the four built-in `SvgNodeView` plugins rendered on an OKLab-tinted 60° simplex mesh. Content items mix `GeometricShapeSvgView` (circles, diamonds, hexagons, and stars that morph smoothly via 64-point paths) with `MultiSectorGlyphSvgView` (proportional donut glyphs whose sector arcs encode barycentric topic weights). Topic clusters alternate between compact `ClusterAnchorSvgView` vertex rings and auto-measured `BadgeClusterSvgView` cards sized via offscreen `getBBox()`.*
+
+## Features
+
+- **Framework-agnostic SVG scene graph**: Keyed DOM reconciliation for background mesh triangles, highlighted edges, convex hull debug wireframes, cluster nodes, and content nodes.
+- **Automatic offscreen `getBBox()` hull measurement**: Omit `measureConvexHull` on any `SvgNodeView` and `@simplex-viz/svg` automatically renders it in a hidden measurement bin, reads `getBBox()`, and caches a tight convex polygon for overlap-free layout.
+- **Smooth 60 fps transitions**: Critically damped spring motion + specialized parametric `morph()` or automatic dual-layer crossfade when switching visual presets or mutating items.
+- **Centralized root-SVG interactions**: Attaches pointer, click, right-click, wheel, drag-to-pan, and `ResizeObserver` listeners solely on the root `<svg>` element and delegates hit-testing to `@simplex-viz/core`'s exact convex geometry solver.
+- **Four built-in view plugins**: Ready-to-use views for geometric shape morphing, multi-sector topic glyphs, vertex anchors, and dynamic text badges.
 
 ## Installation
 
+Install `@simplex-viz/core` alongside `@simplex-viz/svg` in any browser or TypeScript project:
+
 ```bash
 npm install @simplex-viz/core @simplex-viz/svg
 ```
 
-## Included `SvgNodeView` Plugins
+## Quickstart (Vanilla TypeScript)
 
-- `GeometricShapeSvgView` — Circle, rounded diamond, hexagon, and 5-point star with 64-point parametric SVG path morphing.
-- `MultiSectorGlyphSvgView` — Multi-colored topic weight donut glyphs representing exact barycentric weights.
-- `BadgeClusterSvgView` — Dynamic text badges with automatic offscreen `getBBox()` convex hull measurement.
-- `ClusterAnchorSvgView` — Calibrated double-ring vertex anchors with code & member count.
+### Step 1 — Define Your Domain Record & `VisualResolver`
 
-## Quickstart (Vanilla TS)
+Start by describing your data model (`Bookmark`) and mapping each item and topic cluster into visual descriptors for `GeometricShapeSvgView` and `ClusterAnchorSvgView`. `ctx.mixedColorHex` provides the item's barycentric OKLab color blend automatically:
+
+```ts
+import type { VisualResolver } from '@simplex-viz/core';
+import type {
+  ClusterAnchorVisual,
+  GeometricShapeVisual,
+} from '@simplex-viz/svg';
+
+interface Bookmark {
+  readonly url: string;
+  readonly title: string;
+  readonly topics: readonly string[];
+  readonly minutes: number;
+}
+
+const visualResolver: VisualResolver<
+  Bookmark,
+  GeometricShapeVisual,
+  ClusterAnchorVisual
+> = {
+  resolveContentVisual: (bookmark, ctx) => ({
+    shape: bookmark.minutes > 10 ? 'star' : 'circle',
+    radius: 10,
+    fillHex: ctx.mixedColorHex,
+    strokeHex: '#07090E',
+    strokeWidth: 1.4,
+  }),
+  resolveClusterVisual: (cluster) => ({
+    code: cluster.code,
+    label: cluster.defaultLabel,
+    memberCount: cluster.members.length,
+    colorHex: cluster.colorHex,
+    radius: 22,
+  }),
+  getVisualCacheKey: (visual) =>
+    'shape' in visual
+      ? `${visual.shape}:${visual.radius}:${visual.fillHex}`
+      : `${visual.code}:${visual.memberCount}:${visual.colorHex}`,
+};
+```
+
+### Step 2 — Mount `SimplexSvgController`
+
+Pass any container `HTMLElement` to `SimplexSvgController` along with `getId`, `getTags`, `visualResolver`, and the built-in views. The controller creates the root `<svg>`, attaches a `ResizeObserver`, computes the initial triangulation, and begins the 60 fps spring loop:
 
 ```ts
 import {
@@ -27,10 +93,213 @@ import {
   ClusterAnchorSvgView,
 } from '@simplex-viz/svg';
 
-const controller = new SimplexSvgController(containerEl, {
-  items,
+const container = document.getElementById('graph')!;
+
+const controller = new SimplexSvgController(container, {
+  items: myBookmarks,
+  getId: (b) => b.url,
+  getTags: (b) => b.topics,
   visualResolver,
   contentView: new GeometricShapeSvgView(),
   clusterView: new ClusterAnchorSvgView(),
+  meshOptions: { innerPadding: 48, minSideLength: 140, maxSideLength: 280, maxClusters: 10 },
+  layoutOptions: { clusterGapPx: 14, itemGapPx: 5 },
+  onMetricsChange: (metrics) => {
+    console.log(`Clusters: ${metrics.clusterCount}, Overlaps: ${metrics.overlapCount}`);
+  },
 });
 ```
+
+### Step 3 — Wire Hover, Click & Wheel Interactions
+
+Attach centralized pointer, click, context-menu, and wheel handlers via `setInteractions` (or pass `interactions` directly in the constructor). Listeners live exclusively on the root `<svg>`, while hit-testing uses exact convex hulls:
+
+```ts
+controller.setInteractions({
+  onContentHover: (ev) => {
+    if (ev) console.log('Hovered item:', ev.item.title, ev.screenPosition);
+  },
+  onLeftClick: (target) => {
+    if (target.kind === 'content') {
+      console.log('Clicked:', target.item.title);
+    } else if (target.kind === 'cluster') {
+      controller.setFocusedClusterUid(target.cluster.clusterUid);
+    } else {
+      controller.setFocusedClusterUid(null);
+    }
+  },
+  onRightClick: (target) => {
+    console.log('Context menu target:', target.kind);
+    return true; // Suppress browser default context menu
+  },
+  onWheel: 'zoom-to-cursor',
+});
+```
+
+### Step 4 — Apply Live Mutations & Clean Up
+
+Mutate items or reset the camera smoothly at runtime without interrupting user navigation. Call `controller.destroy()` on unmount to stop animations and disconnect observers:
+
+```ts
+controller.addItems({
+  url: 'https://example.com/oklab',
+  title: 'Perceptual Color Mixing',
+  topics: ['oklab', 'color-science'],
+  minutes: 12,
+});
+controller.removeItems('https://example.com/old');
+controller.camera.reset();
+
+// Call on component unmount / teardown:
+// controller.destroy();
+```
+
+## Built-In `SvgNodeView` Plugins
+
+### 1. `GeometricShapeSvgView`
+Renders `'circle' | 'diamond' | 'star' | 'hexagon'` with analytical convex hulls and **64-point parametric SVG path morphing** between shapes and colors. Pass a `GeometricShapeVisual` descriptor from `resolveContentVisual` to control polygon kind, radius, fill, and outline stroke:
+
+```ts
+import type { GeometricShapeVisual } from '@simplex-viz/svg';
+
+// Descriptor shape:
+const visual: GeometricShapeVisual = {
+  shape: 'hexagon', // 'circle' | 'diamond' | 'star' | 'hexagon'
+  radius: 11,
+  fillHex: ctx.mixedColorHex,
+  strokeHex: '#07090E',
+  strokeWidth: 1.4,
+};
+```
+
+### 2. `MultiSectorGlyphSvgView`
+Renders a multi-colored donut glyph whose sector arc angles match an item's exact barycentric weights across its active simplex unit (vertex, edge, or triangle). Map `ctx.unitClusters` directly into `sectors` as shown below to reflect multi-topic membership visually:
+
+```ts
+import type { MultiSectorGlyphVisual } from '@simplex-viz/svg';
+
+const visual: MultiSectorGlyphVisual = {
+  outerRadius: 12,
+  innerRadius: 5,
+  sectors: ctx.unitClusters.map((uc) => ({
+    colorHex: uc.cluster.colorHex,
+    weight: uc.weight,
+  })),
+  centerColorHex: ctx.mixedColorHex,
+};
+```
+
+### 3. `BadgeClusterSvgView`
+Renders dynamic pill/card cluster badges sized to their title and metadata line. Because it intentionally omits `measureConvexHull`, `@simplex-viz/svg` measures the rendered `<svg>` elements via `getBBox()` so varying title lengths remain strictly overlap-free:
+
+```ts
+import type { BadgeClusterVisual } from '@simplex-viz/svg';
+
+const visual: BadgeClusterVisual = {
+  code: cluster.code,
+  title: cluster.defaultLabel,
+  metaLine: `${cluster.members.length} items`,
+  colorHex: cluster.colorHex,
+};
+```
+
+### 4. `ClusterAnchorSvgView`
+Renders calibrated double-ring vertex anchors showing the cluster code and member count. Supply a `ClusterAnchorVisual` descriptor when you want compact circular topic anchors on mesh vertices:
+
+```ts
+import type { ClusterAnchorVisual } from '@simplex-viz/svg';
+
+const visual: ClusterAnchorVisual = {
+  code: cluster.code,
+  label: cluster.defaultLabel,
+  memberCount: cluster.members.length,
+  colorHex: cluster.colorHex,
+  radius: 23,
+};
+```
+
+## Writing Custom `SvgNodeView` Plugins
+
+Implement `SvgNodeView<TVisual>` centered around local origin `(0, 0)`. `SvgRendererAdapter` handles world positioning `(x, y)`, solver scale `α`, opacity, and crossfading on the parent `<g>`.
+
+First, define your visual descriptor and an optional analytical hull via `measureConvexHull` (if omitted, `@simplex-viz/svg` automatically measures the rendered SVG via offscreen `getBBox()`):
+
+```ts
+import type { SvgNodeView } from '@simplex-viz/svg';
+import { rectToConvexPolygon } from '@simplex-viz/core';
+
+interface CardVisual {
+  readonly title: string;
+  readonly colorHex: string;
+}
+
+const getCardWidth = (title: string) => Math.max(80, title.length * 7 + 20);
+```
+
+Next, populate `mountOrUpdate` to construct pure SVG nodes inside `groupEl`, reacting to `state.interaction.isHovered` for instant border emphasis:
+
+```ts
+const SVG_NS = 'http://www.w3.org/2000/svg';
+
+export const CustomCardSvgView: SvgNodeView<CardVisual> = {
+  // Optional: omit to measure automatically via offscreen getBBox()
+  measureConvexHull: (visual) =>
+    rectToConvexPolygon(getCardWidth(visual.title), 28, 6),
+
+  mountOrUpdate: (groupEl, visual, state) => {
+    const doc = groupEl.ownerDocument;
+    while (groupEl.firstChild) groupEl.removeChild(groupEl.firstChild);
+
+    const width = getCardWidth(visual.title);
+    const rect = doc.createElementNS(SVG_NS, 'rect');
+    rect.setAttribute('x', String(-width / 2));
+    rect.setAttribute('y', '-14');
+    rect.setAttribute('width', String(width));
+    rect.setAttribute('height', '28');
+    rect.setAttribute('rx', '6');
+    rect.setAttribute('fill', '#0d1320');
+    rect.setAttribute(
+      'stroke',
+      state.interaction.isHovered ? '#f8fafc' : visual.colorHex,
+    );
+    rect.setAttribute('stroke-width', state.interaction.isHovered ? '2' : '1.2');
+
+    const text = doc.createElementNS(SVG_NS, 'text');
+    text.setAttribute('text-anchor', 'middle');
+    text.setAttribute('y', '4');
+    text.setAttribute('fill', '#f8fafc');
+    text.setAttribute('font-size', '11');
+    text.textContent = visual.title;
+
+    groupEl.appendChild(rect);
+    groupEl.appendChild(text);
+  },
+
+  // Optional: omit to use universal dual-layer crossfade
+  // morph: (groupEl, from, to, progress, state) => false,
+};
+```
+
+## `SimplexSvgController` API Summary
+
+| Method / Property | Description |
+| --- | --- |
+| `addItems(items)` | Appends one or more items and triggers an interruptible transition. |
+| `removeItems(ids)` | Removes items by ID and smoothly fades out exiting nodes. |
+| `setItems(items)` | Replaces the entire corpus while preserving matching clusters & items. |
+| `setViews({ contentView, clusterView })` | Hot-swaps `SvgNodeView` plugins at runtime. |
+| `setVisualResolver(resolver)` | Updates descriptor resolution and crossfades smoothly. |
+| `setSizeMultiplier(multiplier)` | Uniformly scales node sizes (`0.35` – `3.0`) and re-solves zero overlap. |
+| `setShowHulls(show)` | Toggles convex bounding hull wireframe overlays. |
+| `setPinnedIds(ids)` / `setHighlightedIds(ids)` | Controls pinned and highlighted visual emphasis states. |
+| `setFocusedClusterUid(uid \| null)` | Isolates a cluster and its members, dimming unrelated nodes. |
+| `setInteractions(handlers)` | Replaces pointer, click, and wheel callbacks dynamically. |
+| `camera` | Exposes `CameraController` (`zoomToCursor`, `panBy`, `reset`, `getState`, `setState`). |
+| `getMetrics()` / `getClusters()` / `getItems()` | Reads live solver telemetry, clusters, and items. |
+| `getSvgElement()` | Returns the managed root `<svg>` element. |
+| `stepForTest(dtMs)` | Deterministically advances simulation time in unit/DOM tests. |
+| `destroy()` | Cancels `requestAnimationFrame`, disconnects `ResizeObserver`, and removes the `<svg>`. |
+
+## License
+
+MIT — see [LICENSE](https://github.com/ghackenberg/simplex-viz/blob/main/LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplex-viz/svg",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Framework-agnostic SVG rendering engine, offscreen getBBox() hull measurer, and pluggable SvgNodeView system for @simplex-viz/core.",
   "license": "MIT",
   "type": "module",
@@ -20,7 +20,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@simplex-viz/core": "^0.1.1"
+    "@simplex-viz/core": "^0.1.3"
   },
   "keywords": [
     "simplex",