autovisualizer 0.6.0 → 0.8.0

package/README.md

@@ -88,9 +88,29 @@ export const door = createMachine({ id: "door", initial: "closed", states: { clo
 | `audio-src` | A recorded clip per step: `audio-src="audio/{step}.wav"`. A clip that can't play falls back to `speak`. |
 | `counts` | How often each transition was taken, as JSON keyed by state then event: `{"payment":{"PAID":120,"DECLINED":0}}`. Each count shows on its event, and a transition taken 0 times is drawn dashed: a path the code allows that nothing took. Name a state by its key or its full id (`checkout.payment`). |
 | `direction` | `auto` (default), `right` or `down`. `auto` lays the chart out both ways and keeps the one that shows it larger in its space: a long chain goes top to bottom in a wide column, a wide machine left to right in a short box, and a small machine that fits either way goes right. |
+| `base` | The machine before a change, as MachineJSON or `#id` of an element holding it. The chart shows the change: added states and transitions in green, removed ones dashed and red, and a state the change left unreachable flagged. |
+| `colors` | A colour per state, as JSON keyed by state key or full id: `colors='{"payment":"purple","refund":"#e8a33d"}'`. Any CSS colour; the state gets a wash of it in light and dark themes alike. |
+| `caption` | A line under the chart saying what it shows. Screen readers announce the chart by it. |
 
 An event the machine doesn't accept, or a `machine` id it doesn't create, shows an error in the chart.
 
+A state's `description` (XState's own field) is drawn under its name, wrapped to fit.
+
+**Show a change.** Give the earlier version as `base`, and the chart draws the later one with what changed marked:
+
+```html
+<script type="application/json" id="checkout-before">{ ... }</script>
+<auto-visualizer src="/machines/checkout.json" base="#checkout-before"
+  caption="RETRY now loops back into payment; refund can no longer be reached."></auto-visualizer>
+```
+
+**Theme it.** Set the chart's colours from your own CSS with `--autoviz-*` properties: each overrides the chart token of the same name (`--autoviz-active` for the active ring and sendable events). They include `--autoviz-canvas`, `--autoviz-grid`, `--autoviz-node`, `--autoviz-node-fg`, `--autoviz-node-border`, `--autoviz-edge`, `--autoviz-pill`, `--autoviz-pill-fg`, `--autoviz-active`, `--autoviz-added` and `--autoviz-removed`; `src/styles.css` lists every `--sc-*` token. One value applies in both themes, so give the dark theme its own:
+
+```css
+auto-visualizer { --autoviz-active: #e11d48; --autoviz-canvas: #fffaf0; }
+@media (prefers-color-scheme: dark) { auto-visualizer { --autoviz-canvas: #1a1410; } }
+```
+
 **Narrate the walkthrough.** Each step's note is its script. Add `speak` and the browser reads each note aloud, and `autoplay` moves on when the sentence ends:
 
 ```html
@@ -135,7 +155,7 @@ The events `events` and a walkthrough send are drawn as a path: each transition
 
 From React, set `walkthrough`, `counts`, `input` and `context` as JSON strings with `setAttribute` (or as attributes in markup). React renders before `embed.js` defines the element, so an object passed as a prop arrives as the text `[object Object]`.
 
-The chart shows states and events only, so it leaves the machine's name to your page. The mouse wheel and a one-finger swipe scroll the page; drag with the mouse, or use two fingers, to pan and zoom the chart. Charts load as they near the viewport, so a page with ten charts loads the ones your readers reach. Without a `height` in your CSS, the element sizes itself to the chart, between 240px and 720px tall plus the walkthrough bar, so a phone gets a short box instead of a tiny chart in empty space. A `height` in your CSS overrides that. It renders in a shadow root, so your page's styles don't reach in and its styles don't leak out. A chart written as code runs it in its own Web Worker, which needs the page served over HTTP; a chart from a definition runs on the page. `embed.d.ts` and `embed.react.d.ts` next to `embed.js` type the element for TypeScript and JSX.
+The chart shows states and events only, so it leaves the machine's name to your page. The mouse wheel and a one-finger swipe scroll the page; drag with the mouse, or use two fingers, to pan and zoom the chart. The button in the top-right corner shows the chart full screen; inside an iframe, give the iframe `allow="fullscreen"` to show it. Charts load as they near the viewport, so a page with ten charts loads the ones your readers reach. Without a `height` in your CSS, the element sizes itself to the chart, between 240px and 720px tall plus the walkthrough bar, so a phone gets a short box instead of a tiny chart in empty space. A `height` in your CSS overrides that. It renders in a shadow root, so your page's styles don't reach in and its styles don't leak out. `embed.js` carries its own stylesheet and fonts, so a page whose Content Security Policy allows only that script still gets a styled chart. A chart written as code runs it in its own Web Worker, which needs the page served over HTTP; a chart from a definition runs on the page. `embed.d.ts` and `embed.react.d.ts` next to `embed.js` type the element for TypeScript and JSX.
 
 ### In READMEs, issues and pull requests
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autovisualizer",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "See and step through XState v6 and @xstate/effect machines in the browser.",
   "license": "Apache-2.0",
   "author": "Jag Reehal",