@molecule/app-feature-graph-view-svelte 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.
- package/README.md +396 -4
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,11 +1,403 @@
|
|
|
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.751Z
|
|
7
|
+
-->
|
|
8
|
+
|
|
1
9
|
# @molecule/app-feature-graph-view-svelte
|
|
2
10
|
|
|
3
|
-
|
|
11
|
+
Svelte force-directed graph view (Obsidian-style) — the Svelte 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 snippets.
|
|
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.
|
|
4
32
|
|
|
33
|
+
## Quick Start
|
|
34
|
+
|
|
35
|
+
```svelte
|
|
36
|
+
<script lang="ts">
|
|
37
|
+
import {
|
|
38
|
+
GraphView,
|
|
39
|
+
type GraphEdge,
|
|
40
|
+
type GraphNode,
|
|
41
|
+
} from '@molecule/app-feature-graph-view-svelte'
|
|
42
|
+
|
|
43
|
+
let { notes, links } = $props()
|
|
44
|
+
const nodes: GraphNode[] = $derived(
|
|
45
|
+
notes.map((n) => ({ id: n.id, label: n.title, weight: n.linkCount })),
|
|
46
|
+
)
|
|
47
|
+
const edges: GraphEdge[] = $derived(
|
|
48
|
+
links.map((l) => ({ id: l.id, source: l.from, target: l.to })),
|
|
49
|
+
)
|
|
50
|
+
</script>
|
|
51
|
+
|
|
52
|
+
<GraphView {nodes} {edges} onNodeClick={(n) => open(n.id)} />
|
|
5
53
|
```
|
|
6
|
-
|
|
54
|
+
|
|
55
|
+
## Type
|
|
56
|
+
|
|
57
|
+
`feature`
|
|
58
|
+
|
|
59
|
+
## Installation
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
npm install @molecule/app-feature-graph-view-svelte @molecule/app-svelte @molecule/app-ui @molecule/app-ui-svelte svelte
|
|
7
63
|
```
|
|
8
64
|
|
|
9
|
-
|
|
65
|
+
## API
|
|
66
|
+
|
|
67
|
+
### Interfaces
|
|
68
|
+
|
|
69
|
+
#### `ForceLayoutOptions`
|
|
70
|
+
|
|
71
|
+
Force-layout tunables.
|
|
72
|
+
|
|
73
|
+
```typescript
|
|
74
|
+
interface ForceLayoutOptions {
|
|
75
|
+
/** Hard cap on iterations. Defaults to {@link DEFAULT_FORCE_ITERATIONS}. */
|
|
76
|
+
iterations?: number
|
|
77
|
+
/** Repulsive constant between every pair of nodes. */
|
|
78
|
+
repulsion?: number
|
|
79
|
+
/** Spring (Hooke) constant for edges. */
|
|
80
|
+
spring?: number
|
|
81
|
+
/** Ideal edge length (rest distance). */
|
|
82
|
+
restLength?: number
|
|
83
|
+
/** Velocity damping per step (0–1). */
|
|
84
|
+
damping?: number
|
|
85
|
+
/** Optional deterministic seed (for tests). Defaults to a fixed value. */
|
|
86
|
+
seed?: number
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
#### `GraphPoint`
|
|
91
|
+
|
|
92
|
+
A 2-D point in graph (world) coordinates.
|
|
93
|
+
|
|
94
|
+
```typescript
|
|
95
|
+
interface GraphPoint {
|
|
96
|
+
/** X coordinate. */
|
|
97
|
+
x: number
|
|
98
|
+
/** Y coordinate. */
|
|
99
|
+
y: number
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
#### `GraphNode`
|
|
104
|
+
|
|
105
|
+
Single node in the graph.
|
|
106
|
+
|
|
107
|
+
`group` is an opaque grouping discriminator (e.g. tag, folder) the
|
|
108
|
+
caller can use for colouring; `weight` scales the rendered radius.
|
|
109
|
+
|
|
110
|
+
```typescript
|
|
111
|
+
interface GraphNode {
|
|
112
|
+
/** Unique node id. */
|
|
113
|
+
id: string
|
|
114
|
+
/** Human-readable label rendered next to the node. */
|
|
115
|
+
label: string
|
|
116
|
+
/** Optional grouping discriminator (e.g. tag id). */
|
|
117
|
+
group?: string
|
|
118
|
+
/** Optional weight; default 1. Scales the rendered radius. */
|
|
119
|
+
weight?: number
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
#### `GraphEdge`
|
|
124
|
+
|
|
125
|
+
Edge connecting two nodes by id.
|
|
126
|
+
|
|
127
|
+
```typescript
|
|
128
|
+
interface GraphEdge {
|
|
129
|
+
/** Unique edge id. */
|
|
130
|
+
id: string
|
|
131
|
+
/** Source node id. */
|
|
132
|
+
source: string
|
|
133
|
+
/** Target node id. */
|
|
134
|
+
target: string
|
|
135
|
+
/** Optional weight; default 1. Stronger edges pull harder under force layout. */
|
|
136
|
+
weight?: number
|
|
137
|
+
}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
#### `PositionedNode`
|
|
141
|
+
|
|
142
|
+
Internal positioned node used by the renderer; the `x`/`y` coordinates
|
|
143
|
+
are in world (graph) space, with `(0, 0)` at the canvas centre.
|
|
144
|
+
|
|
145
|
+
```typescript
|
|
146
|
+
interface PositionedNode extends GraphNode {
|
|
147
|
+
/** World-space X coordinate. */
|
|
148
|
+
x: number
|
|
149
|
+
/** World-space Y coordinate. */
|
|
150
|
+
y: number
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
#### `GraphViewProps`
|
|
155
|
+
|
|
156
|
+
`<GraphView>` props.
|
|
157
|
+
|
|
158
|
+
```typescript
|
|
159
|
+
interface GraphViewProps {
|
|
160
|
+
/** Nodes to render. */
|
|
161
|
+
nodes: GraphNode[]
|
|
162
|
+
/** Edges to render. */
|
|
163
|
+
edges: GraphEdge[]
|
|
164
|
+
/** Fired when the user clicks (or activates) a node. */
|
|
165
|
+
onNodeClick?: (node: GraphNode) => void
|
|
166
|
+
/** Currently-selected node id (highlighted in the view). */
|
|
167
|
+
selectedNodeId?: string
|
|
168
|
+
/** Layout strategy. Defaults to `'force'`. */
|
|
169
|
+
layout?: GraphLayout
|
|
170
|
+
/** Custom node renderer (overrides the default circle + label). */
|
|
171
|
+
nodeRenderer?: GraphNodeRenderer
|
|
172
|
+
/** Custom edge renderer (overrides the default `<line>`). */
|
|
173
|
+
edgeRenderer?: GraphEdgeRenderer
|
|
174
|
+
/** Force-layout tunables; ignored for non-force layouts. */
|
|
175
|
+
forceOptions?: ForceLayoutOptions
|
|
176
|
+
/** Extra classes merged onto the outer wrapper. */
|
|
177
|
+
className?: string
|
|
178
|
+
}
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
### Types
|
|
182
|
+
|
|
183
|
+
#### `GraphLayout`
|
|
184
|
+
|
|
185
|
+
Available layout strategies.
|
|
186
|
+
|
|
187
|
+
```typescript
|
|
188
|
+
type GraphLayout = 'force' | 'circular' | 'grid'
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
#### `GraphNodeRenderer`
|
|
192
|
+
|
|
193
|
+
Renderer for an individual node: a snippet receiving the positioned node.
|
|
194
|
+
|
|
195
|
+
```typescript
|
|
196
|
+
type GraphNodeRenderer = Snippet<[PositionedNode]>
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
#### `GraphEdgeRenderer`
|
|
200
|
+
|
|
201
|
+
Renderer for an individual edge: a snippet receiving the edge plus both endpoints.
|
|
202
|
+
|
|
203
|
+
```typescript
|
|
204
|
+
type GraphEdgeRenderer = Snippet<[GraphEdge, PositionedNode, PositionedNode]>
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
### Functions
|
|
208
|
+
|
|
209
|
+
#### `createRng(seed)`
|
|
210
|
+
|
|
211
|
+
Tiny deterministic PRNG (mulberry32). Allows reproducible initial
|
|
212
|
+
positions in tests without depending on `Math.random()`.
|
|
213
|
+
|
|
214
|
+
```typescript
|
|
215
|
+
function createRng(seed: number): () => number
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
- `seed` — 32-bit unsigned seed.
|
|
219
|
+
|
|
220
|
+
**Returns:** A function returning floats in `[0, 1)`.
|
|
221
|
+
|
|
222
|
+
#### `circularLayout(nodes, radius)`
|
|
223
|
+
|
|
224
|
+
Place nodes evenly around the unit circle (scaled by `radius`).
|
|
225
|
+
|
|
226
|
+
```typescript
|
|
227
|
+
function circularLayout(nodes: GraphNode[], radius: number): PositionedNode[]
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
- `nodes` — Nodes to position.
|
|
231
|
+
- `radius` — Circle radius in world units.
|
|
232
|
+
|
|
233
|
+
**Returns:** Positioned nodes, in input order.
|
|
234
|
+
|
|
235
|
+
#### `gridLayout(nodes, spacing)`
|
|
236
|
+
|
|
237
|
+
Place nodes on a square-ish grid, centred on the origin.
|
|
238
|
+
|
|
239
|
+
```typescript
|
|
240
|
+
function gridLayout(nodes: GraphNode[], spacing: number): PositionedNode[]
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
- `nodes` — Nodes to position.
|
|
244
|
+
- `spacing` — Pixel spacing between adjacent grid cells.
|
|
245
|
+
|
|
246
|
+
**Returns:** Positioned nodes, in input order.
|
|
247
|
+
|
|
248
|
+
#### `forceLayout(nodes, edges, options)`
|
|
249
|
+
|
|
250
|
+
Run a minimal velocity-Verlet force-directed simulation.
|
|
251
|
+
|
|
252
|
+
Implements:
|
|
253
|
+
|
|
254
|
+
- Pairwise repulsion (Coulomb-like, O(n²)) between every node pair.
|
|
255
|
+
- Spring (Hooke) attraction along each edge toward `restLength`.
|
|
256
|
+
- Per-step velocity damping for stability.
|
|
257
|
+
|
|
258
|
+
Stops early once the maximum per-node displacement-squared drops below
|
|
259
|
+
{@link CONVERGENCE_EPSILON}, or after `iterations` steps — whichever
|
|
260
|
+
comes first.
|
|
261
|
+
|
|
262
|
+
```typescript
|
|
263
|
+
function forceLayout(
|
|
264
|
+
nodes: GraphNode[],
|
|
265
|
+
edges: GraphEdge[],
|
|
266
|
+
options?: ForceLayoutOptions,
|
|
267
|
+
): PositionedNode[]
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
- `nodes` — Nodes to lay out.
|
|
271
|
+
- `edges` — Edges (used only for attractive springs).
|
|
272
|
+
- `options` — Force-layout tunables.
|
|
273
|
+
|
|
274
|
+
**Returns:** Positioned nodes, in input order.
|
|
275
|
+
|
|
276
|
+
#### `layoutNodes(nodes, edges, layout, options)`
|
|
277
|
+
|
|
278
|
+
Compute world-space positions for every node using the chosen layout.
|
|
279
|
+
|
|
280
|
+
```typescript
|
|
281
|
+
function layoutNodes(
|
|
282
|
+
nodes: GraphNode[],
|
|
283
|
+
edges: GraphEdge[],
|
|
284
|
+
layout: GraphLayout,
|
|
285
|
+
options?: ForceLayoutOptions,
|
|
286
|
+
): PositionedNode[]
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
- `nodes` — Nodes to position.
|
|
290
|
+
- `edges` — Edges (consumed only by `force`).
|
|
291
|
+
- `layout` — Layout strategy.
|
|
292
|
+
- `options` — Optional force-layout tunables (ignored for non-force).
|
|
293
|
+
|
|
294
|
+
**Returns:** Positioned nodes.
|
|
295
|
+
|
|
296
|
+
#### `boundingBox(nodes, padding)`
|
|
297
|
+
|
|
298
|
+
Compute the world-space bounding box of a set of positioned nodes,
|
|
299
|
+
with a small padding for visual breathing room.
|
|
300
|
+
|
|
301
|
+
```typescript
|
|
302
|
+
function boundingBox(
|
|
303
|
+
nodes: PositionedNode[],
|
|
304
|
+
padding?: number,
|
|
305
|
+
): { minX: number; minY: number; maxX: number; maxY: number } | null
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
- `nodes` — Positioned nodes.
|
|
309
|
+
- `padding` — Padding (world units) added to every side. Default 40.
|
|
310
|
+
|
|
311
|
+
**Returns:** Bounding box `{ minX, minY, maxX, maxY }` — or `null` if empty.
|
|
312
|
+
|
|
313
|
+
### Constants
|
|
314
|
+
|
|
315
|
+
#### `GraphView`
|
|
316
|
+
|
|
317
|
+
```typescript
|
|
318
|
+
const GraphView: LegacyComponentType
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
#### `DEFAULT_FORCE_ITERATIONS`
|
|
322
|
+
|
|
323
|
+
Default cap on force-layout iterations.
|
|
324
|
+
|
|
325
|
+
```typescript
|
|
326
|
+
const DEFAULT_FORCE_ITERATIONS: 200
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
#### `DEFAULT_REPULSION`
|
|
330
|
+
|
|
331
|
+
Default repulsion strength used by `forceLayout`.
|
|
332
|
+
|
|
333
|
+
```typescript
|
|
334
|
+
const DEFAULT_REPULSION: 800
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
#### `DEFAULT_SPRING`
|
|
338
|
+
|
|
339
|
+
Default spring stiffness used by `forceLayout`.
|
|
340
|
+
|
|
341
|
+
```typescript
|
|
342
|
+
const DEFAULT_SPRING: 0.05
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
#### `DEFAULT_REST_LENGTH`
|
|
346
|
+
|
|
347
|
+
Default ideal edge length used by `forceLayout`.
|
|
348
|
+
|
|
349
|
+
```typescript
|
|
350
|
+
const DEFAULT_REST_LENGTH: 80
|
|
351
|
+
```
|
|
352
|
+
|
|
353
|
+
#### `DEFAULT_DAMPING`
|
|
354
|
+
|
|
355
|
+
Default velocity damping used by `forceLayout`.
|
|
356
|
+
|
|
357
|
+
```typescript
|
|
358
|
+
const DEFAULT_DAMPING: 0.85
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
#### `CONVERGENCE_EPSILON`
|
|
362
|
+
|
|
363
|
+
Convergence threshold (max per-node displacement squared).
|
|
364
|
+
|
|
365
|
+
```typescript
|
|
366
|
+
const CONVERGENCE_EPSILON: 0.01
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
## Injection Notes
|
|
370
|
+
|
|
371
|
+
### Requirements
|
|
372
|
+
|
|
373
|
+
Peer dependencies:
|
|
374
|
+
|
|
375
|
+
- `@molecule/app-svelte` ^3.5.0
|
|
376
|
+
- `@molecule/app-ui` ^1.0.1
|
|
377
|
+
- `@molecule/app-ui-svelte` ^1.1.0
|
|
378
|
+
- `svelte` ^5.0.0
|
|
379
|
+
|
|
380
|
+
### Runtime Dependencies
|
|
381
|
+
|
|
382
|
+
- `@molecule/app-svelte`
|
|
383
|
+
- `@molecule/app-ui`
|
|
384
|
+
- `@molecule/app-ui-svelte`
|
|
385
|
+
- `svelte`
|
|
386
|
+
|
|
387
|
+
The root element fills 100% of its parent — the PARENT must have an
|
|
388
|
+
explicit height (e.g. a fixed-height panel or a flex/grid track) or
|
|
389
|
+
the graph renders zero-tall and appears blank.
|
|
390
|
+
|
|
391
|
+
Interaction surface is click / keyboard-activate + `selectedNodeId`
|
|
392
|
+
highlighting only. Nodes are NOT draggable and there is no built-in
|
|
393
|
+
pan / zoom — the SVG `viewBox` auto-fits the layout bounds. For a
|
|
394
|
+
pannable / zoomable surface, compose with
|
|
395
|
+
`@molecule/app-feature-canvas-svelte` instead.
|
|
396
|
+
|
|
397
|
+
Layout is deterministic (seeded RNG), computed once per
|
|
398
|
+
`(nodes, edges, layout, forceOptions)` change. `forceOptions` is
|
|
399
|
+
ignored by the `circular` and `grid` layouts.
|
|
400
|
+
|
|
401
|
+
## Translations
|
|
10
402
|
|
|
11
|
-
|
|
403
|
+
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-svelte",
|
|
3
|
-
"version": "
|
|
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-svelte",
|
|
6
6
|
"type": "module",
|
|
@@ -61,9 +61,9 @@
|
|
|
61
61
|
"@molecule/app-framework-conformance": "0.0.0",
|
|
62
62
|
"@molecule/app-i18n": "1.2.2",
|
|
63
63
|
"@molecule/app-icons": "1.0.4",
|
|
64
|
-
"@molecule/app-svelte": "3.
|
|
65
|
-
"@molecule/app-ui": "1.
|
|
66
|
-
"@molecule/app-ui-svelte": "1.1
|
|
64
|
+
"@molecule/app-svelte": "3.9.0",
|
|
65
|
+
"@molecule/app-ui": "1.5.0",
|
|
66
|
+
"@molecule/app-ui-svelte": "1.2.1",
|
|
67
67
|
"@sveltejs/package": "3.0.2",
|
|
68
68
|
"@sveltejs/vite-plugin-svelte": "7.1.2",
|
|
69
69
|
"@types/node": "26.6.5",
|