fastdraw 0.2.2 → 0.4.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.
@@ -0,0 +1,93 @@
1
+ Copyright 2012 The Libre Caslon Display Authors (https://github.com/impallari/Libre-Caslon-Display)
2
+
3
+ This Font Software is licensed under the SIL Open Font License, Version 1.1.
4
+ This license is copied below, and is also available with a FAQ at:
5
+ http://scripts.sil.org/OFL
6
+
7
+
8
+ -----------------------------------------------------------
9
+ SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
10
+ -----------------------------------------------------------
11
+
12
+ PREAMBLE
13
+ The goals of the Open Font License (OFL) are to stimulate worldwide
14
+ development of collaborative font projects, to support the font creation
15
+ efforts of academic and linguistic communities, and to provide a free and
16
+ open framework in which fonts may be shared and improved in partnership
17
+ with others.
18
+
19
+ The OFL allows the licensed fonts to be used, studied, modified and
20
+ redistributed freely as long as they are not sold by themselves. The
21
+ fonts, including any derivative works, can be bundled, embedded,
22
+ redistributed and/or sold with any software provided that any reserved
23
+ names are not used by derivative works. The fonts and derivatives,
24
+ however, cannot be released under any other type of license. The
25
+ requirement for fonts to remain under this license does not apply
26
+ to any document created using the fonts or their derivatives.
27
+
28
+ DEFINITIONS
29
+ "Font Software" refers to the set of files released by the Copyright
30
+ Holder(s) under this license and clearly marked as such. This may
31
+ include source files, build scripts and documentation.
32
+
33
+ "Reserved Font Name" refers to any names specified as such after the
34
+ copyright statement(s).
35
+
36
+ "Original Version" refers to the collection of Font Software components as
37
+ distributed by the Copyright Holder(s).
38
+
39
+ "Modified Version" refers to any derivative made by adding to, deleting,
40
+ or substituting -- in part or in whole -- any of the components of the
41
+ Original Version, by changing formats or by porting the Font Software to a
42
+ new environment.
43
+
44
+ "Author" refers to any designer, engineer, programmer, technical
45
+ writer or other person who contributed to the Font Software.
46
+
47
+ PERMISSION & CONDITIONS
48
+ Permission is hereby granted, free of charge, to any person obtaining
49
+ a copy of the Font Software, to use, study, copy, merge, embed, modify,
50
+ redistribute, and sell modified and unmodified copies of the Font
51
+ Software, subject to the following conditions:
52
+
53
+ 1) Neither the Font Software nor any of its individual components,
54
+ in Original or Modified Versions, may be sold by itself.
55
+
56
+ 2) Original or Modified Versions of the Font Software may be bundled,
57
+ redistributed and/or sold with any software, provided that each copy
58
+ contains the above copyright notice and this license. These can be
59
+ included either as stand-alone text files, human-readable headers or
60
+ in the appropriate machine-readable metadata fields within text or
61
+ binary files as long as those fields can be easily viewed by the user.
62
+
63
+ 3) No Modified Version of the Font Software may use the Reserved Font
64
+ Name(s) unless explicit written permission is granted by the corresponding
65
+ Copyright Holder. This restriction only applies to the primary font name as
66
+ presented to the users.
67
+
68
+ 4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
69
+ Software shall not be used to promote, endorse or advertise any
70
+ Modified Version, except to acknowledge the contribution(s) of the
71
+ Copyright Holder(s) and the Author(s) or with their explicit written
72
+ permission.
73
+
74
+ 5) The Font Software, modified or unmodified, in part or in whole,
75
+ must be distributed entirely under this license, and must not be
76
+ distributed under any other license. The requirement for fonts to
77
+ remain under this license does not apply to any document created
78
+ using the Font Software.
79
+
80
+ TERMINATION
81
+ This license becomes null and void if any of the above conditions are
82
+ not met.
83
+
84
+ DISCLAIMER
85
+ THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
86
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
87
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
88
+ OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
89
+ COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
90
+ INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
91
+ DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
92
+ FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
93
+ OTHER DEALINGS IN THE FONT SOFTWARE.
package/guide/guide.md CHANGED
@@ -69,9 +69,17 @@ One statement per line. An indented line continues the statement above it. `//`
69
69
 
