@statewalker/fsm-charts 0.2.5 → 0.2.6

package/README.md

@@ -1 +1,206 @@
-# @statewalker/fsm-charts: Visualization of Hierarchical Finite State Machines
+# @statewalker/fsm-charts
+
+## What it is: statechart layout and rendering for HFSM configurations
+
+Turns a hierarchical state machine (HFSM) configuration (`{ key, transitions, states }`,
+the format `@statewalker/fsm` runs) into a statechart. It lays the chart out with a
+vendored copy of dagre, writes SVG/HTML and CSS as strings, and provides a runtime API
+that highlights states and transitions on the rendered chart. `@statewalker/fsm-viewer`
+builds a ready-made browser viewer on top of it.
+
+## Why it exists: a nested state machine is hard to read as JSON
+
+A configuration with several levels of nested states and wildcard transitions is hard to
+follow as text. This package draws each composite state as its own chart, nested the same
+way the states are, so the structure and the transitions out of every state are visible.
+It works from the configuration alone and does not import `@statewalker/fsm`, so drawing
+a machine does not require running it.
+
+## How to use: lay out, render to strings, then bind to the DOM
+
+```sh
+pnpm add @statewalker/fsm-charts lodash-es
+```
+
+The package has no runtime dependencies, but the layout functions need a lodash object
+passed in as the `lodash` option. Either `lodash` or `lodash-es` works.
+
+```
+FsmStateConfig --buildCharts--> StateChart --buildStatechartsPanel--> HTML + SVG strings
+                                    |        --buildStatechartCss-----> CSS string
+                                    |
+                                    +--> StateChartIndex (key <-> id lookups)
+                                    +--> RuntimeStatechartApi (highlight, panels, clicks on the DOM)
+```
+
+The only entry point is the package root, `@statewalker/fsm-charts` (`dist/index.js` with
+`.d.ts` types; sources are published in `src/`). It is ESM only.
+
+The `config`, `layout` and `html` functions produce plain strings and objects and run
+anywhere, including Node.js. The `dom` helpers and `RuntimeStatechartApi` work on DOM
+elements and need a browser or a DOM implementation such as jsdom.
+
+### What each export is for
+
+**Config**
+
+- `serializeProcessConfig(config)` - format a configuration as JSON text with one
+  transition per line.
+- `splitTransitionString(str)` - parse a chain such as `"Idle -play-> Active -stop-> Idle"`
+  into `[from, event, to]` tuples; `concatTransitionsToString(transitions)` does the
+  reverse.
+- `toFsmStateConfig(json)` - normalize a loosely written configuration (transitions as
+  strings or arrays, duplicates removed) into an `FsmStateConfig`.
+
+**Layout**
+
+- `buildCharts({ lodash, config, newId, ...graphParams })` - lay out the whole state
+  tree. Returns a `StateChart` (nested charts with nodes, edges, sizes). Options:
+  `direction`, `vertical`, `padding`, `getStateLabel`, `initialStateKey`
+  (default `"<initial>"`), `finalStateKey` (default `"<final>"`).
+- `buildFlatCharts(...)` - lay out one flat transition graph (a `TransitionsGraph`).
+- `getGraphParamsProvider({ fontSize, stateFontSize, stateTextPadding, transitionsFontSize, transitionsTextPadding, ... })`
+  - default `getStateParams` / `getTransitionParams` functions that size nodes and
+  edges from their labels.
+- `getLabelDimensions(label, options)` - estimate label size from font size and
+  character width.
+
+**HTML and CSS**
+
+- `buildStatechartsPanel({ statechart, newId, println })` - write nested `<details>`
+  panels, one per composite state, each with its SVG chart.
+- `buildStatechartSvg({ graph, newId, println, ... })` - write the SVG of one chart.
+- `buildStatechartCss({ prefix })` - the stylesheet for the charts, scoped to `prefix`
+  (default `:root`). `buildStatechartStyles`, `buildStatechartStylesWithModifier`,
+  `buildStateDetailsStyle`, `buildStateDetailsStyleWithModifier` and the
+  `activeStatesStyle` / `activeTransitionsStyle` / `selectedStatesStyle` /
+  `selectedTransitionsStyle` objects are its building blocks.
+- `serializeCss(tree)` and `toKebabCase(str)` - CSS helpers.
+
+**DOM** (browser)
+
+- `buildSections`, `visitSectionNodes`, `vistSections`, `findSection`, `visitDom`,
+  `toDomNodesIterator`, `isDomElement` - split a document into sections by headings.
+- `getStatesDescriptions({ element, rootStateKey })`, `visitStateDescriptions` - read
+  per-state descriptions from a document section whose heading matches the root state.
+- `getStateDescriptionRenderer`, `renderSections`, `newTreeBuilder` - helpers to render
+  those descriptions.
+
+**Runtime**
+
+- `StateChartIndex({ statechart })` - lookups over a built chart: `getStatesIds(...keys)`,
+  `getStackByStateId(id)`, `getTransitions(stateId)`, `getEdgeById(id)`,
+  `getStateNodes()` and more.
+- `RuntimeStatechartApi({ element, statechart })` - acts on the rendered chart:
+  `selectState` / `deselectState(s)`, `selectTransition` / `deselectTransition(s)`
+  with a modifier (`"selected"` by default, `"active"` for the running state),
+  `openStatePanel` / `closeStatePanel(s)`, `setStateDescription`, `onStateClick`,
+  `onTransitionClick`, `close()`.
+
+Types such as `StateChart`, `StateGraphNode`, `StateGraphEdge`, `FsmStateConfig` and
+`GraphParamsProvider` are exported as well.
+
+## Examples
+
+### Draw a configuration and highlight a state
+
+```js
+import * as lodash from "lodash-es";
+import {
+  buildCharts,
+  buildStatechartCss,
+  buildStatechartsPanel,
+  getGraphParamsProvider,
+  RuntimeStatechartApi,
+  StateChartIndex,
+} from "@statewalker/fsm-charts";
+
+let counter = 0;
+const newId = (prefix) => `${prefix}-${++counter}`;
+
+const config = {
+  key: "Player",
+  transitions: [
+    ["", "*", "Idle"],
+    ["Idle", "play", "Active"],
+    ["*", "stop", "Idle"],
+  ],
+  states: [
+    { key: "Idle" },
+    {
+      key: "Active",
+      transitions: [
+        ["", "*", "Playing"],
+        ["Playing", "pause", "Paused"],
+        ["Paused", "play", "Playing"],
+      ],
+    },
+  ],
+};
+
+// 1. Layout: nested charts with node and edge geometry.
+const statechart = buildCharts({
+  lodash,
+  config,
+  newId,
+  direction: "lr", // "tb" | "bt" | "lr" | "rl"
+  ...getGraphParamsProvider({ fontSize: 12 }),
+});
+
+// 2. Render: HTML (nested <details> panels with SVG charts) and CSS.
+const lines = [];
+buildStatechartsPanel({ statechart, newId, println: (line) => lines.push(line) });
+const element = document.createElement("div");
+element.id = "chart";
+element.innerHTML = lines.join("\n");
+const style = document.createElement("style");
+style.textContent = buildStatechartCss({ prefix: "#chart" });
+element.append(style);
+document.body.append(element);
+
+// 3. Runtime: map state keys to chart ids and highlight them.
+const index = new StateChartIndex({ statechart });
+const api = new RuntimeStatechartApi({ element, statechart });
+for (const id of index.getStatesIds("Player", "Active", "Playing")) {
+  api.selectState(id, "active");
+  api.openStatePanel(id);
+}
+api.onStateClick((stateId) => console.log(index.getStackByStateId(stateId)));
+```
+
+### Print a configuration compactly
+
+```js
+import { serializeProcessConfig, splitTransitionString } from "@statewalker/fsm-charts";
+
+console.log(serializeProcessConfig(config)); // JSON text, one transition per line
+console.log(splitTransitionString("Idle -play-> Active -stop-> Idle"));
+// [["Idle", "play", "Active"], ["Active", "stop", "Idle"]]
+```
+
+## Internals: vendored layout, injected lodash
+
+- **Layout.** `buildCharts` walks the state tree and lays out each composite state as a
+  separate flat graph with `buildFlatCharts`, which uses the vendored dagre and graphlib
+  sources in `src/dagre` and `src/graphlib`. Pseudo-states are drawn as `"<initial>"` and
+  `"<final>"` nodes; both keys can be changed with `initialStateKey` / `finalStateKey`.
+- **Rendering is string output.** `buildStatechartsPanel` and `buildStatechartSvg` write
+  lines through a `println` callback instead of creating DOM nodes, so the same code
+  renders in a browser, in Node.js, or into a file.
+- **Styling is by CSS variables and modifiers.** `buildStatechartCss` emits rules for the
+  `selected` and `active` modifiers that `RuntimeStatechartApi` toggles, scoped to a
+  `prefix` selector so several charts can share a page.
+- **lodash is injected.** The vendored dagre code calls lodash through a module-level
+  holder that `buildFlatCharts` sets from the `lodash` option, so the host decides which
+  lodash build ends up in its bundle. Without it, layout fails with
+  `TypeError: Cannot read properties of undefined (reading 'has')`.
+- **Entry points by area.** Besides the package root (everything), each area is its own
+  entry: `@statewalker/fsm-charts/config`, `/layout`, `/html`, `/dom` and `/runtime`. Layout
+  and HTML generation import no DOM code, so a Node.js or worker build can take
+  `/layout` and `/html` alone.
+- **Dependencies.** Zero runtime dependencies. dagre and graphlib are vendored; lodash
+  comes from the caller.
+
+## License
+
+MIT.

