glassbrain 0.2.0-alpha.1 → 0.2.0-alpha.2

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/dist/core.js CHANGED
@@ -70,10 +70,10 @@ import {
70
70
  untheme,
71
71
  validateModel,
72
72
  validateStructure
73
- } from "./chunks/chunk-VCM766BZ.js";
73
+ } from "./chunks/chunk-7R6PO7AE.js";
74
74
  import {
75
75
  EN
76
- } from "./chunks/chunk-EJURBBFC.js";
76
+ } from "./chunks/chunk-F3DN7SLR.js";
77
77
  import "./chunks/chunk-ZA47FP7C.js";
78
78
  export {
79
79
  CONTENT_SCALE,
package/dist/index.js CHANGED
@@ -9,7 +9,7 @@ import {
9
9
  clearLayoutCache,
10
10
  computeLayout,
11
11
  projectPlanes
12
- } from "./chunks/chunk-CAXDADCO.js";
12
+ } from "./chunks/chunk-TM27EXYP.js";
13
13
  import {
14
14
  CONTENT_SCALE,
15
15
  DARK_THEME,
@@ -81,15 +81,15 @@ import {
81
81
  untheme,
82
82
  validateModel,
83
83
  validateStructure
84
- } from "./chunks/chunk-VCM766BZ.js";
84
+ } from "./chunks/chunk-7R6PO7AE.js";
85
85
  import {
86
86
  DetailPanel,
87
87
  renderInline,
88
88
  renderMarkdown
89
- } from "./chunks/chunk-37BAJC3L.js";
89
+ } from "./chunks/chunk-ZHPUQDOJ.js";
90
90
  import {
91
91
  EN
92
- } from "./chunks/chunk-EJURBBFC.js";
92
+ } from "./chunks/chunk-F3DN7SLR.js";
93
93
  import "./chunks/chunk-YGRPNAXE.js";
94
94
  import "./chunks/chunk-ZA47FP7C.js";
95
95
  export {
package/dist/internal.js CHANGED
@@ -42,7 +42,7 @@ import {
42
42
  shapeOf,
43
43
  skeletonLineOf,
44
44
  touchGestures
45
- } from "./chunks/chunk-CAXDADCO.js";
45
+ } from "./chunks/chunk-TM27EXYP.js";
46
46
  import {
47
47
  CONTENT_SCALE,
48
48
  DARK_THEME,
@@ -139,15 +139,15 @@ import {
139
139
  untheme,
140
140
  validateModel,
141
141
  validateStructure
142
- } from "./chunks/chunk-VCM766BZ.js";
142
+ } from "./chunks/chunk-7R6PO7AE.js";
143
143
  import {
144
144
  DetailPanel,
145
145
  renderInline,
146
146
  renderMarkdown
147
- } from "./chunks/chunk-37BAJC3L.js";
147
+ } from "./chunks/chunk-ZHPUQDOJ.js";
148
148
  import {
149
149
  EN
150
- } from "./chunks/chunk-EJURBBFC.js";
150
+ } from "./chunks/chunk-F3DN7SLR.js";
151
151
  import "./chunks/chunk-YGRPNAXE.js";
152
152
  import "./chunks/chunk-ZA47FP7C.js";