70
70
  ```
71
71
  look "./team.look" // path relative to this file; leave the line out to use the built-in look
72
- // or a look that ships with FastDraw: look headline | night | reference | sketch | whiteboard | shade | engraved | keys | transit | offset | listing
72
+ // or a look that ships with FastDraw: look reference | shade | sketch | whiteboard
73
+ // (each has a dark version, drawn in the dark theme and by render --dark; name the light one)
74
+ // or one on GitHub, by its address: look "https://raw.githubusercontent.com/coccor/fastdraw-looks/main/engraved.look"
75
+ // (coccor/fastdraw-looks also has headline, keys, listing, offset and transit; azure, aws, gcp and kubernetes:
76
+ // a cloud's colours, its own icons and its groups such as vpc and resource-group; and print, blueprint,
77
+ // high-contrast and terminal)
73
78
  // for a dark theme, keep the line and run fastdraw render x.fdraw --dark to get x-dark.png too
74
79
  canvas paper=#ffffff dots=none dotgap=24 // optional: changes the look's background for this diagram only
80
+ // the page pattern can be dots=, grid=, lines= (ruled), cross= (small + marks), iso= (isometric dots),
81
+ // bars= (stripes), diag= (45-degree lines), graph= (graph paper) or hex= (hexagons), each a colour such
82
+ // as ink/0.08, with a gap key: dotgap= gridgap= linegap= crossgap= isogap= bargap= diaggap= graphgap= hexgap=
75
83
 
76
84
  // shape: id: style "text" at x,y WxH key=value ...
77
85
  api: node "Orders API" sub="REST · :8080" tag="API" at 200,120
@@ -213,18 +221,18 @@ An arrow can end on a row: `orders.user_id -- users.id`. It attaches to the left
213
221
 
214
222
  `icon=name` puts a small icon in any box: `db: store "Orders DB" icon=database at 440,120`. `fastdraw sizes` lists the icons the look has (server, database, user, cloud, queue, lock, mail, function, ai and about 120 more with friendly names, plus every other Phosphor icon under its own name, about 1,500 in all). `fastdraw icons email` searches them by name or meaning: it finds `mail`, and `k8s` finds `pod`.
215
223
 
216
- - The icon sits just left of the text and the pair is centred. `icon.pos=top` puts it above the text instead; the box then needs about 28px more height.
224
+ - The icon sits just left of the text and the pair is centred. `icon.pos=top` puts it above the text instead; the box then needs about 28px more height. On a zone, `icon.pos=corner` draws the icon as a tab in its top-left corner with the zone's name beside it, as cloud providers draw a group's icon (`icon.size=` sets the tab, 24 by default).
217
225
  - With no text, the icon fills the box.
218
226
  - An icon on its own, with no box, is the `icon` style: `api: icon "Orders API" at 60,220 40x40 icon=server` (24x24 unless you give `WxH`). The icon is the shape, so `fill=`, `stroke=` and `sw=` style the icon itself (`fill=accent/0.2 stroke=accent sw=2`), and its text is a caption centred underneath. Lines attach to the icon and go around other icons' captions.
219
227
  - `icon.size=20` and `icon.color=link` change it; by default it takes the colour of the box's text.
220
228
  - `icon.fill=accent/0.2` lays a tint under the icon's main part for a two-tone look (none by default), and `icon.width=2` sets its line thickness in pixels; a built-in icon comes in four weights (thin, light, regular, bold), and the nearest is used. Both take look colours, tints or hex (`icon.fill=#ffd400`), and both work in a look's `style` lines so every box of a style gets the same.
221
229
  - `icon.style=solid` draws a built-in icon filled in one colour, and `icon.style=duotone` draws its outline over a light tint of the same drawing (`icon=database icon.style=duotone`). They take `icon.color=` (on an `icon` shape, `stroke=`); a duotone's tint is `icon.fill=` when set, else a light shade of the icon's colour. Outline, solid and duotone are the same drawing; every built-in icon has all three, a look's own icons only the outline. Keep one style across a diagram.
