@simplex-viz/react 0.1.2 → 0.1.3

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ghackenberg/simplex-viz/main/docs/assets/logo-react.png" width="640" alt="SimplexViz / react — @simplex-viz/react" />
+</p>
+
 # @simplex-viz/react
 
 End-to-end type-safe React bindings, declarative JSX node renderers, and imperative controller hooks for `@simplex-viz/core` and `@simplex-viz/svg`.
@@ -6,7 +10,15 @@ End-to-end type-safe React bindings, declarative JSX node renderers, and imperat
 - **Source & Monorepo:** <https://github.com/ghackenberg/simplex-viz/tree/main/packages/react>
 - **Companion Packages:** [`@simplex-viz/core`](https://www.npmjs.com/package/@simplex-viz/core) · [`@simplex-viz/svg`](https://www.npmjs.com/package/@simplex-viz/svg)
 
----
+## Declarative JSX Slot Architecture
+
+In React, `<SimplexTopicGraph />` lets you drop custom JSX directly into cluster and content slots instead of hand-writing imperative SVG DOM code. The wireframe preview below illustrates how those two component slots populate a single visualization:
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ghackenberg/simplex-viz/main/docs/assets/preview-react.png" width="100%" alt="@simplex-viz/react preview showing minimalist renderClusterNode and renderContentNode JSX slot placeholders with automatic getBBox() collision sizing" />
+</p>
+
+*Figure: Architectural slot layout rendered with `@simplex-viz/react`. Dashed topic cards illustrate the `renderClusterNode` JSX slot positioned on a subtle 60° simplex mesh, while minimalist skeleton content cards represent `renderContentNode` slots complete with color accents, type/time metadata, and interactive selection highlights (amber for pinned, cyan for hovered). Every JSX element is measured automatically via offscreen `getBBox()` so custom React SVG cards remain strictly overlap-free.*
 
 ## Features
 
@@ -17,28 +29,21 @@ End-to-end type-safe React bindings, declarative JSX node renderers, and imperat
 - **Full generic type inference**: Infers `<TItem, TContentVisual, TClusterVisual, TTagMeta, TClusterMeta>` end-to-end across `items`, `getId`, `getTags`, `deriveClusterMeta`, `visualResolver`, `renderContentNode`, `renderClusterNode`, hover events, and click targets.
 - **`useSimplexGraphController`**: Imperative hook for live item mutations (`addItems`, `removeItems`, `setItems`), camera controls (`zoomBy`, `resetCamera`), and telemetry getters.
 
----
-
 ## Installation
 
+Install the React wrapper together with its core engine and SVG scene-graph peer packages (`react >= 18.0.0` and `react-dom >= 18.0.0`):
+
 ```bash
 npm install @simplex-viz/core @simplex-viz/svg @simplex-viz/react
 ```
 
-Peer dependencies: `react >= 18.0.0` and `react-dom >= 18.0.0`.
+## Quickstart: Declarative JSX Node Renderers
 
----
+### Step 1 — Define Domain, Visual, and Cluster Metadata Types
 
-## Quickstart: Declarative JSX Node Renderers
+Describe your domain item (`Article`), visual cache descriptors (`ArticleVisual`, `ClusterVisual`), and aggregate cluster stats (`ClusterStats`). TypeScript preserves these types across every callback prop on `<SimplexTopicGraph />`:
 
 ```tsx
-import { useMemo, useState } from 'react';
-import {
-  SimplexTopicGraph,
-  useSimplexGraphController,
-} from '@simplex-viz/react';
-import type { VisualResolver } from '@simplex-viz/core';
-
 interface Article {
   readonly slug: string;
   readonly title: string;
@@ -64,6 +69,77 @@ interface ClusterStats {
   readonly count: number;
   readonly avgMinutes: number;
 }
+```
+
+### Step 2 — Define Declarative JSX Node Renderers
+
+Write standard SVG JSX centered around `(0, 0)` for individual items and topic clusters. `@simplex-viz/react` measures the resulting `<g>` subtree automatically via offscreen `getBBox()` whenever `getVisualCacheKey` changes, guaranteeing collision-free card placement:
+
+```tsx
+import type {
+  ClusterDescriptor,
+  ContentLayoutContext,
+  NodeRenderState,
+} from '@simplex-viz/core';
+
+const renderArticleNode = (
+  article: Article,
+  ctx: ContentLayoutContext<Article, undefined, ClusterStats>,
+  state: NodeRenderState<ArticleVisual>,
+) => (
+  <g>
+    <rect
+      x={-54}
+      y={-15}
+      width={108}
+      height={30}
+      rx={6}
+      fill="#0f172a"
+      stroke={state.interaction.isPinned ? '#f59e0b' : ctx.mixedColorHex}
+      strokeWidth={state.interaction.isHovered ? 2 : 1.2}
+    />
+    <text textAnchor="middle" y={4} fill="#f8fafc" fontSize={9}>
+      {article.title.slice(0, 16)}
+    </text>
+  </g>
+);
+
+const renderTopicCluster = (
+  cluster: ClusterDescriptor<Article, undefined, ClusterStats>,
+  state: NodeRenderState<ClusterVisual>,
+) => (
+  <g>
+    <rect
+      x={-68}
+      y={-20}
+      width={136}
+      height={40}
+      rx={8}
+      fill="#090d16"
+      stroke={state.interaction.isHovered ? '#f8fafc' : cluster.colorHex}
+      strokeWidth={1.6}
+    />
+    <text textAnchor="middle" y={-2} fill="#f8fafc" fontSize={10} fontWeight={600}>
+      {`${cluster.code} · ${cluster.defaultLabel}`}
+    </text>
+    <text textAnchor="middle" y={12} fill="#94a3b8" fontSize={8.5}>
+      {`${cluster.meta.count} items · avg ${cluster.meta.avgMinutes.toFixed(0)}m`}
+    </text>
+  </g>
+);
+```
+
+### Step 3 — Initialize State, Controller Hook & Memoized `VisualResolver`
+
+Inside your React component, set up selection state, create a typed controller handle with `useSimplexGraphController`, and memoize `visualResolver` with `useMemo` so re-renders never trigger unintended crossfade transitions:
+
+```tsx
+import { useMemo, useState } from 'react';
+import {
+  SimplexTopicGraph,
+  useSimplexGraphController,
+} from '@simplex-viz/react';
+import type { VisualResolver } from '@simplex-viz/core';
 
 export function KnowledgeAtlas({ articles }: { articles: readonly Article[] }) {
   const [focusedClusterUid, setFocusedClusterUid] = useState<string | null>(null);
@@ -97,7 +173,13 @@ export function KnowledgeAtlas({ articles }: { articles: readonly Article[] }) {
     }),
     [],
   );
+```
+
+### Step 4 — Render `<SimplexTopicGraph />` with Camera Toolbar & Click Handling
+
+Finally, wire the camera toolbar (`handle.zoomBy`, `handle.resetCamera`), pass the JSX renderers from Step 2, and handle left-clicks to toggle pinned items or isolate clicked topic clusters:
 
+```tsx
   return (
     <div style={{ width: '100%', height: '640px', position: 'relative' }}>
       <div style={{ position: 'absolute', top: 12, left: 12, zIndex: 10 }}>
@@ -120,48 +202,8 @@ export function KnowledgeAtlas({ articles }: { articles: readonly Article[] }) {
         visualResolver={visualResolver}
         pinnedIds={pinnedIds}
         focusedClusterUid={focusedClusterUid}
-        renderContentNode={(article, ctx, state) => (
-          <g>
-            <rect
-              x={-54}
-              y={-15}
-              width={108}
-              height={30}
-              rx={6}
-              fill="#0f172a"
-              stroke={state.interaction.isPinned ? '#f59e0b' : ctx.mixedColorHex}
-              strokeWidth={state.interaction.isHovered ? 2 : 1.2}
-            />
-            <text
-              textAnchor="middle"
-              y={4}
-              fill="#f8fafc"
-              fontSize={9}
-            >
-              {article.title.slice(0, 16)}
-            </text>
-          </g>
-        )}
-        renderClusterNode={(cluster, state) => (
-          <g>
-            <rect
-              x={-68}
-              y={-20}
-              width={136}
-              height={40}
-              rx={8}
-              fill="#090d16"
-              stroke={state.interaction.isHovered ? '#f8fafc' : cluster.colorHex}
-              strokeWidth={1.6}
-            />
-            <text textAnchor="middle" y={-2} fill="#f8fafc" fontSize={10} fontWeight={600}>
-              {`${cluster.code} · ${cluster.defaultLabel}`}
-            </text>
-            <text textAnchor="middle" y={12} fill="#94a3b8" fontSize={8.5}>
-              {`${cluster.meta.count} items · avg ${cluster.meta.avgMinutes.toFixed(0)}m`}
-            </text>
-          </g>
-        )}
+        renderContentNode={renderArticleNode}
+        renderClusterNode={renderTopicCluster}
         onLeftClick={(target) => {
           if (target.kind === 'content') {
             setPinnedIds((prev) => {
@@ -184,11 +226,9 @@ export function KnowledgeAtlas({ articles }: { articles: readonly Article[] }) {
 }
 ```
 
----
-
 ## Using Portable `SvgNodeView` Plugins (60 fps Without JSX Re-Renders)
 
-For larger graphs or built-in shape morphing, pass `contentView` and `clusterView` from `@simplex-viz/svg` instead of `renderContentNode` / `renderClusterNode`:
+For larger graphs or built-in shape morphing without per-frame JSX overhead, instantiate `GeometricShapeSvgView` and `ClusterAnchorSvgView` once outside the component and pass them via `contentView` and `clusterView` instead of `renderContentNode` / `renderClusterNode`:
 
 ```tsx
 import { SimplexTopicGraph } from '@simplex-viz/react';
@@ -216,8 +256,6 @@ export function FastGraph({ items, visualResolver }) {
 
 > **Tip:** Memoize `visualResolver` (e.g., via `useMemo`) and keep `contentView` / `clusterView` instances stable outside render to avoid unnecessary crossfades. Changing `visualResolver` or switching view props intentionally triggers a smooth crossfade/morph transition.
 
----
-
 ## `<SimplexTopicGraph />` Props Reference
 
 ### Data, Typing & Metadata
@@ -264,8 +302,6 @@ export function FastGraph({ items, visualResolver }) {
 | `onFpsUpdate` | `(fps: number) => void` |
 | `controllerRef` | Ref populated with the underlying `SimplexSvgController` instance. |
 
----
-
 ## `useSimplexGraphController()` Hook
 
 Returns `{ controllerRef, handle }`:
@@ -279,8 +315,6 @@ Returns `{ controllerRef, handle }`:
 - `handle.getClusters()` — Returns current `ClusterDescriptor[]`.
 - `handle.getRawController()` — Returns the underlying `SimplexSvgController | null`.
 
----
-
 ## License
 
 MIT — see [LICENSE](https://github.com/ghackenberg/simplex-viz/blob/main/LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplex-viz/react",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "End-to-end type-safe React bindings, declarative JSX node renderers, and hooks for @simplex-viz/core and @simplex-viz/svg.",
   "license": "MIT",
   "type": "module",
@@ -20,8 +20,8 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@simplex-viz/core": "^0.1.2",
-    "@simplex-viz/svg": "^0.1.2"
+    "@simplex-viz/core": "^0.1.3",
+    "@simplex-viz/svg": "^0.1.3"
   },
   "peerDependencies": {
     "react": ">=18.0.0",