@molecule/app-feature-graph-view-vue 0.0.1-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +461 -4
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,11 +1,468 @@
1
+ <!--
2
+ AUTO-GENERATED — DO NOT EDIT THIS FILE.
3
+ Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
4
+ Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
5
+ To change this document, edit the module-level JSDoc in src/index.ts.
6
+ Generated: 2026-11-21T12:46:30.982Z
7
+ -->
8
+
1
9
  # @molecule/app-feature-graph-view-vue
2
10
 
3
- Force-directed graph view (Obsidian-style) for visualizing note / page linkages
11
+ Vue force-directed graph view (Obsidian-style) — the Vue counterpart of
12
+ `@molecule/app-feature-graph-view-react`: the same exports, the same props
13
+ (React names), and the same DOM for the same input.
14
+
15
+ Exports:
16
+
17
+ - `<GraphView>` — top-level node-and-edge visualization with built-in
18
+ `force`, `circular`, and `grid` layouts, click + selection support,
19
+ and pluggable node / edge renderers.
20
+ - `GraphNode`, `GraphEdge`, `GraphLayout`, `GraphPoint`, `PositionedNode`,
21
+ `GraphNodeRenderer`, `GraphEdgeRenderer`, `GraphViewProps` types.
22
+ - Pure layout helpers (`forceLayout`, `circularLayout`, `gridLayout`,
23
+ `layoutNodes`, `boundingBox`, `createRng`).
24
+
25
+ Used by note-taking and other apps to visualize page / note linkages
26
+ the same way Obsidian does — a force-directed map of which notes link
27
+ to which.
28
+
29
+ > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
30
+ > It is written to be read by coding agents as much as by people, and is generated from this
31
+ > package's source — edit `src/index.ts` JSDoc, not this file.
32
+
33
+ ## Quick Start
34
+
35
+ ```ts
36
+ import { createApp, defineComponent, h } from 'vue'
37
+ import { GraphView, type GraphEdge, type GraphNode } from '@molecule/app-feature-graph-view-vue'
38
+
39
+ const nodes: GraphNode[] = [
40
+ { id: 'a', label: 'Alpha' },
41
+ { id: 'b', label: 'Beta', group: 'project', weight: 2 },
42
+ ]
43
+ const edges: GraphEdge[] = [{ id: 'e1', source: 'a', target: 'b' }]
44
+
45
+ const NoteGraph = defineComponent({
46
+ setup() {
47
+ return () =>
48
+ h(GraphView, {
49
+ nodes,
50
+ edges,
51
+ onNodeClick: (node: GraphNode) => console.log(`open ${node.id}`),
52
+ })
53
+ },
54
+ })
55
+
56
+ createApp(NoteGraph).mount('#app')
57
+ ```
58
+
59
+ ## Type
60
+
61
+ `feature`
62
+
63
+ ## Installation
64
+
65
+ ```bash
66
+ npm install @molecule/app-feature-graph-view-vue @molecule/app-ui @molecule/app-ui-vue @molecule/app-vue vue
67
+ ```
68
+
69
+ ## API
70
+
71
+ ### Interfaces
72
+
73
+ #### `ForceLayoutOptions`
74
+
75
+ Force-layout tunables.
76
+
77
+ ```typescript
78
+ interface ForceLayoutOptions {
79
+ /** Hard cap on iterations. Defaults to {@link DEFAULT_FORCE_ITERATIONS}. */
80
+ iterations?: number
81
+ /** Repulsive constant between every pair of nodes. */
82
+ repulsion?: number
83
+ /** Spring (Hooke) constant for edges. */
84
+ spring?: number
85
+ /** Ideal edge length (rest distance). */
86
+ restLength?: number
87
+ /** Velocity damping per step (0–1). */
88
+ damping?: number
89
+ /** Optional deterministic seed (for tests). Defaults to a fixed value. */
90
+ seed?: number
91
+ }
92
+ ```
93
+
94
+ #### `GraphPoint`
95
+
96
+ A 2-D point in graph (world) coordinates.
97
+
98
+ ```typescript
99
+ interface GraphPoint {
100
+ /** X coordinate. */
101
+ x: number
102
+ /** Y coordinate. */
103
+ y: number
104
+ }
105
+ ```
106
+
107
+ #### `GraphNode`
108
+
109
+ Single node in the graph.
110
+
111
+ `group` is an opaque grouping discriminator (e.g. tag, folder) the
112
+ caller can use for colouring; `weight` scales the rendered radius.
113
+
114
+ ```typescript
115
+ interface GraphNode {
116
+ /** Unique node id. */
117
+ id: string
118
+ /** Human-readable label rendered next to the node. */
119
+ label: string
120
+ /** Optional grouping discriminator (e.g. tag id). */
121
+ group?: string
122
+ /** Optional weight; default 1. Scales the rendered radius. */
123
+ weight?: number
124
+ }
125
+ ```
126
+
127
+ #### `GraphEdge`
128
+
129
+ Edge connecting two nodes by id.
130
+
131
+ ```typescript
132
+ interface GraphEdge {
133
+ /** Unique edge id. */
134
+ id: string
135
+ /** Source node id. */
136
+ source: string
137
+ /** Target node id. */
138
+ target: string
139
+ /** Optional weight; default 1. Stronger edges pull harder under force layout. */
140
+ weight?: number
141
+ }
142
+ ```
143
+
144
+ #### `PositionedNode`
145
+
146
+ Internal positioned node used by the renderer; the `x`/`y` coordinates
147
+ are in world (graph) space, with `(0, 0)` at the canvas centre.
148
+
149
+ ```typescript
150
+ interface PositionedNode extends GraphNode {
151
+ /** World-space X coordinate. */
152
+ x: number
153
+ /** World-space Y coordinate. */
154
+ y: number
155
+ }
156
+ ```
157
+
158
+ #### `GraphViewProps`
159
+
160
+ `<GraphView>` props.
161
+
162
+ ```typescript
163
+ interface GraphViewProps {
164
+ /** Nodes to render. */
165
+ nodes: GraphNode[]
166
+ /** Edges to render. */
167
+ edges: GraphEdge[]
168
+ /** Fired when the user clicks (or activates) a node. */
169
+ onNodeClick?: (node: GraphNode) => void
170
+ /** Currently-selected node id (highlighted in the view). */
171
+ selectedNodeId?: string
172
+ /** Layout strategy. Defaults to `'force'`. */
173
+ layout?: GraphLayout
174
+ /** Custom node renderer (overrides the default circle + label). */
175
+ nodeRenderer?: GraphNodeRenderer
176
+ /** Custom edge renderer (overrides the default `<line>`). */
177
+ edgeRenderer?: GraphEdgeRenderer
178
+ /** Force-layout tunables; ignored for non-force layouts. */
179
+ forceOptions?: ForceLayoutOptions
180
+ /** Extra classes merged onto the outer wrapper. */
181
+ className?: string
182
+ }
183
+ ```
184
+
185
+ ### Types
186
+
187
+ #### `GraphLayout`
188
+
189
+ Available layout strategies.
190
+
191
+ ```typescript
192
+ type GraphLayout = 'force' | 'circular' | 'grid'
193
+ ```
194
+
195
+ #### `GraphNodeRenderer`
196
+
197
+ Renderer for an individual node. Receives the positioned node.
198
+
199
+ ```typescript
200
+ type GraphNodeRenderer = (node: PositionedNode) => VNodeChild
201
+ ```
202
+
203
+ #### `GraphEdgeRenderer`
204
+
205
+ Renderer for an individual edge. Receives the edge plus both endpoints.
206
+
207
+ ```typescript
208
+ type GraphEdgeRenderer = (
209
+ edge: GraphEdge,
210
+ source: PositionedNode,
211
+ target: PositionedNode,
212
+ ) => VNodeChild
213
+ ```
214
+
215
+ ### Functions
216
+
217
+ #### `createRng(seed)`
218
+
219
+ Tiny deterministic PRNG (mulberry32). Allows reproducible initial
220
+ positions in tests without depending on `Math.random()`.
221
+
222
+ ```typescript
223
+ function createRng(seed: number): () => number
224
+ ```
225
+
226
+ - `seed` — 32-bit unsigned seed.
227
+
228
+ **Returns:** A function returning floats in `[0, 1)`.
229
+
230
+ #### `circularLayout(nodes, radius)`
231
+
232
+ Place nodes evenly around the unit circle (scaled by `radius`).
233
+
234
+ ```typescript
235
+ function circularLayout(nodes: GraphNode[], radius: number): PositionedNode[]
236
+ ```
237
+
238
+ - `nodes` — Nodes to position.
239
+ - `radius` — Circle radius in world units.
240
+
241
+ **Returns:** Positioned nodes, in input order.
242
+
243
+ #### `gridLayout(nodes, spacing)`
244
+
245
+ Place nodes on a square-ish grid, centred on the origin.
246
+
247
+ ```typescript
248
+ function gridLayout(nodes: GraphNode[], spacing: number): PositionedNode[]
249
+ ```
250
+
251
+ - `nodes` — Nodes to position.
252
+ - `spacing` — Pixel spacing between adjacent grid cells.
253
+
254
+ **Returns:** Positioned nodes, in input order.
255
+
256
+ #### `forceLayout(nodes, edges, options)`
257
+
258
+ Run a minimal velocity-Verlet force-directed simulation.
259
+
260
+ Implements:
261
+
262
+ - Pairwise repulsion (Coulomb-like, O(n²)) between every node pair.
263
+ - Spring (Hooke) attraction along each edge toward `restLength`.
264
+ - Per-step velocity damping for stability.
265
+
266
+ Stops early once the maximum per-node displacement-squared drops below
267
+ {@link CONVERGENCE_EPSILON}, or after `iterations` steps — whichever
268
+ comes first.
269
+
270
+ ```typescript
271
+ function forceLayout(
272
+ nodes: GraphNode[],
273
+ edges: GraphEdge[],
274
+ options?: ForceLayoutOptions,
275
+ ): PositionedNode[]
276
+ ```
277
+
278
+ - `nodes` — Nodes to lay out.
279
+ - `edges` — Edges (used only for attractive springs).
280
+ - `options` — Force-layout tunables.
281
+
282
+ **Returns:** Positioned nodes, in input order.
4
283
 