package/dist/StateChart-cXyVRcs-.d.ts

@@ -0,0 +1,94 @@
+//#region src/types/Dimensions.d.ts
+/**
+ * Visual element dimensions.
+ * @typedef {Object} Dimensions
+ */
+type Dimensions = {
+  width: number;
+  height: number;
+};
+//#endregion
+//#region src/types/Transition.d.ts
+/**
+ * A transition from one state to another.
+ * Contains the state before the transition, the event that triggers the transition, and the state after the transition.
+ */
+type Transition = [string, string, string];
+//#endregion
+//#region src/types/FsmStateConfig.d.ts
+type FsmStateConfig = {
+  key: string;
+  transitions?: Transition[];
+  states?: FsmStateConfig[];
+} & Record<string, any>;
+//#endregion
+//#region src/types/Label.d.ts
+/**
+ * Human-readable label
+ */
+type Label = {
+  text: string;
+};
+//#endregion
+//#region src/types/GraphParamsProvider.d.ts
+/**
+ * Provides default functions measuring dimensions for state nodes and transition edges in the graph.
+ */
+type GraphParamsProvider = {
+  getStateParams: (stateKey: string, state?: string) => Dimensions & Label & Record<string, any>;
+  getTransitionParams: (fromStateKey: string, event: string, toStateKey: string) => Dimensions & Label & Record<string, any>;
+};
+//#endregion
+//#region src/types/Padding.d.ts
+/**
+ * Padding type.
+ */
+type Padding = [number, number, number, number] | [number, number] | number;
+//#endregion
+//#region src/types/Position.d.ts
+/**
+ * X/Y position of a node in the graph.
+ */
+type Position = {
+  x: number;
+  y: number;
+};
+//#endregion
+//#region src/types/StateGraphNode.d.ts
+/**
+ * Information about a state node in the graph.
+ */
+type StateGraphNode = Dimensions & Position & {
+  id: string;
+  key: string;
+  text: string;
+} & Record<string, any>;
+//#endregion
+//#region src/types/StateGraphEdge.d.ts
+/**
+ * Information about a state graph edge.
+ */
+type StateGraphEdge = Dimensions & Position & {
+  id: string;
+  from: string;
+  event: string;
+  to: string;
+  points: Position[];
+} & Record<string, any>;
+//#endregion
+//#region src/types/TransitionsGraph.d.ts
+/**
+ * Coordinates for state nodes and endges corresponding to state transitions.
+ */
+type TransitionsGraph = Position & Dimensions & {
+  nodes: StateGraphNode[];
+  edges: StateGraphEdge[];
+};
+//#endregion
+//#region src/types/StateChart.d.ts
+type StateChart = TransitionsGraph & StateGraphNode & {
+  children?: StateChart[];
+} & Record<string, any>;
+//#endregion
+export { Position as a, Label as c, Dimensions as d, StateGraphNode as i, FsmStateConfig as l, TransitionsGraph as n, Padding as o, StateGraphEdge as r, GraphParamsProvider as s, StateChart as t, Transition as u };
+//# sourceMappingURL=StateChart-cXyVRcs-.d.ts.map