222
- - A look can bring its own colour icons (a cloud vendor's set, product logos). `fastdraw sizes <look>` lists them first; use them the same way: `icon=virtual-machine`. They keep their own colours. Run `fastdraw icons <look> word` to search a large set.
230
+ - A look can bring its own colour icons (a cloud vendor's set, product logos), best by their web address from a recommended source (`fastdraw guide look`, Icons). Use them the same way: `icon=virtual-machine`. They keep their own colours. A set in a folder next to the look is listed by `fastdraw sizes <look>` and searched by `fastdraw icons <look> word`; for a set on the web, `fastdraw icons <look> word` searches it too. When `fastdraw sizes` says the look hides the built-in icons, use the look's own.
223
231
  - Use icons where they say something the name does not (what kind of thing a box is), on every box of a row or on none. Two or three kinds of icon in one diagram is plenty.
224
232
 
225
233
  A shape's text is styled with `title.size=`, `title.color=`, `title.weight=`, `title.font=` (and `sub.` the same for the second line).
226
234
 
227
- Any appearance property can be overridden on one element: `fill=`, `stroke=`, `sw=` (stroke width), `dash=4,3`, `radius=`. Colours are `#hex`, a colour name from the look, or either followed by `/opacity` (`ink/0.3`). Prefer the look's styles; override only with a reason.
235
+ Any appearance property can be overridden on one element: `fill=`, `stroke=`, `sw=` (stroke width), `dash=4,3`, `radius=`. `opacity=0.5` draws the whole element (box, line or text, with its text and arrowheads) see-through, from `0` to `1`. `rotate=30` turns a shape clockwise about its middle, by any angle in degrees (negative turns it the other way); its text, icon and caption turn with it, and lines attach to its turned sides. Lines themselves do not turn. Colours are `#hex`, a colour name from the look, or either followed by `/opacity` (`ink/0.3`). Prefer the look's styles; override only with a reason. For `sw=`, leave the style's width unless a line or outline must read heavier or lighter than its kind; then `sw=1` (thin), `sw=1.6` (medium) or `sw=2.4` (bold) are the widths a person can pick again in the editor, and any other width shows there as the nearest of them.
228
236
 
229
237
  ### Connectors
230
238
 
@@ -244,9 +252,16 @@ Any appearance property can be overridden on one element: `fill=`, `stroke=`, `s
244
252
  |---|---|---|
245
253
  | `arrow` | filled arrowhead | the default head |
246
254
  | `open` | two strokes, not filled | a dependency, an asynchronous message |
255
+ | `stealth` | filled arrowhead swept back to a notch | a sharper default head |
256
+ | `double` | two filled arrowheads in a row | a fast or repeated flow |
257
+ | `half` | one stroke on the left side, a harpoon | an asynchronous message, one half of a two-way pair |
247
258
  | `triangle` | hollow triangle | inherits from / implements (points at the parent) |
248
259
  | `diamond`, `diamond-solid` | hollow or filled diamond | aggregation, composition (sits on the owner) |
249
260
  | `dot`, `circle` | filled or hollow circle | a start point, a provided interface |
261
+ | `square`, `square-solid` | hollow or filled square | a port, a stub end |
262
+ | `bar` | a short bar across the end | blocks, inhibits, a hard stop |
263
+ | `cross` | an X on the end | rejected, cancelled, destroyed |
264
+ | `stop` | a ring the line runs into | a station on a route (`stop.color=` colours the ring) |
250
265
  | `one`, `only-one` | one bar, two bars | exactly one |
251
266
  | `many`, `one-many` | crow's foot, crow's foot and bar | many, one or more |
252
267
  | `zero-one`, `zero-many` | circle and bar, circle and crow's foot | optional one, optional many |
@@ -280,7 +295,7 @@ Labels are drawn in small caps on a paper-coloured patch, above a horizontal lin
280
295
 
281
296
  ### Text
282
297
 
283
- `text "words" at x,y style=name` — `at` is the left end of the text baseline. `anchor=middle` or `anchor=end` changes that. `rotate=-90` turns the text to read upwards about its `at` point (`rotate=90`: downwards), for a label along a vertical axis. Overrides: `size=`, `color=`, `weight=`, `font=sans|mono|serif`, `italic=1` (only where the font has an italic face; the bundled sans and mono do not, the serif does).
298
+ `text "words" at x,y style=name` — `at` is the left end of the text baseline. `anchor=middle` or `anchor=end` changes that. `width=240` makes the text a box: `at` is the left end of its first line, the words wrap to the width, and `align=center` or `align=right` lines them up in it. `rotate=-90` turns the text to read upwards about its `at` point (`rotate=90`: downwards), for a label along a vertical axis; any other angle in degrees turns it that far clockwise. Overrides: `size=`, `color=`, `weight=`, `font=sans|mono|serif`, `italic=1` (only where the font has an italic face; the bundled sans and mono do not, the serif does).
284
299
 
285
300
  Spaces inside the quotes are drawn as written, here and in every other text (labels, `sub=`, table cells): leading spaces indent, and a run of spaces stays a run. So indented code or lined-up columns can be one text per line at the same x, with `font=mono` for the columns to line up: `text " orders:" at 40,58 font=mono`.
286
301
 
package/guide/look.md CHANGED
@@ -2,7 +2,9 @@
2
2
 
3
3
  A look is one text file (`.look`) that decides how every style is drawn: colours, fonts, shapes, lines and text. Diagrams point to it with `look "./team.look"`. Change the look and every diagram that uses it changes.
4
4
 
5
- Eleven looks ship with FastDraw and need no file: `look engraved`, `look headline`, `look keys`, `look listing`, `look night`, `look offset`, `look reference`, `look shade`, `look sketch`, `look transit` and `look whiteboard` (a bare name, no quotes or `.look`). Six of them are styles of drawing more than palettes: `shade` (hairline boxes with a hatched shadow), `engraved` (double rules and a black plate, like a printed plate), `keys` (boxes with a side, like keycaps), `transit` (thick route lines with stops, like a network map), `offset` (two inks printed out of register) and `listing` (a printout on striped listing paper). In the editor, the **Look** button shows the diagram in each of them and the built-in look, to try one before keeping it.
5
+ Four looks ship with FastDraw besides the built-in one and need no file: `look reference`, `look shade`, `look sketch` and `look whiteboard` (a bare name, no quotes or `.look`). `shade` is a style of drawing more than a palette: hairline boxes with a hatched shadow. Each comes in a light and a dark version (see [Dark version](#dark-version)); a diagram names the light one.
6
+
7
+ A look can also be named by the https address of its file, such as one in a public GitHub repository: `look "https://raw.githubusercontent.com/coccor/fastdraw-looks/main/engraved.look"`. The repository coccor/fastdraw-looks holds cloud looks, each at that address with its own name: `azure`, `aws`, `gcp` and `kubernetes` are drawn the way each one's own documentation draws diagrams (AWS without boxes, each service an icon with its name under it, in boxes 144x104, and groups with their icon as a corner tab; Google Cloud as nested coloured panels of white cards), with its own icons (`icon=app-service`, `icon=lambda`, `icon=bigquery`, `icon=deploy`) and extra styles for its groups (`resource-group`, `vnet`, `vpc`, `public-subnet`, `region`, `project`, `cluster`, `namespace`); `fastdraw sizes` and `fastdraw icons` on the address list them. It holds looks for a use: `print` (black and greys only; things differ by weight, dashes and texture, for printing in black and white), `blueprint` (white outlines on bright blue squared paper, groups as double-line walls, everything one white), `high-contrast` (black on white, heavy lines, every style told apart by more than colour, for low vision and colour blindness) and `terminal` (one monospace face on near-black; keep text in boxes short). It holds company styles: `carbon` (IBM's technical diagrams: small nodes as a coloured square with a white icon and the name under it, black circles for people, large colour-block nodes for the subject and `compute`, framed groups `cloud-group`, `region`, `az`, `subnet`, `security-group`), `vercel` (Vercel's docs: boxes of words in regular Geist, a hatched outer panel with `region` and grey `panel` inside, a browser-window `external`, `chip` and `badge`, line labels on pills) and `figjam` (a FigJam board: flat shapes without outlines, violet circles where a flow starts, terracotta diamonds, stickies, sections named on a tag above their corner, `cursor` and `name-tag`). It also holds `tiles` (white tiles without outlines on a soft shadow, groups named beside a round badge on their corner, labels on dark pills, status dots). And six more styles of drawing: `engraved` (double rules and a black plate, like a printed plate), `headline` (flat blocks under a serif headline, like a newspaper graphic), `keys` (boxes with a side, like keycaps), `listing` (a printout on striped listing paper), `offset` (two inks printed out of register) and `transit` (thick route lines with stops, like a network map). The command line fetches a look named this way on every run and keeps a copy, which `--offline` uses. In the editor, the **Look** button shows the diagram in each look and the built-in one, to try one before keeping it; **From GitHub** in the same panel lists the looks in any public repository.
6
8
 
7
9
  ## How to work
8
10
 
@@ -20,8 +22,13 @@ The looks that ship with FastDraw all define the same styles (the ones above plu
20
22
  One statement per line; an indented line continues the one above; `//` starts a comment.
21
23
 
22
24
  ```
23
- canvas paper=paper dots=ink/0.06 dotgap=22 // paper= background colour; dots= dot colour and dotgap= spacing are optional; a diagram's own canvas line can override any of the three
25
+ canvas paper=paper dots=ink/0.06 dotgap=22 // paper= background colour; dots= dot colour and dotgap= spacing are optional; a diagram's own canvas line can override these and the patterns below
24
26
  // sketch=1 draws every outline and line by hand (2 is rougher); see looks/sketch.look
27
+ // grid=colour rules the page in squares like graph or blueprint paper (gridgap= is the square, default 24)
28
+ // lines=colour rules it like a notebook (linegap=, default 24), cross=colour puts a small + at every
29
+ // crossgap (default 24), iso=colour lays dots on a triangle lattice for isometric drawings (isogap=)
30
+ // diag=colour hatches the page at 45 degrees (diaggap=, default 12), graph=colour rules graph paper with a
31
+ // heavier line every fifth square (graphgap=, default 10), hex=colour lays a honeycomb (hexgap= is a side, default 14)
25
32
  // bars=colour stripes the page like listing paper (bargap= is the stripe height), feed=colour adds
26
33
  // sprocket holes down both edges, grain=0.5 lays paper grain over everything (0 to 1)
27
34
  // tint=hue or tint=alpha: how colour/opacity tints mix (see Colours)
@@ -54,7 +61,37 @@ On a light page a tint such as `amber/0.1` is the colour at that opacity over wh
54
61
 
55
62
  `font sans|mono|serif "Family"` sets the family for each role; styles then say `font=sans`.
56
63
 
57
- Five families are bundled and always available: **Geist**, **Geist Mono** and **Newsreader** (the built-in look), **Libre Franklin** and **Instrument Serif**. To use any other font, put its files in a folder next to the look and name the folder:
64
+ These families ship with FastDraw and are drawn the same everywhere, with nothing else needed: **Geist**, **Geist Mono** and **Libre Caslon Display** (the built-in look), **Newsreader**, **Libre Franklin**, **Instrument Serif** and **Sketch Hand**.
65
+
66
+ **For any other font, give the address of its files on the web.** That is the way to prefer: the look then works wherever it is opened (the editor, shared links, embedded diagrams, the command line), and nothing has to be committed next to it.
67
+
68
+ ```
69
+ font sans "Inter" "https://cdn.jsdelivr.net/fontsource/fonts/inter@5.3.0/latin-{weight}-{style}.ttf"
70
+ font mono "JetBrains Mono" "https://cdn.jsdelivr.net/fontsource/fonts/jetbrains-mono@5.3.0/latin-{weight}-normal.ttf"
71
+ ```
72
+
73
+ - `{weight}` is filled in with 400, 500, 600 and 700, and `{style}` with `normal` and `italic`; leave either out when the file name does not change with it. Only the faces the text uses are fetched.
74
+ - Use **TTF or OTF** addresses: the command line's PNG renderer reads only those (the editor also takes WOFF2). The family name inside the files must match `font sans "..."` exactly.
75
+ - Give an address with a fixed version (`inter@5.3.0`, not `inter@latest`), so the look does not change under you. The address must be https and must not redirect.
76
+ - The editor and embedded diagrams fetch the files from that address in the reader's browser; `fastdraw check` and `render` fetch them once and keep a copy in a cache folder (`--offline` uses only the copy). Exported SVGs carry the faces they use. fastdraw.dev images of private READMEs and the Rust crate do not fetch, and draw the role's shipped font instead.
77
+
78
+ **Recommended:** [Fontsource](https://fontsource.org), served by jsDelivr, has static TTF files for every Google font and many more, under open licences. The address is `https://cdn.jsdelivr.net/fontsource/fonts/<id>@<version>/latin-{weight}-{style}.ttf`, where `<id>` is the name on fontsource.org in small letters with `-` for spaces. Checked and known to work:
79
+
80
+ | Font | Role | Address |
81
+ | --- | --- | --- |
82
+ | Inter | sans | `https://cdn.jsdelivr.net/fontsource/fonts/inter@5.3.0/latin-{weight}-{style}.ttf` |
83
+ | IBM Plex Sans | sans | `https://cdn.jsdelivr.net/fontsource/fonts/ibm-plex-sans@5.3.0/latin-{weight}-{style}.ttf` |
84
+ | Source Sans 3 | sans | `https://cdn.jsdelivr.net/fontsource/fonts/source-sans-3@5.3.1/latin-{weight}-{style}.ttf` |
85
+ | Roboto | sans | `https://cdn.jsdelivr.net/fontsource/fonts/roboto@5.3.0/latin-{weight}-{style}.ttf` |
86
+ | Open Sans | sans | `https://cdn.jsdelivr.net/fontsource/fonts/open-sans@5.3.0/latin-{weight}-{style}.ttf` |
87
+ | Noto Sans | sans | `https://cdn.jsdelivr.net/fontsource/fonts/noto-sans@5.3.0/latin-{weight}-{style}.ttf` |
88
+ | JetBrains Mono | mono | `https://cdn.jsdelivr.net/fontsource/fonts/jetbrains-mono@5.3.0/latin-{weight}-{style}.ttf` |
89
+ | IBM Plex Mono | mono | `https://cdn.jsdelivr.net/fontsource/fonts/ibm-plex-mono@5.3.0/latin-{weight}-{style}.ttf` |
90
+ | Fira Code | mono | `https://cdn.jsdelivr.net/fontsource/fonts/fira-code@5.3.0/latin-{weight}-normal.ttf` |
91
+
92
+ `latin` covers Western European text; Fontsource also has `latin-ext`, `cyrillic`, `greek` and others in the same place. A brand font that is not on the web (Segoe UI, a licensed corporate face) cannot be used this way: give the look the closest open font instead.
93
+
94
+ **A font folder** is the other way, for fonts that must not be fetched or are not on the web: put the files next to the look and name the folder.
58
95
 
59
96
  ```
60
97
  fontdir "./fonts" // relative to the look file
@@ -64,8 +101,11 @@ font sans "Fira Sans"
64
101
  - Files must be **TTF or OTF**, one file per weight and style you use (for example Regular and SemiBold; add Italic if a style sets `italic=1`). Box titles use weight 600 by default. Use static files, not a single variable font.
65
102
  - The family name is read from inside the files, so `font sans "..."` must match it exactly. `fastdraw sizes team.look` lists the fonts and flags any family it found no file for; `fastdraw check` warns about it too.
66
103
  - Commit the font folder with the look, and keep the font's licence file beside it. Use fonts whose licence allows redistribution (for example the SIL Open Font License).
67
- - Ligatures are turned off in every font, in the editor, the SVG and the PNG: `--`, `->`, `>=`, `!=` and `...` are drawn as the characters written, never as one joined glyph, so code, command-line flags and SQL read as typed.
68
- - In the browser editor the look's fonts load when a folder is open. A diagram opened as a single file, pasted, or restored from an exported image is drawn with fallback fonts until its folder is opened.
104
+ - In the browser editor a folder's fonts load only when the folder is open.
105
+
106
+ Wherever a font's files cannot be read or fetched (a font folder in a shared link or an embedded diagram, an address that cannot be reached), text is drawn in the shipped family for its role: Geist for sans, Geist Mono for mono, Newsreader for serif.
107
+
108
+ Ligatures are turned off in every font, in the editor, the SVG and the PNG: `--`, `->`, `>=`, `!=` and `...` are drawn as the characters written, never as one joined glyph, so code, command-line flags and SQL read as typed.
69
109
 
70
110
  ### Styles
71
111
 
@@ -88,7 +128,11 @@ font sans "Fira Sans"
88
128
  | `halftone=colour` | fill with a field of printed dots; `halftone.gap=` spaces them, `halftone.r=` sizes them |
89
129
  | `shade=colour` | a shadow of fine diagonal lines down the right and bottom of the shape; `shade.size=` is how far it reaches (default 5), `shade.gap=` and `shade.sw=` space and weigh its lines |
90
130
  | `depth=N` | a slab N pixels below the shape, so it reads as a solid with a side; `depth.fill=` and `depth.stroke=` colour it. A line that ends on the bottom edge ends on the slab |
131
+ | `shadow=colour` | a soft shadow under the shape: the shape grown in six fading steps, `shadow.size=` far (default 12), `shadow.dx=` to the side (default 0) and `shadow.dy=` lower (default 4); give a faint colour such as `#3b3f8c/0.1` |
91
132
  | `inner=colour` | a second, finer rule just inside the outline; `inner.gap=` (default 3.5) and `inner.sw=` |
133
+ | `side=colour` | a bar down the left edge of a box, `side.w=` wide (default 4), as IBM draws a side-bar node and a group |
134
+ | `icon.block=colour` | with the icon at the left: the strip that holds it is filled, as tall as the box and `icon.block.w=` wide (square by default), the icon centred in it and the text 12px after it, as IBM draws a colour-block node; give the icon a light `icon.color=` |
135
+ | `icon.bg=colour` | a filled square behind the icon, `icon.bg.size=` across (the icon plus 12px each side by default); `icon.bg.shape=circle` for a circle; `icon.bg.shadow=colour` lays a soft shadow under it (`icon.bg.shadow.size=`, `.dx=`, `.dy=`, default 8, 0, 3). With `icon.pos=top`, `fill=none stroke=none` and a white `icon.color` it draws IBM's small node: a coloured square with a white icon and the name under it |
92
136
  | `corners=plus` | a mark on each corner of a box: `plus` or `square`; `corners.color=`, `corners.size=` |
93
137
  | `offset=dx,dy` | print the fill that far out of register with the outline |
94
138
  | `blend=multiply` | let this style's ink darken what it overlaps, like overprinting (also on line and text styles) |
@@ -98,6 +142,8 @@ font sans "Fira Sans"
98
142
  | `sub.*` | the second line (`sub=` on an element): `sub.font`, `sub.size`, `sub.color` |
99
143
  | `tag.*` | the corner marker (`tag=`): `tag.color`, `tag.border`, `tag.font`, `tag.size` |
100
144
  | `ghost.*` | the big faint number (`ghost=`): `ghost.color`, `ghost.size` |
145
+ | `icon.pos=`, `icon.size=` | where a box's icon goes: `left` of the text (the default), on `top` of it, or in the top-left `corner` as a tab, with a left-aligned caption starting after it (for a group's icon, as cloud providers draw them); `icon.size` is its size in pixels |
146
+ | `icon.dx=`, `icon.dy=` | move the icon from where it would sit, in pixels: with `icon.pos=corner` and `icon.bg=`, `icon.dx=-8 icon.dy=-8` puts a group's badge out onto its corner |
101
147
 
102
148
  On a dark or saturated fill, set `title.color`, `sub.color`, `tag.color` and `tag.border` to something that contrasts, or the text disappears. Set these explicitly on every style; do not rely on defaults. Diagrams also lay their own text over boxes (a caption drawn on the subject): where a style's fill would swallow that text, it is drawn in the style's `title.color` instead, so a dark `focal` needs a light `title.color`.
103
149
 
@@ -135,7 +181,7 @@ The tag sits 8px in from the top-left corner and is 12px tall, so keep a path's
135
181
  | `stroke=`, `sw=`, `dash=` | colour, width, dash pattern |
136
182
  | `route=` | `ortho` (right-angle turns), `straight`, or `curve` (a smooth line) |
137
183
  | `radius=` | corner radius of the turns |
138
- | `head=` | the marker `->` draws: `arrow` (default), `open`, `triangle`, `diamond`, `diamond-solid`, `dot`, `circle`, or one of the relationship ends (`one`, `only-one`, `many`, `one-many`, `zero-one`, `zero-many`). `head=none` marks a style meant for plain lines, never arrows |
184
+ | `head=` | the marker `->` draws: `arrow` (default), `open`, `stealth`, `double`, `half`, `triangle`, `diamond`, `diamond-solid`, `square`, `square-solid`, `dot`, `circle`, `bar`, `cross`, or one of the relationship ends (`one`, `only-one`, `many`, `one-many`, `zero-one`, `zero-many`). `head=none` marks a style meant for plain lines, never arrows |
139
185
  | `tail=` | a marker for the start of the line, if the style always has one. `stop` is a ring, like a station on a route map (`stop.color=`) |
140
186
  | `head.size=` | scale the arrowhead, for a wide line (1 is the default; 0.5 to 4) |
141
187
  | `cap=round` | round the ends and corners of the line |
@@ -143,7 +189,7 @@ The tag sits 8px in from the top-left corner and is 12px tall, so keep a path's
143
189
  | `double=colour` | a finer line of that colour on top, which turns a wide line into two rails; `double.sw=` |
144
190
  | `label.*` | the text on the line: `label.font`, `label.size`, `label.color`, `label.spacing`, `label.caps=0` to keep the label's own case (default is capitals), `label.weight`, `label.italic=1`. `label.fill=` and `label.border=` make the label a plate instead of a patch of paper (`label.radius=`, `label.pad=`, `label.sw=`) |
145
191
 
146
- **Text styles** (`style name text ...`): `font=`, `size=`, `weight=`, `color=`, `italic=1`, `spacing=`, `caps=1`. `echo=colour` prints the text a second time underneath, a little off (`echo.dx=`, `echo.dy=`, default 3).
192
+ **Text styles** (`style name text ...`): `font=`, `size=`, `weight=`, `color=`, `italic=1`, `spacing=`, `caps=1`. `dy=6` draws the text 6px lower than its `at` point (negative: higher), for a font that sits high or low on its baseline; the file's positions stay as they are. `echo=colour` prints the text a second time underneath, a little off (`echo.dx=`, `echo.dy=`, default 3).
147
193
 
148
194
  ### Built-in styles you can restyle
149
195
 
@@ -159,16 +205,60 @@ icon queue "M4 6h16" "M4 12h16" "M4 18h16"
159
205
 
160
206
  The quoted parts are SVG path data drawn in a 24x24 box; they are stroked, not filled, in the colour of the box's text. Keep to simple outlines with a 1.5 stroke in mind, so they sit with the built-in ones. An icon of your own (or one you replace) is an outline only: it has no solid or duotone style. A style can carry an icon (`style store extends node icon=database`), and `icon.size=`, `icon.color=`, `icon.pos=top` work in a style too.
161
207
 
162
- **Colour icons and vendor sets** go in a folder of SVG files next to the look:
208
+ **Colour icons and vendor sets** (Azure, AWS, Google Cloud, Kubernetes, product logos): prefer **giving their address on the web**. The look then works wherever it is opened, a shared link stays short, and nothing has to be committed next to the look.
209
+
210
+ ```
211
+ // a whole set whose file names are the icon names: {name} is replaced by the icon=... of each box
212
+ icondir "https://cdn.jsdelivr.net/gh/benc-uk/icon-collection@e33ee714d05a24a81cf6ccd967ef34b22cb77e65/azure-docs/{name}.svg"
213
+
214
+ // one icon from a set whose file names are not (AWS, the Azure icon set as Microsoft names it)
215
+ icon lambda "https://cdn.jsdelivr.net/npm/aws-icons@3.3.0/icons/architecture-service/AWSLambda.svg"
216
+ icon s3 "https://cdn.jsdelivr.net/npm/aws-icons@3.3.0/icons/architecture-service/AmazonSimpleStorageService.svg"
217
+ ```
218
+
219
+ - A diagram then writes `icon=key-vault`, `icon=lambda`. Only the icons a diagram uses are fetched.
220
+ - **Seeing what a set has.** For a set on `cdn.jsdelivr.net` with a fixed version, FastDraw reads jsDelivr's list of the package's files, so `fastdraw icons team.look vault` searches the whole set, `fastdraw preview-look` draws it (the first 200), and the editor's icon picker offers it. For a set anywhere else (or a GitHub repository too big for jsDelivr to list), write its names in the look: `icondir "https://.../{name}.svg" names="pod deploy svc"`. Without either, the set still works, by name. Several `icondir` addresses are tried in order, after the icon's own `icon` line; an address without `{name}` is a folder, and `/<name>.svg` is added to it.
221
+ - Give an address with a fixed version or commit (`aws-icons@3.3.0`, `@e33ee71...`), never `@latest` or a branch: a set that renames a file would change your diagrams. The address must be https and must not redirect.
222
+ - The editor and embedded diagrams fetch the files in the reader's browser; `fastdraw check` and `render` fetch them once and keep a copy in a cache folder (`--offline` uses only the copy). The server sees a request for the file, nothing else. Exported images carry the icons they use.
223
+ - Where the files cannot be fetched (no network, the Rust crate, fastdraw.dev images of private READMEs), the closest built-in icon is drawn and a warning says so. An icon found at none of the addresses is an error, as a misspelt built-in name is.
224
+ - Check the vendor's terms for its icons; FastDraw ships none of them. Writing an address in a look does not copy the icons anywhere.
225
+
226
+ **Recommended sources.** Each is served (by jsDelivr, or GitHub for Kubernetes) with the headers the browser needs, and the versions below were checked. jsDelivr does not serve files from GitHub repositories over 50 MB; use `raw.githubusercontent.com/<owner>/<repo>/<commit>/<path>` for those.
227
+
228
+ | Set | What it has | `icondir` address, or the pattern for `icon` lines |
229
+ | --- | --- | --- |
230
+ | Azure (Ben Coleman's collection) | about 150 Azure service icons, file names in small letters (`key-vault`, `app-service`, `cosmos-db`, `virtual-machine`, `application-insights`) | `https://cdn.jsdelivr.net/gh/benc-uk/icon-collection@e33ee714d05a24a81cf6ccd967ef34b22cb77e65/azure-docs/{name}.svg` |
231
+ | Azure, Microsoft's names | the full Azure set as Microsoft names the files (`Virtual-Machine.svg`, `Key-Vaults.svg`): one `icon` line each | `https://cdn.jsdelivr.net/gh/benc-uk/icon-collection@e33ee714d05a24a81cf6ccd967ef34b22cb77e65/azure-icons/<File-Name>.svg` |
232
+ | AWS (`aws-icons`) | the AWS architecture icons (`AWSLambda.svg`, `AmazonEC2.svg`): one `icon` line each; `resource/` has the smaller resource icons | `https://cdn.jsdelivr.net/npm/aws-icons@3.3.0/icons/architecture-service/<FileName>.svg` |
233
+ | Google Cloud (`gcp-icons`) | 45 Google Cloud product icons (`bigquery`, `alloydb`, `gke`, `cloudsql`, `vertexai`); five end in `-512-color-rgb.svg` (`cloudrun`, `computeengine`, `apigee`, `networking`, `secops`) and need an `icon` line | `https://cdn.jsdelivr.net/npm/gcp-icons@1.0.6/dist/icons/{name}-512-color.svg` |
234
+ | Kubernetes | the 30 Kubernetes resource icons by their short names; not listed by jsDelivr, so give `names="c-role cm crb crd cronjob deploy ds ep group hpa ing job limits netpol ns pod psp pv pvc quota rb role rs sa sc secret sts svc user vol"` | `https://raw.githubusercontent.com/kubernetes/community/d0476ffb364cd9dc6b007221410db3b50989ebc3/icons/svg/resources/labeled/{name}.svg` |
235
+ | Simple Icons | about 3,000 brand and product logos, one colour (`github`, `postgresql`, `docker`, `stripe`) | `https://cdn.jsdelivr.net/npm/simple-icons@16.38.0/icons/{name}.svg` |
236
+ | Devicon | logos of languages and tools in their colours (`docker`, `postgresql`, `react`, `python`); the repository is too big for jsDelivr to list, so add `names="..."` with the ones you use | `https://cdn.jsdelivr.net/gh/devicons/devicon@v2.16.0/icons/{name}/{name}-original.svg` |
237
+ | Lucide | outline icons like the built-in ones, drawn in black | `https://cdn.jsdelivr.net/npm/lucide-static@1.74.0/icons/{name}.svg` |
238
+ | Tabler | outline icons, drawn in black | `https://cdn.jsdelivr.net/npm/@tabler/icons@3.52.0/icons/outline/{name}.svg` |
239
+
240
+ `fastdraw icons team.look <word>` searches a listed set; to browse one by hand, open its package on jsdelivr.com (for example `https://www.jsdelivr.com/package/npm/aws-icons`).
241
+
242
+ **A folder of SVG files** next to the look is the other way, for icons that must not be fetched or are not on the web:
163
243
 
164
244
  ```
165
245
  icondir "./icons"
166
246
  ```
167
247
 
168
- Every `.svg` file directly in that folder becomes an icon, drawn exactly as the file looks, in its own colours. The icon's name is the file name in small letters with everything that is not a letter or digit turned into `-`, and a leading number-and-`icon-service-` prefix dropped: `10021-icon-service-Virtual-Machine.svg` is `icon=virtual-machine`, `Load Balancer.svg` is `icon=load-balancer`. `fastdraw icons team.look` lists them and `fastdraw icons team.look storage` searches. This is how a team adds, say, the Azure or AWS architecture icons: download the set from the vendor, copy the files you use into the folder, and commit them with the look (check the vendor's terms first; FastDraw ships none of them).
248
+ Every `.svg` file directly in that folder becomes an icon, drawn exactly as the file looks, in its own colours. The icon's name is the file name in small letters with everything that is not a letter or digit turned into `-`, and a leading number-and-`icon-service-` prefix dropped: `10021-icon-service-Virtual-Machine.svg` is `icon=virtual-machine`, `Load Balancer.svg` is `icon=load-balancer`. `fastdraw icons team.look` lists them and `fastdraw icons team.look storage` searches. Commit the folder with the look. A shared link carries the folder's icons that the diagram uses inside it.
249
+
250
+ **A look that offers only its own icons.** A vendor look (Azure, AWS) usually wants its own set offered, not the built-in outlines next to it:
251
+
252
+ ```
253
+ icons builtin=hidden
254
+ ```
255
+
256
+ The built-in icons are then left out of the editor's icon picker, `fastdraw preview-look`, `sizes` and `icons`, and a misspelt icon name is answered with the look's own icons. A diagram that already uses a built-in icon (`icon=database`) still draws it, so a diagram can move between looks without breaking. `icons builtin=shown` is the default.
257
+
258
+ Either way:
169
259
 
170
260
  - A file icon keeps its colours; `icon.color=` does not apply to it.
171
- - Files over 300 KB are skipped. Only the icons a diagram uses are carried inside its exported image.
261
+ - Files over 300 KB are skipped.
172
262
  - A file with the same name as a built-in icon replaces it.
173
263
 
174
264
  ### Dark version
@@ -180,7 +270,9 @@ dark night // a look that ships with FastDraw
180
270
  dark "./team-night.look" // a look file, relative to this look file
181
271
  ```
182
272
 
183
- The built-in look's dark version is `night`, and Night names itself, since it is already dark. A dark look should keep the same style names, so the diagram draws the same way in both. Without a `dark` line, `--dark` stops with an error that names the look. To draw one diagram with another look without changing the file, use `fastdraw render x.fdraw --look night` (or `--look ./other.look`).
273
+ The built-in look's dark version is `night`, and every look that ships names its own: `shade` names `shade-dark`, `sketch` names `sketch-dark`, and so on. A dark version names itself, since it is already dark. A dark look should keep the same style names, shapes, sizes and fonts, so the diagram draws the same way in both.
274
+
275
+ The editor and an embedded diagram follow their theme: in the dark theme a diagram is drawn with the look its look's `dark` line names, and the file keeps its look line. The editor's **Look** panel shows each look once, drawn in the version for the theme, and a diagram that names a dark version (`look night`) is drawn in its light look in the light theme. Export image draws either version. Without a `dark` line a look is drawn as it is in both themes, and `--dark` stops with an error that names the look. To draw one diagram with another look without changing the file, use `fastdraw render x.fdraw --look night` (or `--look ./other.look`).
184
276
 
185
277
  ### Guidance
186
278
 
@@ -201,4 +293,4 @@ The built-in look's dark version is `night`, and Night names itself, since it is
201
293
  - Shapes cannot contain extra drawn details beyond the outline, one icon, the tag and the ghost number. The tag's position is fixed. Icons are outlines in one colour.
202
294
  - The background can have dots but not grid lines.
203
295
  - `path` outlines have no arcs (`A`); use curves (`C`, `Q`). Arrows attach to the outline's bounding box.
204
- - Exported images carry the diagram and look but not the font files, so someone reopening an image without the repo sees fallback fonts for any font that is not bundled.
296
+ - Exported images carry the diagram and look but not the files of a font folder, so someone reopening an image without the repo sees the role's shipped font for it. Fonts given by web address are fetched again.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fastdraw",
3
- "version": "0.2.2",
3
+ "version": "0.4.0",
4
4
  "description": "Diagrams that an AI agent writes as text and a person edits on a canvas",
5
5
  "keywords": [
6
6
  "diagram",
@@ -41,6 +41,9 @@
41
41
  "node": ">=20"
42
42
  },
43
43
  "scripts": {
44
+ "rust:data": "node --experimental-strip-types --disable-warning=ExperimentalWarning tools/rust-data.ts",
45
+ "rust:cases": "node --experimental-strip-types --disable-warning=ExperimentalWarning tools/rust-cases.ts > crates/fastdraw-render/tests/geometry.json",
46
+ "rust:parity": "node --experimental-strip-types --disable-warning=ExperimentalWarning tools/rust-parity.ts",
44
47
  "test": "node --disable-warning=ExperimentalWarning --test test/*.test.ts",
45
48
  "dev": "vite",
46
49
  "build:editor": "vite build && vite build -c vite.embed.config.ts --outDir dist-editor --emptyOutDir false",
@@ -49,7 +52,7 @@
49
52
  "build:cli": "esbuild src/cli.ts --bundle --platform=node --format=esm --target=node20 --external:@resvg/resvg-js --banner:js=\"#!/usr/bin/env node\" --outfile=dist/cli.js",
50
53
  "prepack": "npm run build:cli && npm run build:embed",
51
54
  "build:embed": "vite build -c vite.embed.config.ts",
52
- "version": "node tools/syncPluginVersion.ts && git add plugins/fastdraw/.claude-plugin/plugin.json"
55
+ "version": "node tools/syncPluginVersion.ts && git add plugins/fastdraw/.claude-plugin/plugin.json crates/fastdraw-render/Cargo.toml Cargo.lock"
53
56
  },
54
57
  "dependencies": {
55
58
  "@resvg/resvg-js": "^2.6.2"
@@ -14,5 +14,5 @@
14
14
  "sequence",
15
15
  "fdraw"
16
16
  ],
17
- "version": "0.2.2"
17
+ "version": "0.4.0"
18
18
  }
@@ -17,5 +17,6 @@ Run FastDraw's commands as `npx -y fastdraw <command>` (for example `npx -y fast
17
17
  3. Always finish with `fastdraw check <file>` clean and a look at the PNG from `fastdraw render <file>`.
18
18
  4. When the diagram is done, always ask the person what to do next, with your tool for asking a question; do not end your turn without asking. The choices: **Open in fastdraw.dev** (run `fastdraw open <file>` in the background, then read its output and give the person the link it prints, in case no browser window appeared; it saves their edits back to the file), **Preview as PNG** (open the rendered PNG in their image viewer) or **Nothing**. Do not open anything before they choose.
19
19
  5. For a site with light and dark themes, `fastdraw render <file or folder> --dark` writes `x.png` and `x-dark.png` (the look's dark version, Night for the built-in look). Do not copy the file to swap its look line; `--look <name|file.look>` draws with another look. A folder means every `.fdraw` file under it, for `check` too.
20
- 6. When changing an existing diagram, do not move, resize or restyle what is already there unless asked. A person may have arranged it by hand.
21
- 7. For a docs site (a web page, not a GitHub README), put the diagram on the page with `<fastdraw-diagram src="....fdraw">` from https://fastdraw.dev/embed.js, with the rendered PNG inside it as the fallback image. It draws the file live, pannable and zoomable, and follows the page's dark mode.
20
+ 6. When a diagram needs vendor icons (Azure, AWS, Google Cloud, Kubernetes, product logos) or a font that does not ship with FastDraw, add them to the look by their https:// address from the recommended sources in `fastdraw guide look` (`icondir "https://.../{name}.svg"`, `icon lambda "https://..."`, `font sans "Inter" "https://..."`), with a fixed version in the address. Do not download icon or font files into the repo unless the person asks for that or the files are not on the web.
21
+ 7. When changing an existing diagram, do not move, resize or restyle what is already there unless asked. A person may have arranged it by hand.
22
+ 8. For a docs site (a web page, not a GitHub README), put the diagram on the page with `<fastdraw-diagram src="....fdraw">` from https://fastdraw.dev/embed.js, with the rendered PNG inside it as the fallback image. It draws the file live, pannable and zoomable, and follows the page's dark mode.