pele-animate 0.14.0 → 0.15.0

package/README.md

@@ -1,78 +1,55 @@
 # pele-animate
 
+[![npm](https://img.shields.io/npm/v/pele-animate)](https://www.npmjs.com/package/pele-animate)
+[![CI](https://github.com/dkdev24/pele-animate/actions/workflows/ci.yml/badge.svg)](https://github.com/dkdev24/pele-animate/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/pele-animate)](LICENSE)
+
 Mermaid diagrams that explain themselves one step at a time, with icons. You choose the order things appear in, readers
 step through it, and nodes can carry icons. A small post-processor for [Pele](https://github.com/obsidianmd/pele) (MIT),
 which renders the Mermaid; this adds the step order, the playback and the icons. It is not a theme package.
 Unofficial add-on; not affiliated with or endorsed by the Pele or Obsidian teams.
-The source stays valid Mermaid, so GitHub or Obsidian still show a normal diagram.
-
-- Nodes appear in order (BFS from the sources, or pinned with a `%% pa:` comment), edges draw in, labels fade in.
-- Hover or focus: tokens travel the edges in sequence. The intro plays once on scroll-in. Click (or Enter) enters step mode: previous / play-pause / next buttons, with Space (play/pause), ←/→ (step) and Esc (leave).
-- `@{ icon: "name" }` nodes become illustrations from a glyph pack. Unknown names get a neutral rounded-square glyph.
-- Sequence diagrams: participant boxes in a row get the tallest height (Pele sizes each to its own text). Group and box titles are bold.
-- Idle state is the finished picture; `prefers-reduced-motion` turns the motion off. Light and dark themes.
-
-## Compare
-
-The same Mermaid source, three renderers. The pele-animate images loop: the intro draws in, then tokens travel the edges (as on hover).
-Regenerate with `examples/capture.sh`.
-
-```mermaid
-flowchart LR
-  A[Player] -->|auth token| B[OTT service]
-  A -->|license request| C[DRM server]
-  C -->|license| A
-```
-
-| Renderer | Result |
-|---|---|
-| Mermaid | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/m1.png" width="560" alt="Flowchart rendered by Mermaid"> |
-| Pele | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/p1.png" width="560" alt="Flowchart rendered by Pele"> |
-| pele-animate | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/a1.gif" width="560" alt="Animated flowchart: nodes appear, edges draw in, tokens travel"> |
-
-```mermaid
-sequenceDiagram
-  Player->>OTT: sign in
-  OTT-->>Player: token
-  Player->>DRM: token
-  DRM-->>Player: license
-```
 
-| Renderer | Result |
-|---|---|
-| Mermaid | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/m2.png" width="560" alt="Sequence diagram rendered by Mermaid"> |
-| Pele | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/p2.png" width="560" alt="Sequence diagram rendered by Pele"> |
-| pele-animate | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/a2.gif" width="560" alt="Animated sequence diagram: messages appear in order, tokens travel"> |
-
-With icons (`@{ icon }` nodes from the Tabler `computers` pack, `%% pa: 1=C 2=L 3=S` pins the order):
+**[Website](https://pele-animate.pages.dev/) · [Docs](docs/getting-started.md) · [npm](https://www.npmjs.com/package/pele-animate) · [Changelog](CHANGELOG.md)**
 
 <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/a3.gif" width="560" alt="Animated scene with Tabler icons: a request, a load balancer and a cloud service">
 
+- **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.
+- 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
 
 ```sh
 npm i pele-animate pele
+# or
+pnpm add pele-animate pele
+yarn add pele-animate pele
+bun add pele-animate pele
 ```
 
+`pele` is a peer dependency (`^1.7.0`): install it alongside. Both packages run in the browser and need the DOM, so mount them on the client (see [recipes](docs/recipes.md)). ESM only.
+
 ## Use
 
 ```js
 import { mount } from 'pele';
-import { watch } from 'pele-animate';
+import { watch, prepare } from 'pele-animate';
 import { icons } from 'pele-animate/glyphs';
 import 'pele-animate/tabler/computers'; // one Tabler icon category; import as many as you need
 import 'pele-animate/style.css';
 
 for (const el of document.querySelectorAll('pre.mermaid')) {
   const src = el.textContent;
-  mount(el, src, { icons });
+  mount(el, prepare(src), { icons });
   watch(el, src); // re-applies after Pele re-lays-out on resize
 }
 ```
 
 Mermaid source:
 
-```mermaid
+```mermaid-icons
 flowchart LR
   %% pa: 1=C 2=L 3=S
   C@{ icon: "http-get", form: "square", h: 88, label: "Request" }
@@ -98,6 +75,38 @@ Everything is in [`docs/`](docs/getting-started.md), and ships inside the npm pa
 **Coding agents:** the package includes a skill, `skills/pele-animate/`, that wires the library into a project and checks the
 result in a browser. See [For coding agents](docs/agents.md).
 
+## Compare
+
+The same Mermaid source, three renderers. The pele-animate images loop: the intro draws in, then tokens travel the edges (as on hover).
+Regenerate with `examples/capture.sh`.
+
+```mermaid
+flowchart LR
+  A[Client] -->|request| B[API]
+  A -->|sign in| C[Auth server]
+  C -->|token| A
+```
+
+| Renderer | Result |
+|---|---|
+| Mermaid | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/m1.png" width="560" alt="Flowchart rendered by Mermaid"> |
+| Pele | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/p1.png" width="560" alt="Flowchart rendered by Pele"> |
+| pele-animate | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/a1.gif" width="560" alt="Animated flowchart: nodes appear, edges draw in, tokens travel"> |
+
+```mermaid
+sequenceDiagram
+  Client->>API: sign in
+  API-->>Client: token
+  Client->>Data: query with token
+  Data-->>Client: result
+```
+
+| Renderer | Result |
+|---|---|
+| Mermaid | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/m2.png" width="560" alt="Sequence diagram rendered by Mermaid"> |
+| Pele | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/p2.png" width="560" alt="Sequence diagram rendered by Pele"> |
+| pele-animate | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/a2.gif" width="560" alt="Animated sequence diagram: messages appear in order, tokens travel"> |
+
 ## Credits and license
 
 MIT. Built on [Pele](https://github.com/obsidianmd/pele) by kepano (MIT); this is an unofficial add-on, not affiliated with or

package/docs/api.md

@@ -14,6 +14,7 @@ TypeScript types ship with the package (`types/`).
 | Export | Signature | Description |
 |---|---|---|
 | `watch` | `watch(container: HTMLElement, source?: string, options?: { controls?: boolean }): void` | Marks the container as a scene (`pa-scene`), animates each SVG Pele renders into it and re-applies after Pele re-lays-out on resize. `controls: false` keeps click-to-replay instead of step mode. |
+| `prepare` | `prepare(source?: string): string` | Returns the Mermaid source with icon-node labels padded so Pele lays out a box at least as wide as the icon (`h`). Pass its result to `mount()` and the original source to `watch()`. Without it, a label shorter than the icon puts edge ends and arrowheads under the icon. |
 | `animate` | `animate(svg: SVGSVGElement, options?: { hover?: Element; source?: string }): void` | Animates one rendered svg. `source` is read for `%% pa:` pins. Sets `svg.paSteps`. |
 | `replay` | `replay(svg: SVGSVGElement \| null \| undefined): void` | Plays the intro again. |
 | `parseOrder` | `parseOrder(source?: string): Map<string, number>` | Parses the `%% pa:` comment: node id, or `'X>Y'` for an edge, to a 0-based step. |

package/docs/contributing.md

@@ -17,6 +17,7 @@ pnpm build   # builds the site (a placeholder until the site lands)
 
 - The package is plain ESM at the repository root: no build step. The site lives in `site/`.
 - Docs are the Markdown files in `docs/`. A fenced block marked `mermaid` must render, and every `@{ icon }` name in it must exist.
+- Fence convention: ```` ```mermaid live ```` is a diagram GitHub can also draw; the site animates it. A diagram with `@{ icon }` nodes uses ```` ```mermaid-icons live ````, because GitHub's Mermaid cannot draw icons (it shows "?" boxes), so GitHub shows the source text and the site animates it.
 - Tabler packs are generated: `node scripts/build-tabler.mjs <path to a tabler-icons checkout>` rewrites `tabler/*.js`. Do not edit those
   files by hand. The Tabler version is recorded in each file header and in `THIRD-PARTY-NOTICES.md`.
 - Add an entry to `CHANGELOG.md` for any user-visible change. Breaking changes also get a section in `docs/migrating.md`.

package/docs/getting-started.md

@@ -15,10 +15,14 @@ unofficial add-on for Pele and does not change how Pele lays out or draws diagra
 
 ```sh
 npm i pele-animate pele
+# or
+pnpm add pele-animate pele
+yarn add pele-animate pele
+bun add pele-animate pele
 ```
 
-`pele` is a peer dependency (`^1.7.0`). Both run in the browser: they need the DOM, so mount them on the client (see
-[recipes](./recipes.md) for frameworks).
+`pele` is a peer dependency (`^1.7.0`): install it alongside. Both run in the browser and need the DOM, so mount them on the client (see
+[recipes](./recipes.md) for frameworks). The packages are ESM only.
 
 ## First diagram
 
@@ -26,20 +30,20 @@ Put the Mermaid source in an element, then mount it with Pele and hand it to `wa
 
 ```js
 import { mount } from 'pele';
-import { watch } from 'pele-animate';
+import { watch, prepare } from 'pele-animate';
 import { icons } from 'pele-animate/glyphs';
 import 'pele-animate/tabler/computers'; // icons: one Tabler category, import as many as you need
 import 'pele-animate/style.css';
 
 const el = document.querySelector('pre.mermaid');
 const src = el.textContent;
-mount(el, src, { icons }); // Pele draws the SVG
+mount(el, prepare(src), { icons }); // Pele draws the SVG
 watch(el, src);            // pele-animate animates it, and re-applies when Pele re-lays-out on resize
 ```
 
 The Mermaid source:
 
-```mermaid live
+```mermaid-icons live
 flowchart LR
   %% pa: 1=C 2=L 3=S
   C@{ icon: "http-get", form: "square", h: 88, label: "Request" }

package/docs/how-it-works.md

@@ -16,7 +16,7 @@ Two layers, one diagram:
 
 ## The calls
 
-- `mount(el, src, { icons })` is Pele's. The `icons` option is how glyphs get in (see [icons](./icons.md)).
+- `mount(el, prepare(src), { icons })` is Pele's. The `icons` option is how glyphs get in (see [icons](./icons.md)).
 - `watch(el, src)` is pele-animate's. It marks the container as a scene (class `pa-scene`), animates each SVG Pele renders into
   it, and re-applies after Pele re-draws on resize. The intro is skipped on those re-draws once it has played.
 - `animate(svg, { source })` does one SVG. Use it if you render with Pele yourself and do not want `watch()`.

package/docs/icons.md

@@ -9,17 +9,18 @@ section: Guides
 
 A flowchart node becomes an illustrated node with Mermaid's own `@{ }` syntax:
 
-```mermaid live
+```mermaid-icons live
 flowchart LR
   A@{ icon: "device-desktop", form: "square", h: 88, label: "Laptop" }
   B@{ icon: "server", form: "square", h: 88, label: "Server" }
-  A --> B
+  A -->|request| B
 ```
 
 Both names are in the Tabler `devices` category, so this needs `import 'pele-animate/tabler/devices'`.
 
 - `icon` is the glyph name. `label` is the caption.
 - `form: "square", h: 88` makes a large frameless icon. Leave both out for a small icon inside a frame.
+- Call `mount(el, prepare(src), { icons })` with `prepare` from `pele-animate`. Pele sizes an icon node from its label, so a label shorter than `h` would put edge ends and arrowheads under the icon; `prepare` pads the label so the box fits.
 - Unknown names get a neutral rounded square, never a blank slot. Pele ships no icons of its own, so every name must come
   from a pack you import.
 
@@ -60,6 +61,7 @@ Brand, Letters, Numbers, Zodiac and Gender are not included. Counts are for Tabl
 
 Do not guess names. Look them up:
 
+- The [icon browser](https://pele-animate.pages.dev/icons/) searches names and tags and copies a ready snippet; the same list is [icons.json](https://pele-animate.pages.dev/icons.json).
 - Tabler's own site, [tabler.io/icons](https://tabler.io/icons), lists names and categories (use the outline style).
 - In your project: `node_modules/pele-animate/tabler/<category>.js` lists every name in that category as an object key.
 - Names that exist in more than one place are not a problem: Tabler names are plain (`server`, `lock`), `doverunner-*` names are prefixed.

package/docs/recipes.md

@@ -13,14 +13,14 @@ rendered.** Load them with dynamic `import()` inside the framework's mounted hoo
 The shape is always:
 
 ```js
-const [{ mount }, { watch }, { icons }] = await Promise.all([
+const [{ mount }, { watch, prepare }, { icons }] = await Promise.all([
   import('pele'),
   import('pele-animate'),
   import('pele-animate/glyphs'),
   import('pele-animate/tabler/computers'), // your icon categories
   import('pele-animate/style.css'),
 ]);
-mount(el, src, { icons });
+mount(el, prepare(src), { icons });
 watch(el, src);
 ```
 
@@ -49,13 +49,13 @@ Notes for all of them:
 <script>
   // runs in the browser only
   import { mount } from 'pele';
-  import { watch } from 'pele-animate';
+  import { watch, prepare } from 'pele-animate';
   import { icons } from 'pele-animate/glyphs';
   import 'pele-animate/tabler/computers';
   import 'pele-animate/style.css';
   document.querySelectorAll('pre.mermaid').forEach((el) => {
     const src = el.textContent ?? '';
-    mount(el as HTMLElement, src, { icons });
+    mount(el as HTMLElement, prepare(src), { icons });
     watch(el as HTMLElement, src);
   });
 </script>
@@ -69,10 +69,10 @@ Notes for all of them:
   let el;
   const src = 'flowchart LR\n  A --> B';
   onMount(async () => {
-    const [{ mount }, { watch }, { icons }] = await Promise.all([
+    const [{ mount }, { watch, prepare }, { icons }] = await Promise.all([
       import('pele'), import('pele-animate'), import('pele-animate/glyphs'), import('pele-animate/style.css'),
     ]);
-    mount(el, src, { icons });
+    mount(el, prepare(src), { icons });
     watch(el, src);
   });
 </script>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pele-animate",
-  "version": "0.14.0",
+  "version": "0.15.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.js

@@ -77,6 +77,26 @@ function equalizeActors(svg) {
   }
 }
 
+// Pele sizes an icon node's layout box from its label alone but draws the icon at `h`, so a label narrower than the icon puts
+// the edge ends (and arrowheads) under the icon. Pad such labels with non-breaking spaces so the box is at least `h` wide.
+// Use as: mount(el, prepare(src), { icons }); keep passing the original `src` to watch().
+const NBSP = '\u00a0';
+const WJ = '\u2060'; // zero-width, not whitespace: keeps Pele from trimming the padding
+export function prepare(source = '') {
+  return source.replace(/@\{([^}]*)\}/g, (all, body) => {
+    const h = +/\bh:\s*(\d+)/.exec(body)?.[1];
+    if (!h) return all;
+    const label = /\blabel:\s*"([^"]*)"/.exec(body)?.[1] ?? '';
+    // ponytail: a character counts as ~7 px (a space too); a real measurer would be exact. Over-padding only widens the gap.
+    const need = Math.ceil(h / 7) - label.length;
+    if (need <= 0) return all;
+    const pad = NBSP.repeat(Math.ceil(need / 2));
+    const next = `label: "${WJ}${pad}${label}${pad}${WJ}"`;
+    return `@{${/\blabel:/.test(body) ? body.replace(/\blabel:\s*"[^"]*"/, next) : `${body.replace(/\s*$/, '')}, ${next} `}}`;
+  });
+}
+
+
 export function animate(svg, { hover = svg, source = '' } = {}) {
   fitGlyphs(svg);
   equalizeActors(svg);

package/skills/pele-animate/SKILL.md

@@ -30,12 +30,12 @@ npm i pele-animate pele        # or pnpm / yarn / bun; pele is a peer dependency
 ## 2. Mount (client side)
 
 ```js
-const [{ mount }, { watch }, { icons }] = await Promise.all([
+const [{ mount }, { watch, prepare }, { icons }] = await Promise.all([
   import('pele'), import('pele-animate'), import('pele-animate/glyphs'),
   import('pele-animate/tabler/computers'),   // one import per icon category you use
   import('pele-animate/style.css'),
 ]);
-mount(el, src, { icons });   // Pele draws the SVG from the Mermaid text in `src`
+mount(el, prepare(src), { icons });   // Pele draws the SVG from the Mermaid text in `src`
 watch(el, src);              // pele-animate animates it (also on resize)
 ```
 
@@ -58,7 +58,7 @@ TypeScript: a CSS side-effect import needs a `*.css` module declaration unless t
 
 Icon nodes use Mermaid's own syntax:
 
-```mermaid
+```mermaid-icons
 flowchart LR
   %% pa: 1=C 2=L 3=S
   C@{ icon: "http-get", form: "square", h: 88, label: "Request" }

package/types/index.d.ts

@@ -27,6 +27,8 @@ export function parseOrder(source?: string): Map<string, number>;
 export function animate(svg: SVGSVGElement, options?: AnimateOptions): void;
 
 /** Animate every svg Pele renders into `container`, re-applying after Pele re-lays-out on resize. */
+/** Pad icon-node labels narrower than `h` so Pele's layout box is at least as wide as the drawn icon. Use as `mount(el, prepare(src), { icons })`; pass the original `src` to `watch()`. */
+export function prepare(source?: string): string;
 export function watch(container: HTMLElement, source?: string, options?: WatchOptions): void;
 
 /** Play the intro again. */