treelines 0.0.0-stage → 0.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/LICENSE +21 -0
- package/README.md +170 -2
- package/dist/core.cjs +207 -0
- package/dist/core.cjs.map +1 -0
- package/dist/core.d.cts +133 -0
- package/dist/core.d.ts +133 -0
- package/dist/core.js +175 -0
- package/dist/core.js.map +1 -0
- package/dist/index.cjs +548 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +300 -0
- package/dist/index.d.ts +300 -0
- package/dist/index.js +525 -0
- package/dist/index.js.map +1 -0
- package/package.json +80 -4
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,300 @@
|
|
|
1
|
+
import * as react from 'react';
|
|
2
|
+
import { HTMLAttributes, CSSProperties, SVGAttributes, ReactNode, ReactElement } from 'react';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* The layout: where every node goes and the path of every connector, from the graph and the node sizes alone. No DOM and
|
|
6
|
+
* no React, so it runs anywhere (the server included) and gives the same numbers every time.
|
|
7
|
+
*
|
|
8
|
+
* The shape it draws: a list of lanes, each a root you can unfold. An unfolded lane shows the graph below its root
|
|
9
|
+
* beside it, in columns by depth: a node's column is its distance from the root, its row follows its parents (the average
|
|
10
|
+
* of where they are), pushed further along so nothing overlaps. Lanes stack, the open ones with room around them.
|
|
11
|
+
*
|
|
12
|
+
* "Main" is the axis the graph grows along (x when it grows to the right), "cross" the one lanes and rows stack along.
|
|
13
|
+
*/
|
|
14
|
+
type Id = string | number;
|
|
15
|
+
interface Point {
|
|
16
|
+
x: number;
|
|
17
|
+
y: number;
|
|
18
|
+
}
|
|
19
|
+
interface Size {
|
|
20
|
+
width: number;
|
|
21
|
+
height: number;
|
|
22
|
+
}
|
|
23
|
+
interface Rect extends Point, Size {
|
|
24
|
+
}
|
|
25
|
+
/** From, to, and optionally what was folded into it (see `foldPassThrough`): opaque to the layout, counted by renderers. */
|
|
26
|
+
type Edge<I extends Id = Id, V = unknown> = readonly [from: I, to: I, via?: readonly V[]];
|
|
27
|
+
/** A root and the graph that unfolds from it. The edges should only reach nodes below the root. */
|
|
28
|
+
interface Lane<I extends Id = Id, V = unknown> {
|
|
29
|
+
root: I;
|
|
30
|
+
edges: readonly Edge<I, V>[];
|
|
31
|
+
}
|
|
32
|
+
/** Which way the graph grows from its root: to the right (lanes stack downwards), or down (lanes sit side by side). */
|
|
33
|
+
type Direction = "right" | "down";
|
|
34
|
+
/** How a connector runs: a smooth S-curve, right angles, or a straight line. */
|
|
35
|
+
type ConnectorShape = "curve" | "elbow" | "straight";
|
|
36
|
+
interface LayoutOptions<I extends Id = Id, V = unknown> {
|
|
37
|
+
lanes: readonly Lane<I, V>[];
|
|
38
|
+
/** The roots whose graph is unfolded. A lane without edges has nothing to unfold and stays folded. */
|
|
39
|
+
open?: Iterable<I>;
|
|
40
|
+
/** The size of a lane's root. */
|
|
41
|
+
rootSize: Size | ((id: I) => Size);
|
|
42
|
+
/** The size of the nodes below it; `depth` is 1 for the root's children. */
|
|
43
|
+
nodeSize: Size | ((id: I, depth: number) => Size);
|
|
44
|
+
gap?: {
|
|
45
|
+
/** Between columns, from the root's column on. */
|
|
46
|
+
column?: number;
|
|
47
|
+
/** Between nodes in one column. */
|
|
48
|
+
row?: number;
|
|
49
|
+
/** Between lanes. */
|
|
50
|
+
lane?: number;
|
|
51
|
+
};
|
|
52
|
+
/** Room kept around an unfolded lane (its `band`), on both sides along the cross axis. */
|
|
53
|
+
padding?: number;
|
|
54
|
+
/** Where the first lane starts along the cross axis. */
|
|
55
|
+
start?: number;
|
|
56
|
+
direction?: Direction;
|
|
57
|
+
shape?: ConnectorShape;
|
|
58
|
+
/** Breaks ties between nodes that want the same row: by default the order they first appear in. */
|
|
59
|
+
compare?: (a: I, b: I) => number;
|
|
60
|
+
}
|
|
61
|
+
interface PlacedNode<I extends Id = Id> {
|
|
62
|
+
id: I;
|
|
63
|
+
/** 0 for the root. */
|
|
64
|
+
depth: number;
|
|
65
|
+
rect: Rect;
|
|
66
|
+
}
|
|
67
|
+
interface PlacedEdge<I extends Id = Id, V = unknown> {
|
|
68
|
+
from: I;
|
|
69
|
+
to: I;
|
|
70
|
+
via: readonly V[];
|
|
71
|
+
/** Where it leaves `from` (the middle of its far side) and enters `to` (the middle of its near side). */
|
|
72
|
+
start: Point;
|
|
73
|
+
end: Point;
|
|
74
|
+
/** Halfway between them: where a "+N" marker for the folded nodes goes. */
|
|
75
|
+
mid: Point;
|
|
76
|
+
/** An SVG path: `<path d={edge.path} />`. */
|
|
77
|
+
path: string;
|
|
78
|
+
}
|
|
79
|
+
interface PlacedLane<I extends Id = Id, V = unknown> {
|
|
80
|
+
root: I;
|
|
81
|
+
/** Asked to be open (see `LayoutOptions.open`). */
|
|
82
|
+
open: boolean;
|
|
83
|
+
/** Open and with something to show. */
|
|
84
|
+
unfolded: boolean;
|
|
85
|
+
/** The root first, then the nodes below it in reading order (breadth first), which is also a good tab order. */
|
|
86
|
+
nodes: PlacedNode<I>[];
|
|
87
|
+
edges: PlacedEdge<I, V>[];
|
|
88
|
+
/**
|
|
89
|
+
* The room an unfolded lane takes along the cross axis, padding included: for a background behind it. It runs the whole
|
|
90
|
+
* width of the layout along the main axis.
|
|
91
|
+
*/
|
|
92
|
+
band?: {
|
|
93
|
+
start: number;
|
|
94
|
+
size: number;
|
|
95
|
+
};
|
|
96
|
+
}
|
|
97
|
+
interface Layout<I extends Id = Id, V = unknown> {
|
|
98
|
+
lanes: PlacedLane<I, V>[];
|
|
99
|
+
/** The far edge of the furthest node, and where the next lane would start: the layout's size. */
|
|
100
|
+
width: number;
|
|
101
|
+
height: number;
|
|
102
|
+
}
|
|
103
|
+
/** Builds a connector's SVG path between two points, the graph growing in `direction`. */
|
|
104
|
+
declare function connectorPath(start: Point, end: Point, shape?: ConnectorShape, direction?: Direction): string;
|
|
105
|
+
declare function layout<I extends Id = Id, V = unknown>(options: LayoutOptions<I, V>): Layout<I, V>;
|
|
106
|
+
|
|
107
|
+
/**
|
|
108
|
+
* Working with the graph itself, apart from where it is drawn: the routes through a node, folding the nodes that only
|
|
109
|
+
* pass a route on, and turning nested data into lanes.
|
|
110
|
+
*/
|
|
111
|
+
interface Trace<I extends Id = Id> {
|
|
112
|
+
/** The node and everything that leads to it. */
|
|
113
|
+
up: Set<I>;
|
|
114
|
+
/** The node and everything it leads to. */
|
|
115
|
+
down: Set<I>;
|
|
116
|
+
}
|
|
117
|
+
/** Every route through `id`: what leads to it and what it leads to. For highlighting a node's routes on hover. */
|
|
118
|
+
declare function trace<I extends Id>(edges: readonly Edge<I, unknown>[], id: I): Trace<I>;
|
|
119
|
+
/** Whether an edge lies on a route through the traced node: both ends lead to it, or both come from it. */
|
|
120
|
+
declare const onTrace: <I extends Id>(t: Trace<I>, [a, b]: Edge<I, unknown>) => boolean;
|
|
121
|
+
/**
|
|
122
|
+
* Folds the nodes that only pass a route on: a node that is not the root, not kept, and has exactly one parent and one
|
|
123
|
+
* child becomes part of the edge around it, listed in its `via`. A long chain of such nodes becomes one edge with a "+N".
|
|
124
|
+
* A loop that folds back onto where it started is left out.
|
|
125
|
+
*/
|
|
126
|
+
declare function foldPassThrough<I extends Id>(edges: readonly Edge<I, unknown>[], root: I, keep: (id: I) => boolean): Edge<I, I>[];
|
|
127
|
+
/**
|
|
128
|
+
* Nested data as lanes: one per top-level item, its edges running from every node to its children. The same id twice
|
|
129
|
+
* is the same node, so shared children (a graph rather than a tree) work too.
|
|
130
|
+
*/
|
|
131
|
+
declare function fromTree<T, I extends Id>(roots: readonly T[], getId: (node: T) => I, getChildren: (node: T) => readonly T[] | null | undefined): {
|
|
132
|
+
lanes: Lane<I, never>[];
|
|
133
|
+
nodes: Map<I, T>;
|
|
134
|
+
};
|
|
135
|
+
|
|
136
|
+
/**
|
|
137
|
+
* The React parts. Headless: they place your elements and tell them their state, they draw no boxes of their own.
|
|
138
|
+
*
|
|
139
|
+
* <Graph.Root lanes={lanes} rootSize={…} nodeSize={…}>
|
|
140
|
+
* <Graph.Canvas>
|
|
141
|
+
* <Graph.Connectors />
|
|
142
|
+
* <Graph.Nodes>{(node) => <Graph.Node>{node.id}</Graph.Node>}</Graph.Nodes>
|
|
143
|
+
* </Graph.Canvas>
|
|
144
|
+
* </Graph.Root>
|
|
145
|
+
*
|
|
146
|
+
* State reaches the markup as data attributes (data-root, data-expanded, data-selected, data-highlighted, data-dimmed)
|
|
147
|
+
* and through `className`/`style` functions, so it is styled with plain CSS or Tailwind.
|
|
148
|
+
*/
|
|
149
|
+
/** A node in a lane: the lane's root and the node's id (the same node can sit in several lanes). */
|
|
150
|
+
type Selection<I extends Id = Id> = {
|
|
151
|
+
lane: I;
|
|
152
|
+
id: I;
|
|
153
|
+
} | null;
|
|
154
|
+
interface NodeState {
|
|
155
|
+
/** The lane's root itself (it opens and closes the lane). */
|
|
156
|
+
root: boolean;
|
|
157
|
+
/** 0 for a root. */
|
|
158
|
+
depth: number;
|
|
159
|
+
/** A root with something to unfold. */
|
|
160
|
+
expandable: boolean;
|
|
161
|
+
/** A root whose lane is unfolded. */
|
|
162
|
+
expanded: boolean;
|
|
163
|
+
selected: boolean;
|
|
164
|
+
/**
|
|
165
|
+
* On a route through the hovered or focused node (or the selected one, when nothing is hovered). Matched by id, so the
|
|
166
|
+
* same node lights up wherever it appears, as the root of another lane too.
|
|
167
|
+
*/
|
|
168
|
+
highlighted: boolean;
|
|
169
|
+
/** Routes are being traced and this node is not on one. */
|
|
170
|
+
dimmed: boolean;
|
|
171
|
+
/** Its size is not known yet (measured sizes only). */
|
|
172
|
+
measuring: boolean;
|
|
173
|
+
}
|
|
174
|
+
interface EdgeState {
|
|
175
|
+
highlighted: boolean;
|
|
176
|
+
dimmed: boolean;
|
|
177
|
+
}
|
|
178
|
+
interface NodeInfo<I extends Id = Id> {
|
|
179
|
+
lane: I;
|
|
180
|
+
id: I;
|
|
181
|
+
depth: number;
|
|
182
|
+
rect: Rect;
|
|
183
|
+
state: NodeState;
|
|
184
|
+
}
|
|
185
|
+
interface EdgeInfo<I extends Id = Id, V = unknown> extends PlacedEdge<I, V> {
|
|
186
|
+
lane: I;
|
|
187
|
+
state: EdgeState;
|
|
188
|
+
}
|
|
189
|
+
interface BandInfo<I extends Id = Id> {
|
|
190
|
+
lane: I;
|
|
191
|
+
/** Along the cross axis (y when the graph grows to the right): where the unfolded lane's room starts and how big it is. */
|
|
192
|
+
start: number;
|
|
193
|
+
size: number;
|
|
194
|
+
}
|
|
195
|
+
type Styled<S> = {
|
|
196
|
+
className?: string | ((state: S) => string | undefined);
|
|
197
|
+
style?: CSSProperties | ((state: S) => CSSProperties | undefined);
|
|
198
|
+
};
|
|
199
|
+
interface RootProps<I extends Id = Id, V = unknown> {
|
|
200
|
+
lanes: readonly Lane<I, V>[];
|
|
201
|
+
/** The size of every lane's root. Leave it out to measure each root as you render it. */
|
|
202
|
+
rootSize?: Size | ((id: I) => Size);
|
|
203
|
+
/** The size of the nodes below. Leave it out to measure them. Fixed sizes need no measuring and lay out on the server too. */
|
|
204
|
+
nodeSize?: Size | ((id: I, depth: number) => Size);
|
|
205
|
+
gap?: {
|
|
206
|
+
column?: number;
|
|
207
|
+
row?: number;
|
|
208
|
+
lane?: number;
|
|
209
|
+
};
|
|
210
|
+
/** Room around an unfolded lane (its band). */
|
|
211
|
+
padding?: number;
|
|
212
|
+
/** Where the first lane starts along the cross axis. */
|
|
213
|
+
start?: number;
|
|
214
|
+
direction?: Direction;
|
|
215
|
+
shape?: ConnectorShape;
|
|
216
|
+
/** Breaks ties between nodes that want the same row. */
|
|
217
|
+
compare?: (a: I, b: I) => number;
|
|
218
|
+
/** The unfolded lanes (by root): controlled. */
|
|
219
|
+
open?: readonly I[];
|
|
220
|
+
defaultOpen?: readonly I[];
|
|
221
|
+
onOpenChange?: (open: I[]) => void;
|
|
222
|
+
/** Several lanes open at once. By default opening one closes the other. */
|
|
223
|
+
multiple?: boolean;
|
|
224
|
+
/** The selected node: controlled. */
|
|
225
|
+
selected?: Selection<I>;
|
|
226
|
+
defaultSelected?: Selection<I>;
|
|
227
|
+
onSelectedChange?: (selected: Selection<I>) => void;
|
|
228
|
+
/** Arrow keys move between nodes (and the right arrow unfolds a folded root). On by default. */
|
|
229
|
+
keyboardNavigation?: boolean;
|
|
230
|
+
children?: ReactNode;
|
|
231
|
+
}
|
|
232
|
+
declare function Root<I extends Id = Id, V = unknown>(props: RootProps<I, V>): react.JSX.Element;
|
|
233
|
+
interface CanvasProps extends Omit<HTMLAttributes<HTMLDivElement>, "className" | "style">, Styled<{
|
|
234
|
+
width: number;
|
|
235
|
+
height: number;
|
|
236
|
+
measuring: boolean;
|
|
237
|
+
}> {
|
|
238
|
+
}
|
|
239
|
+
/** The area the graph is drawn in: positioned, and as big as the layout. Hidden while measured sizes are still unknown. */
|
|
240
|
+
declare function Canvas({ className, style, children, ...rest }: CanvasProps): react.JSX.Element;
|
|
241
|
+
/** One element per unfolded lane, for a background behind it: you render it, with the band's place along the cross axis. */
|
|
242
|
+
declare function Bands<I extends Id = Id>({ children }: {
|
|
243
|
+
children: (band: BandInfo<I>) => ReactNode;
|
|
244
|
+
}): react.JSX.Element;
|
|
245
|
+
interface ConnectorsProps<I extends Id = Id, V = unknown> extends Omit<SVGAttributes<SVGSVGElement>, "children"> {
|
|
246
|
+
/** Class or style per connector, from its state; or render each connector yourself. */
|
|
247
|
+
pathClassName?: string | ((edge: EdgeInfo<I, V>) => string | undefined);
|
|
248
|
+
pathStyle?: CSSProperties | ((edge: EdgeInfo<I, V>) => CSSProperties | undefined);
|
|
249
|
+
children?: (edge: EdgeInfo<I, V>) => ReactNode;
|
|
250
|
+
}
|
|
251
|
+
/** The connector lines, as SVG paths in one SVG over the canvas. Decorative: hidden from assistive technology. */
|
|
252
|
+
declare function Connectors<I extends Id = Id, V = unknown>({ pathClassName, pathStyle, children, ...rest }: ConnectorsProps<I, V>): react.JSX.Element;
|
|
253
|
+
/** One element per connector with folded nodes in it ("+N"): you render it, at `edge.mid`. */
|
|
254
|
+
declare function Markers<I extends Id = Id, V = unknown>({ children }: {
|
|
255
|
+
children: (edge: EdgeInfo<I, V>) => ReactNode;
|
|
256
|
+
}): react.JSX.Element;
|
|
257
|
+
/** Every node, root first then the nodes below in reading order, lane by lane. Render each with <Graph.Node>. */
|
|
258
|
+
declare function Nodes<I extends Id = Id>({ children }: {
|
|
259
|
+
children: (node: NodeInfo<I>) => ReactNode;
|
|
260
|
+
}): react.JSX.Element;
|
|
261
|
+
type NodeElementProps = HTMLAttributes<HTMLElement> & Record<`data-${string}`, string | undefined>;
|
|
262
|
+
interface NodeProps extends Omit<HTMLAttributes<HTMLButtonElement>, "className" | "style">, Styled<NodeState> {
|
|
263
|
+
/** Another element instead of the button, or a function that renders one with the props it gets. */
|
|
264
|
+
render?: ReactElement | ((props: NodeElementProps & {
|
|
265
|
+
ref: (el: HTMLElement | null) => void;
|
|
266
|
+
}, state: NodeState) => ReactElement);
|
|
267
|
+
}
|
|
268
|
+
/**
|
|
269
|
+
* A node: a button by default, placed where the layout puts it. A root opens and closes its lane (and is selected); a
|
|
270
|
+
* node below toggles its selection. Hover and focus trace its routes. Your handlers run first; `event.preventDefault()`
|
|
271
|
+
* in one skips the graph's own.
|
|
272
|
+
*/
|
|
273
|
+
declare function Node({ render, className, style, onClick, onMouseEnter, onMouseLeave, onFocus, onBlur, onKeyDown, children, ...rest }: NodeProps): react.JSX.Element;
|
|
274
|
+
/** The graph's state, for parts of your own: a details panel, a "show more", a legend. */
|
|
275
|
+
declare function useGraph<I extends Id = Id>(): {
|
|
276
|
+
layout: Layout<I, unknown>;
|
|
277
|
+
open: readonly I[];
|
|
278
|
+
selected: Selection<I>;
|
|
279
|
+
/** The routes being traced, and in which lane. */
|
|
280
|
+
traced: {
|
|
281
|
+
lane: I;
|
|
282
|
+
trace: Trace<I>;
|
|
283
|
+
} | null;
|
|
284
|
+
measuring: boolean;
|
|
285
|
+
toggleLane: (root: I) => void;
|
|
286
|
+
select: (lane: I, id: I) => void;
|
|
287
|
+
};
|
|
288
|
+
/** The node a <Graph.Node> renders, for components inside it. */
|
|
289
|
+
declare function useNode(): NodeInfo;
|
|
290
|
+
declare const Graph: {
|
|
291
|
+
Root: typeof Root;
|
|
292
|
+
Canvas: typeof Canvas;
|
|
293
|
+
Bands: typeof Bands;
|
|
294
|
+
Connectors: typeof Connectors;
|
|
295
|
+
Markers: typeof Markers;
|
|
296
|
+
Nodes: typeof Nodes;
|
|
297
|
+
Node: typeof Node;
|
|
298
|
+
};
|
|
299
|
+
|
|
300
|
+
export { type BandInfo, type CanvasProps, type ConnectorShape, type ConnectorsProps, type Direction, type Edge, type EdgeInfo, type EdgeState, Graph, type Id, type Lane, type Layout, type LayoutOptions, type NodeInfo, type NodeProps, type NodeState, type PlacedEdge, type PlacedLane, type PlacedNode, type Point, type Rect, type RootProps, type Selection, type Size, type Trace, connectorPath, foldPassThrough, fromTree, layout, onTrace, trace, useGraph, useNode };
|