fastdraw 0.1.0 → 0.2.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/README.md +60 -147
- package/agents/AGENTS-snippet.md +5 -0
- package/agents/README.md +8 -0
- package/agents/claude-skill/fastdraw/SKILL.md +8 -3
- package/dist/cli.js +12408 -275
- package/dist-embed/embed/draw-CFzc4XD7.js +1070 -0
- package/dist-embed/embed/iconSetAll-6ydegXby.js +1 -0
- package/dist-embed/embed.js +35 -0
- package/dist-embed/fonts/Geist-Bold.ttf +0 -0
- package/dist-embed/fonts/Geist-Medium.ttf +0 -0
- package/dist-embed/fonts/Geist-Regular.ttf +0 -0
- package/dist-embed/fonts/Geist-SemiBold.ttf +0 -0
- package/dist-embed/fonts/GeistMono-Medium.ttf +0 -0
- package/dist-embed/fonts/GeistMono-Regular.ttf +0 -0
- package/dist-embed/fonts/InstrumentSerif-Italic.ttf +0 -0
- package/dist-embed/fonts/InstrumentSerif-Regular.ttf +0 -0
- package/dist-embed/fonts/LibreFranklin-Bold.ttf +0 -0
- package/dist-embed/fonts/LibreFranklin-Medium.ttf +0 -0
- package/dist-embed/fonts/LibreFranklin-Regular.ttf +0 -0
- package/dist-embed/fonts/LibreFranklin-SemiBold.ttf +0 -0
- package/dist-embed/fonts/Newsreader-Italic.ttf +0 -0
- package/dist-embed/fonts/Newsreader-Medium.ttf +0 -0
- package/dist-embed/fonts/Newsreader-Regular.ttf +0 -0
- package/dist-embed/fonts/Newsreader-SemiBold.ttf +0 -0
- package/dist-embed/fonts/SketchHand-Regular.ttf +0 -0
- package/fonts/Geist-Bold.ttf +0 -0
- package/fonts/Geist-Variable.woff2 +0 -0
- package/guide/axonometric-plan.md +2 -2
- package/guide/exploded.md +1 -1
- package/guide/guide.md +41 -8
- package/guide/look.md +42 -12
- package/guide/security-matrix.md +4 -4
- package/guide/swimlane.md +61 -5
- package/licenses/phosphor-icons.txt +21 -0
- package/package.json +20 -13
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
function k(t,e,i){return t==="light"||t==="dark"?t:e==="light"||e==="dark"?e:i?"dark":"light"}function w(t){let e=t.dataset.theme;return e==="light"||e==="dark"?e:t.classList.contains("dark")?"dark":t.classList.contains("light")?"light":null}function v(t,e){let i=e?.dark??(t?void 0:"night");return i&&i!==t?i:null}function M(t){let e="";for(let i=0;i<t.length;i+=32768)e+=String.fromCharCode(...t.subarray(i,i+32768));return btoa(e).replace(/\+/g,"-").replace(/\//g,"_").replace(/=+$/,"")}async function A(t,e){let i=new Blob([t]).stream().pipeThrough(e).getReader(),s=[],a=0;for(;;){let{done:r,value:o}=await i.read();if(r)break;if(a+=o.length,a>4e6)throw await i.cancel(),Error("too large");s.push(o)}let n=new Uint8Array(a),h=0;for(let r of s)n.set(r,h),h+=r.length;return n}async function L(t){let e=JSON.stringify(t.look?{name:t.name,text:t.text,look:t.look}:{name:t.name,text:t.text});return M(await A(new TextEncoder().encode(e),new CompressionStream("deflate-raw")))}async function E(t,e){let i=new URL(t);return i.hash="fdraw="+await L(e),i.href}var C=new URL("fonts/",""+import.meta.url).href,f=()=>import("./embed/draw-CFzc4XD7.js"),m=t=>`<svg viewBox="0 0 24 24" aria-hidden="true"><path d="${t}"/></svg>`,u={in:m("M10.5 4a6.5 6.5 0 1 1 0 13a6.5 6.5 0 0 1 0-13zM15.3 15.3 20 20M7.5 10.5h6M10.5 7.5v6"),out:m("M10.5 4a6.5 6.5 0 1 1 0 13a6.5 6.5 0 0 1 0-13zM15.3 15.3 20 20M7.5 10.5h6"),fit:m("M4 9V5.5A1.5 1.5 0 0 1 5.5 4H9M15 4h3.5A1.5 1.5 0 0 1 20 5.5V9M20 15v3.5a1.5 1.5 0 0 1-1.5 1.5H15M9 20H5.5A1.5 1.5 0 0 1 4 18.5V15"),full:m("M14 4h6v6M10 20H4v-6M20 4l-6.5 6.5M4 20l6.5-6.5"),exit:m("M20 10h-6V4M4 14h6v6M14 10l6.5-6.5M10 14l-6.5 6.5"),open:m("M13 4h7v7M20 4l-9 9M17 14v4.5a1.5 1.5 0 0 1-1.5 1.5h-10A1.5 1.5 0 0 1 4 18.5v-10A1.5 1.5 0 0 1 5.5 7H10")},F=`
|
|
2
|
+
:host { display: block; position: relative; }
|
|
3
|
+
:host([hidden]) { display: none; }
|
|
4
|
+
[hidden] { display: none !important; }
|
|
5
|
+
.frame { position: relative; width: 100%; aspect-ratio: var(--fd-ratio, 2); overflow: hidden; outline: none; }
|
|
6
|
+
.frame:fullscreen { width: 100vw; height: 100vh; max-height: none !important; aspect-ratio: auto; }
|
|
7
|
+
.view { position: absolute; inset: 0; touch-action: pan-y; cursor: default; outline: none; }
|
|
8
|
+
.view.pannable { touch-action: none; cursor: grab; }
|
|
9
|
+
.view.dragging { cursor: grabbing; }
|
|
10
|
+
.view:focus-visible { box-shadow: inset 0 0 0 2px #dc2f2f; }
|
|
11
|
+
.view svg { display: block; width: 100%; height: 100%; user-select: none; -webkit-user-select: none; }
|
|
12
|
+
.bar {
|
|
13
|
+
position: absolute; top: 8px; right: 8px; display: flex; align-items: center; gap: 1px; padding: 3px;
|
|
14
|
+
background: rgba(255, 255, 255, 0.94); border: 1px solid #e4e4e7; border-radius: 10px;
|
|
15
|
+
box-shadow: 0 1px 2px rgba(24, 24, 27, 0.06), 0 2px 8px rgba(24, 24, 27, 0.05);
|
|
16
|
+
opacity: 0; transition: opacity 0.15s;
|
|
17
|
+
}
|
|
18
|
+
.frame:hover .bar, .frame:focus-within .bar { opacity: 1; }
|
|
19
|
+
@media (hover: none) { .bar { opacity: 1; } }
|
|
20
|
+
@media (prefers-reduced-motion: reduce) { .bar { transition: none; } }
|
|
21
|
+
.bar button, .bar a {
|
|
22
|
+
all: unset; box-sizing: border-box; display: grid; place-items: center; width: 28px; height: 28px;
|
|
23
|
+
border-radius: 7px; color: #52525b; cursor: pointer;
|
|
24
|
+
}
|
|
25
|
+
.bar button:hover, .bar a:hover { background: #fde3e1; color: #dc2f2f; }
|
|
26
|
+
.bar button:focus-visible, .bar a:focus-visible { outline: 2px solid #dc2f2f; outline-offset: -1px; }
|
|
27
|
+
.bar button:disabled { opacity: 0.35; cursor: default; background: none; color: #52525b; }
|
|
28
|
+
.bar .sep { width: 1px; height: 16px; margin: 0 3px; background: #e4e4e7; }
|
|
29
|
+
.bar svg { width: 16px; height: 16px; fill: none; stroke: currentColor; stroke-width: 1.75; stroke-linecap: round; stroke-linejoin: round; }
|
|
30
|
+
.frame.dark .bar { background: rgba(24, 24, 27, 0.92); border-color: #3f3f46; box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3); }
|
|
31
|
+
.frame.dark .bar button, .frame.dark .bar a { color: #a1a1aa; }
|
|
32
|
+
.frame.dark .bar button:hover, .frame.dark .bar a:hover { background: rgba(255, 107, 95, 0.2); color: #ffb4ab; }
|
|
33
|
+
.frame.dark .bar .sep { background: #3f3f46; }
|
|
34
|
+
.frame.dark .view:focus-visible { box-shadow: inset 0 0 0 2px #ff6b5f; }
|
|
35
|
+
`,S=typeof matchMedia=="function"?matchMedia("(prefers-reduced-motion: reduce)"):null,p=typeof matchMedia=="function"?matchMedia("(prefers-color-scheme: dark)"):null,b=new Set,y=!1;function $(){if(y)return;y=!0;let t=()=>b.forEach(e=>e.themeChanged());new MutationObserver(t).observe(document.documentElement,{attributes:!0,attributeFilter:["data-theme","class"]}),p?.addEventListener("change",t)}var x=class extends HTMLElement{static observedAttributes=["src","theme","max-height","editor"];#x;#s;#i;#m;#c;#l=null;#e=null;#L=null;#d=0;#t={x:0,y:0,k:1};#a=0;#r=0;#o=!0;#u=0;#n=new Map;#b=!1;constructor(){super();let t=this.attachShadow({mode:"open"});t.innerHTML=`<style>${F}</style><div class="fallback"><slot></slot></div><div class="frame" part="frame" hidden><div class="view" part="view" tabindex="0" role="img"></div><div class="bar" part="toolbar" role="toolbar" aria-label="Diagram controls"><button type="button" data-act="in" aria-label="Zoom in" title="Zoom in (+)">${u.in}</button><button type="button" data-act="out" aria-label="Zoom out" title="Zoom out (\u2212)">${u.out}</button><button type="button" data-act="fit" aria-label="Fit to view" title="Fit (0)">${u.fit}</button><button type="button" data-act="full" aria-label="Full screen" title="Full screen">${u.full}</button><span class="sep"></span><a class="open" target="_blank" rel="noopener" aria-label="Open in FastDraw" title="Open in FastDraw">${u.open}</a></div></div>`,this.#x=t.querySelector(".fallback"),this.#s=t.querySelector(".frame"),this.#i=t.querySelector(".view"),this.#m=t.querySelector("a.open"),this.#c=t.querySelector("[data-act=full]"),document.fullscreenEnabled||(this.#c.hidden=!0),t.querySelector(".bar").addEventListener("click",i=>{let s=i.target.closest("button")?.dataset.act;s==="in"?this.zoomBy(1.4):s==="out"?this.zoomBy(1/1.4):s==="fit"?this.fit():s==="full"&&this.#O()}),this.addEventListener("keydown",i=>this.#T(i));let e=this.#i;e.addEventListener("pointerdown",i=>this.#D(i)),e.addEventListener("pointermove",i=>this.#H(i)),e.addEventListener("pointerup",i=>this.#z(i)),e.addEventListener("pointercancel",i=>this.#z(i)),e.addEventListener("wheel",i=>this.#U(i),{passive:!1}),e.addEventListener("dblclick",()=>this.fit()),new ResizeObserver(()=>this.#B()).observe(this.#s),document.addEventListener("fullscreenchange",()=>this.#K())}connectedCallback(){b.add(this),$(),this.#R(),this.#l||this.#E()}disconnectedCallback(){b.delete(this)}attributeChangedCallback(t,e,i){e!==i&&this.isConnected&&(t==="src"?this.#E():t==="theme"?this.themeChanged():t==="max-height"?this.#R():t==="editor"&&this.#$())}get theme(){return k(this.getAttribute("theme"),w(document.documentElement),!!p?.matches)}themeChanged(){this.#l&&this.theme!==this.#L&&this.#C()}async#E(){let t=this.getAttribute("src"),e=++this.#d;if(t)try{let i=await(await f()).fetchSource(new URL(t,document.baseURI).href);if(e!==this.#d)return;this.#l=i,this.#o=!0,await this.#C(),this.#$()}catch(i){e===this.#d&&this.#F(i)}}async#C(){let t=this.#l,e=this.theme,i=++this.#d;try{let s=await(await f()).draw(t,e==="dark",this.getAttribute("fonts")??C);if(i!==this.#d)return;let a=this.#e&&this.#e.w===s.w&&this.#e.h===s.h&&this.#e.x===s.x&&this.#e.y===s.y;this.#e=s,this.#L=e,this.#i.innerHTML=s.svg;let n=this.#i.querySelector("svg");n.removeAttribute("width"),n.removeAttribute("height"),n.setAttribute("preserveAspectRatio","xMidYMid meet"),this.#i.setAttribute("aria-label",this.#I()),this.#s.style.background=s.paper,this.#s.style.setProperty("--fd-ratio",`${s.w} / ${s.h}`),this.#s.classList.toggle("dark",e==="dark"),this.#s.hidden=!1,this.#x.hidden=!0,this.#g(),this.#o||!a?this.#M():this.#h(this.#t),this.dataset.ready="",this.dispatchEvent(new CustomEvent("fastdraw-ready",{detail:{theme:e}}))}catch(s){i===this.#d&&this.#F(s)}}#F(t){console.error(`fastdraw-diagram: could not draw ${this.getAttribute("src")}`,t),this.#e||(this.#s.hidden=!0,this.#x.hidden=!1,this.dispatchEvent(new CustomEvent("fastdraw-error",{detail:{error:t}})))}#I(){return(this.getAttribute("alt")??this.querySelector("img")?.getAttribute("alt"))||`Diagram ${this.#S()}`}#S(){let t=new URL(this.#l?.url??this.getAttribute("src")??"diagram.fdraw",document.baseURI).pathname,e=t.slice(t.lastIndexOf("/")+1)||"diagram.fdraw";try{e=decodeURIComponent(e)}catch{}return e}async#$(){let t=this.#l;if(t)try{this.#m.href=await E(this.getAttribute("editor")||"https://fastdraw.dev/edit/",{name:this.#S(),text:t.text,...t.look?{look:{path:t.look.path,text:t.look.text}}:{}}),this.#m.hidden=!1}catch(e){console.warn("fastdraw-diagram: no link to the editor",e),this.#m.hidden=!0}}#R(){let t=this.getAttribute("max-height");this.#s.style.maxHeight=t?/^\d+(\.\d+)?$/.test(t)?`${t}px`:t:"inherit"}#g(){let t=this.#i.getBoundingClientRect();this.#a=t.width,this.#r=t.height}#f(){return this.#a/this.#e.w}#p(){let t=this.#e;return Math.min(this.#a/t.w,this.#r/t.h)}#k(){let t=this.#p();return{min:Math.min(t,this.#f())*.75,max:Math.max(this.#f()*8,4)}}#q(t){let e=this.#e,{min:i,max:s}=this.#k(),a=Math.min(s,Math.max(i,t.k)),n=this.#a/a,h=this.#r/a,r=(o,l,d,c)=>d<=c?l+d/2-c/2:Math.min(l+d-c,Math.max(l,o));return{k:a,x:r(t.x,e.x,e.w,n),y:r(t.y,e.y,e.h,h)}}#h(t){if(!this.#e||!this.#a||!this.#r)return;this.#t=this.#q(t);let{x:e,y:i,k:s}=this.#t,a=this.#e;this.#i.querySelector("svg")?.setAttribute("viewBox",`${e} ${i} ${this.#a/s} ${this.#r/s}`);let n=a.w*s>this.#a+.5||a.h*s>this.#r+.5;this.#i.classList.toggle("pannable",n);let{min:h,max:r}=this.#k();this.shadowRoot.querySelector("[data-act=in]").disabled=s>=r-1e-6,this.shadowRoot.querySelector("[data-act=out]").disabled=s<=h+1e-6}#w(t){cancelAnimationFrame(this.#u);let e=this.#q(t);if(S?.matches){this.#h(e);return}let i={...this.#t},s=performance.now(),a=n=>{let h=Math.min(1,(n-s)/180),r=1-(1-h)**3,o=i.k*(e.k/i.k)**r,l=(e.x-i.x)/(1/e.k-1/i.k||1),d=(e.y-i.y)/(1/e.k-1/i.k||1),c=Math.abs(e.k-i.k)>1e-9;this.#h(c?{k:o,x:i.x+l*(1/o-1/i.k),y:i.y+d*(1/o-1/i.k)}:{k:o,x:i.x+(e.x-i.x)*r,y:i.y+(e.y-i.y)*r}),h<1&&(this.#u=requestAnimationFrame(a))};this.#u=requestAnimationFrame(a)}#v(t,e,i,s=!1){let a=this.#t,{min:n,max:h}=this.#k(),r=Math.min(h,Math.max(n,t)),o={k:r,x:a.x+e/a.k-e/r,y:a.y+i/a.k-i/r};this.#o=!1,s?this.#w(o):this.#h(o)}#M(){this.#e&&(this.#o=!0,cancelAnimationFrame(this.#u),this.#y()?this.#h({k:this.#p(),x:0,y:0}):this.#h({k:this.#f(),x:this.#e.x,y:this.#e.y}))}zoomBy(t){this.#e&&this.#v(this.#t.k*t,this.#a/2,this.#r/2,!0)}fit(){this.#e&&(this.#o=!this.#y()&&this.#p()>=this.#f()-1e-6,this.#w({k:this.#p(),x:0,y:0}))}get zoom(){return this.#t.k}#B(){if(!this.#e)return;let t=this.#t.x+this.#a/2/this.#t.k,e=this.#t.y+this.#r/2/this.#t.k;this.#g(),this.#o?this.#M():this.#h({k:this.#t.k,x:t-this.#a/2/this.#t.k,y:e-this.#r/2/this.#t.k})}#A(t){let e=this.#i.getBoundingClientRect();return{x:t.clientX-e.left,y:t.clientY-e.top}}#D(t){!this.#e||t.pointerType==="mouse"&&t.button!==0||(this.#i.setPointerCapture(t.pointerId),this.#n.set(t.pointerId,this.#A(t)),this.#b=!1,cancelAnimationFrame(this.#u))}#H(t){let e=this.#n.get(t.pointerId);if(!e)return;let i=this.#A(t);if(this.#n.size===1){if(!this.#b&&Math.hypot(i.x-e.x,i.y-e.y)<3)return;this.#b=!0,this.#i.classList.add("dragging"),this.#o=!1,this.#h({k:this.#t.k,x:this.#t.x-(i.x-e.x)/this.#t.k,y:this.#t.y-(i.y-e.y)/this.#t.k}),this.#n.set(t.pointerId,i);return}let[s,a]=[...this.#n.entries()].slice(0,2).map(([c,g])=>c===t.pointerId?i:g),[n,h]=[...this.#n.values()].slice(0,2),r=Math.hypot(h.x-n.x,h.y-n.y),o=Math.hypot(a.x-s.x,a.y-s.y),l={x:(n.x+h.x)/2,y:(n.y+h.y)/2},d={x:(s.x+a.x)/2,y:(s.y+a.y)/2};this.#n.set(t.pointerId,i),r&&(this.#b=!0,this.#v(this.#t.k*(o/r),l.x,l.y),this.#h({k:this.#t.k,x:this.#t.x-(d.x-l.x)/this.#t.k,y:this.#t.y-(d.y-l.y)/this.#t.k}))}#z(t){this.#n.delete(t.pointerId),this.#n.size||this.#i.classList.remove("dragging")}#U(t){if(!this.#e||!(t.ctrlKey||t.metaKey))return;t.preventDefault();let e=t.deltaY*(t.deltaMode===1?16:t.deltaMode===2?this.#r:1),i=this.#A(t);this.#v(this.#t.k*Math.exp(-Math.max(-60,Math.min(60,e))*.006),i.x,i.y)}#T(t){if(!this.#e||t.ctrlKey||t.metaKey||t.altKey)return;let e={ArrowLeft:[-1,0],ArrowRight:[1,0],ArrowUp:[0,-1],ArrowDown:[0,1]};if(t.key==="+"||t.key==="=")this.zoomBy(1.4);else if(t.key==="-"||t.key==="_")this.zoomBy(1/1.4);else if(t.key==="0")this.fit();else if(e[t.key]&&t.composedPath()[0]===this.#i&&this.#i.classList.contains("pannable"))this.#o=!1,this.#w({k:this.#t.k,x:this.#t.x+e[t.key][0]*60/this.#t.k,y:this.#t.y+e[t.key][1]*60/this.#t.k});else return;t.preventDefault()}#y(){return this.shadowRoot.fullscreenElement===this.#s}#O(){this.#y()?document.exitFullscreen().catch(()=>{}):this.#s.requestFullscreen().catch(t=>console.warn("fastdraw-diagram: full screen was refused",t))}#K(){let t=this.#y();this.#c.innerHTML=t?u.exit:u.full,this.#c.setAttribute("aria-label",t?"Leave full screen":"Full screen"),this.#c.title=t?"Leave full screen (Esc)":"Full screen",this.#e&&requestAnimationFrame(()=>{this.#g(),this.#M()})}};typeof customElements<"u"&&!customElements.get("fastdraw-diagram")&&customElements.define("fastdraw-diagram",x);export{x as FastDrawDiagram,v as t};
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
@@ -16,7 +16,7 @@ A box from `x0,y0` to `x1,y1`, standing from z to z+h, has four top corners: A (
|
|
|
16
16
|
|
|
17
17
|
```
|
|
18
18
|
// desk: 24,28 to 68,52, z 6 to 16 · origin 450,142
|
|
19
|
-
polygon at 422,152 points=24,0;68,22;68,32;44,44;0,22;0,12 fill
|
|
19
|
+
polygon at 422,152 points=24,0;68,22;68,32;44,44;0,22;0,12 fill=card stroke=ink sw=1 overlap=ok // silhouette A B Bb Cb Db D
|
|
20
20
|
polygon at 422,164 points=0,0;44,22;44,32;0,10 fill=ink/0.07 stroke=none overlap=ok mask=0 // left face: D C Cb Db
|
|
21
21
|
polygon at 466,174 points=0,12;24,0;24,10;0,22 fill=ink/0.15 stroke=none overlap=ok mask=0 // right face: C B Bb Cb
|
|
22
22
|
polygon at 422,164 points=0,0;44,22;44,32;44,22;68,10 open=1 stroke=ink/0.55 sw=0.8 overlap=ok // inner edges: D C Cb C B
|
|
@@ -40,7 +40,7 @@ One room or one building: the accent floor tint and an accent tag. Its furniture
|
|
|
40
40
|
|
|
41
41
|
## Text
|
|
42
42
|
|
|
43
|
-
- Each room is named by a tag: `rect "Kitchen" sub="café, lockers" at 456,300 96x32 radius=2 fill
|
|
43
|
+
- Each room is named by a tag: `rect "Kitchen" sub="café, lockers" at 456,300 96x32 radius=2 fill=card stroke=ink/0.12 sw=0.8 title.size=12 sub.size=8 overlap=ok`. The focal tag has `stroke=accent title.color=accent sub.color=accent`. Tags are level, never tilted onto the floor, and written after every box so no wall cuts them. One or two words per name.
|
|
44
44
|
- A tag goes on open floor inside its room: project a floor point (z=6), centre the 96x32 tag on it. Accept the spot only if the whole tag rectangle lies inside the slab outline and does not touch the silhouette of any box (tall boxes in front of the spot reach 2h units up the screen) or another tag. Step the point in 5-unit moves until it passes; a script can test the rectangle's corners and edge midpoints with a point-in-polygon check. On a 300x200 plan with two furnished rooms there is room for about one spot per room.
|
|
45
45
|
- When no spot passes (a small plan, a crowded room, a building tag that would sit on furniture), put the tag outside the slab: a 6x6 dot (`ellipse ... fill=ink stroke=none overlap=ok`) on the floor point, a level leader to the tag (`px,py -- tagright,py stroke=ink/0.4 sw=0.8 layer=front`) and the tag 12px beyond the slab's left corner (`ox - Y`) or right corner (`ox + X`), at the same height as the dot. Pick a height where the leader crosses no tall box. A building's tag may instead sit on its roof.
|
|
46
46
|
|
package/guide/exploded.md
CHANGED
|
@@ -10,7 +10,7 @@ FastDraw has no 3D. A plate is four `rect`s with the same `at` and size, each wi
|
|
|
10
10
|
// title at y=52. One plate: a square slab with rounded corners, 384 wide and 208 high on screen (16 of that is its thickness).
|
|
11
11
|
// This is the bottom one of three: y = 96 + 116 * 2
|
|
12
12
|
title: text "What the thermostat is made of" at 40,52 style=h1
|
|
13
|
-
data: rect at 208,328 384x208 fill
|
|
13
|
+
data: rect at 208,328 384x208 fill=card stroke=ink sw=1.2 overlap=ok shape=path
|
|
14
14
|
path="M0,0.462 Q0.003,0.442 0.013,0.433 L0.469,0.029 Q0.5,0 0.531,0.029 L0.987,0.433 Q0.997,0.442 1,0.462 L1,0.538 Q0.997,0.558 0.987,0.567 L0.531,0.971 Q0.5,1 0.469,0.971 L0.013,0.567 Q0.003,0.558 0,0.538 Z"
|
|
15
15
|
rect at 208,328 384x208 fill=ink/0.07 stroke=none overlap=ok mask=0 shape=path // left face, lit
|
|
16
16
|
path="M0,0.462 Q0.003,0.481 0.013,0.49 L0.469,0.894 Q0.484,0.909 0.5,0.909 L0.5,0.986 Q0.484,0.986 0.469,0.971 L0.013,0.567 Q0.003,0.558 0,0.538 Z"
|
package/guide/guide.md
CHANGED
|
@@ -4,24 +4,54 @@ FastDraw draws diagrams from a small text file (`.fdraw`). You place every eleme
|
|
|
4
4
|
|
|
5
5
|
## How to work
|
|
6
6
|
|
|
7
|
-
1.
|
|
8
|
-
2.
|
|
9
|
-
3. Run `fastdraw
|
|
7
|
+
1. To create or change a look (how styles are drawn), run `fastdraw guide look` instead of the steps below.
|
|
8
|
+
2. Choose the kind of diagram as described in "Choosing the kind" below (`fastdraw guide list` says what each kind shows), and agree it with the person before drawing. If the kind has its own guide, run `fastdraw guide <kind>` and follow it; where it differs from the general rules in this guide, the kind's guide wins.
|
|
9
|
+
3. Run `fastdraw sizes <look file>` to see the styles you can use, their default sizes, and the look's own guidance. Follow that guidance. A diagram with no `look` line uses the built-in look: run `fastdraw sizes` with no file to see it.
|
|
10
10
|
4. Plan the composition on paper first: rows and columns, where the main thing sits.
|
|
11
|
-
5. Write the file.
|
|
11
|
+
5. Write the file. A new diagram goes in `docs/diagrams/` (create the folder) unless the person names another place or the repo already keeps its `.fdraw` files somewhere. Never put it at the top of the repo: `fastdraw open` lends the diagram's whole folder to the editor.
|
|
12
12
|
6. Run `fastdraw check <file>`. Fix every error and warning. Read the hints and fix the ones that are real.
|
|
13
13
|
7. Run `fastdraw render <file>` and **look at the PNG**. Fix what looks wrong: cramped labels, uneven gaps, lopsided composition, a label sitting on a border. Repeat from 6 until it is clean and looks good.
|
|
14
|
-
8.
|
|
14
|
+
8. When the diagram is done, tell the person where the file is and **ask what they want to do next**, with these three choices (use your tool for asking a question if you have one). Always ask; do not stop without it.
|
|
15
|
+
- **Open in fastdraw.dev**: run `fastdraw open <file>` in the background. It opens the web editor at the diagram, with its look, and saves their edits into the same file. Read its output and give the person the link it prints, in case no browser window appeared. Read the file again before you change it after that.
|
|
16
|
+
- **Preview as PNG**: open the PNG from `fastdraw render` in their image viewer (`xdg-open <file.png>` on Linux, `wslview` or `explorer.exe` under WSL, `open` on macOS, `start ""` on Windows).
|
|
17
|
+
- **Nothing**: stop there.
|
|
18
|
+
|
|
19
|
+
Do not open anything before they choose.
|
|
15
20
|
|
|
16
21
|
When you change an existing diagram: do not move, resize or restyle anything that is already there unless asked. Place only what you add, in free space.
|
|
17
22
|
|
|
23
|
+
## Choosing the kind
|
|
24
|
+
|
|
25
|
+
Choose by what the reader has to understand, not by a word in the request: a "request flow" or a "user flow" is not a flowchart. `fastdraw guide list` says what every kind shows. The usual choices:
|
|
26
|
+
|
|
27
|
+
| The reader has to see | Kind |
|
|
28
|
+
|---|---|
|
|
29
|
+
| how a request moves through the parts of a system, step by step | `swimlane` with columns; `sequence` when the exact messages and replies matter; `architecture` when the parts and their connections matter more than the order |
|
|
30
|
+
| decisions: yes/no questions and where each answer leads | `flowchart` |
|
|
31
|
+
| work passing between people or teams | `swimlane` with rows; `process` when inputs, outputs and tools matter |
|
|
32
|
+
| the parts of a system and what talks to what | `architecture`; where it runs: `deployment`; what plugs into a platform: `integration` |
|
|
33
|
+
| a change to a system, before and after | `architecture-delta` |
|
|
34
|
+
| data moving through a pipeline | `data-flow`; storage tiers: `medallion`; a whole data stack: `high-level` |
|
|
35
|
+
| the states one thing goes through | `state` |
|
|
36
|
+
| events in order, or a plan | `timeline`; `gantt` |
|
|
37
|
+
| a hierarchy | `tree`; owners: `org-chart`; containment: `nested`; stacked levels: `layers` |
|
|
38
|
+
| a data model | `er`; real tables: `db-schema`; classes: `uml-class` |
|
|
39
|
+
| numbers | `bar`, `line`, `scatter`, `heatmap`, `sankey`, `treemap`, `waterfall` |
|
|
40
|
+
|
|
41
|
+
- Name at least two kinds that could fit before you pick. When two fit, pick the one whose main axis is what the person asked about: order over time, structure, or decisions.
|
|
42
|
+
- Draw a flowchart only when there are real yes/no questions. Steps in a row with no decision are a swimlane, or a process.
|
|
43
|
+
- If a three-column table would say the same thing, write the table instead.
|
|
44
|
+
|
|
45
|
+
**Agree the kind before drawing.** Unless the request already names it ("a sequence diagram of..."), tell the person in one short message which kind you would draw and the closest other kind, with a line on what each shows, and ask which they want (use your tool for asking a question if you have one, your pick first). If you cannot ask, draw your pick and say which other kind would also have worked.
|
|
46
|
+
|
|
18
47
|
## The file
|
|
19
48
|
|
|
20
49
|
One statement per line. An indented line continues the statement above it. `//` starts a comment; so does a line starting with `# `.
|
|
21
50
|
|
|
22
51
|
```
|
|
23
52
|
look "./team.look" // path relative to this file; leave the line out to use the built-in look
|
|
24
|
-
// or a look that ships with FastDraw: look headline | reference | sketch | whiteboard
|
|
53
|
+
// or a look that ships with FastDraw: look headline | night | reference | sketch | whiteboard | shade | engraved | keys | transit | offset | listing
|
|
54
|
+
// for a dark theme, keep the line and run fastdraw render x.fdraw --dark to get x-dark.png too
|
|
25
55
|
canvas paper=#ffffff dots=none dotgap=24 // optional: changes the look's background for this diagram only
|
|
26
56
|
|
|
27
57
|
// shape: id: style "text" at x,y WxH key=value ...
|
|
@@ -162,13 +192,14 @@ An arrow can end on a row: `orders.user_id -- users.id`. It attaches to the left
|
|
|
162
192
|
|
|
163
193
|
### Icons
|
|
164
194
|
|
|
165
|
-
`icon=name` puts a small
|
|
195
|
+
`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`.
|
|
166
196
|
|
|
167
197
|
- 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.
|
|
168
198
|
- With no text, the icon fills the box.
|
|
169
199
|
- 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.
|
|
170
200
|
- `icon.size=20` and `icon.color=link` change it; by default it takes the colour of the box's text.
|
|
171
|
-
- `icon.fill=accent/0.2`
|
|
201
|
+
- `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.
|
|
202
|
+
- `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.
|
|
172
203
|
- 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.
|
|
173
204
|
- 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.
|
|
174
205
|
|
|
@@ -232,6 +263,8 @@ Labels are drawn in small caps on a paper-coloured patch, above a horizontal lin
|
|
|
232
263
|
|
|
233
264
|
`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).
|
|
234
265
|
|
|
266
|
+
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`.
|
|
267
|
+
|
|
235
268
|
### Legend
|
|
236
269
|
|
|
237
270
|
One statement draws a whole legend: a rule line, a heading, and one entry per style, spaced and wrapped for you.
|
package/guide/look.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
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
|
-
|
|
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.
|
|
6
6
|
|
|
7
7
|
## How to work
|
|
8
8
|
|
|
@@ -13,7 +13,7 @@ Four looks ship with FastDraw and need no file: `look headline`, `look reference
|
|
|
13
13
|
|
|
14
14
|
Keep the style names from the built-in look (`node`, `focal`, `store`, `cloud`, `external`, `optional`, `step`, `terminal`, `terminal-focal`, `decision`, `zone`, `bar`, `arrow`, `primary`, `link`, `return`, `lifeline`, `rule`, `h1`, `eyebrow`, `caption`, `note`, `small`). The diagram guides and existing diagrams use those names. You may add more styles of your own.
|
|
15
15
|
|
|
16
|
-
The looks that ship with FastDraw all define the same styles (the ones above plus `kicker`, `dek`, `legend`, `table`, `matrix`, `chart`, `relation`, `sticky`, `sticky-orange` and `sticky-violet`), so a diagram can move between them without a style going plain. A test holds them to that: after editing one in `looks/`, run `node tools/bundle-looks.mjs`.
|
|
16
|
+
The looks that ship with FastDraw all define the same styles (the ones above plus `kicker`, `dek`, `legend`, `table`, `matrix`, `chart`, `relation`, `sticky`, `sticky-orange` and `sticky-violet`), so a diagram can move between them without a style going plain. A test holds them to that: after editing one in `looks/`, run `node tools/bundle-looks.mjs`. The six style looks are written by `tools/gen-style-looks.py`; change them there.
|
|
17
17
|
|
|
18
18
|
## The file
|
|
19
19
|
|
|
@@ -22,6 +22,9 @@ One statement per line; an indented line continues the one above; `//` starts a
|
|
|
22
22
|
```
|
|
23
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
|
|
24
24
|
// sketch=1 draws every outline and line by hand (2 is rougher); see looks/sketch.look
|
|
25
|
+
// bars=colour stripes the page like listing paper (bargap= is the stripe height), feed=colour adds
|
|
26
|
+
// sprocket holes down both edges, grain=0.5 lays paper grain over everything (0 to 1)
|
|
27
|
+
// tint=hue or tint=alpha: how colour/opacity tints mix (see Colours)
|
|
25
28
|
|
|
26
29
|
color paper #ffffff // a named colour
|
|
27
30
|
color ink #1c1f2a
|
|
@@ -43,7 +46,9 @@ guidance "Use focal on at most two things in one diagram."
|
|
|
43
46
|
|
|
44
47
|
### Colours
|
|
45
48
|
|
|
46
|
-
A colour value is `#hex`, a name defined with `color`, or either followed by `/opacity`: `ink/0.3`, `#ffffff/0.85`. `none` means no fill or no stroke. Define `paper`, `ink` and `muted` at least; built-in parts fall back to those names.
|
|
49
|
+
A colour value is `#hex`, a name defined with `color`, or either followed by `/opacity`: `ink/0.3`, `#ffffff/0.85`. `none` means no fill or no stroke. Define `paper`, `ink` and `muted` at least; built-in parts fall back to those names. `card` is the fill of a plain box (white unless a look sets it; a dark look sets it to its box colour), so a diagram that writes `fill=card` stays right in every look.
|
|
50
|
+
|
|
51
|
+
On a light page a tint such as `amber/0.1` is the colour at that opacity over what is underneath. On a dark page that blend loses the hue: 10% of amber over navy is grey. So when `paper` is dark, a tint of a coloured colour is mixed so it keeps its hue: it gets lighter and takes on the tint's colour as if the page were neutral grey, and stays see-through. `amber/0.1` on Night is a dark amber, the counterpart of the pale amber on the built-in look, so one diagram reads in both. Tints of greys (`ink/0.06`) are blended as before. `canvas tint=alpha` turns this off for a dark look; `canvas tint=hue` turns it on for a light one.
|
|
47
52
|
|
|
48
53
|
### Fonts
|
|
49
54
|
|
|
@@ -59,6 +64,7 @@ font sans "Fira Sans"
|
|
|
59
64
|
- 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.
|
|
60
65
|
- 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.
|
|
61
66
|
- 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.
|
|
62
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.
|
|
63
69
|
|
|
64
70
|
### Styles
|
|
@@ -79,16 +85,25 @@ font sans "Fira Sans"
|
|
|
79
85
|
| `size=WxH` | default size when a diagram gives none |
|
|
80
86
|
| `fill=`, `stroke=`, `sw=`, `dash=5,4` | fill colour, stroke colour, stroke width, dash pattern |
|
|
81
87
|
| `hatch=colour` | fill with diagonal pencil lines on top of `fill=`; `hatch.gap=` spaces them, `hatch.sw=` weighs them |
|
|
88
|
+
| `halftone=colour` | fill with a field of printed dots; `halftone.gap=` spaces them, `halftone.r=` sizes them |
|
|
89
|
+
| `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
|
+
| `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 |
|
|
91
|
+
| `inner=colour` | a second, finer rule just inside the outline; `inner.gap=` (default 3.5) and `inner.sw=` |
|
|
92
|
+
| `corners=plus` | a mark on each corner of a box: `plus` or `square`; `corners.color=`, `corners.size=` |
|
|
93
|
+
| `offset=dx,dy` | print the fill that far out of register with the outline |
|
|
94
|
+
| `blend=multiply` | let this style's ink darken what it overlaps, like overprinting (also on line and text styles) |
|
|
82
95
|
| `sketch=0` | with `canvas sketch=` on: draw this style with clean lines (works on line styles too) |
|
|
83
96
|
| `layer=back` | draw behind everything (for regions like `zone`) |
|
|
84
|
-
| `title.*` | the main text: `title.font`, `title.size`, `title.weight`, `title.color`, `title.italic=1`, `title.spacing` (in em), `title.caps=1`; `title.pos=top` puts it as a small caption at the top edge |
|
|
97
|
+
| `title.*` | the main text: `title.font`, `title.size`, `title.weight`, `title.color`, `title.italic=1`, `title.spacing` (in em), `title.caps=1`; `title.pos=top` puts it as a small caption at the top edge, `title.dy=` moves that caption up or down and `title.fill=` colours the patch behind it (`none` for no patch) |
|
|
85
98
|
| `sub.*` | the second line (`sub=` on an element): `sub.font`, `sub.size`, `sub.color` |
|
|
86
99
|
| `tag.*` | the corner marker (`tag=`): `tag.color`, `tag.border`, `tag.font`, `tag.size` |
|
|
87
100
|
| `ghost.*` | the big faint number (`ghost=`): `ghost.color`, `ghost.size` |
|
|
88
101
|
|
|
89
|
-
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.
|
|
102
|
+
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
|
+
|
|
104
|
+
Keep type close to the built-in look's sizes (12px titles, 9px second lines, 10px line labels). Diagrams are laid out for those, so larger type overflows boxes that fit before.
|
|
90
105
|
|
|
91
|
-
The tag sits 8px in from the top-left corner and is 12px tall, so keep a path's details (a cylinder rim) out of the top 20px or flatten them. A `title.pos=top` caption is centred on the top edge with a paper-coloured
|
|
106
|
+
The tag sits 8px in from the top-left corner and is 12px tall, so keep a path's details (a cylinder rim) out of the top 20px or flatten them. A `title.pos=top` caption is centred on the top edge with a patch behind it, 6px wider than the words on each side. A patch that crosses the outline is paper-coloured, so the edge stops at the words; one that sits inside the shape takes the shape's own fill, so it hides the page dots behind the words and is otherwise invisible.
|
|
92
107
|
|
|
93
108
|
**Table styles** (`shape=table`) use `fill`, `stroke`, `sw`, `radius`, `dash` and `title.*` like any box, plus:
|
|
94
109
|
|
|
@@ -121,10 +136,14 @@ The tag sits 8px in from the top-left corner and is 12px tall, so keep a path's
|
|
|
121
136
|
| `route=` | `ortho` (right-angle turns), `straight`, or `curve` (a smooth line) |
|
|
122
137
|
| `radius=` | corner radius of the turns |
|
|
123
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 |
|
|
124
|
-
| `tail=` | a marker for the start of the line, if the style always has one |
|
|
125
|
-
| `
|
|
139
|
+
| `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
|
+
| `head.size=` | scale the arrowhead, for a wide line (1 is the default; 0.5 to 4) |
|
|
141
|
+
| `cap=round` | round the ends and corners of the line |
|
|
142
|
+
| `casing=colour` | a wider line of that colour underneath, so lines that cross stay apart; `casing.width=` is how far it shows on each side |
|
|
143
|
+
| `double=colour` | a finer line of that colour on top, which turns a wide line into two rails; `double.sw=` |
|
|
144
|
+
| `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=`) |
|
|
126
145
|
|
|
127
|
-
**Text styles** (`style name text ...`): `font=`, `size=`, `weight=`, `color=`, `italic=1`, `spacing=`, `caps=1`.
|
|
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).
|
|
128
147
|
|
|
129
148
|
### Built-in styles you can restyle
|
|
130
149
|
|
|
@@ -132,13 +151,13 @@ The tag sits 8px in from the top-left corner and is 12px tall, so keep a path's
|
|
|
132
151
|
|
|
133
152
|
### Icons
|
|
134
153
|
|
|
135
|
-
Every look starts with a set of
|
|
154
|
+
Every look starts with a set of built-in icons (see `fastdraw sizes`), each as an outline, solid or duotone: about 130 with friendly names, and every other Phosphor icon under Phosphor's own name (`anchor`, `acorn`; `fastdraw icons <word>` finds them; a Phosphor name that a friendly name already uses, such as `book`, is `ph-book`). Add your own, or replace one, with
|
|
136
155
|
|
|
137
156
|
```
|
|
138
157
|
icon queue "M4 6h16" "M4 12h16" "M4 18h16"
|
|
139
158
|
```
|
|
140
159
|
|
|
141
|
-
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
|
|
160
|
+
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.
|
|
142
161
|
|
|
143
162
|
**Colour icons and vendor sets** go in a folder of SVG files next to the look:
|
|
144
163
|
|
|
@@ -152,13 +171,24 @@ Every `.svg` file directly in that folder becomes an icon, drawn exactly as the
|
|
|
152
171
|
- Files over 300 KB are skipped. Only the icons a diagram uses are carried inside its exported image.
|
|
153
172
|
- A file with the same name as a built-in icon replaces it.
|
|
154
173
|
|
|
174
|
+
### Dark version
|
|
175
|
+
|
|
176
|
+
`dark` names the look that draws the same diagrams on a dark page. `fastdraw render x.fdraw --dark` writes `x.png` with the diagram's look and `x-dark.png` with the look its `dark` line names, for a site that shows one or the other with the reader's theme.
|
|
177
|
+
|
|
178
|
+
```
|
|
179
|
+
dark night // a look that ships with FastDraw
|
|
180
|
+
dark "./team-night.look" // a look file, relative to this look file
|
|
181
|
+
```
|
|
182
|
+
|
|
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`).
|
|
184
|
+
|
|
155
185
|
### Guidance
|
|
156
186
|
|
|
157
187
|
`guidance "..."` lines are shown to agents by `fastdraw sizes`. Use them for rules a drawing tool cannot enforce: how many accent elements are allowed, when to use `tag=`, what `sub=` is for.
|
|
158
188
|
|
|
159
189
|
## What makes a look good
|
|
160
190
|
|
|
161
|
-
- **On dark paper,
|
|
191
|
+
- **On dark paper, tints are quiet.** A tint (`accent/0.15`) keeps its hue but stays dark; for the one thing that must stand out, a solid accent with dark text on it is clearer.
|
|
162
192
|
- **Decide the accent first.** One colour carries the focus (`focal`, `terminal-focal`, `primary`). Everything else is ink, greys and paper. A look with three bright colours has no focus.
|
|
163
193
|
- **Separate by more than colour.** `external`, `optional`, `cloud` and `store` should differ in shape, fill or dash, so they read in greyscale and for colour-blind readers.
|
|
164
194
|
- **Two or three stroke weights at most**, and the accent arrow slightly heavier than the default arrow.
|
package/guide/security-matrix.md
CHANGED
|
@@ -9,12 +9,12 @@ Title at 40,52 (`style=h1`); the header row starts at y=96. A `table`/`matrix` w
|
|
|
9
9
|
```
|
|
10
10
|
// columns: labels at x=40 (200 wide), then one per role: x = 248 + 144*j, 136 wide
|
|
11
11
|
// rows: header at y=96 (52 high), then y = 160 + 40*k, 36 high
|
|
12
|
-
corner: rect "Component" sub="vs. AD group" at 40,96 200x52 radius=6 fill
|
|
12
|
+
corner: rect "Component" sub="vs. AD group" at 40,96 200x52 radius=6 fill=card stroke=ink/0.12 title.size=11
|
|
13
13
|
r1: rect "Data Engineer" sub="GRP-DATA-ENG" at 248,96 136x52 radius=6 fill=ink/0.07 stroke=none title.weight=700 sub.color=muted title.size=11
|
|
14
14
|
|
|
15
|
-
c1: rect "Object storage" at 40,160 200x36 radius=4 fill
|
|
15
|
+
c1: rect "Object storage" at 40,160 200x36 radius=4 fill=card stroke=ink/0.12 title.size=11 title.align=left
|
|
16
16
|
text "S3" at 228,181 style=small anchor=end
|
|
17
|
-
c11: rect "Write" at 248,160 136x36 radius=4 title.size=10 title.weight=400 stroke=ink/0.12 fill
|
|
17
|
+
c11: rect "Write" at 248,160 136x36 radius=4 title.size=10 title.weight=400 stroke=ink/0.12 fill=card
|
|
18
18
|
```
|
|
19
19
|
|
|
20
20
|
Four levels, and only four. The cell text is free ("SELECT", "Login", "R/W"); the look of the cell comes from the level it belongs to:
|
|
@@ -22,7 +22,7 @@ Four levels, and only four. The cell text is free ("SELECT", "Login", "R/W"); th
|
|
|
22
22
|
| Level | Add to the cell |
|
|
23
23
|
|---|---|
|
|
24
24
|
| Full / admin | `fill=ink/0.12 title.weight=600` |
|
|
25
|
-
| Read and write | `fill
|
|
25
|
+
| Read and write | `fill=card title.weight=400` |
|
|
26
26
|
| Read only | `fill=muted/0.08 title.color=muted title.weight=400` |
|
|
27
27
|
| No access | `fill=none title.color=soft title.weight=400` |
|
|
28
28
|
|
package/guide/swimlane.md
CHANGED
|
@@ -1,8 +1,17 @@
|
|
|
1
1
|
# Swimlane diagrams
|
|
2
2
|
|
|
3
|
-
Shows a process that passes between people or
|
|
3
|
+
Shows a process that passes between people, teams or parts of a system: who does each step, and where the work changes hands.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Rows or columns
|
|
6
|
+
|
|
7
|
+
Pick one before you start:
|
|
8
|
+
|
|
9
|
+
- **Columns** (one vertical lane per actor, time running down): for a request or call path through a system, such as browser, gateway, services and stores, or for any flow where each step hands over to the next. It reads top to bottom like a sequence diagram but keeps a box for each step. See "Columns" at the end.
|
|
10
|
+
- **Rows** (one horizontal lane per actor, time running right): for a business process between people or teams, where an actor often does several steps in a row.
|
|
11
|
+
|
|
12
|
+
## Rows
|
|
13
|
+
|
|
14
|
+
### Lanes
|
|
6
15
|
|
|
7
16
|
One horizontal lane per actor, in the order they first act. The look has no lane style; draw lanes with plain lines (`--`) and text. Title at `40,52` (`style=h1`); the first lane line is y=96. Lanes are 112px tall: lane k (from 0) has its top line at `y = 96 + 112k`. (Tall lanes leave a 64px vertical handoff, long enough for a head and a label.)
|
|
8
17
|
|
|
@@ -17,7 +26,7 @@ text "Reviewer" at 60,268 style=eyebrow // baseline 60px under the lane's top l
|
|
|
17
26
|
- All lanes have the same height. The name column is 120px wide (x 40 to 160). Every lane has a name; keep it to about 14 characters.
|
|
18
27
|
- Three to five lanes. With more, merge actors that never act separately. The lines run as far right as the steps need (x=960 above), all to the same x.
|
|
19
28
|
|
|
20
|
-
|
|
29
|
+
### Steps
|
|
21
30
|
|
|
22
31
|
- A step is a `node` written `120x48` (the default 144x64 does not fit the lane), placed 32px under its lane's top line, so it is centred in the lane. Widths 120 to 136; 80 for a one-word step. Main text is the action; `sub=` (small sans) is the tool or detail.
|
|
23
32
|
- A step belongs to one lane. Never stretch a step across two.
|
|
@@ -27,7 +36,7 @@ text "Reviewer" at 60,268 style=eyebrow // baseline 60px under the lane's top l
|
|
|
27
36
|
- Lanes need not have the same number of steps. A lane with one step is fine.
|
|
28
37
|
- The step the process exists to reach gets `focal`.
|
|
29
38
|
|
|
30
|
-
|
|
39
|
+
### Arrows
|
|
31
40
|
|
|
32
41
|
- Arrows inside a lane are plain, straight and unlabelled.
|
|
33
42
|
- Arrows that cross a lane line are the handoffs, the point of the diagram. Label them. The handoff that costs most (waiting, coupling, an approval) uses `style=primary`.
|
|
@@ -35,6 +44,53 @@ text "Reviewer" at 60,268 style=eyebrow // baseline 60px under the lane's top l
|
|
|
35
44
|
- A label on a segment that crosses a lane line lands on that line, and `check` reports it. Move it into the gap above the line with `lpos=x,y`: x is the segment's x plus 12 plus half the label's width (a label is about 5px wide per character), y is the lane line minus 6. This holds for a vertical handoff and for the vertical leg of an elbow alike. A label on a horizontal leg sits 10px above that leg and needs no `lpos`.
|
|
36
45
|
- If the flow snakes back to the left, reorder the steps or the lanes until it runs mostly left to right and downward.
|
|
37
46
|
|
|
38
|
-
|
|
47
|
+
### Legend
|
|
39
48
|
|
|
40
49
|
One `legend at 40,Y` statement, 32px under the last lane line, with entries for the step, the focal step and each arrow style used.
|
|
50
|
+
|
|
51
|
+
## Columns
|
|
52
|
+
|
|
53
|
+
### Lanes
|
|
54
|
+
|
|
55
|
+
One vertical lane per actor, left to right in the order they first act; the one that starts the flow (the browser, the user) is on the left. Title at `40,52` (`style=h1`). Columns are 208px wide: column k (from 0) starts at `x = 40 + 208k`. The names sit in a header row at the top.
|
|
56
|
+
|
|
57
|
+
```
|
|
58
|
+
40,96 -- 872,96 stroke=ink/0.22 // top of the header (872 = 40 + 208 * columns)
|
|
59
|
+
40,140 -- 872,140 stroke=ink/0.22 // under the names
|
|
60
|
+
248,96 -- 248,676 style=rule // between columns: one every 208px
|
|
61
|
+
40,96 -- 40,676 stroke=ink/0.22 // left edge; the right edge is the same at x=872
|
|
62
|
+
40,676 -- 872,676 stroke=ink/0.22 // bottom line: 24px under the last step
|
|
63
|
+
text "API gateway" at 268,124 style=eyebrow // 20px inside the column, baseline y=124
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
- Three to five columns. Every column has a name; keep it to about 16 characters.
|
|
67
|
+
|
|
68
|
+
### Steps
|
|
69
|
+
|
|
70
|
+
- A step is a `node` written `136x48`, 36px inside its column (`x = 40 + 208k + 36`), so it is centred in it. Main text is the action; `sub=` is the detail (an endpoint, a table, a tool).
|
|
71
|
+
- One step per row: row r has its top at `y = 164 + 88r`. Each step happens after the one above it, even in another column. This is what makes the order readable without numbers.
|
|
72
|
+
- The step the request exists for gets `focal`.
|
|
73
|
+
|
|
74
|
+
### Arrows
|
|
75
|
+
|
|
76
|
+
- To the next step in the same column: `a -> b`, straight down, unlabelled.
|
|
77
|
+
- To a step in another column, always on the next row: `a.right -> b.top` when it is to the right, `a.left -> b.top` when it is to the left. The arrow leaves the side, runs across and turns down onto the step.
|
|
78
|
+
- These handoffs are the point of the diagram. Label each with what is sent: the call (`"POST /orders"`) or the answer (`"201 Created"`). A label would sit across a column line, so place it inside the receiving column with `lpos=x,y`: y is the sending step's top plus 14. Going right, x is the last column line the arrow crosses plus 12 plus half the label's width (about 5px per character); going left, x is the receiving column's right line (`40 + 208(k + 1)` for column k) minus 12 minus half the label's width.
|
|
79
|
+
- A response or callback uses `style=return`. The call that costs most (the slowest, or the one that can fail the request) uses `style=primary`.
|
|
80
|
+
- A flow with more than about eight steps is two diagrams, or a sequence diagram.
|
|
81
|
+
|
|
82
|
+
### Legend
|
|
83
|
+
|
|
84
|
+
One `legend at 40,Y` statement, 32px under the bottom line, with entries for the step, the focal step and each arrow style used.
|
|
85
|
+
|
|
86
|
+
For example:
|
|
87
|
+
|
|
88
|
+
```
|
|
89
|
+
place: node "Place order" sub="checkout page" at 76,164 136x48
|
|
90
|
+
token: node "Check token" sub="JWT · rate limit" at 284,252 136x48
|
|
91
|
+
charge: focal "Charge card" sub="Stripe" at 700,428 136x48
|
|
92
|
+
confirm: node "Confirm order" sub="status=paid" at 492,516 136x48
|
|
93
|
+
|
|
94
|
+
place.right -> token.top "POST /orders" lpos=290,178
|
|
95
|
+
charge.left -> confirm.top "paid" style=return lpos=642,442
|
|
96
|
+
```
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2023 Phosphor Icons
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "fastdraw",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.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",
|
|
@@ -22,13 +22,19 @@
|
|
|
22
22
|
"bin": {
|
|
23
23
|
"fastdraw": "dist/cli.js"
|
|
24
24
|
},
|
|
25
|
+
"exports": {
|
|
26
|
+
"./embed": "./dist-embed/embed.js",
|
|
27
|
+
"./package.json": "./package.json"
|
|
28
|
+
},
|
|
25
29
|
"files": [
|
|
26
30
|
"dist/cli.js",
|
|
31
|
+
"dist-embed",
|
|
27
32
|
"guide",
|
|
28
33
|
"fonts",
|
|
29
34
|
"agents",
|
|
30
35
|
"README.md",
|
|
31
|
-
"LICENSE"
|
|
36
|
+
"LICENSE",
|
|
37
|
+
"licenses"
|
|
32
38
|
],
|
|
33
39
|
"engines": {
|
|
34
40
|
"node": ">=20"
|
|
@@ -36,26 +42,27 @@
|
|
|
36
42
|
"scripts": {
|
|
37
43
|
"test": "node --disable-warning=ExperimentalWarning --test test/*.test.ts",
|
|
38
44
|
"dev": "vite",
|
|
39
|
-
"build:editor": "vite build",
|
|
45
|
+
"build:editor": "vite build && vite build -c vite.embed.config.ts --outDir dist-editor --emptyOutDir false",
|
|
40
46
|
"typecheck": "tsc -p .",
|
|
41
47
|
"test:e2e": "playwright test",
|
|
42
48
|
"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",
|
|
43
|
-
"prepack": "npm run build:cli"
|
|
49
|
+
"prepack": "npm run build:cli && npm run build:embed",
|
|
50
|
+
"build:embed": "vite build -c vite.embed.config.ts"
|
|
44
51
|
},
|
|
45
52
|
"dependencies": {
|
|
46
53
|
"@resvg/resvg-js": "^2.6.2"
|
|
47
54
|
},
|
|
48
55
|
"devDependencies": {
|
|
49
56
|
"@playwright/test": "^1.65.0",
|
|
50
|
-
"@types/node": "^
|
|
51
|
-
"@types/react": "^
|
|
52
|
-
"@types/react-dom": "^
|
|
53
|
-
"@vitejs/plugin-react": "^
|
|
54
|
-
"esbuild": "^0.
|
|
57
|
+
"@types/node": "^26.6.6",
|
|
58
|
+
"@types/react": "^19.3.0",
|
|
59
|
+
"@types/react-dom": "^19.3.0",
|
|
60
|
+
"@vitejs/plugin-react": "^6.3.0",
|
|
61
|
+
"esbuild": "^0.28.2",
|
|
55
62
|
"lucide-react": "^1.72.0",
|
|
56
|
-
"react": "^
|
|
57
|
-
"react-dom": "^
|
|
58
|
-
"typescript": "^
|
|
59
|
-
"vite": "^
|
|
63
|
+
"react": "^19.3.1",
|
|
64
|
+
"react-dom": "^19.3.1",
|
|
65
|
+
"typescript": "^7.0.2",
|
|
66
|
+
"vite": "^8.3.8"
|
|
60
67
|
}
|
|
61
68
|
}
|