package/dist/StateChart-cXyVRcs-.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StateChart-cXyVRcs-.d.ts","names":[],"sources":["../src/types/Dimensions.ts","../src/types/Transition.ts","../src/types/FsmStateConfig.ts","../src/types/Label.ts","../src/types/GraphParamsProvider.ts","../src/types/Padding.ts","../src/types/Position.ts","../src/types/StateGraphNode.ts","../src/types/StateGraphEdge.ts","../src/types/TransitionsGraph.ts","../src/types/StateChart.ts"],"mappings":";;;;;KAIY;EACV;EACA;;;;;;;;KCFU;;;KCOA;EACV;EACA,cAAc;EACd,SAAS;IACP;;;;;;KCZQ;EAEV;;;;;;;KCCU;EACV,iBAAiB,kBAAkB,mBAAmB,aAAa,QAAQ;EAC3E,sBACE,sBACA,eACA,uBACG,aAAa,QAAQ;;;;;;;KCThB;;;;;;KCAA;EAAa;EAAW;;;;;;;KCGxB,iBAAiB,aAC3B;EACE;EACA;EACA;IAEE;;;;;;KCNM,iBAAiB,aAC3B;EACE;EACA;EACA;EACA;EACA,QAAQ;IACN;;;;;;KCLM,mBAAmB,WAC7B;EACE,OAAO;EACP,OAAO;;;;KCRC,aAAa,mBACvB;EACE,WAAW;IACT"}

