jsmind 0.9.0 → 2.0.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 (40) hide show
  1. package/LICENSE +2 -2
  2. package/README.md +78 -67
  3. package/README.zh.md +81 -0
  4. package/dist/cli.js +4482 -0
  5. package/dist/cli.js.map +1 -0
  6. package/dist/jsmind.cjs +4101 -0
  7. package/dist/jsmind.cjs.map +1 -0
  8. package/dist/jsmind.d.ts +1269 -0
  9. package/dist/jsmind.js +4099 -0
  10. package/dist/jsmind.js.map +1 -0
  11. package/dist/jsmind.umd.js +4107 -0
  12. package/dist/jsmind.umd.js.map +1 -0
  13. package/package.json +65 -52
  14. package/es6/README-en.md +0 -37
  15. package/es6/README.md +0 -34
  16. package/es6/jsmind.draggable-node.js +0 -9
  17. package/es6/jsmind.draggable-node.js.map +0 -1
  18. package/es6/jsmind.js +0 -9
  19. package/es6/jsmind.js.map +0 -1
  20. package/es6/jsmind.screenshot.js +0 -9
  21. package/es6/jsmind.screenshot.js.map +0 -1
  22. package/style/jsmind.css +0 -408
  23. package/types/generated/index.d.ts +0 -8
  24. package/types/generated/jsmind.common.d.ts +0 -66
  25. package/types/generated/jsmind.d.ts +0 -343
  26. package/types/generated/jsmind.data_provider.d.ts +0 -56
  27. package/types/generated/jsmind.dom.d.ts +0 -59
  28. package/types/generated/jsmind.format.d.ts +0 -100
  29. package/types/generated/jsmind.graph.d.ts +0 -180
  30. package/types/generated/jsmind.layout_provider.d.ts +0 -182
  31. package/types/generated/jsmind.mind.d.ts +0 -121
  32. package/types/generated/jsmind.node.d.ts +0 -62
  33. package/types/generated/jsmind.option.d.ts +0 -64
  34. package/types/generated/jsmind.plugin.d.ts +0 -21
  35. package/types/generated/jsmind.shortcut_provider.d.ts +0 -52
  36. package/types/generated/jsmind.util.d.ts +0 -26
  37. package/types/generated/jsmind.view_provider.d.ts +0 -347
  38. package/types/generated/plugins/jsmind.draggable-node.d.ts +0 -229
  39. package/types/generated/plugins/jsmind.screenshot.d.ts +0 -83
  40. package/types/tsconfig.declaration.json +0 -19
