Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 63 additions & 4 deletions 3d.html
Original file line number Diff line number Diff line change
Expand Up @@ -145,6 +145,9 @@
.drawer code{font-family:var(--mono);font-size:.92em}
.drawer textarea{flex:1;resize:none;border:1px solid var(--line-2);border-radius:10px;padding:12px;font-family:var(--mono);font-size:12.5px;line-height:1.5;background:var(--paper);min-height:0;white-space:pre;overflow:auto}
.drawer textarea:focus{outline:2px solid var(--brand-100);border-color:var(--brand)}
.drawer .url-row{display:flex;gap:6px;align-items:center}
.drawer .url-row input{flex:1;min-width:0;border:1px solid var(--line-2);border-radius:8px;padding:8px 10px;font:12.5px var(--mono);background:var(--paper);color:var(--ink)}
.drawer .url-row input:focus{outline:2px solid var(--brand-100);border-color:var(--brand)}
.row{display:flex;gap:8px;flex-wrap:wrap;align-items:center}
.err{display:none;border:1px solid #f0b3a3;background:#fdf0ec;color:#8f2412;border-radius:8px;padding:8px 10px;font-size:13px}
.err.show{display:block}
Expand Down Expand Up @@ -413,7 +416,11 @@ <h2 id="aboutTitle">Flow<br><span>Explainer</span></h2>
<div class="scrim" id="scrim"></div>
<div class="drawer" id="drawer">
<div class="row" style="justify-content:space-between"><h3 id="drawerTitle">Paste your markdown</h3><button class="btn ghost icon" id="btnClose" aria-label="Close">✕</button></div>
<p>Paste a GitHub markdown file that contains a <code>```mermaid</code> block (<b>flowchart</b>, <b>sequenceDiagram</b>, <b>stateDiagram</b>, <b>classDiagram</b>, <b>erDiagram</b>, <b>gantt</b>, <b>pie</b>, <b>mindmap</b>, <b>journey</b>, <b>timeline</b>, <b>quadrantChart</b>, <b>gitGraph</b>, <b>xychart</b>, <b>sankey</b>, <b>block</b>, <b>architecture</b>, <b>C4</b>, <b>kanban</b>, <b>packet</b>, <b>requirementDiagram</b>, <b>radar</b>, <b>treemap</b> or <b>zenuml</b>). Optional: a numbered list under the diagram becomes the explanation for each step, and <code>- **Box name**: text</code> adds a note to a box.</p>
<p>Paste a GitHub markdown file that contains a <code>```mermaid</code> block (<b>flowchart</b>, <b>sequenceDiagram</b>, <b>stateDiagram</b>, <b>classDiagram</b>, <b>erDiagram</b>, <b>gantt</b>, <b>pie</b>, <b>mindmap</b>, <b>journey</b>, <b>timeline</b>, <b>quadrantChart</b>, <b>gitGraph</b>, <b>xychart</b>, <b>sankey</b>, <b>block</b>, <b>architecture</b>, <b>C4</b>, <b>kanban</b>, <b>packet</b>, <b>requirementDiagram</b>, <b>radar</b>, <b>treemap</b> or <b>zenuml</b>). Optional: a numbered list under the diagram becomes the explanation for each step, and <code>- **Box name**: text</code> adds a note to a box. Or load a <b>public</b> URL (GitHub blob links are rewritten to raw).</p>
<div class="url-row">
<input id="mdUrl" type="url" inputmode="url" autocomplete="off" spellcheck="false" placeholder="https://…/file.md or github.com/…/blob/…/file.md" aria-label="Markdown URL">
<button class="btn" id="btnUrl" type="button" title="Fetch markdown from this public URL">Load URL</button>
</div>
<textarea id="src" spellcheck="false"></textarea>
<div class="err" id="err"></div>
<div class="row">
Expand Down Expand Up @@ -2297,6 +2304,39 @@ <h2 id="aboutTitle">Flow<br><span>Explainer</span></h2>
const staticPage=(dim,embed)=>tidyUrl(rootUrl()+'/'+(dim==='3d'?'3d.html':'index.html'))+(embed?'?embed=1':'');
const linkOpts=()=>(DSK!=='original'?'&s='+DSK:'')+(ICONS_ON?'':'&i=0');
const clientLink=async()=>(isStaticHost()?staticPage(is3dView()?'3d':'2d'):pageUrl(is3dView()?'/3d':''))+'#c='+await encode(/** @type {any} */(S).md)+linkOpts();
/**
* Turn a pasted GitHub blob URL into a raw URL browsers can fetch.
* @param {string} raw
* @returns {string}
*/
function normalizeMdUrl(raw){
let u;
try{u=new URL(String(raw||'').trim())}catch(e){throw new Error('That does not look like a URL.',{cause:e})}
if(u.protocol!=='http:'&&u.protocol!=='https:')throw new Error('Only http(s) URLs are allowed.');
if(/^(www\.)?github\.com$/i.test(u.hostname)){
const m=u.pathname.match(/^\/([^/]+)\/([^/]+)\/blob\/([^/]+)\/(.+)$/);
if(m)return 'https://raw.githubusercontent.com/'+m[1]+'/'+m[2]+'/'+m[3]+'/'+m[4]+u.search;
}
return u.href;
}
/**
* Fetch markdown text from a public URL (browser CORS applies).
* @param {string} raw
* @returns {Promise<string>}
*/
async function fetchMarkdown(raw){
const href=normalizeMdUrl(raw);
let res;
try{res=await fetch(href,{mode:'cors',credentials:'omit',redirect:'follow'})}
catch(e){throw new Error('Could not fetch that URL (network or CORS). Use a public raw URL, paste the file, or share a #c= client link.',{cause:e})}
if(!res.ok)throw new Error('Fetch failed ('+res.status+' '+res.statusText+'). Check the URL is public.');
const text=await res.text();
if(text.length>1500000)throw new Error('File is too large (max about 1.5 MB).');
if(!text.trim())throw new Error('That URL returned an empty file.');
return text;
}
/** Shareable hash that reloads markdown from a URL on open. @param {string} url */
const urlLink=url=>(isStaticHost()?staticPage(is3dView()?'3d':'2d'):pageUrl(is3dView()?'/3d':''))+'#u='+encodeURIComponent(normalizeMdUrl(url))+linkOpts();
/**
* iframe HTML for pasting into a website, like YouTube's "Embed" code.
* @param {string} url the /embed link (with #c=…)
Expand Down Expand Up @@ -2863,6 +2903,18 @@ <h2 id="aboutTitle">Flow<br><span>Explainer</span></h2>
$('#btnRender').onclick=tryRender;
$('#exSel').onchange=e=>{if(e.target.value){$('#src').value=$('#'+e.target.value).textContent.trim()+'\n';e.target.value='';tryRender()}};
$('#file').onchange=async e=>{const f=e.target.files[0];if(f){$('#src').value=await f.text();tryRender()}e.target.value=''};
async function loadFromUrlField(){
const raw=$('#mdUrl').value.trim();if(!raw){showErr('Paste a public markdown URL first.');return}
const btn=$('#btnUrl');btn.disabled=true;showErr('');
try{
const md=await fetchMarkdown(raw);$('#src').value=md;
try{history.replaceState(null,'',urlLink(raw))}catch(e){}
tryRender();
}catch(e){showErr(e instanceof Error?e.message:String(e))}
finally{btn.disabled=false}
}
$('#btnUrl').onclick=()=>{loadFromUrlField()};
$('#mdUrl').addEventListener('keydown',(/** @type {KeyboardEvent} */e)=>{if(e.key==='Enter'){e.preventDefault();loadFromUrlField()}});
$('#sceneSel').onchange=e=>openScene(+e.target.value);
$('#btnPlay').onclick=()=>S.playing?stopPlay():play();
$('#btnFit').onclick=()=>{if(home)flyTo(home)};
Expand Down Expand Up @@ -3072,10 +3124,17 @@ <h2 id="aboutTitle">Flow<br><span>Explainer</span></h2>

