Skip to content

Commit 080f52f

Browse files
alixanderalixander
authored
Merge pull request #2422 from stereobooster/typescript-defs
TypeScript signatures
2 parents 6b79a24 + 1e89c55 commit 080f52f

File tree

3 files changed

+347
-1
lines changed

3 files changed

+347
-1
lines changed

‎ci/release/changelogs/next.md

+1
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@
2424
- `noXMLTag`
2525
- Support relative imports. Improve elk error handling: [#2382](https://github.com/terrastruct/d2/pull/2382)
2626
- Support fonts (`fontRegular`, `fontItalic`, `fontBold`, `fontSemiBold`): [#2384](https://github.com/terrastruct/d2/pull/2384)
27+
- Add TypeScript signatures
2728

2829
- d2cli:
2930
- Support `validate` command. [#2415](https://github.com/terrastruct/d2/pull/2415)

‎d2js/js/index.d.ts

+343
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,343 @@
1+
export class D2 {
2+
compile(input: string, options?: Omit<CompileRequest, "fs">): Promise<CompileResponse>;
3+
compile(input: CompileRequest): Promise<CompileResponse>;
4+
5+
render(diagram: Diagram, options?: RenderOptions): Promise<string>;
6+
}
7+
8+
export interface RenderOptions {
9+
/** Enable sketch mode [default: false] */
10+
sketch?: boolean;
11+
/** Theme ID to use [default: 0] */
12+
themeID?: number;
13+
/** Theme ID to use when client is in dark mode */
14+
darkThemeID?: number;
15+
/** Center the SVG in the containing viewbox [default: false] */
16+
center?: boolean;
17+
/** Pixels padded around the rendered diagram [default: 100] */
18+
pad?: number;
19+
/** Scale the output. E.g., 0.5 to halve the default size. The default will render SVG's that will fit to screen. Setting to 1 turns off SVG fitting to screen. */
20+
scale?: number;
21+
/** Adds an appendix for tooltips and links [default: false] */
22+
forceAppendix?: boolean;
23+
/** Target board/s to render. If target ends with '', it will be rendered with all of its scenarios, steps, and layers. Otherwise, only the target board will be rendered. E.g. target: 'layers.x.*' to render layer 'x' with all of its children. Pass '' to render all scenarios, steps, and layers. By default, only the root board is rendered. Multi-board outputs are currently only supported for animated SVGs and so animateInterval must be set to a value greater than 0 when targeting multiple boards. */
24+
target?: string;
25+
/** If given, multiple boards are packaged as 1 SVG which transitions through each board at the interval (in milliseconds). */
26+
animateInterval?: number;
27+
/** Add a salt value to ensure the output uses unique IDs. This is useful when generating multiple identical diagrams to be included in the same HTML doc, so that duplicate IDs do not cause invalid HTML. The salt value is a string that will be appended to IDs in the output. */
28+
salt?: string;
29+
/** Omit XML tag (<?xml ...?>) from output SVG files. Useful when generating SVGs for direct HTML embedding. */
30+
noXMLTag?: boolean;
31+
}
32+
33+
export interface CompileOptions extends RenderOptions {
34+
/** Layout engine to use [default: 'dagre'] */
35+
layout?: "dagre" | "elk";
36+
/** A byte array containing .ttf file to use for the regular font. If none provided, Source Sans Pro Regular is used. */
37+
fontRegular?: Uint8Array;
38+
/** A byte array containing .ttf file to use for the italic font. If none provided, Source Sans Pro Italic is used. */
39+
fontItalic?: Uint8Array;
40+
/** A byte array containing .ttf file to use for the bold font. If none provided, Source Sans Pro Bold is used. */
41+
fontBold?: Uint8Array;
42+
/** A byte array containing .ttf file to use for the semibold font. If none provided, Source Sans Pro Semibold is used. */
43+
fontSemibold?: Uint8Array;
44+
}
45+
46+
export interface CompileRequest {
47+
/** A mapping of D2 file paths to their content*/
48+
fs: Record<string, string>;
49+
/** The path of the entry D2 file [default: index]*/
50+
inputPath: string;
51+
/** The CompileOptions to pass to the compiler*/
52+
options: CompileOptions;
53+
}
54+
55+
export interface CompileResponse {
56+
/** Compiled D2 diagram*/
57+
diagram: Diagram /* d2target.Diagram */;
58+
/** RenderOptions: Render options merged with configuration set in diagram*/
59+
renderOptions: RenderOptions;
60+
fs: Record<string, string>;
61+
graph: Graph;
62+
inputPath: string;
63+
}
64+
65+
export interface Diagram {
66+
config?: RenderOptions;
67+
name: string;
68+
/**
69+
* See docs on the same field in d2graph to understand what it means.
70+
*/
71+
isFolderOnly: boolean;
72+
description?: string;
73+
fontFamily?: any /* d2fonts.FontFamily */;
74+
shapes: Shape[];
75+
connections: Connection[];
76+
root: Shape;
77+
legend?: Legend;
78+
layers?: (Diagram | undefined)[];
79+
scenarios?: (Diagram | undefined)[];
80+
steps?: (Diagram | undefined)[];
81+
}
82+
83+
export interface Legend {
84+
shapes?: Shape[];
85+
connections?: Connection[];
86+
}
87+
88+
export type Shape = (Class | SQLTable | Text) & ShapeBase;
89+
90+
export interface ShapeBase {
91+
id: string;
92+
type: string;
93+
classes?: string[];
94+
pos: Point;
95+
width: number /* int */;
96+
height: number /* int */;
97+
opacity: number /* float64 */;
98+
strokeDash: number /* float64 */;
99+
strokeWidth: number /* int */;
100+
borderRadius: number /* int */;
101+
fill: string;
102+
fillPattern?: string;
103+
stroke: string;
104+
animated: boolean;
105+
shadow: boolean;
106+
"3d": boolean;
107+
multiple: boolean;
108+
"double-border": boolean;
109+
tooltip: string;
110+
link: string;
111+
prettyLink?: string;
112+
icon?: string /* url.URL */;
113+
iconPosition: string;
114+
/**
115+
* Whether the shape should allow shapes behind it to bleed through
116+
* Currently just used for sequence diagram groups
117+
*/
118+
blend: boolean;
119+
contentAspectRatio?: number /* float64 */;
120+
labelPosition?: string;
121+
zIndex: number /* int */;
122+
level: number /* int */;
123+
/**
124+
* These are used for special shapes, sql_table and class
125+
*/
126+
primaryAccentColor?: string;
127+
secondaryAccentColor?: string;
128+
neutralAccentColor?: string;
129+
}
130+
131+
export interface Point {
132+
x: number /* int */;
133+
y: number /* int */;
134+
}
135+
136+
export interface Class {
137+
fields: ClassField[];
138+
methods: ClassMethod[];
139+
}
140+
141+
export interface ClassField {
142+
name: string;
143+
type: string;
144+
visibility: string;
145+
}
146+
147+
export interface ClassMethod {
148+
name: string;
149+
return: string;
150+
visibility: string;
151+
}
152+
153+
export interface SQLTable {
154+
columns: SQLColumn[];
155+
}
156+
157+
export interface SQLColumn {
158+
name: Text;
159+
type: Text;
160+
constraint: string[];
161+
reference: string;
162+
}
163+
164+
export interface Text {
165+
label: string;
166+
fontSize: number /* int */;
167+
fontFamily: string;
168+
language: string;
169+
color: string;
170+
italic: boolean;
171+
bold: boolean;
172+
underline: boolean;
173+
labelWidth: number /* int */;
174+
labelHeight: number /* int */;
175+
labelFill?: string;
176+
}
177+
178+
export interface Connection extends Text {
179+
id: string;
180+
classes?: string[];
181+
src: string;
182+
srcArrow: Arrowhead;
183+
srcLabel?: Text;
184+
dst: string;
185+
dstArrow: Arrowhead;
186+
dstLabel?: Text;
187+
opacity: number /* float64 */;
188+
strokeDash: number /* float64 */;
189+
strokeWidth: number /* int */;
190+
stroke: string;
191+
fill?: string;
192+
borderRadius?: number /* float64 */;
193+
labelPosition: string;
194+
labelPercentage: number /* float64 */;
195+
link: string;
196+
prettyLink?: string;
197+
route: (any /* geo.Point */ | undefined)[];
198+
isCurve?: boolean;
199+
animated: boolean;
200+
tooltip: string;
201+
icon?: string /* url.URL */;
202+
iconPosition?: string;
203+
zIndex: number /* int */;
204+
}
205+
206+
export type Arrowhead =
207+
| "none"
208+
| "arrow"
209+
| "unfilled-triangle"
210+
| "triangle"
211+
| "diamond"
212+
| "filled-diamond"
213+
| "circle"
214+
| "filled-circle"
215+
| "box"
216+
| "filled-box"
217+
| "line"
218+
| "cf-one"
219+
| "cf-many"
220+
| "cf-one-required"
221+
| "cf-many-required";
222+
223+
export interface Graph {
224+
name: string;
225+
/**
226+
* IsFolderOnly indicates a board or scenario itself makes no modifications from its
227+
* base. Folder only boards do not have a render and are used purely for organizing
228+
* the board tree.
229+
*/
230+
isFolderOnly: boolean;
231+
ast?: any /* d2ast.Map */;
232+
root?: Object;
233+
legend?: Legend;
234+
edges: (Edge | undefined)[];
235+
objects: (Object | undefined)[];
236+
layers?: (Graph | undefined)[];
237+
scenarios?: (Graph | undefined)[];
238+
steps?: (Graph | undefined)[];
239+
theme?: any /* d2themes.Theme */;
240+
/**
241+
* Object.Level uses the location of a nested graph
242+
*/
243+
rootLevel?: number /* int */;
244+
/**
245+
* Currently this holds data embedded from source code configuration variables
246+
* Plugins only have access to exported graph, so this data structure allows
247+
* carrying arbitrary metadata that any plugin might handle
248+
*/
249+
data?: { [key: string]: any };
250+
}
251+
252+
export interface Edge {
253+
index: number /* int */;
254+
srcTableColumnIndex?: number /* int */;
255+
dstTableColumnIndex?: number /* int */;
256+
labelPosition?: string;
257+
labelPercentage?: number /* float64 */;
258+
isCurve: boolean;
259+
route?: (any /* geo.Point */ | undefined)[];
260+
src_arrow: boolean;
261+
srcArrowhead?: Attributes;
262+
/**
263+
* TODO alixander (Mon Sep 12 2022): deprecate SrcArrow and DstArrow and just use SrcArrowhead and DstArrowhead
264+
*/
265+
dst_arrow: boolean;
266+
dstArrowhead?: Attributes;
267+
references?: EdgeReference[];
268+
attributes?: Attributes;
269+
zIndex: number /* int */;
270+
}
271+
272+
export interface Attributes {
273+
label: Scalar;
274+
labelDimensions: TextDimensions;
275+
style: Style;
276+
icon?: string /* url.URL */;
277+
tooltip?: Scalar;
278+
link?: Scalar;
279+
width?: Scalar;
280+
height?: Scalar;
281+
top?: Scalar;
282+
left?: Scalar;
283+
/**
284+
* TODO consider separate Attributes struct for shape-specific and edge-specific
285+
* Shapes only
286+
*/
287+
near_key?: any /* d2ast.KeyPath */;
288+
language?: string;
289+
/**
290+
* TODO: default to ShapeRectangle instead of empty string
291+
*/
292+
shape: Scalar;
293+
direction: Scalar;
294+
constraint: string[];
295+
gridRows?: Scalar;
296+
gridColumns?: Scalar;
297+
gridGap?: Scalar;
298+
verticalGap?: Scalar;
299+
horizontalGap?: Scalar;
300+
labelPosition?: Scalar;
301+
iconPosition?: Scalar;
302+
/**
303+
* These names are attached to the rendered elements in SVG
304+
* so that users can target them however they like outside of D2
305+
*/
306+
classes?: string[];
307+
}
308+
309+
export interface EdgeReference {
310+
map_key_edge_index: number /* int */;
311+
}
312+
313+
export interface Scalar {
314+
value: string;
315+
}
316+
317+
export interface Style {
318+
opacity?: Scalar;
319+
stroke?: Scalar;
320+
fill?: Scalar;
321+
fillPattern?: Scalar;
322+
strokeWidth?: Scalar;
323+
strokeDash?: Scalar;
324+
borderRadius?: Scalar;
325+
shadow?: Scalar;
326+
"3d"?: Scalar;
327+
multiple?: Scalar;
328+
font?: Scalar;
329+
fontSize?: Scalar;
330+
fontColor?: Scalar;
331+
animated?: Scalar;
332+
bold?: Scalar;
333+
italic?: Scalar;
334+
underline?: Scalar;
335+
filled?: Scalar;
336+
doubleBorder?: Scalar;
337+
textTransform?: Scalar;
338+
}
339+
340+
export interface TextDimensions {
341+
width: number /* int */;
342+
height: number /* int */;
343+
}

‎d2js/js/package.json

+3-1
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,10 @@
3131
"./worker": "./dist/browser/worker.js"
3232
},
3333
"files": [
34-
"dist"
34+
"dist",
35+
"index.d.ts"
3536
],
37+
"types": "./index.d.ts",
3638
"scripts": {
3739
"build": "./make.sh build",
3840
"test": "bun test test/unit",

0 commit comments

Comments
 (0)