package/dist/StateChartIndex-BK2315qj.d.ts

@@ -0,0 +1,142 @@
+import { i as StateGraphNode, r as StateGraphEdge, t as StateChart } from "./StateChart-cXyVRcs-.js";
+//#region src/runtime/RuntimeStatechartApi.d.ts
+type RuntimeListener = (id: string) => void;
+declare class RuntimeStatechartApi {
+  element: HTMLElement;
+  statechart: StateChart;
+  _listenersCounter: number;
+  _transitionsClickListeners: Record<number, RuntimeListener>;
+  _statesClickListeners: Record<number, RuntimeListener>;
+  _registry: Record<number, () => void>;
+  constructor({ element, statechart }: {
+    element: HTMLElement;
+    statechart: StateChart;
+  });
+  close(): void;
+  onStateClick(listener: RuntimeListener): () => void;
+  onTransitionClick(listener: RuntimeListener): () => void;
+  openStatePanels(): void;
+  closeStatePanels(): void;
+  isStatePanelOpen(stateId: string): boolean;
+  toggleState(...stateIds: string[]): boolean;
+  activateStates(...stateIds: string[]): void;
+  focusStates(...stateIds: string[]): void;
+  setStateDescription(stateId: string, description: Node | string | undefined): void;
+  closeStatePanel(stateId: string): void;
+  openStatePanel(stateId: string): void;
+  deselectTransitions(modifier?: string): void;
+  deselectTransition(id: string, modifier?: string): void;
+  selectTransition(id: string, modifier?: string): void;
+  toggleTransition(id: string, modifier?: string): void;
+  isTransitionSelected(id: string, modifier?: string): boolean;
+  deselectStates(modifier?: string): void;
+  isStateSelected(id: string, modifier?: string): boolean;
+  deselectState(id: string, modifier?: string): void;
+  selectState(id: string, modifier?: string): void;
+  _addListener<T = Function>(index: Record<string, T>, listener: T): () => void;
+  _bindListeners(): void;
+  _setStatePanelStatus(selector: string, open: boolean): void;
+  _addStateModifier(cssSelector: string, modifier?: string): void;
+  _removeStateModifier(cssSelector: string, modifier?: string): void;
+  _applyStateModifier(cssSelector: string, modifier: string | undefined, apply: (elm: Element | null, className: string) => void): void;
+  _addTransitionsModifier(cssSelector: string, modifier?: string): void;
+  _removeTransitionsModifier(cssSelector: string, modifier?: string): void;
+  _applyTransitionsModifier(cssSelector: string, modifier: string | undefined, apply: (elm: Element | null, className: string) => void): void;
+}
+//#endregion
+//#region src/runtime/StateChartIndex.d.ts
+declare class StateChartIndex {
+  statechart: StateChart;
+  _chartsIndex: Record<string, StateChart>;
+  _nodesIndex: Record<string, StateGraphNode>;
+  _nodesParentsIndex: Record<string, string>;
+  _edgeIndex: Record<string, StateGraphEdge>;
+  _edgesParentsIndex: Record<string, string>;
+  initialStateKey: string;
+  finalStateKey: string;
+  constructor({ statechart, initialStateKey, finalStateKey }: {
+    statechart: StateChart;
+    initialStateKey?: string;
+    finalStateKey?: string;
+  });
+  /**
+   * Returns a state node or a chart by the specified identifier.
+   * @param id the id of a state node or a chart
+   * @returns a state node or a chart
+   */
+  getNodeById(id: string): StateGraphNode | undefined;
+  /**
+   * Returns a chart by the specified identifier.
+   * @param id the id of a state node or a chart
+   * @returns a state node or a chart
+   */
+  getChartById(id: string): StateChart | undefined;
+  /**
+   * Returns an edge by the specified identifier.
+   * @param id the id of a graph edge
+   * @returns a graph edge
+   */
+  getEdgeById(id: string): StateGraphEdge | undefined;
+  /**
+   * Returns a list of all nodes in this chart.
+   * @return a list of all nodes
+   */
+  getAllNodes(): StateGraphNode[];
+  /**
+   * Returns a list of all non-empty state nodes in this chart.
+   * The result excludes nodes for initial and fina states.
+   * @return a list of all non-empty state nodes
+   */
+  getStateNodes(): StateGraphNode[];
+  /**
+   * Transforms a stack of state keys to the corresponding identifiers.
+   * If a key in the stack was not found then this method returns
+   * an empty stack.
+   * @param stack a stack of state keys
+   * @returns a stack of state identifiers for the given states
+   */
+  getStatesIds(...stack: string[]): string[];
+  /**
+   * Returns graph nodes for the specified identifier.
+   * @param id the id of a  node
+   * @returns a stack of nodes
+   */
+  getStackByStateId(id?: string): StateGraphNode[];
+  /**
+   * Returns an edge object corresponding to the transition from the state
+   * @param stateId identifier of the source state
+   * @param event an event triggering the transition
+   * @returns graph edge
+   */
+  getTransition(stateId?: string, event?: string): StateGraphEdge | undefined;
+  /**
+   * Returns a list of edge objects corresponding to all transitions from the state
+   * @param stateId identifier of the source state
+   * @returns a list of graph edges
+   */
+  getTransitions(stateId?: string): StateGraphEdge[];
+  /**
+   * Returns a graph node corresponding to the specified state id.
+   * @param stateId identifier of the state
+   * @returns graph node
+   * @see getStateChart
+   */
+  getStateNode(stateId?: string): StateGraphNode | undefined;
+  /**
+   * Returns a chart corresponding to the specified state id.
+   * @param stateId identifier of the state
+   * @returns graph node
+   * @see getStateNode
+   */
+  getStateChart(stateId?: string): StateChart | undefined;
+  /**
+   * Returns ids of the previous and next state for the specified transition
+   * @param transition a graph edge instance defining transition
+   * @returns an array with two identifiers - [sourceStateId, targetStateId] - the source state id and target state id
+   */
+  getTransitionStateIds(transition?: StateGraphEdge): [string | undefined, string | undefined];
+  _buildIndexes(): void;
+}
+//#endregion
+export { RuntimeListener as n, RuntimeStatechartApi as r, StateChartIndex as t };
+//# sourceMappingURL=StateChartIndex-BK2315qj.d.ts.map