(async function init(){
if(isEmbed())document.body.classList.add('embed','client');
let md=null;const m=location.hash.match(/^#([cd])=([^&]+)/);initStyle();wireUi();
if(m){try{md=await decode(m[2]);if(m[1]==='c')document.body.classList.add('client')}catch(e){md=null}}
let md=null,fromHash=false,urlErr='';const m=location.hash.match(/^#([cdu])=([^&]+)/);initStyle();wireUi();
if(m){
fromHash=true;
try{
if(m[1]==='u'){md=await fetchMarkdown(decodeURIComponent(m[2]));$('#mdUrl').value=decodeURIComponent(m[2])}
else{md=await decode(m[2]);if(m[1]==='c')document.body.classList.add('client')}
}catch(e){md=null;urlErr=e instanceof Error?e.message:String(e)}
}
if(md==null&&!m&&!isEmbed())try{md=localStorage.getItem('flowx.md')}catch(e){}
if(md)try{load(md,!!m||isEmbed());return}catch(e){}
if(md)try{load(md,fromHash||isEmbed());return}catch(e){if(fromHash&&m&&m[1]==='u'){drawer(true);showErr(e instanceof Error?e.message:String(e));return}}
if(urlErr){drawer(true);showErr(urlErr);toast(urlErr)}
const t=document.title;load($('#ex1').textContent.trim()+'\n',true);document.title=t; // keep the descriptive page title for the built-in demo
})();
</script>
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Turns pasted GitHub markdown (Mermaid flowchart, sequence, state, class, ER, gan
- `3d.html` — Three.js version (real 3D blocks, rotatable camera). Also served via zo.space (route `/flow-explainer/:file`; Three.js 0.187.0 jsDelivr-minified in `vendor/`, imported as `./vendor/three.module.js` and served by route `/flow-explainer/vendor/:file`).
- Both files are standalone and edited directly; they share the same markdown parser, layout, panel, timeline and `#c=` client-link code (copied, not imported). The shared core (`/* ---------- shared core:` … `/* ---------- end of diagram styles + settings`: helpers, markdown + Mermaid parsers, layout, diagram styles/settings UI) is edited in `index.html` only, then copied with `python3 tools/sync-parser.py` (`--check` to verify). Layout spacing differs per page via `IS_3D_PAGE`. Non-parser fixes (render, buildScene, iconFor) still go into both files by hand.
- Every diagram type is converted into the same `{nodes,links,steps,groups}` graph. Extra node fields: `note`, `icon` (forced emoji), `iconFallback`, `ci` (palette index), `hk` (height factor: pie, journey, xychart, sankey, packet). Graph flags: `fixed` (parser set `gx/gy`, skip `layout()`; non-pie fixed parsers call `routeFixed()` to give links `pts`: timeline, quadrant, git, xychart, block, kanban, packet), `noZones` (colour groups without zone slabs, mindmap), `diagramTitle` (used when the markdown has no heading).
- Both read the same `localStorage` key `flowx.md`; the 2D/3D button keeps the URL hash and works with both `/flow-explainer` ↔ `/flow-explainer/3d` and `index.html` ↔ `3d.html` (static hosting).
- Both read the same `localStorage` key `flowx.md`; the 2D/3D button keeps the URL hash and works with both `/flow-explainer` ↔ `/flow-explainer/3d` and `index.html` ↔ `3d.html` (static hosting). Hash loaders: `#c=` / `#d=` compressed markdown, `#u=` public URL (`normalizeMdUrl` / `fetchMarkdown`; GitHub blob → raw). Edit drawer has **Load URL**; `embed.js` accepts `data-u` as an alternative to `data-c`.
- Public repo: https://github.com/solutionforest/flow-explainer (MIT). README images in `docs/images/` were made with the Snapshot button; sample inputs in `examples/`.
- 📸 Snapshot (edit mode only): modal exports a README PNG (title header, optional step-number badges, group legend, optional credit strip `drawCredit()`: icon + “Made with Flow Explainer” + `flow-explainer.laravel.cloud`, on by default) + "Copy README text" (image link + numbered steps). Overlap checker lists label/box/step-number collisions; "minor" = label sitting on an arrow line.
- 2D: `render()` places node labels (lift/side shift), arrow labels and badges greedily to avoid collisions; export serialises the SVG with scene CSS inlined.
Expand Down
7 changes: 4 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ The full source of that picture is [`examples/how-it-works.md`](examples/how-it-
Or [run it yourself](#run-it-yourself).

1. Open `index.html` (2D) or `3d.html` (3D) from any static file server — see [Run it yourself](#run-it-yourself).
2. Press **New** (or **Edit** to change the current one), paste your markdown, then **Render ▶**. **Use template** fills in a starter file, **Open .md** loads one from your computer, and the **Examples** menu in the top bar loads a sample.
2. Press **New** (or **Edit** to change the current one), paste your markdown, then **Render ▶**. **Use template** fills in a starter file, **Open .md** loads one from your computer, **Load URL** fetches a public `.md` (GitHub blob links are rewritten to raw), and the **Examples** menu in the top bar loads a sample. You can also open `#u=<url-encoded-url>` directly.
3. Press **▶ Play**, or step with **Next / Back**, the ← → keys, or the numbered timeline at the bottom.
4. Press **Copy client link** and send it. The link opens in view-only mode, without Edit or Snapshot, and in the diagram style you picked.
5. Open **⚙ Settings** (top right) to pick a diagram style, show or hide the emoji icons on the blocks, or switch between 3D and 2D.
Expand Down Expand Up @@ -313,7 +313,7 @@ Script tag (GitHub Pages — good default for third-party sites):
data-title="How an online ticket order is handled"></script>
```

`data-c` is the same payload as a client link’s `#c=`. Optional: `data-view="3d"`, `data-text="1"`, `data-switch="0"`, `data-s="teal"`, `data-i="0"`, `data-size="640x480"`, `data-host="https://flow-explainer.laravel.cloud"` (force Cloud player while loading the script from Pages).
`data-c` is the same payload as a client link’s `#c=`. Or use `data-u="https://…/file.md"` to have the player fetch public markdown (`#u=`). Optional: `data-view="3d"`, `data-text="1"`, `data-switch="0"`, `data-s="teal"`, `data-i="0"`, `data-size="640x480"`, `data-host="https://flow-explainer.laravel.cloud"` (force Cloud player while loading the script from Pages).

iframe (Cloud) equivalent:

Expand All @@ -329,9 +329,10 @@ The host must allow framing (Cloud uses frame = `all`). Diagram data still lives

- Your markdown is kept in your browser's local storage (`flowx.md`) so it survives a reload.
- A client link stores the diagram compressed inside the part of the address after `#`. Browsers never send that part to a server, so the host only sees a request for the page.
- **Load from URL** (`#u=…` or Edit → Load URL) makes your browser `fetch` that public file. Flow Explainer’s server still does not see the markdown, but the remote host sees the request. CORS must allow the fetch (raw GitHub URLs usually do; many other hosts do not).
- Anyone who has a client link can read the diagram, so treat it like the document itself. The link is compressed, not encrypted. **Copy client link** shows this reminder every time.
- Chat apps, email and browser history keep the full link wherever you paste it.
- The page loads no fonts, scripts or trackers from other sites. Everything it needs is in this repository.
- The page loads no fonts, scripts or trackers from other sites (except when you choose to fetch a markdown URL). Everything else it needs is in this repository.

## Project layout

Expand Down
8 changes: 5 additions & 3 deletions embed.js
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
/*! Flow Explainer embed loader
* https://github.com/solutionforest/flow-explainer
* Drop on any site: <script async src="…/embed.js" data-c="…" data-text="0"></script>
* Or load markdown from a public URL: data-u="https://…/file.md" (instead of data-c).
* Builds an iframe to the player. data-c is the same payload as a client link’s #c=.
*/
(function () {
Expand All @@ -9,8 +10,9 @@
if (!s || !s.getAttribute) return;
var d = s.dataset || {};
var c = d.c || d.payload || '';
if (!c) {
if (typeof console !== 'undefined') console.warn('[flow-explainer] data-c is required');
var u = d.u || d.url || '';
if (!c && !u) {
if (typeof console !== 'undefined') console.warn('[flow-explainer] data-c or data-u is required');
return;
}
var view = String(d.view || '2d').toLowerCase() === '3d' ? '3d' : '2d';
Expand Down Expand Up @@ -47,7 +49,7 @@
return;
}

var hash = '#c=' + c;
var hash = u ? '#u=' + encodeURIComponent(u) : '#c=' + c;
if (d.s) hash += '&s=' + encodeURIComponent(d.s);
if (d.i === '0') hash += '&i=0';
// Default: hide step text (diagram + controls only). Pass data-text="1" to show it.
Expand Down
Loading
Loading