pele-animate 0.15.0 → 0.16.0

package/README.md

@@ -16,7 +16,7 @@ Unofficial add-on; not affiliated with or endorsed by the Pele or Obsidian teams
 - **You set the order.** Nodes appear in the order of a `%% pa:` comment, or by default along the edges; edges draw in and labels fade in.
 - **Readers step through it.** Click (or Enter) starts step mode: previous / play-pause / next buttons, Space, ←/→ and Esc. Hover or focus sends tokens along the edges.
 - **Icons.** `@{ icon: "name" }` nodes use any of 4,368 [Tabler](https://github.com/tabler/tabler-icons) icons (loaded per category) or your own. Unknown names get a neutral rounded square.
-- Flowcharts and sequence diagrams. The finished picture is the resting state; `prefers-reduced-motion` turns the motion off. Light and dark themes.
+- Flowcharts, sequence diagrams, architecture diagrams, state diagrams, C4 context, block, class and ER diagrams, timelines, journeys, git graphs and Gantt charts. The finished picture is the resting state; `prefers-reduced-motion` turns the motion off. Light and dark themes.
 - The source stays valid Mermaid. One catch: GitHub's own Mermaid renderer does not know the icon names and draws "?" boxes, so the icon examples in this repository are shown as source text.
 
 ## Install

package/docs/diagram-types.md

@@ -7,7 +7,7 @@ section: Start
 
 # Diagram types
 
-pele-animate supports **flowcharts** and **sequence diagrams**. Pele renders other diagram types too, but they are outside what
+pele-animate supports **flowcharts**, **sequence diagrams**, **architecture diagrams** and **state diagrams** and **C4 context diagrams** and **block diagrams**, **class diagrams**, **ER diagrams**, **timelines**, **user journeys**, **git graphs** and **Gantt charts**. Pele renders other diagram types too, but they are outside what
 pele-animate is built for.
 
 ## Flowcharts
@@ -36,8 +36,173 @@ sequenceDiagram
 
 **Limit:** Pele ignores `@{ icon }` on sequence participants (the box shows its id), so icons apply to flowcharts only.
 
+## Architecture diagrams
+
+`architecture-beta`: services in groups, joined by edges. Services appear in step order like flowchart nodes, groups stay visible,
+and `%% pa:` pins work the same way. The icon in parentheses is looked up in your icon packs, so Tabler names and `doverunner-*`
+names work (import the packs as for [icons](./icons.md)).
+
+```mermaid-icons live
+architecture-beta
+  group edge(cloud)[Edge]
+  group core(cloud)[Core]
+  service user(device-desktop)[User]
+  service cdn(cloud-computing)[CDN] in edge
+  service api(server)[API] in core
+  service db(database)[Database] in core
+  user:R --> L:cdn
+  cdn:R --> L:api
+  api:R --> L:db
+```
+
+Icons here are small and fixed in size; `form` and `h` apply to flowcharts only. Edges are read from their written direction
+(`user:R --> L:cdn` is user to cdn). A node id containing `-` can be mistaken for two ids on an edge, so use plain ids.
+
+## State diagrams
+
+`stateDiagram-v2`: states appear in step order, transitions draw from their source state, and transition labels fade in. The
+start and end markers are nodes too, with the ids `root_start` and `root_end`, so pins can name them.
+
+```mermaid live
+stateDiagram-v2
+  %% pa: 1=root_start 2=Idle 3=Running 4=Paused 5=root_end
+  [*] --> Idle
+  Idle --> Running: start
+  Running --> Paused: pause
+  Paused --> Running: resume
+  Running --> [*]: done
+```
+
+Without pins the order is breadth-first from the start marker, which shows `Paused` and the end marker together. Pele gives
+state edges no readable ids, so pele-animate finds each transition's ends from where its path starts and stops. Composite
+states and forks are untested. State diagrams take no icons.
+
+## C4 context diagrams
+
+`C4Context`: people and systems appear in step order and each `Rel` draws from its source, with its label. Pins use the ids you
+give `Person(...)` and `System(...)`; an edge pin is `3=app>drm`.
+
+```mermaid live
+C4Context
+  %% pa: 1=viewer 2=app 3=drm,cdn
+  Person(viewer, "Viewer", "Watches video")
+  System(app, "Player app", "Plays protected video")
+  System_Ext(drm, "DRM service", "Issues licenses")
+  System(cdn, "CDN", "Delivers segments")
+  Rel(viewer, app, "uses")
+  Rel(app, drm, "license")
+  Rel(app, cdn, "segments")
+```
+
+Pele lays C4 diagrams out in rows, so a long label between two boxes in the same row can leave no room for the arrowhead:
+keep `Rel` labels short. Only `C4Context` has been checked; the other C4 types and boundaries are untested. C4 shapes take no icons.
+
+## Block diagrams
+
+`block-beta`: blocks appear in step order and each arrow draws from its source block. Pins use the block ids.
+
+```mermaid live
+block-beta
+  columns 3
+  %% pa: 1=client 2=server 3=db
+  client["Client"] space server["Server"]
+  space space db[("Database")]
+  client --> server
+  server --> db
+```
+
+Pele routes arrows between blocks in straight lines or short bends, so place linked blocks in the same row or column; a diagonal
+neighbour can give a bent arrow that runs along another one. Block diagrams take no icons.
+
+## Class diagrams
+
+`classDiagram`: classes appear in step order, relationships draw from the class written first. `Animal <|-- Dog` reveals `Animal`
+and then `Dog`, whichever way the arrowhead points. Pins use the class names.
+
+```mermaid live
+classDiagram
+  %% pa: 1=Animal 2=Dog,Cat 3=Owner
+  Animal <|-- Dog
+  Animal <|-- Cat
+  Dog --> Owner : has
+  Animal : +name
+  Dog : +bark()
+```
+
+## ER diagrams
+
+`erDiagram`: entities appear in step order, relationships draw from the entity written first (`CUSTOMER ||--o{ ORDER` reveals
+`CUSTOMER`, then `ORDER`).
+
+```mermaid live
+erDiagram
+  %% pa: 1=CUSTOMER 2=ORDER 3=LINE,PRODUCT
+  CUSTOMER ||--o{ ORDER : places
+  ORDER ||--|{ LINE : contains
+  PRODUCT ||--o{ LINE : in
+```
+
+Neither takes icons.
+
+## Timelines, journeys, git graphs and Gantt charts
+
+These have no edges to follow, so each steps through its items in reading order and `%% pa:` pins do nothing (as for sequence
+diagrams). Section headers, axes, grids and legends stay visible.
+
+- **`timeline`:** one step per time period, with its events.
+
+```mermaid live
+timeline
+  title History
+  section Early
+    2002 : Launch : Beta
+    2004 : Growth
+  section Late
+    2010 : Scale
+```
+
+- **`journey`:** one step per task: the task, its face, and the line segment that joins it to the task before.
+
+```mermaid live
+journey
+  title My day
+  section Work
+    Make tea: 5: Me, Bob
+    Do work: 3: Me
+  section Home
+    Relax: 4: Me
+```
+
+- **`gitGraph`:** one step per commit in the order written, with the edge that ends on it. A branch's label and lane appear with
+  its first commit.
+
+```mermaid live
+gitGraph
+  commit id: "a"
+  branch dev
+  commit id: "b"
+  checkout main
+  commit id: "c"
+  merge dev id: "m"
+```
+
+- **`gantt`:** one step per task, top to bottom.
+
+```mermaid live
+gantt
+  dateFormat YYYY-MM-DD
+  section Build
+    Design :a1, 2024-01-01, 3d
+    Code :after a1, 4d
+  section Ship
+    Test :2024-01-08, 2d
+```
+
+None of these take icons. Only these small examples have been checked in a browser; long diagrams, `todayMarker`, tags, cherry-picks and
+parallel tasks are untested.
+
 ## Everything else
 
-Other Mermaid types (class, state, ER, gantt, pie and the rest) render through Pele as usual. pele-animate is not designed for
+Other Mermaid types (pie, quadrant, radar and the rest) render through Pele as usual. pele-animate is not designed for
 them and its behavior on them is untested, so use plain Pele for those. Step mode has been checked in a browser on
-flowcharts only; sequence diagrams have not been checked the same way yet.
+the types above only; sequence diagrams have not been checked the same way yet.

package/docs/faq.md

@@ -22,7 +22,7 @@ you want to explain in order.
 **How big is it?** The core (`pele-animate.js` plus CSS) is about 20 KB unminified. Icon packs are separate modules, so you only
 ship the categories you import (the largest, `system`, is about 199 KB unminified).
 
-**Which diagrams does it support?** Flowcharts and sequence diagrams ([diagram types](./diagram-types.md)).
+**Which diagrams does it support?** Flowcharts, sequence diagrams, architecture diagrams, state diagrams, C4 context, block, class and ER diagrams, timelines, journeys, git graphs and Gantt charts ([diagram types](./diagram-types.md)).
 
 **Can I use my own icons?** Yes ([custom icons](./custom-icons.md)).
 

package/docs/step-order.md

@@ -14,6 +14,12 @@ them. By default, the order follows the edges. A `%% pa:` comment lets you set i
 
 - **Flowchart:** nodes appear by level, counting from the nodes nothing points to. Each edge draws from its source once the source
   is on screen, and its target appears as the edge lands. Branches of a decision appear together.
+- **Architecture diagram:** like a flowchart: services appear by level, edges follow their written direction, pins work the same way.
+- **Timeline, journey, git graph, Gantt chart:** one step per item in reading order (period, task, commit, task); pins do nothing.
+- **Class and ER diagrams:** like a flowchart, but a relationship runs from the class or entity written first.
+- **Block diagram:** like a flowchart, from the blocks nothing points to.
+- **C4 context diagram:** like a flowchart, from the people and systems nothing points to.
+- **State diagram:** like a flowchart, starting from the start marker (`root_start`); the end marker is `root_end`.
 - **Sequence diagram:** actors first, then the messages in order.
 
 ## Pins

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pele-animate",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Step-by-step animated Mermaid diagrams with icons: an unofficial add-on for the Pele renderer.",
   "type": "module",
   "license": "MIT",

package/pele-animate.css

@@ -2,14 +2,16 @@
 .pa-ready:not(.pa-in):not(.pa-step) .pele-node,
 .pa-ready:not(.pa-in):not(.pa-step) .pele-edge-label,
 .pa-ready:not(.pa-in):not(.pa-step) .pele-lifeline,
-.pa-ready:not(.pa-in):not(.pa-step) .pele-marker { opacity: 0; }
+.pa-ready:not(.pa-in):not(.pa-step) .pele-marker,
+.pa-ready:not(.pa-in):not(.pa-step) .pa-item { opacity: 0; }
 .pa-ready:not(.pa-in):not(.pa-step) .pele-edge > path:not(.pele-marker) { stroke-dasharray: var(--len); stroke-dashoffset: var(--len); }
 
 /* Keyframes carry the dash, so edges that are dashed in the diagram go back to their own dash pattern afterwards. */
 .pa-ready.pa-in:not(.pa-step) .pele-node,
 .pa-ready.pa-in:not(.pa-step) .pele-edge-label,
 .pa-ready.pa-in:not(.pa-step) .pele-lifeline,
-.pa-ready.pa-in:not(.pa-step) .pele-marker { animation: pa-fade .4s ease-out backwards; animation-delay: var(--d, 0s); }
+.pa-ready.pa-in:not(.pa-step) .pele-marker,
+.pa-ready.pa-in:not(.pa-step) .pa-item { animation: pa-fade .4s ease-out backwards; animation-delay: var(--d, 0s); }
 .pa-ready.pa-in:not(.pa-step) .pele-edge > path:not(.pele-marker) { animation: pa-draw .4s ease-out backwards; animation-delay: var(--d, 0s); }
 .pa-ready.pa-done:not(.pa-step) * { animation: none !important; }
 @keyframes pa-fade { from { opacity: 0; } }
@@ -19,7 +21,7 @@
 
 @media (prefers-reduced-motion: reduce) {
   .pa-ready * { animation: none !important; }
-  .pa-ready:not(.pa-step) .pele-node, .pa-ready:not(.pa-step) .pele-edge-label, .pa-ready:not(.pa-step) .pele-lifeline, .pa-ready:not(.pa-step) .pele-marker { opacity: 1 !important; }
+  .pa-ready:not(.pa-step) .pele-node, .pa-ready:not(.pa-step) .pele-edge-label, .pa-ready:not(.pa-step) .pele-lifeline, .pa-ready:not(.pa-step) .pele-marker, .pa-ready:not(.pa-step) .pa-item { opacity: 1 !important; }
   .pa-ready .pele-edge > path { stroke-dasharray: none; stroke-dashoffset: 0 !important; }
 }
 
@@ -51,6 +53,9 @@
 /* Edge labels sit on the line; give them the panel color so the line doesn't strike through the text. */
 .pa-scene .pele-edge-label rect { fill: var(--pa-bg); }
 
+/* Pele colours text on solid fills (timeline periods, gantt bars, git branch tags) with --_bg, which the scene makes transparent: use the panel surface instead. */
+.pa-scene text[fill="var(--_bg)"] { fill: var(--pele-surface); }
+
 /* Group and box titles read as headings. */
 :where(.pa-scene) .pele-cluster-label { font-weight: 700; }
 

package/pele-animate.js

@@ -16,11 +16,33 @@ export function parseOrder(source = '') {
   return levels;
 }
 
+// Edge ids by diagram type: flowchart `L_A_B_0`, architecture and C4 `A-B` (repeat edges get `-N`), block `1-A-B`, class `id_A_B_1`,
+// ER `id_entity-A-0_entity-B-1_0`. Ends follow the written order (`A <|-- B` is A, then B).
+const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 function endpoints(edgeId, ids) {
-  for (const s of ids) for (const d of ids) if (new RegExp(`^L_${s}_${d}_\\d+$`).test(edgeId)) return [s, d];
+  for (const s of ids)
+    for (const d of ids)
+      if (new RegExp(`^(?:L_${esc(s)}_${esc(d)}_\\d+|(?:\\d+-)?${esc(s)}-${esc(d)}(?:-\\d+)?|id_${esc(s)}_${esc(d)}_\\d+|id_entity-${esc(s)}-\\d+_entity-${esc(d)}-\\d+_\\d+)$`).test(edgeId)) return [s, d];
   return null;
 }
 
+// State diagrams name edges `edge0`, `edge1`, ... with no ends in the id, so read the ends off the geometry:
+// the node nearest to where the path starts (source) and ends (target).
+function geoEndpoints(edge, boxes) {
+  const path = edge.querySelector('path:not(.pele-marker)');
+  if (!path) return null;
+  const near = (pt) => {
+    let best = null, bd = 12; // an end more than 12 px from every node is not an end
+    for (const [id, b] of boxes) {
+      const d = Math.hypot(Math.max(b.x - pt.x, 0, pt.x - b.x - b.width), Math.max(b.y - pt.y, 0, pt.y - b.y - b.height));
+      if (d < bd) { bd = d; best = id; }
+    }
+    return best;
+  };
+  const s = near(path.getPointAtLength(0)), d = near(path.getPointAtLength(path.getTotalLength()));
+  return s && d ? [s, d] : null;
+}
+
 function bfs(ids, pairs, pinned) {
   const level = new Map(pinned);
   const hasIn = new Set(pairs.map(([, d]) => d));
@@ -97,11 +119,77 @@ export function prepare(source = '') {
 }
 
 
+// Diagrams with no edges to follow (timeline, journey, gitGraph, gantt) step through their items in reading order.
+// Returns [[element, ...], ...], one array per step, or null for any other diagram.
+const pts = (path) => path.getAttribute('d').match(/-?[\d.]+/g)?.map(Number) ?? [];
+function sequentialSteps(svg) {
+  const all = (sel) => [...svg.querySelectorAll(sel)];
+  if (svg.classList.contains('pele-timeline')) return all('.pele-period').map((p) => [p]);
+  if (svg.classList.contains('pele-gantt')) return all('.pele-task').map((t) => [t]);
+  if (svg.classList.contains('pele-journey')) {
+    const tasks = all('.pele-task'), faces = all('.pele-face');
+    const line = svg.querySelector('path.pele-edge');
+    // The satisfaction line is one polyline `M x,yL x,y...`: split it so each segment arrives with its task.
+    const segs = [];
+    if (line && /^M[-\d.,]+(L[-\d.,]+)+$/.test(line.getAttribute('d'))) {
+      const p = line.getAttribute('d').slice(1).split('L');
+      for (let i = 1; i < p.length; i++) {
+        const seg = line.cloneNode();
+        seg.setAttribute('d', `M${p[i - 1]}L${p[i]}`);
+        line.before(seg);
+        segs.push(seg);
+      }
+      line.remove();
+    }
+    return tasks.map((t, i) => [t, faces[i], segs[i - 1]].filter(Boolean));
+  }
+  if (svg.classList.contains('pele-gitGraph')) {
+    const commits = all('.pele-commit');
+    const at = (c) => { const e = c.querySelector('circle'); return [+e.getAttribute('cx'), +e.getAttribute('cy')]; };
+    const steps = commits.map((c) => [c]);
+    // an edge arrives with the commit it ends on
+    for (const e of all('.pele-edge')) {
+      const path = e.matches('path') ? e : e.querySelector('path');
+      const end = path.getPointAtLength(path.getTotalLength());
+      let best = steps.length - 1, bd = Infinity;
+      commits.forEach((c, i) => { const [x, y] = at(c), d = Math.hypot(x - end.x, y - end.y); if (d < bd) { bd = d; best = i; } });
+      steps[best]?.push(e);
+    }
+    // a branch (label and lane) appears with its first commit: the commit whose y is on the lane
+    for (const b of all('.pele-branch')) {
+      const y = pts(b.querySelector('.pele-lane'))[1];
+      const first = commits.findIndex((c) => Math.abs(at(c)[1] - y) < 1);
+      steps[first < 0 ? 0 : first].push(b);
+    }
+    return steps;
+  }
+  return null;
+}
+
+// Intro for sequentialSteps: each step fades in after the one before; the same steps drive step mode.
+function introSteps(svg, steps) {
+  const u = Math.min(UNIT, MAX_INTRO / Math.max(1, steps.length));
+  steps.forEach((els, i) => els.forEach((el) => { el.classList.add('pa-item'); el.style.setProperty('--d', `${i * u}s`); }));
+  svg.paSteps = steps.map((els) => els.map((el) => [el, [el]]));
+  reveal(svg);
+}
+
+function reveal(svg) {
+  if (!('IntersectionObserver' in window)) return svg.classList.add('pa-in');
+  svg.classList.remove('pa-in');
+  const io = new IntersectionObserver(([en]) => {
+    if (en.isIntersecting) { svg.classList.add('pa-in'); io.disconnect(); }
+  }, { threshold: 0.3 });
+  io.observe(svg);
+}
+
 export function animate(svg, { hover = svg, source = '' } = {}) {
   fitGlyphs(svg);
   equalizeActors(svg);
   svg.querySelectorAll('.pa-dot').forEach((d) => d.remove());
   svg.classList.add('pa-ready');
+  const seq = sequentialSteps(svg);
+  if (seq) return introSteps(svg, seq);
   const nodes = [...svg.querySelectorAll('.pele-node')];
   const edges = [...svg.querySelectorAll('.pele-edge')];
   const ids = [...new Set(nodes.map((n) => n.dataset.id))];
@@ -116,7 +204,17 @@ export function animate(svg, { hover = svg, source = '' } = {}) {
     edges.forEach((e, i) => { times.set(e, 0.5 + i * u); step.set(e, i + 1); });
     nodes.forEach((n) => step.set(n, 0));
   } else {
-    const pairs = edges.map((e) => endpoints(e.dataset.id, ids));
+    const boxes = new Map();
+    const pairs = edges.map((e) => {
+      const found = endpoints(e.dataset.id, ids);
+      if (found) return found;
+      if (!boxes.size)
+        for (const n of nodes) {
+          const b = n.getBBox(), t = n.transform.baseVal.consolidate()?.matrix;
+          boxes.set(n.dataset.id, { x: b.x + (t?.e ?? 0), y: b.y + (t?.f ?? 0), width: b.width, height: b.height });
+        }
+      return geoEndpoints(e, boxes);
+    });
     const level = bfs(ids, pairs.filter(Boolean), parseOrder(source));
     const u = Math.min(UNIT, MAX_INTRO / (Math.max(0, ...level.values()) + 1));
     const k = u / UNIT;
@@ -184,12 +282,7 @@ export function animate(svg, { hover = svg, source = '' } = {}) {
   hover.addEventListener('focusin', play);
   hover.addEventListener('focusout', stop);
 
-  if (!('IntersectionObserver' in window)) return svg.classList.add('pa-in');
-  svg.classList.remove('pa-in');
-  const io = new IntersectionObserver(([en]) => {
-    if (en.isIntersecting) { svg.classList.add('pa-in'); io.disconnect(); }
-  }, { threshold: 0.3 });
-  io.observe(svg);
+  reveal(svg);
 }
 
 const STEP_MS = 1200; // autoplay pace in step mode