package/dist/StateChartIndex-BK2315qj.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StateChartIndex-BK2315qj.d.ts","names":[],"sources":["../src/runtime/RuntimeStatechartApi.ts","../src/runtime/StateChartIndex.ts"],"mappings":";;KAEY,mBAAmB;cAClB;EACX,SAAS;EACT,YAAY;EACZ;EACA,4BAA4B,eAAe;EAC3C,uBAAuB,eAAe;EACtC,WAAW;EAEX,cACE,SACA;IAEA,SAAS;IACT,YAAY;;EAOd;EAOA,aAAa,UAAU;EAGvB,kBAAkB,UAAU;EAI5B;EAGA;EAGA,iBAAiB;EAOjB,eAAe;EAaf,kBAAkB;EAQlB,eAAe;EAUf,oBAAoB,iBAAiB,aAAa;EAUlD,gBAAgB;EAGhB,eAAe;EAIf,oBAAoB;EAGpB,mBAAmB,YAAY;EAG/B,iBAAiB,YAAY;EAG7B,iBAAiB,YAAY;EAS7B,qBAAqB,YAAY;EAMjC,eAAe;EAGf,gBAAgB,YAAY;EAK5B,cAAc,YAAY;EAG1B,YAAY,YAAY;EAMxB,aAAa,IAAI,UAAU,OAAO,eAAe,IAAI,UAAU;EAQ/D;EA+BA,qBAAqB,kBAAkB;EAOvC,kBAAkB,qBAAqB;EAGvC,qBAAqB,qBAAqB;EAG1C,oBACE,qBACA,8BACA,QAAQ,KAAK,gBAAgB;EAgB/B,wBAAwB,qBAAqB;EAG7C,2BAA2B,qBAAqB;EAGhD,0BACE,qBACA,8BACA,QAAQ,KAAK,gBAAgB;;;;cCzNpB;EACX,YAAY;EACZ,cAAc,eAAe;EAC7B,aAAa,eAAe;EAC5B,oBAAoB;EACpB,YAAY,eAAe;EAC3B,oBAAoB;EACpB;EACA;EAEA,cACE,YACA,iBACA;IAEA,YAAY;IACZ;IACA;;;;;;;EAcF,YAAY,aAAa;;;;;;EASzB,aAAa,aAAa;;;;;;EAS1B,YAAY,aAAa;;;;;EAQzB,eAAe;;;;;;EASf,iBAAiB;;;;;;;;EAajB,gBAAgB;;;;;;EAkBhB,kBAAkB,cAAc;;;;;;;EAqBhC,cAAc,kBAAkB,iBAAiB;;;;;;EAcjD,eAAe,mBAAmB;;;;;;;EAclC,aAAa,mBAAmB;;;;;;;EAUhC,cAAc,mBAAmB;;;;;;EASjC,sBAAsB,aAAa;EAoBnC"}