153
153
  export {
@@ -0,0 +1,20 @@
1
+ import type { GraphModel, GraphNode } from './model.js';
2
+ import type { LayerSpec } from './profile.js';
3
+ /** Beyond this many ordered children the planes stop being an outline and become a stack of cards. */
4
+ export declare const MAX_DERIVED_LAYERS = 8;
5
+ export interface DerivedLayers {
6
+ /** Empty when the graph has no ordered siblings at the top of a single root. */
7
+ layers: LayerSpec[];
8
+ /** node id → layer id. Empty when `layers` is empty. */
9
+ layerOf: Map<string, string>;
10
+ /** The node whose children are the layers (the graph root), for messages. */
11
+ anchor?: string;
12
+ }
13
+ /** Ordered children of `id`, or null when that run is not ordered (all of them carry a distinct order, or none does). */
14
+ export declare function orderedChildren(children: Gy, id: string): GraphNode[] | null;
15
+ type Gy = Map<string, GraphNode[]>;
16
+ export declare function childrenMap(model: GraphModel): Gy;
17
+ export declare function deriveLayers(model: GraphModel, colors?: string[]): DerivedLayers;
18
+ /** Layers in reading order for a node id, for messages and the outline. */
19
+ export declare function layerIndexOf(derived: DerivedLayers, id: string): number;
20
+ export {};
@@ -0,0 +1,18 @@
1
+ import type { CyElement } from '../elements.js';
2
+ import type { Positions } from './planes.js';
3
+ export interface OrderInfo {
4
+ /** child id → parent id (the element table's parent, virtual root included). */
5
+ parentOf: Map<string, string>;
6
+ /** Node ids in a numbered run, sorted; absent for unordered runs. */
7
+ orderedKids: Map<string, string[]>;
8
+ /** Every node id, for subtree walks. */
9
+ nodeIds: Set<string>;
10
+ /** At least one run is numbered (otherwise there is nothing to do). */
11
+ any: boolean;
12
+ }
13
+ /** Read `order` off the elements. Returns null when nothing is numbered: the layout then stays exactly as it was. */
14
+ export declare function readOrder(elements: CyElement[]): OrderInfo | null;
15
+ /** Pre-solve positions: ordered runs on arcs (clockwise, first at 12 o'clock), the rest by hash. */
16
+ export declare function orderSeed(elements: CyElement[], info: OrderInfo): Positions;
17
+ /** Post-pass: rotate every ordered run into place, sub-tree by sub-tree. */
18
+ export declare function enforceOrder(elements: CyElement[], info: OrderInfo, positions: Positions): Positions;
package/dist/model.d.ts CHANGED
@@ -6,6 +6,9 @@ export interface GraphNode {
6
6
  kind?: string;
7
7
  /** Compound parent node id: expresses "nested inside", the only source of structural hierarchy. */
8
8
  parent?: string;
9
+ /** Position among its siblings: every child of a parent carries one, or none does. The layout reads it
10
+ * clockwise, and a run of ordered siblings is what opens the layer view. */
11
+ order?: number;
9
12
  /** **Where it hung in the previous version** (filled by `diffModels`, only `moved` nodes in a union have it).
10
13
  *
11
14
  * An edge is defined by its two ends; **change one and it is another edge**. So "moved to another branch" is not a node attribute
@@ -16,7 +19,8 @@ export interface GraphNode {
16
19
  * `null` means "it was a top level in the previous version" (not the same as `undefined`, "no such information": in connected mode
17
20
  * top levels hang on the virtual root, which is also a real edge). Ordinary parse results never carry this field. */
18
21
  prevParent?: string | null;
19
- /** Layer id. Inferred by profile.layerOf by default. Multi-layer views / 2.5D planes group by it. */
22
+ /** Layer id. **Derived, never written in a file**: profile.layerOf (or the CLI's derived layers) assigns it
23
+ * from the ordered level a node hangs under. Multi-layer views / 2.5D planes group by it. */
20
24
  layer?: string;
21
25
  /** The **primary** source: who owns the content (what a future write-back writes to). Stamped automatically by parseSources. */
22
26
  origin?: string;
@@ -2,8 +2,8 @@
2
2
  "use client";
3
3
  import {
4
4
  DetailPanel
5
- } from "../chunks/chunk-37BAJC3L.js";
6
- import "../chunks/chunk-EJURBBFC.js";
5
+ } from "../chunks/chunk-ZHPUQDOJ.js";
6
+ import "../chunks/chunk-F3DN7SLR.js";
7
7
  import "../chunks/chunk-ZA47FP7C.js";
8
8
  export {
9
9
  DetailPanel as default
@@ -189,6 +189,9 @@ export interface GraphCanvasProps {
189
189
  onEdit?: (op: EditOp) => void;
190
190
  /** Replace the free-form part of the edit panel (label / kind / data, JSON) with the host's own editor. */
191
191
  renderEditor?: RenderEditor;
192
+ /** "Restructure" in ⋯: the host re-hangs and renumbers the graph (see cli/restructure.ts) and hands back a new model.
193
+ * Without it the item is absent. Pure callback: the library never edits. */
194
+ onRestructure?: () => void;
192
195
  /**
193
196
  * How markdown in details (rendered by default) resolves relative URLs: images, links. Return null = cannot resolve
194
197
  * (link keeps only its text, image is not drawn). E.g. data extracted from a repository's docs resolves to that repository's raw file URLs.
@@ -2,10 +2,10 @@
2
2
  "use client";
3
3
  import {
4
4
  GraphCanvas
5
- } from "../chunks/chunk-CAXDADCO.js";
6
- import "../chunks/chunk-VCM766BZ.js";
7
- import "../chunks/chunk-37BAJC3L.js";
8
- import "../chunks/chunk-EJURBBFC.js";
5
+ } from "../chunks/chunk-TM27EXYP.js";
6
+ import "../chunks/chunk-7R6PO7AE.js";
7
+ import "../chunks/chunk-ZHPUQDOJ.js";
8
+ import "../chunks/chunk-F3DN7SLR.js";
9
9
  import "../chunks/chunk-YGRPNAXE.js";
10
10
  import "../chunks/chunk-ZA47FP7C.js";
11
11
  export {
@@ -37,6 +37,8 @@ export interface ToolbarProps {
37
37
  onAdd?: (what: 'node' | 'edge') => void;
38
38
  /** "Relayout" in ⋯: another arrangement of the same data. Without it the item is absent. */
39
39
  onRelayout?: () => void;
40
+ /** "Restructure" in ⋯: re-hang and renumber to raise the shape score. Without it the item is absent. */
41
+ onRestructure?: () => void;
40
42
  }
41
43
  export default function Toolbar(p: ToolbarProps): import("react").JSX.Element;
42
44
  export declare function ZoomDock(p: {
package/dist/strings.d.ts CHANGED
@@ -56,6 +56,7 @@ export interface GraphStrings {
56
56
  addEdge: string;
57
57
  /** The canvas ⋯ menu: lay out the same data again. */
58
58
  relayout: string;
59
+ restructure: string;
59
60
  edit: string;
60
61
  editNode: string;
61
62
  newNode: string;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "glassbrain",
3
- "version": "0.2.0-alpha.1",
3
+ "version": "0.2.0-alpha.2",
4
4
  "description": "Know what your agent knows: open, diff and review the knowledge graphs agents write. Plain JSON in, one html file out.",
5
5
  "keywords": [
6
6
  "knowledge-graph",
@@ -2,7 +2,7 @@
2
2
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3
3
  "$id": "https://unpkg.com/glassbrain/schema/graph.schema.json",
4
4
  "title": "glassbrain graph",
5
- "description": "One file of a glassbrain knowledge graph. A graph is nodes plus edges; structure comes from `parent` (containment), not from edges. Several files in one folder are merged into one graph (same id = same node). Unknown fields are kept and shown in the detail panel.",
5
+ "description": "One file of a glassbrain knowledge graph. A graph is nodes plus edges; structure comes from `parent` (containment), not from edges. Every node carries `parent`: a node id, or null for the root. Several files in one folder are merged into one graph (same id = same node). Unknown fields are kept and shown in the detail panel.",
6
6
  "type": "object",
7
7
  "anyOf": [{ "required": ["nodes"] }, { "required": ["edges"] }],
8
8
  "properties": {
@@ -20,14 +20,14 @@
20
20
  "$defs": {
21
21
  "node": {
22
22
  "type": "object",
23
- "required": ["id"],
23
+ "required": ["id", "parent"],
24
24
  "properties": {
25
25
  "id": { "type": ["string", "number"], "description": "Stable identity. Keep it the same across versions: that is how a diff knows it is the same thing." },
26
26
  "label": { "type": "string", "description": "Display name. Falls back to `name`, then `id`." },
27
27
  "name": { "type": "string", "description": "Alias of `label`." },
28
28
  "kind": { "type": "string", "description": "What sort of thing this is. Colors come from the profile's `nodePalette[kind]`; kinds not in the palette are drawn as skeleton." },
29
- "parent": { "type": "string", "description": "Id of the node this one sits inside. This is the only source of structure: the layout is built from it." },
30
- "layer": { "type": "string", "description": "Layer id (for the 2.5D plane view). Defaults to the profile's first layer." },
29
+ "parent": { "type": ["string", "null"], "description": "Id of the node this one sits inside; null for the root. Required: the only source of structure, and the layout, the layers and the outline are all built from it." },
30
+ "order": { "type": "number", "exclusiveMinimum": 0, "description": "Position among its siblings (1, 2, 3…; 3.5 inserts between 3 and 4). Either every child of a parent has one or none does, and no two siblings share one." },
31
31
  "flags": { "type": "array", "items": { "type": "string" }, "description": "Boolean markers; each becomes a CSS-like class. A flag listed in the profile's `placeholderFlags` draws the node as a placeholder." },
32
32
  "description": { "type": "string", "description": "Markdown shown in the detail panel. `[text](node:<id>)` links jump to another node." }
33
33
  },
@@ -2,57 +2,129 @@
2
2
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3
3
  "$id": "https://unpkg.com/glassbrain/schema/profile.schema.json",
4
4
  "title": "glassbrain profile (_profile.json)",
5
- "description": "The declarative part of a glassbrain profile, as a `_profile.json` next to the graph files. Everything is optional: with no profile a graph still renders (kinds without a color are drawn as skeleton). Parsers, merge and domain validation are code and live in a TypeScript profile instead.",
5
+ "description": "The declarative part of a glassbrain profile, as a `_profile.json` next to the graph files. Everything is optional: with no profile a graph still renders (kinds without a color are drawn as skeleton). Layers are not configured here: they are derived from `order` in the graph. Parsers, merge and domain validation are code and live in a TypeScript profile instead.",
6
6
  "type": "object",
7
7
  "properties": {
8
- "layers": {
8
+ "nodePalette": {
9
+ "$ref": "#/$defs/colors",
10
+ "description": "Node kind → color. Kinds not listed are skeleton."
11
+ },
12
+ "edgePalette": {
13
+ "$ref": "#/$defs/colors",
14
+ "description": "Edge kind → color."
15
+ },
16
+ "nodeSize": {
17
+ "$ref": "#/$defs/numbers",
18
+ "description": "Node kind → size multiplier (1 = default)."
19
+ },
20
+ "edgeWidth": {
21
+ "$ref": "#/$defs/numbers",
22
+ "description": "Edge kind → width multiplier."
23
+ },
24
+ "placeholderFlags": {
9
25
  "type": "array",
10
- "description": "Layers for the 2.5D plane view. One default layer if omitted.",
11
26
  "items": {
12
- "type": "object",
13
- "required": ["id", "label"],
14
- "properties": {
15
- "id": { "type": "string" },
16
- "label": { "type": "string" },
17
- "z": { "type": "number", "description": "Plane order: 0 is the bottom." },
18
- "color": { "type": "string", "description": "Hue of the plane." },
19
- "structural": { "type": "boolean", "description": "false = placed around the main structure instead of taking part in it." }
27
+ "type": "string"
28
+ },
29
+ "description": "Nodes with any of these flags are drawn as placeholders (declared, not yet filled)."
30
+ },
31
+ "kindLabels": {
32
+ "$ref": "#/$defs/strings",
33
+ "description": "Kind → human-readable name (nodes and edges share this map)."
34
+ },
35
+ "edgeLabels": {
36
+ "$ref": "#/$defs/strings",
37
+ "description": "Same as kindLabels, for edge kinds; merged into it."
38
+ },
39
+ "appearance": {
40
+ "type": "object",
41
+ "description": "View defaults only. Layers themselves are derived from the graph: a run of ordered siblings is one layer.",
42
+ "properties": {
43
+ "defaultLayers": {
44
+ "type": "boolean",
45
+ "description": "Open with the layer (2.5D plane) view on when the graph has ordered siblings. Default false."
46
+ },
47
+ "layerColors": {
48
+ "type": "array",
49
+ "items": {
50
+ "type": "string"
51
+ },
52
+ "description": "Hue per layer, in order. Defaults to the theme's palette."
20
53
  }
21
54
  }
22
55
  },
23
- "nodePalette": { "$ref": "#/$defs/colors", "description": "Node kind → color. Kinds not listed are skeleton." },
24
- "edgePalette": { "$ref": "#/$defs/colors", "description": "Edge kind → color." },
25
- "nodeSize": { "$ref": "#/$defs/numbers", "description": "Node kind → size multiplier (1 = default)." },
26
- "edgeWidth": { "$ref": "#/$defs/numbers", "description": "Edge kind → width multiplier." },
27
- "placeholderFlags": { "type": "array", "items": { "type": "string" }, "description": "Nodes with any of these flags are drawn as placeholders (declared, not yet filled)." },
28
- "kindLabels": { "$ref": "#/$defs/strings", "description": "Kind → human-readable name (nodes and edges share this map)." },
29
- "edgeLabels": { "$ref": "#/$defs/strings", "description": "Same as kindLabels, for edge kinds; merged into it." },
30
- "style": { "type": "array", "description": "Extra cytoscape style rules, appended after the base style." },
56
+ "style": {
57
+ "type": "array",
58
+ "description": "Extra cytoscape style rules, appended after the base style."
59
+ },
31
60
  "detail": {
32
61
  "type": "object",
33
62
  "description": "Detail panel field tables.",
34
63
  "properties": {
35
- "line": { "$ref": "#/$defs/fields" },
36
- "list": { "$ref": "#/$defs/fields" },
37
- "skip": { "type": "array", "items": { "type": "string" } },
38
- "flagNotes": { "$ref": "#/$defs/strings" }
64
+ "line": {
65
+ "$ref": "#/$defs/fields"
66
+ },
67
+ "list": {
68
+ "$ref": "#/$defs/fields"
69
+ },
70
+ "skip": {
71
+ "type": "array",
72
+ "items": {
73
+ "type": "string"
74
+ }
75
+ },
76
+ "flagNotes": {
77
+ "$ref": "#/$defs/strings"
78
+ }
39
79
  }
40
80
  },
41
- "singleRoot": { "type": "boolean", "description": "Wrap several top-level nodes in one root box (default true)." },
42
- "rootLabel": { "type": "string" },
43
- "diffIgnore": { "type": "array", "items": { "type": "string" }, "description": "Node fields that do not count as a change when diffing (fields every rebuild rewrites, e.g. cluster ids or line numbers). Used by the glassbrain CLI." }
81
+ "rootLabel": {
82
+ "type": "string"
83
+ },
84
+ "diffIgnore": {
85
+ "type": "array",
86
+ "items": {
87
+ "type": "string"
88
+ },
89
+ "description": "Node fields that do not count as a change when diffing (fields every rebuild rewrites, e.g. cluster ids or line numbers). Used by the glassbrain CLI."
90
+ }
44
91
  },
45
92
  "additionalProperties": true,
46
93
  "$defs": {
47
- "colors": { "type": "object", "additionalProperties": { "type": "string" } },
48
- "numbers": { "type": "object", "additionalProperties": { "type": "number" } },
49
- "strings": { "type": "object", "additionalProperties": { "type": "string" } },
94
+ "colors": {
95
+ "type": "object",
96
+ "additionalProperties": {
97
+ "type": "string"
98
+ }
99
+ },
100
+ "numbers": {
101
+ "type": "object",
102
+ "additionalProperties": {
103
+ "type": "number"
104
+ }
105
+ },
106
+ "strings": {
107
+ "type": "object",
108
+ "additionalProperties": {
109
+ "type": "string"
110
+ }
111
+ },
50
112
  "fields": {
51
113
  "type": "array",
52
114
  "items": {
53
115
  "type": "object",
54
- "required": ["key", "label"],
55
- "properties": { "key": { "type": "string" }, "label": { "type": "string" } }
116
+ "required": [
117
+ "key",
118
+ "label"
119
+ ],
120
+ "properties": {
121
+ "key": {
122
+ "type": "string"
123
+ },
124
+ "label": {
125
+ "type": "string"
126
+ }
127
+ }
56
128
  }
57
129
  }
58
130
  }