@@ -0,0 +1,1269 @@
1
+ /**
2
+ * @license BSD-3-Clause
3
+ * @copyright 2014-2025 hizzgdev@163.com
4
+ *
5
+ * Project Home:
6
+ * https://github.com/hizzgdev/jsmind-v2/
7
+ */
8
+ /**
9
+ * Interface for observer pattern.
10
+ *
11
+ * @public
12
+ */
13
+ interface JmObserver<T> {
14
+ /**
15
+ * This method will be called when state changes in observed object.
16
+ *
17
+ * @param observedObject - The object being observed.
18
+ * @param event - The event data.
19
+ */
20
+ update(observedObject: T, event: unknown): void;
21
+ }
22
+
23
+ /**
24
+ * Manager for observers of an observed object.
25
+ *
26
+ * @public
27
+ */
28
+ declare class JmObserverManager<T> {
29
+ /** The object being observed. */
30
+ observedObject: T;
31
+ /** @internal */
32
+ _observers: JmObserver<T>[];
33
+ /**
34
+ * Creates an observer manager for an observed object.
35
+ *
36
+ * @param observedObject - The object to observe.
37
+ */
38
+ constructor(observedObject: T);
39
+ /**
40
+ * Adds an observer to the observed object.
41
+ *
42
+ * @param observer - An object that contains an `update(observedObject, event)` method.
43
+ * @throws {@link JsMindError} If the observer is not a valid JmObserver instance.
44
+ */
45
+ addObserver(observer: JmObserver<T>): void;
46
+ /**
47
+ * Removes an observer that was previously added by the `addObserver` method.
48
+ *
49
+ * @param observer - The observer to remove.
50
+ */
51
+ removeObserver(observer: JmObserver<T>): void;
52
+ /**
53
+ * Removes all observers from the object.
54
+ */
55
+ clearObservers(): void;
56
+ /**
57
+ * Notifies the event to all observers.
58
+ *
59
+ * @remarks
60
+ * This is an asynchronous method. Each observer is notified in a separate
61
+ * asynchronous operation.
62
+ *
63
+ * @param event - Events are defined by different observed objects, which
64
+ * represent specific information about the changes.
65
+ */
66
+ notifyObservers(event: unknown): Promise<void>;
67
+ }
68
+
69
+ /**
70
+ * Style and theme data structures for JsMind mind maps.
71
+ *
72
+ * @remarks
73
+ * This module only defines data. Nothing here draws anything — the rendering
74
+ * layer consumes these values but never appears in this file.
75
+ *
76
+ * @packageDocumentation
77
+ */
78
+ /**
79
+ * Semantic tone. Expresses color only, never geometry.
80
+ *
81
+ * @remarks
82
+ * Semantic roles are about color; geometry is orthogonal (a node can be
83
+ * warning-colored, thick-bordered and large-font at once). Keeping them apart
84
+ * gives the agent fewer side effects per change, which makes generated output
85
+ * more controllable.
86
+ *
87
+ * @public
88
+ */
89
+ declare const JmTone: {
90
+ /** Default tone, resolved from the theme's neutral palette. */
91
+ readonly Default: "default";
92
+ /** Primary or emphasis tone. */
93
+ readonly Primary: "primary";
94
+ /** Success or positive tone. */
95
+ readonly Success: "success";
96
+ /** Warning or caution tone. */
97
+ readonly Warning: "warning";
98
+ /** Danger or negative tone. */
99
+ readonly Danger: "danger";
100
+ /** Informational or neutral-accent tone. */
101
+ readonly Info: "info";
102
+ /**
103
+ * Accent tone for an element that stands out without carrying a judgement.
104
+ *
105
+ * @remarks
106
+ * `primary` already means "this is the important one", which is a claim
107
+ * about the content. `accent` is the option for "make this one visually
108
+ * distinct" with no claim attached — the purple that v1 exposed as
109
+ * `theme-wisteria` and that none of the semantic tones could absorb.
110
+ */
111
+ readonly Accent: "accent";
112
+ };
113
+ type JmTone = typeof JmTone[keyof typeof JmTone];
114
+ /**
115
+ * Font weight.
116
+ *
117
+ * @remarks
118
+ * An enum rather than an inline union so the CLI can enumerate the accepted
119
+ * values instead of repeating them. `JmLinePattern` and `JmLineCurve` had this
120
+ * shape already; `fontWeight` was the odd one out.
121
+ *
122
+ * @public
123
+ */
124
+ declare const JmFontWeight: {
125
+ /** Regular weight. */
126
+ readonly Normal: "normal";
127
+ /** Emphasised weight. */
128
+ readonly Bold: "bold";
129
+ };
130
+ type JmFontWeight = typeof JmFontWeight[keyof typeof JmFontWeight];
131
+ /**
132
+ * Line dash style.
133
+ *
134
+ * @public
135
+ */
136
+ declare const JmLinePattern: {
137
+ /** Continuous line. */
138
+ readonly Solid: "solid";
139
+ /** Dashed line. */
140
+ readonly Dashed: "dashed";
141
+ /** Dotted line. */
142
+ readonly Dotted: "dotted";
143
+ };
144
+ type JmLinePattern = typeof JmLinePattern[keyof typeof JmLinePattern];
145
+ /**
146
+ * How a line travels between its two endpoints.
147
+ *
148
+ * @remarks
149
+ * A different axis from {@link JmLinePattern}: `pattern` says whether the
150
+ * stroke is dashed, `curve` says what shape it traces. They are separable on
151
+ * purpose - a straight dashed line and a curved dashed line both need to exist,
152
+ * and a single `style` string (as in v1's `line_style`) could only ever express
153
+ * one of the two.
154
+ *
155
+ * @public
156
+ */
157
+ declare const JmLineCurve: {
158
+ /** Straight segment from one endpoint to the other. */
159
+ readonly Straight: "straight";
160
+ /**
161
+ * Cubic bezier leaving each endpoint horizontally.
162
+ *
163
+ * @remarks
164
+ * The default, and what v1 drew. Edges leaving a node always read better
165
+ * when they depart along the horizontal axis: siblings sit in a column, so a
166
+ * straight segment between two of them cuts diagonally across the layout.
167
+ */
168
+ readonly Bezier: "bezier";
169
+ };
170
+ type JmLineCurve = typeof JmLineCurve[keyof typeof JmLineCurve];
171
+ /**
172
+ * Visual style of a single line.
173
+ *
174
+ * @remarks
175
+ * Shared by two places: `JmNodeStyle.incoming` (the line connecting a node to
176
+ * its parent) and `JmEdge.style` (lines for additional, non-hierarchical
177
+ * relationships). One shape avoids two vocabularies for the same thing.
178
+ *
179
+ * @public
180
+ */
181
+ interface JmLineStyle {
182
+ /** Line color, e.g. `#4a9eff`. */
183
+ color?: string;
184
+ /** Line width in pixels. */
185
+ width?: number;
186
+ /**
187
+ * Line pattern.
188
+ *
189
+ * @remarks
190
+ * Named `pattern` rather than `style` because this type is itself reached
191
+ * through `node.style.incoming`, and `.style.style` reads badly. `pattern`
192
+ * also covers `solid` honestly — `solid` is not a dash.
193
+ */
194
+ pattern?: JmLinePattern;
195
+ /** How the line travels between its endpoints. Defaults to `bezier`. */
196
+ curve?: JmLineCurve;
197
+ }
198
+ /**
199
+ * Visual overrides for a single node.
200
+ *
201
+ * @remarks
202
+ * Every field is optional and unset fields fall back to the theme. The node
203
+ * carries only what differs from the theme, so a theme change still reaches
204
+ * every node that did not explicitly override anything.
205
+ *
206
+ * `incoming` lives on the child node: a line connects exactly one child, which
207
+ * makes the child the natural owner. The name mirrors the layout layer
208
+ * (`calculateNodeIncomingPoint` / `calculateNodeOutgoingPoint`).
209
+ *
210
+ * @public
211
+ */
212
+ interface JmNodeStyle {
213
+ /** Semantic tone for this node. Overrides background/border/color from the theme. */
214
+ tone?: JmTone;
215
+ /** Background color, e.g. `#ffffff`. */
216
+ background?: string;
217
+ /** Text color. */
218
+ color?: string;
219
+ /** Border color. */
220
+ borderColor?: string;
221
+ /** Border width in pixels. */
222
+ borderWidth?: number;
223
+ /** Border dash style. */
224
+ borderStyle?: JmLinePattern;
225
+ /** Font size in pixels. */
226
+ fontSize?: number;
227
+ /** Font weight. */
228
+ fontWeight?: JmFontWeight;
229
+ /** Style of the line connecting this node to its parent. */
230
+ incoming?: JmLineStyle;
231
+ }
232
+ /**
233
+ * Colors a tone resolves to.
234
+ *
235
+ * @remarks
236
+ * `line` is the color of the connecting line, which usually differs from
237
+ * `border` so that a subtree reads as one visual grouping.
238
+ *
239
+ * @public
240
+ */
241
+ interface JmTonePalette {
242
+ /**
243
+ * Node background color.
244
+ *
245
+ * @remarks
246
+ * Every field here carries a `Color` suffix. The palette sits alongside
247
+ * `JmNodeStyle`, which already uses `borderColor`, so `borderColor` means
248
+ * the same thing in both places and an agent reading the JSON never has to
249
+ * guess whether `fill` or `border` is a color or a length.
250
+ */
251
+ fillColor: string;
252
+ /** Node text color. */
253
+ textColor: string;
254
+ /** Node border color. */
255
+ borderColor: string;
256
+ /** Connecting line color. */
257
+ lineColor: string;
258
+ }
259
+ /**
260
+ * One drop shadow, in CSS terms.
261
+ *
262
+ * @remarks
263
+ * Spelled out as four numbers and a color rather than kept as a CSS string
264
+ * like `"1px 1px 1px #666"` so it can be merged field by field — an override
265
+ * that changes only the blur should not have to restate the offsets — and so
266
+ * an agent writing the JSON never has to get CSS shorthand syntax right.
267
+ *
268
+ * @public
269
+ */
270
+ interface JmThemeShadowLayer {
271
+ /** Horizontal offset in pixels. */
272
+ offsetX: number;
273
+ /** Vertical offset in pixels. */
274
+ offsetY: number;
275
+ /** Blur radius in pixels. */
276
+ blur: number;
277
+ /** Shadow color, e.g. `#666666`. */
278
+ color: string;
279
+ }
280
+ /**
281
+ * Drop shadows for the three visual states a node can be in.
282
+ *
283
+ * @remarks
284
+ * States live in the theme rather than in CSS because they change the node's
285
+ * appearance, and "how does this node look" belongs with the rest of the
286
+ * appearance. `normal` is the resting state; `hover` and `selected` are what
287
+ * the pointer and the selection do to it.
288
+ *
289
+ * @public
290
+ */
291
+ interface JmThemeShadow {
292
+ /** Shadow when the node is idle. */
293
+ normal: JmThemeShadowLayer;
294
+ /** Shadow while the pointer is over the node. */
295
+ hover: JmThemeShadowLayer;
296
+ /** Shadow when the node is selected. */
297
+ selected: JmThemeShadowLayer;
298
+ }
299
+ /**
300
+ * A partial replacement for {@link JmThemeShadow}.
301
+ *
302
+ * @remarks
303
+ * Every level is optional so a style can restyle one state, or one field of one
304
+ * state (`hover.blur`), without restating the rest. The merged result is always
305
+ * complete.
306
+ *
307
+ * @public
308
+ */
309
+ interface JmThemeShadowOverride {
310
+ /** Override for the idle shadow. */
311
+ normal?: Partial<JmThemeShadowLayer>;
312
+ /** Override for the hover shadow. */
313
+ hover?: Partial<JmThemeShadowLayer>;
314
+ /** Override for the selected shadow. */
315
+ selected?: Partial<JmThemeShadowLayer>;
316
+ }
317
+ /**
318
+ * Partial overrides for {@link JmThemeNode}.
319
+ *
320
+ * @remarks
321
+ * Identical to `Partial<JmThemeNode>` except for `shadow`, which allows
322
+ * overriding a single state rather than all three.
323
+ *
324
+ * @public
325
+ */
326
+ type JmThemeNodeOverride = Omit<Partial<JmThemeNode>, 'shadow'> & {
327
+ /** Override for the node shadows. */
328
+ shadow?: JmThemeShadowOverride;
329
+ };
330
+ /**
331
+ * Geometry and typography shared by every node.
332
+ *
333
+ * @public
334
+ */
335
+ interface JmThemeNode {
336
+ /** Corner radius in pixels. */
337
+ radius: number;
338
+ /** Inner padding in pixels. */
339
+ padding: number;
340
+ /** Base font size in pixels. */
341
+ fontSize: number;
342
+ /**
343
+ * Root node font size in pixels.
344
+ *
345
+ * @remarks
346
+ * Separate from `fontSize` because the root is the one node that reads as a
347
+ * title: v1 rendered it at 24px against a 16px body. Folding it into
348
+ * `fontSize` would have forced every theme to pick one and lose the
349
+ * hierarchy.
350
+ */
351
+ rootFontSize: number;
352
+ /** Font family. */
353
+ fontFamily: string;
354
+ /**
355
+ * Line height as a multiple of the font size.
356
+ *
357
+ * @remarks
358
+ * Unitless multiplier, matching the CSS `line-height: 1.125` form, so it
359
+ * scales with `fontSize` instead of needing a matching pixel value per size.
360
+ */
361
+ lineHeight: number;
362
+ /** Default border width in pixels. */
363
+ borderWidth: number;
364
+ /**
365
+ * Maximum node width in pixels before text wraps.
366
+ *
367
+ * @remarks
368
+ * Wrapping is a layout input, not a detail: it decides how tall a node is,
369
+ * which decides where its children go.
370
+ */
371
+ maxWidth: number;
372
+ /** Drop shadows for the idle, hover and selected states. */
373
+ shadow: JmThemeShadow;
374
+ }
375
+ /**
376
+ * Geometry shared by every line of a mind map.
377
+ *
378
+ * @public
379
+ */
380
+ interface JmThemeLine {
381
+ /** Default line width in pixels. */
382
+ width: number;
383
+ /** Default line pattern. Named `pattern` to match `JmLineStyle.pattern`. */
384
+ pattern: JmLinePattern;
385
+ /** Default curve shape. Named `curve` to match `JmLineStyle.curve`. */
386
+ curve: JmLineCurve;
387
+ }
388
+ /**
389
+ * Geometry of the collapse/expand control.
390
+ *
391
+ * @public
392
+ */
393
+ interface JmThemeExpander {
394
+ /** Expander width and height in pixels. */
395
+ size: number;
396
+ /**
397
+ * Corner radius in pixels.
398
+ *
399
+ * @remarks
400
+ * `size / 2` gives a circle, which is what the stylesheet did with
401
+ * `border-radius: 50%`. A number keeps it in the same units as every other
402
+ * length here; percentage radii only make sense when the box can grow.
403
+ */
404
+ radius: number;
405
+ /** Font size of the character or count drawn inside, in pixels. */
406
+ fontSize: number;
407
+ /** Line height of that content, in pixels. */
408
+ lineHeight: number;
409
+ /** Border width in pixels. */
410
+ borderWidth: number;
411
+ }
412
+ /**
413
+ * Style declaration for a whole mind map, as stored in the data file.
414
+ *
415
+ * @remarks
416
+ * Named in the singular, like the per-node and per-edge style fields: one
417
+ * `style` concept, with the scope decided by where it sits. `mind.style` covers
418
+ * the whole map; `node.style` covers one node; `edge.style` covers one edge.
419
+ * Carrying both `styles` and `style` in one document only differed by an `s`,
420
+ * which is a trap for an agent generating the JSON.
421
+ *
422
+ * Read this as: "this mind map looks like this — it inherits from `theme`, then
423
+ * overrides the fields listed below."
424
+ *
425
+ * Splitting inheritance from overrides into one flat declaration avoids the
426
+ * ambiguity of a nested `{ name, ...overrides }` form, where `name` could be
427
+ * read either as "what this theme is called" or as "which theme to inherit".
428
+ * Here `theme` can only mean the latter.
429
+ *
430
+ * - `theme` names a built-in preset to inherit from. Omitted means `"default"`,
431
+ * so a file that only overrides a few colors does not have to name it.
432
+ * - Every other field is an override applied on top of that preset, merged
433
+ * deeply.
434
+ *
435
+ * @public
436
+ */
437
+ interface JmStyle {
438
+ /** Name of the built-in theme to inherit from. Defaults to `"default"`. */
439
+ theme?: string;
440
+ /** Canvas background color. */
441
+ background?: string;
442
+ /** Per-tone color overrides. */
443
+ tones?: Partial<Record<JmTone, Partial<JmTonePalette>>>;
444
+ /** Node geometry overrides. */
445
+ node?: JmThemeNodeOverride;
446
+ /** Line geometry overrides. */
447
+ line?: Partial<JmThemeLine>;
448
+ /** Expander geometry overrides. */
449
+ expander?: Partial<JmThemeExpander>;
450
+ }
451
+
452
+ /**
453
+ * Options for creating a new edge.
454
+ *
455
+ * @public
456
+ */
457
+ interface EdgeCreationOptions {
458
+ /** Optional edge ID, will be generated if not provided. */
459
+ edgeId?: string;
460
+ /** Optional label for the edge. */
461
+ label?: string;
462
+ /** Optional visual style for the edge line. */
463
+ style?: JmLineStyle;
464
+ }
465
+ /**
466
+ * Edge of mind map.
467
+ *
468
+ * @remarks
469
+ * Edges represent additional relationships between nodes (not parent-child relationships).
470
+ *
471
+ * @public
472
+ */
473
+ declare class JmEdge {
474
+ /** The unique identifier of the edge. */
475
+ id: string;
476
+ /** The ID of the source node. */
477
+ sourceNodeId: string;
478
+ /** The ID of the target node. */
479
+ targetNodeId: string;
480
+ /** The type of the edge. */
481
+ type: JmEdgeType;
482
+ /** The optional label of the edge. */
483
+ label: string | null;
484
+ /**
485
+ * Visual style of the edge line.
486
+ *
487
+ * @remarks
488
+ * Uses the same `JmLineStyle` as `JmNodeStyle.incoming` so that
489
+ * hierarchical and additional relationships share one vocabulary.
490
+ */
491
+ style?: JmLineStyle;
492
+ /**
493
+ * Creates a new edge.
494
+ *
495
+ * @param id - The unique identifier of the edge.
496
+ * @param sourceNodeId - The ID of the source node.
497
+ * @param targetNodeId - The ID of the target node.
498
+ * @param type - The type of the edge.
499
+ * @param label - Optional label for the edge.
500
+ * @throws {@link JsMindError} If any of the required parameters are invalid.
501
+ */
502
+ constructor(id: string, sourceNodeId: string, targetNodeId: string, type: JmEdgeType, label?: string | null);
503
+ }
504
+ /**
505
+ * Type of edge - only for additional relationships (not parent-child).
506
+ *
507
+ * @public
508
+ */
509
+ declare const JmEdgeType: {
510
+ /** Link edge type. */
511
+ readonly Link: "link";
512
+ };
513
+ type JmEdgeType = typeof JmEdgeType[keyof typeof JmEdgeType];
514
+
515
+ /**
516
+ * Represents a size with width and height.
517
+ *
518
+ * @public
519
+ */
520
+ declare class JmSize {
521
+ /** The width value. */
522
+ width: number;
523
+ /** The height value. */
524
+ height: number;
525
+ /**
526
+ * Creates a new size instance.
527
+ *
528
+ * @param width - The width value.
529
+ * @param height - The height value.
530
+ */
531
+ constructor(width: number, height: number);
532
+ }
533
+ declare class JmPoint {
534
+ x: number;
535
+ y: number;
536
+ constructor(x: number, y: number);
537
+ offset(offset: JmPoint): JmPoint;
538
+ static readonly Zero: JmPoint;
539
+ }
540
+
541
+ declare class JmElement {
542
+ private readonly ATTR_PREFIX;
543
+ private readonly _element;
544
+ private _cachedRect;
545
+ constructor(element: HTMLElement);
546
+ get element(): HTMLElement;
547
+ get classList(): DOMTokenList;
548
+ get innerHTML(): string;
549
+ set innerHTML(value: string);
550
+ get cachedRect(): JmSize;
551
+ set cachedRect(rect: DOMRect);
552
+ get style(): CSSStyleDeclaration;
553
+ get clientWidth(): number;
554
+ get clientHeight(): number;
555
+ hide(): void;
556
+ show(position: JmPoint): void;
557
+ setAttribute(key: string, value: string): void;
558
+ getAttribute(key: string): string | null;
559
+ removeAttribute(key: string): void;
560
+ appendChild(child: JmElement | HTMLElement | SVGSVGElement): void;
561
+ }
562
+
563
+ /**
564
+ * Content types and utilities for JsMind nodes.
565
+ *
566
+ * @packageDocumentation
567
+ */
568
+ /**
569
+ * Enumeration for content types of node.
570
+ *
571
+ * @public
572
+ */
573
+ declare const JmNodeContentType: {
574
+ /** Text content type. */
575
+ readonly Text: "text";
576
+ };
577
+ type JmNodeContentType = typeof JmNodeContentType[keyof typeof JmNodeContentType];
578
+ /**
579
+ * Content of mind map node.
580
+ *
581
+ * @public
582
+ */
583
+ declare class JmNodeContent {
584
+ /** The type of the content. */
585
+ type: JmNodeContentType;
586
+ /** The actual content value. */
587
+ value: unknown;
588
+ /**
589
+ * Creates a content object.
590
+ *
591
+ * @param type - The type of content.
592
+ * @param value - The actual content value.
593
+ * @throws {@link Error} If the content type is invalid.
594
+ */
595
+ constructor(type: JmNodeContentType, value: unknown);
596
+ /**
597
+ * Checks if content is of specific type.
598
+ *
599
+ * @param type - The type to check.
600
+ * @returns True if content is of the specified type.
601
+ */
602
+ hasType(type: JmNodeContentType): boolean;
603
+ /**
604
+ * Checks if content is text type.
605
+ *
606
+ * @returns True if content is text type.
607
+ */
608
+ isText(): boolean;
609
+ getText(): string;
610
+ /**
611
+ * Creates a text content object.
612
+ *
613
+ * @param text - The text content.
614
+ * @returns The content object.
615
+ */
616
+ static createText(text: string): JmNodeContent;
617
+ /**
618
+ * Creates a content object from an object with type and value.
619
+ *
620
+ * @param obj - The object to create content from.
621
+ * @returns The content object.
622
+ */
623
+ static fromObject(obj: {
624
+ type: JmNodeContentType;
625
+ value: unknown;
626
+ }): JmNodeContent;
627
+ }
628
+
629
+ /**
630
+ * Options for creating a new node.
631
+ *
632
+ * @public
633
+ */
634
+ interface NodeCreationOptions {
635
+ /** Optional custom node ID. */
636
+ nodeId?: string;
637
+ /** Whether the node is folded (default: false). */
638
+ folded?: boolean;
639
+ /** Direction of the node (default: null). */
640
+ side?: JmNodeSide;
641
+ /** Additional data for the node (default: {}). */
642
+ data?: Record<string, unknown>;
643
+ /** Visual overrides for the node (default: none). */
644
+ style?: JmNodeStyle;
645
+ }
646
+ /**
647
+ * Options for specifying node destination.
648
+ *
649
+ * @public
650
+ */
651
+ interface NodeDestinationOptions {
652
+ /** The ID of the target parent node (required). */
653
+ parentId: string;
654
+ /** The position index among siblings (if not provided, adds to end). */
655
+ position?: number;
656
+ /** The direction of the node (if not provided, keeps current direction). */
657
+ side?: JmNodeSide;
658
+ }
659
+ declare class JmNodeViewData {
660
+ element: JmElement | null;
661
+ expander: JmElement | null;
662
+ leadingLine: SVGPathElement | null;
663
+ }
664
+ declare class JmNodeLayoutData {
665
+ side: JmNodeSide;
666
+ visible: boolean;
667
+ size: JmSize;
668
+ withDescendantsSize: JmSize;
669
+ offsetToParent: JmPoint;
670
+ }
671
+ declare class NodeInternalData {
672
+ view: JmNodeViewData;
673
+ layout: JmNodeLayoutData;
674
+ }
675
+ /**
676
+ * Node of mind map.
677
+ *
678
+ * @public
679
+ */
680
+ declare class JmNode {
681
+ /** The unique identifier of the node. */
682
+ id: string;
683
+ /** The content of the node. */
684
+ content: JmNodeContent;
685
+ /** The parent node, or null if this is the root node. */
686
+ parent: JmNode | null;
687
+ /** Array of child nodes. */
688
+ children: JmNode[];
689
+ /** Whether the node is folded (collapsed). */
690
+ folded: boolean;
691
+ /** The direction of the node. */
692
+ side: JmNodeSide;
693
+ /** Additional data associated with the node. */
694
+ data: Record<string, unknown>;
695
+ /**
696
+ * Visual overrides for this node.
697
+ *
698
+ * @remarks
699
+ * Unset fields fall back to the theme. Storing only the difference keeps
700
+ * theme changes propagating to every node that did not override anything.
701
+ */
702
+ style?: JmNodeStyle;
703
+ /** View data associated with the node. */
704
+ _data: NodeInternalData;
705
+ /**
706
+ * Creates a new node.
707
+ *
708
+ * @param id - The unique identifier of the node.
709
+ * @param content - The content of the node.
710
+ * @throws {@link JsMindError} If the node ID or content is invalid.
711
+ */
712
+ constructor(id: string, content: JmNodeContent);
713
+ /**
714
+ * Lists all subnode IDs recursively.
715
+ *
716
+ * @returns Array of all subnode IDs including this node's children and their descendants.
717
+ */
718
+ getAllSubnodeIds(): string[];
719
+ /**
720
+ * Compares this node with another node.
721
+ *
722
+ * @param other - The other node to compare with.
723
+ * @returns True if they are equal, false otherwise.
724
+ */
725
+ equals(other: JmNode): boolean;
726
+ /**
727
+ * Checks if this node is a descendant of another node.
728
+ *
729
+ * @param potentialAncestor - The potential ancestor node.
730
+ * @returns True if this node is a descendant of potentialAncestor.
731
+ */
732
+ isDescendant(potentialAncestor: JmNode): boolean;
733
+ isRoot(): boolean;
734
+ }
735
+ /**
736
+ * Enumeration for directions of node.
737
+ *
738
+ * @public
739
+ */
740
+ declare const JmNodeSide: {
741
+ /** Left direction. */
742
+ readonly SideB: -1;
743
+ /** Center direction. */
744
+ readonly Center: 0;
745
+ /** Right direction. */
746
+ readonly SideA: 1;
747
+ };
748
+ type JmNodeSide = typeof JmNodeSide[keyof typeof JmNodeSide];
749
+
750
+ /**
751
+ * Metadata for the mind map.
752
+ *
753
+ * @public
754
+ */
755
+ interface MindMetadata {
756
+ /** The author of the mind map. */
757
+ author: string;
758
+ /** The name of the mind map. */
759
+ name: string;
760
+ /** The version of the mind map. */
761
+ version: string;
762
+ }
763
+ /**
764
+ * Configuration options for the mind map.
765
+ *
766
+ * @public
767
+ */
768
+ interface MindOptions {
769
+ rootNodeId: string;
770
+ }
771
+ interface ViewPadding {
772
+ left: number;
773
+ right: number;
774
+ top: number;
775
+ bottom: number;
776
+ }
777
+ declare const ViewExpanderStyle: {
778
+ readonly Char: "char";
779
+ readonly Number: "number";
780
+ };
781
+ type ViewExpanderStyle = typeof ViewExpanderStyle[keyof typeof ViewExpanderStyle];
782
+ interface ViewExpanderOptions {
783
+ style: ViewExpanderStyle;
784
+ }
785
+ interface ViewOptions {
786
+ padding: ViewPadding;
787
+ expander: ViewExpanderOptions;
788
+ }
789
+ interface LayoutOptions {
790
+ parentChildSpace: number;
791
+ siblingSpace: number;
792
+ cousinSpace: number;
793
+ expanderSize: number;
794
+ }
795
+ /**
796
+ * Options for JsMind.
797
+ *
798
+ * @public
799
+ */
800
+ interface JsMindOptions {
801
+ mind: MindOptions;
802
+ view: ViewOptions;
803
+ layout: LayoutOptions;
804
+ }
805
+
806
+ /**
807
+ * Interface for generating unique IDs.
808
+ *
809
+ * @remarks
810
+ * IdGenerator is an interface for generating unique IDs.
811
+ *
812
+ * @example
813
+ * ```typescript
814
+ * class MyIdGenerator extends IdGenerator {
815
+ * constructor() {
816
+ * super();
817
+ * this._seq = 0;
818
+ * }
819
+ * newId() {
820
+ * return 'my' + (this._seq++);
821
+ * }
822
+ * }
823
+ * ```
824
+ *
825
+ * @public
826
+ */
827
+ declare class IdGenerator {
828
+ /**
829
+ * Generates a new unique ID.
830
+ *
831
+ * @returns A new unique ID.
832
+ * @throws {@link Error} If not implemented.
833
+ */
834
+ newId(): string;
835
+ }
836
+ /**
837
+ * Simple implementation of IdGenerator.
838
+ *
839
+ * @public
840
+ */
841
+ declare class SimpleIdGenerator extends IdGenerator {
842
+ /** The seed value for ID generation. */
843
+ seed: number;
844
+ /** The sequence counter. */
845
+ seq: number;
846
+ /** The prefix for generated IDs. */
847
+ prefix: string;
848
+ /**
849
+ * Creates a new SimpleIdGenerator instance.
850
+ *
851
+ * @param prefix - Optional prefix for generated IDs. Defaults to empty string.
852
+ */
853
+ constructor(prefix?: string);
854
+ /**
855
+ * Generates a new unique ID.
856
+ *
857
+ * @returns A new unique ID with the format: prefix + (seed + seq).toString(36)
858
+ */
859
+ newId(): string;
860
+ }
861
+
862
+ /**
863
+ * Represents a mind map with nodes and edges.
864
+ *
865
+ * @public
866
+ */
867
+ declare class JmMind {
868
+ /** Metadata for the mind map. */
869
+ meta: MindMetadata;
870
+ /** Configuration options for the mind map. */
871
+ options: MindOptions;
872
+ /**
873
+ * Style declaration for the mind map.
874
+ *
875
+ * @remarks
876
+ * This mind map inherits from `style.theme` (default `"default"`) and
877
+ * overrides whatever else the declaration lists. Resolution and deep
878
+ * merging happen at render time via `resolveJmStyle`, not here — this
879
+ * field only stores what the file said.
880
+ */
881
+ style?: JmStyle;
882
+ /** Manager for observers of this mind map. */
883
+ observerManager: JmObserverManager<JmMind>;
884
+ /** Manager for node operations. */
885
+ nodeManager: JmNodeManager;
886
+ /** @internal Internal ID generator for nodes and edges. */
887
+ _idGenerator: SimpleIdGenerator;
888
+ /** @internal Dictionary of all nodes by ID. */
889
+ _nodes: Record<string, JmNode>;
890
+ /** @internal Dictionary of all edges by ID. */
891
+ _edges: Record<string, JmEdge>;
892
+ /** @internal The root node of the mind map. */
893
+ _root: JmNode;
894
+ /**
895
+ * Creates a new mind map.
896
+ *
897
+ * @param metadata - Metadata for the mind map.
898
+ * @param options - Configuration options for the mind map.
899
+ */
900
+ constructor(metadata?: Partial<MindMetadata>, options?: Partial<MindOptions>);
901
+ /**
902
+ * Gets the root node.
903
+ *
904
+ * @returns The root node.
905
+ */
906
+ get root(): JmNode;
907
+ /**
908
+ * Adds an edge between two nodes.
909
+ *
910
+ * @param sourceNodeId - The source node ID.
911
+ * @param targetNodeId - The target node ID.
912
+ * @param type - The edge type.
913
+ * @param options - Optional edge creation options.
914
+ * @returns The created edge.
915
+ * @throws {@link JsMindError} If the source or target node does not exist.
916
+ */
917
+ addEdge(sourceNodeId: string, targetNodeId: string, type: JmEdgeType, options?: EdgeCreationOptions): JmEdge;
918
+ addChildNode(content: unknown, parentId: string): JmNode;
919
+ /**
920
+ * Adds a new node to the mind map at a specific destination.
921
+ *
922
+ * @param content - Content for the new node.
923
+ * @param destOptions - Destination options (required).
924
+ * @param nodeOptions - Optional node creation options.
925
+ * @returns The created node.
926
+ * @throws {@link JsMindError} If destOptions.parentId is missing.
927
+ */
928
+ addNode(content: JmNodeContent, destOptions: NodeDestinationOptions, nodeOptions?: NodeCreationOptions): JmNode;
929
+ /**
930
+ * Finds a node from the mind map by the given ID.
931
+ *
932
+ * @param nodeId - The given node ID.
933
+ * @returns The corresponding node in this mind map if it exists, otherwise null.
934
+ */
935
+ findNodeById(nodeId: string): JmNode | null;
936
+ /**
937
+ * Gets all edges for a specific node.
938
+ *
939
+ * @param nodeId - The node ID.
940
+ * @param type - Optional edge type filter.
941
+ * @returns Array of edges involving the node.
942
+ */
943
+ getEdges(nodeId: string, type?: JmEdgeType | null): JmEdge[];
944
+ /**
945
+ * Moves a node to a new parent and position.
946
+ *
947
+ * @param nodeId - The ID of the node to move.
948
+ * @param destOptions - Destination options.
949
+ * @returns The moved node.
950
+ * @throws {@link JsMindError} If destOptions are missing, node not found, or invalid move operation.
951
+ */
952
+ moveNode(nodeId: string, destOptions: NodeDestinationOptions): JmNode;
953
+ /**
954
+ * Removes an edge by ID.
955
+ *
956
+ * @param edgeId - The edge ID to remove.
957
+ * @returns True if the edge was removed, false if not found.
958
+ */
959
+ removeEdge(edgeId: string): boolean;
960
+ /**
961
+ * Removes a node and all its descendants.
962
+ *
963
+ * @param nodeId - The ID of the node to remove.
964
+ * @throws {@link JsMindError} If trying to remove the root node.
965
+ */
966
+ removeNode(nodeId: string): void;
967
+ /**
968
+ * Adds a node to a new parent at a specific position.
969
+ *
970
+ * @private
971
+ * @param node - The node to add.
972
+ * @param targetParent - The new parent node.
973
+ * @param targetPosition - The position index among siblings.
974
+ */
975
+ _addNodeToParent(node: JmNode, targetParent: JmNode, targetPosition?: number | null): void;
976
+ /**
977
+ * Creates the root node.
978
+ *
979
+ * @private
980
+ * @returns The created root node.
981
+ */
982
+ _createRootNode(): JmNode;
983
+ /**
984
+ * Emits NodeMoved event only if something actually changed.
985
+ *
986
+ * @private
987
+ * @param node - The node that was moved.
988
+ * @param oldParent - The old parent node.
989
+ * @param oldPosition - The old position index.
990
+ * @param oldSide - The old side.
991
+ */
992
+ _emitNodeMovedEventIfChanged(node: JmNode, oldParent: JmNode | null, oldPosition: number, oldSide: JmNodeSide | null): void;
993
+ /**
994
+ * Creates a new node and adds it to the mind map.
995
+ *
996
+ * @private
997
+ * @param content - Content for the node.
998
+ * @param nodeOptions - Optional node creation options.
999
+ * @returns The created node.
1000
+ */
1001
+ _newNode(content: JmNodeContent, nodeOptions?: NodeCreationOptions): JmNode;
1002
+ /**
1003
+ * Handles node update events.
1004
+ *
1005
+ * @private
1006
+ * @param node - The node that was updated.
1007
+ * @param prop - The property that was updated.
1008
+ * @param originValue - The original value.
1009
+ * @param newValue - The new value.
1010
+ */
1011
+ _onNodeUpdated(node: JmNode, prop: string, originValue: unknown, newValue: unknown): void;
1012
+ /**
1013
+ * Removes a node from its current parent.
1014
+ *
1015
+ * @private
1016
+ * @param node - The node to remove from parent.
1017
+ */
1018
+ _removeNodeFromParent(node: JmNode): void;
1019
+ /**
1020
+ * Repositions a node within the same parent (optimized operation).
1021
+ *
1022
+ * @private
1023
+ * @param node - The node to reposition.
1024
+ * @param targetPosition - The new position index among siblings.
1025
+ */
1026
+ _repositionNode(node: JmNode, targetPosition: number): void;
1027
+ /**
1028
+ * Retrieves a node by node ID.
1029
+ *
1030
+ * @private
1031
+ * @param nodeId - The node ID.
1032
+ * @returns The corresponding node.
1033
+ * @throws {@link JsMindError} If the node doesn't exist.
1034
+ */
1035
+ _getNodeById(nodeId: string): JmNode;
1036
+ private lite;
1037
+ }
1038
+ /**
1039
+ * Manager for node operations with proxy-based access control.
1040
+ *
1041
+ * @internal
1042
+ */
1043
+ declare class JmNodeManager {
1044
+ /** The mind map instance. */
1045
+ mind: JmMind;
1046
+ /** Set of readonly field names. */
1047
+ readonlyFields: Set<string>;
1048
+ /** Set of unsafe array method names. */
1049
+ unsafeArrayMethods: Set<string>;
1050
+ /**
1051
+ * Creates a new JmNodeManager instance.
1052
+ *
1053
+ * @param mind - The mind map instance.
1054
+ */
1055
+ constructor(mind: JmMind);
1056
+ /**
1057
+ * Manages a node with proxy-based access control.
1058
+ *
1059
+ * @param node - The node to manage.
1060
+ * @returns The managed node with proxy.
1061
+ */
1062
+ manage(node: JmNode): JmNode;
1063
+ /**
1064
+ * Getter trap for the proxy.
1065
+ *
1066
+ * @param node - The node.
1067
+ * @param prop - The property name.
1068
+ * @returns The property value.
1069
+ */
1070
+ getterTrap(node: JmNode, prop: string | symbol): unknown;
1071
+ /**
1072
+ * Setter trap for the proxy.
1073
+ *
1074
+ * @param node - The node.
1075
+ * @param prop - The property name.
1076
+ * @param value - The new value.
1077
+ * @returns True if the operation succeeded.
1078
+ * @throws {@link JsMindError} If trying to set a readonly property.
1079
+ */
1080
+ setterTrap(node: JmNode, prop: string | symbol, value: unknown): boolean;
1081
+ }
1082
+
1083
+ /**
1084
+ * @fileoverview Turns the rendered content of the view's shadow root into an image.
1085
+ *
1086
+ * The browser has no API that converts a DOM subtree into pixels. Element
1087
+ * Capture and Region Capture come closest, but both sit on top of the Screen
1088
+ * Capture API and need the user to grant a capture prompt, which rules them out
1089
+ * for an export a script can call.
1090
+ *
1091
+ * What every DOM-to-image library does instead, and what this does, is hand the
1092
+ * markup back to the browser as an SVG `<foreignObject>` and let the rendering
1093
+ * engine paint it. Canvas only appears at the very end, to turn those pixels
1094
+ * into a file: `drawImage` then `toBlob`. Nothing is redrawn by hand, so the
1095
+ * output matches the view exactly, including text wrapping, shadows and the
1096
+ * theme.
1097
+ *
1098
+ * Excluded from the unit coverage figure (see `test:coverage` in package.json).
1099
+ * Everything left here talks to the browser - cloneNode, Image, canvas - so the
1100
+ * unit suite cannot reach a line of it. The UI suite exercises it for real,
1101
+ * against the built bundle, but a bundle carries no source line numbers to
1102
+ * report coverage against. The parts worth asserting in isolation live in
1103
+ * `export-svg.ts`; what remains is calls into browser APIs with no logic to check.
1104
+ */
1105
+ /** Image formats a caller may ask for. */
1106
+ declare const JmImageType: {
1107
+ readonly Png: "image/png";
1108
+ readonly Jpeg: "image/jpeg";
1109
+ readonly Webp: "image/webp";
1110
+ };
1111
+ type JmImageType = typeof JmImageType[keyof typeof JmImageType];
1112
+ /** Options for {@link captureShadowContent}. */
1113
+ interface JmExportImageOptions {
1114
+ /**
1115
+ * Device pixel ratio to render at. 2 gives a crisp result on high-density
1116
+ * screens and stays cheap; 1 mirrors what the user sees.
1117
+ */
1118
+ scale?: number;
1119
+ /** Output format. JPEG and WebP are lossy, PNG is not. */
1120
+ type?: JmImageType;
1121
+ /**
1122
+ * Quality for the lossy formats, 0 to 1. Ignored for PNG, where the browser
1123
+ * rejects a quality argument.
1124
+ */
1125
+ quality?: number;
1126
+ }
1127
+ /** What a capture produced. */
1128
+ interface JmExportImageResult {
1129
+ blob: Blob;
1130
+ /** Pixel width of the image, i.e. the content width times `scale`. */
1131
+ width: number;
1132
+ /** Pixel height of the image. */
1133
+ height: number;
1134
+ /** Content width in CSS pixels, before scaling. */
1135
+ cssWidth: number;
1136
+ /** Content height in CSS pixels, before scaling. */
1137
+ cssHeight: number;
1138
+ }
1139
+
1140
+ /**
1141
+ * Base interfaces for JsMind serialization.
1142
+ *
1143
+ * @packageDocumentation
1144
+ */
1145
+
1146
+ /**
1147
+ * Base interface for all mind map serializers.
1148
+ *
1149
+ * @public
1150
+ */
1151
+ interface JmMindSerializer {
1152
+ /**
1153
+ * Serializes a mind map to the specific format.
1154
+ *
1155
+ * @param mind - The mind map to serialize.
1156
+ * @returns The serialized data in the specific format.
1157
+ * @throws {@link JsMindError} If serialization fails.
1158
+ */
1159
+ serialize(mind: JmMind): unknown;
1160
+ /**
1161
+ * Deserializes data to a mind map.
1162
+ *
1163
+ * @param data - The data to deserialize.
1164
+ * @returns The deserialized mind map.
1165
+ * @throws {@link JsMindError} If deserialization fails.
1166
+ */
1167
+ deserialize(data: unknown): JmMind;
1168
+ /**
1169
+ * Gets the format name this serializer supports.
1170
+ *
1171
+ * @returns The format name.
1172
+ * @throws {@link JsMindError} If format name is not implemented.
1173
+ */
1174
+ getFormatName(): string;
1175
+ /**
1176
+ * Validates if the data can be deserialized by this serializer.
1177
+ *
1178
+ * @param data - The data to validate.
1179
+ * @returns True if the data is valid for this format.
1180
+ * @throws {@link JsMindError} If validation fails.
1181
+ */
1182
+ validate(data: unknown): boolean;
1183
+ }
1184
+
1185
+ declare class JmMindSerializerFactory {
1186
+ static create(format: string): JmMindSerializer;
1187
+ }
1188
+
1189
+ /**
1190
+ * Main class for jsMind mind map operations.
1191
+ *
1192
+ * @public
1193
+ */
1194
+ declare class JsMind {
1195
+ /**
1196
+ * Gets the version of jsMind.
1197
+ *
1198
+ * @returns The version string.
1199
+ */
1200
+ static get Version(): string;
1201
+ /**
1202
+ * Gets the author of jsMind.
1203
+ *
1204
+ * @returns The author string.
1205
+ */
1206
+ static get Author(): string;
1207
+ /**
1208
+ * Exported classes for browser use.
1209
+ */
1210
+ static Mind: typeof JmMind;
1211
+ static Serializer: typeof JmMindSerializerFactory;
1212
+ static NodeSide: {
1213
+ readonly SideB: -1;
1214
+ readonly Center: 0;
1215
+ readonly SideA: 1;
1216
+ };
1217
+ /** The options for this jsMind instance. */
1218
+ options: JsMindOptions;
1219
+ /** The currently opened mind map, or null if none is open. */
1220
+ mind: JmMind | null;
1221
+ /** The state coordinator instance for managing the state of the mind map. */
1222
+ private readonly coordinator;
1223
+ /** Issues display-affecting commands. */
1224
+ private readonly commander;
1225
+ /**
1226
+ * Creates a new jsMind instance.
1227
+ *
1228
+ * @param options - Configuration options for the jsMind instance.
1229
+ */
1230
+ private constructor();
1231
+ static create(container: string | HTMLElement, options?: JsMindOptions): Promise<JsMind>;
1232
+ /**
1233
+ * Opens a mind map.
1234
+ *
1235
+ * @param mind - The mind map instance to open.
1236
+ * @returns The opened mind map instance.
1237
+ */
1238
+ open(mind: JmMind): Promise<void>;
1239
+ /**
1240
+ * Closes the current mind map (cleanup method).
1241
+ *
1242
+ * @remarks
1243
+ * This method can be extended in the future for cleanup operations
1244
+ * like removing observers, clearing caches, etc.
1245
+ */
1246
+ close(): void;
1247
+ /**
1248
+ * Serializes the current mind map to JSON.
1249
+ *
1250
+ * @returns JSON string representation of the mind map.
1251
+ * @throws {@link Error} If no mind map is open or serialization fails.
1252
+ */
1253
+ serialize(): string;
1254
+ /**
1255
+ * Renders the open mind map to an image.
1256
+ *
1257
+ * The size is the rendered content's own size: whitespace inside the
1258
+ * container is part of the picture, and a map larger than its container is
1259
+ * not cropped.
1260
+ *
1261
+ * @param options - Scale, format and quality. Defaults to PNG at 2x.
1262
+ * @returns The encoded image, as a Blob, plus its pixel dimensions.
1263
+ * @throws {@link JsMindError} If no mind map is open, or if the browser
1264
+ * cannot encode the result.
1265
+ */
1266
+ exportImage(options?: JmExportImageOptions): Promise<JmExportImageResult>;
1267
+ }
1268
+
1269
+ export { JsMind as default };