284
+ #### `layoutNodes(nodes, edges, layout, options)`
285
+
286
+ Compute world-space positions for every node using the chosen layout.
287
+
288
+ ```typescript
289
+ function layoutNodes(
290
+ nodes: GraphNode[],
291
+ edges: GraphEdge[],
292
+ layout: GraphLayout,
293
+ options?: ForceLayoutOptions,
294
+ ): PositionedNode[]
5
295
  ```
6
- npm install @molecule/app-feature-graph-view-vue
296
+
297
+ - `nodes` — Nodes to position.
298
+ - `edges` — Edges (consumed only by `force`).
299
+ - `layout` — Layout strategy.
300
+ - `options` — Optional force-layout tunables (ignored for non-force).
301
+
302
+ **Returns:** Positioned nodes.
303
+
304
+ #### `boundingBox(nodes, padding)`
305
+
306
+ Compute the world-space bounding box of a set of positioned nodes,
307
+ with a small padding for visual breathing room.
308
+
309
+ ```typescript
310
+ function boundingBox(
311
+ nodes: PositionedNode[],
312
+ padding?: number,
313
+ ): { minX: number; minY: number; maxX: number; maxY: number } | null
7
314
  ```
8
315
 
9
- Part of the [Molecule](https://www.molecule.dev) package fleet. This page carries the manifest summary; the full generated documentation ships with the package's first committed version.
316
+ - `nodes` — Positioned nodes.
317
+ - `padding` — Padding (world units) added to every side. Default 40.
318
+
319
+ **Returns:** Bounding box `{ minX, minY, maxX, maxY }` — or `null` if empty.
320
+
321
+ ### Constants
322
+
323
+ #### `GraphView`
324
+
325
+ Force-directed graph view (Obsidian-style).
326
+
327
+ Renders nodes + edges into an SVG, computing positions via a built-in
328
+ minimal velocity-Verlet simulation. Three layouts are supported —
329
+ `force` (default), `circular` and `grid` — and either nodes or edges
330
+ can be overridden via custom renderers.
331
+
332
+ Style is driven by `getClassMap()`. Inline styles are reserved for
333
+ SVG geometry — `transform`, viewBox computation, stroke widths — which
334
+ classes can't express.
335
+
336
+ ```typescript
337
+ const GraphView: DefineComponent<
338
+ ExtractPropTypes<{
339
+ nodes: { type: PropType<GraphNode[]>; required: true }
340
+ edges: { type: PropType<GraphEdge[]>; required: true }
341
+ onNodeClick: PropType<(node: GraphNode) => void>
342
+ selectedNodeId: StringConstructor
343
+ layout: { type: PropType<GraphLayout>; default: string }
344
+ nodeRenderer: PropType<GraphNodeRenderer>
345
+ edgeRenderer: PropType<GraphEdgeRenderer>
346
+ forceOptions: PropType<ForceLayoutOptions>
347
+ className: StringConstructor
348
+ }>,
349
+ () => VNode,
350
+ {},
351
+ {},
352
+ {},
353
+ ComponentOptionsMixin,
354
+ ComponentOptionsMixin,
355
+ {},
356
+ string,
357
+ PublicProps,
358
+ Readonly<
359
+ ExtractPropTypes<{
360
+ nodes: { type: PropType<GraphNode[]>; required: true }
361
+ edges: { type: PropType<GraphEdge[]>; required: true }
362
+ onNodeClick: PropType<(node: GraphNode) => void>
363
+ selectedNodeId: StringConstructor
364
+ layout: { type: PropType<GraphLayout>; default: string }
365
+ nodeRenderer: PropType<GraphNodeRenderer>
366
+ edgeRenderer: PropType<GraphEdgeRenderer>
367
+ forceOptions: PropType<ForceLayoutOptions>
368
+ className: StringConstructor
369
+ }>
370
+ > &
371
+ Readonly<{}>,
372
+ { layout: GraphLayout },
373
+ {},
374
+ {},
375
+ {},
376
+ string,
377
+ ComponentProvideOptions,
378
+ true,
379
+ {},
380
+ any
381
+ >
382
+ ```
383
+
384
+ **Returns:** The graph-view component.
385
+
386
+ #### `DEFAULT_FORCE_ITERATIONS`
387
+
388
+ Default cap on force-layout iterations.
389
+
390
+ ```typescript
391
+ const DEFAULT_FORCE_ITERATIONS: 200
392
+ ```
393
+
394
+ #### `DEFAULT_REPULSION`
395
+
396
+ Default repulsion strength used by `forceLayout`.
397
+
398
+ ```typescript
399
+ const DEFAULT_REPULSION: 800
400
+ ```
401
+
402
+ #### `DEFAULT_SPRING`
403
+
404
+ Default spring stiffness used by `forceLayout`.
405
+
406
+ ```typescript
407
+ const DEFAULT_SPRING: 0.05
408
+ ```
409
+
410
+ #### `DEFAULT_REST_LENGTH`
411
+
412
+ Default ideal edge length used by `forceLayout`.
413
+
414
+ ```typescript
415
+ const DEFAULT_REST_LENGTH: 80
416
+ ```
417
+
418
+ #### `DEFAULT_DAMPING`
419
+
420
+ Default velocity damping used by `forceLayout`.
421
+
422
+ ```typescript
423
+ const DEFAULT_DAMPING: 0.85
424
+ ```
425
+
426
+ #### `CONVERGENCE_EPSILON`
427
+
428
+ Convergence threshold (max per-node displacement squared).
429
+
430
+ ```typescript
431
+ const CONVERGENCE_EPSILON: 0.01
432
+ ```
433
+
434
+ ## Injection Notes
435
+
436
+ ### Requirements
437
+
438
+ Peer dependencies:
439
+
440
+ - `@molecule/app-ui` ^1.0.1
441
+ - `@molecule/app-ui-vue` ^1.1.0
442
+ - `@molecule/app-vue` ^3.5.0
443
+ - `vue` ^3.4.0
444
+
445
+ ### Runtime Dependencies
446
+
447
+ - `@molecule/app-ui`
448
+ - `@molecule/app-ui-vue`
449
+ - `@molecule/app-vue`
450
+ - `vue`
451
+
452
+ The root element fills 100% of its parent — the PARENT must have an
453
+ explicit height (e.g. a fixed-height panel or a flex/grid track) or
454
+ the graph renders zero-tall and appears blank.
455
+
456
+ Interaction surface is click / keyboard-activate + `selectedNodeId`
457
+ highlighting only. Nodes are NOT draggable and there is no built-in
458
+ pan / zoom — the SVG `viewBox` auto-fits the layout bounds. For a
459
+ pannable / zoomable surface, compose with
460
+ `@molecule/app-feature-canvas-vue` instead.
461
+
462
+ Layout is deterministic (seeded RNG), computed once per
463
+ `(nodes, edges, layout, forceOptions)` change. `forceOptions` is
464
+ ignored by the `circular` and `grid` layouts.
465
+
466
+ ## Translations
10
467
 
11
- License: Apache-2.0
468
+ Translation strings are provided by `@molecule/app-locales-feature-graph-view`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/app-feature-graph-view-vue",
3
- "version": "0.0.1-stage",
3
+ "version": "1.1.0",
4
4
  "description": "Force-directed graph view (Obsidian-style) for visualizing note / page linkages",
5
5
  "homepage": "https://www.molecule.dev/packages/app-feature-graph-view-vue",
6
6
  "type": "module",
@@ -55,9 +55,9 @@
55
55
  "@molecule/app-framework-conformance": "0.0.0",
56
56
  "@molecule/app-i18n": "1.2.2",
57
57
  "@molecule/app-icons": "1.0.4",
58
- "@molecule/app-ui": "1.4.0",
59
- "@molecule/app-ui-vue": "1.1.5",
60
- "@molecule/app-vue": "3.7.2",
58
+ "@molecule/app-ui": "1.5.0",
59
+ "@molecule/app-ui-vue": "1.2.1",
60
+ "@molecule/app-vue": "3.9.0",
61
61
  "@types/node": "26.6.5",
62
62
  "jsdom": "30.1.3",
63
63
  "typescript": "6.0.3",