@statewalker/fsm-charts 0.0.1

package/src/layout/StateChart.ts

@@ -0,0 +1,8 @@
+import type { TransitionsGraph } from "./TransitionsGraph.ts";
+
+export type StateChart = {
+  id: string;
+  key: string;
+  children?: StateChart[];
+  graph: TransitionsGraph;
+} & Record<string, any>;

package/src/layout/StateGraphEdge.ts

@@ -0,0 +1,14 @@
+import { Dimensions } from "./Dimensions.ts";
+import { Position } from "./Position.ts";
+
+/**
+ * Information about a state graph edge.
+ */
+export type StateGraphEdge = Dimensions &
+  Position & {
+    id: string;
+    from: string;
+    event: string;
+    to: string;
+    points: Position[];
+  } & Record<string, any>;

package/src/layout/StateGraphNode.ts

@@ -0,0 +1,12 @@
+import { Dimensions } from "./Dimensions";
+import { Position } from "./Position";
+
+/**
+ * Information about a state node in the graph.
+ */
+export type StateGraphNode = Dimensions &
+  Position & {
+    id: string;
+    key: string;
+    state: string;
+  } & Record<string, any>;

package/src/layout/Transition.ts

@@ -0,0 +1,5 @@
+/**
+ * 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.
+ */
+export type Transition = [string, string, string];

package/src/layout/TransitionsGraph.ts

@@ -0,0 +1,13 @@
+import { Dimensions } from "./Dimensions.ts";
+import { Position } from "./Position.ts";
+import { StateGraphEdge } from "./StateGraphEdge.ts";
+import { StateGraphNode } from "./StateGraphNode.ts";
+
+/**
+ * Coordinates for state nodes and endges corresponding to state transitions.
+ */
+export type TransitionsGraph = Position &
+  Dimensions & {
+    nodes: StateGraphNode[];
+    edges: StateGraphEdge[];
+  };

package/src/layout/buildCharts.ts

@@ -0,0 +1,74 @@
+import type { GraphParamsProvider } from "./GraphParamsProvider.ts";
+import type { StateGraphNode } from "./StateGraphNode.ts";
+import type { StateGraphEdge } from "./StateGraphEdge.ts";
+import type { Padding } from "./Padding.ts";
+import type { Position } from "./Position.ts";
+import type { Dimensions } from "./Dimensions.ts";
+import type { FsmStateConfig } from "../FsmStateConfig.ts";
+import type { StateChart } from "./StateChart.ts";
+
+import { layout } from "../dagre/layout.js";
+import { Graph } from "../graphlib/graph.js";
+import { getPadding } from "../utils/getPadding.ts";
+import { getLodash, setLodash } from "../lodash-es/index.ts";
+import { buildFlatCharts } from "./buildFlatCharts.ts";
+/**
+ * Build graphs corresponding to the specified transitions.
+ * @param config - State configuration with transitions and sub-states.
+ * @param newId - A function that generates unique ids for nodes and edges.
+ * @param getStateParams - A function that returns the dimensions of a state node.
+ * @param getTransitionParams - A function that returns the dimensions of a transition edge.
+ * @param initialStateKey - The key for the initial state.
+ * @param finalStateKey - The key for the final state.
+ * @returns {StateChart} - The graph with nodes and edges.
+ */
+export function buildCharts({
+  lodash,
+  config,
+  newId,
+  getStateParams,
+  getTransitionParams,
+  padding = [5, 5],
+  initialStateKey = "<initial>",
+  finalStateKey = "<final>",
+}: {
+  config: FsmStateConfig;
+  lodash: any;
+  newId: (prefix: string) => string;
+  initialStateKey?: string;
+  finalStateKey?: string;
+  padding?: Padding;
+} & GraphParamsProvider): StateChart {
+  return buildChart(config);
+
+  function buildChart(config: FsmStateConfig, id: string = newId("state")) {
+    const graph = buildFlatCharts({
+      lodash,
+      transitions: config.transitions,
+      newId,
+      getStateParams,
+      getTransitionParams,
+      padding,
+      initialStateKey,
+      finalStateKey,
+    });
+    const index = graph.nodes.reduce((index, node) => {
+      index[node.key as string] = node.id as string;
+      return index;
+    }, {} as Record<string, string>);
+
+    const children: StateChart[] = [];
+    if (config.states) {
+      for (const child of config.states) {
+        const childId = index[child.key];
+        children.push(buildChart(child, childId));
+      }
+    }
+    return {
+      id,
+      key: config.key,
+      graph,
+      children,
+    };
+  }
+}

package/src/layout/buildFlatCharts.ts

@@ -0,0 +1,142 @@
+import { layout } from "../dagre/layout.js";
+import { Graph } from "../graphlib/graph.js";
+
+import type { GraphParamsProvider } from "./GraphParamsProvider.ts";
+import type { Transition } from "./Transition.ts";
+import type { TransitionsGraph } from "./TransitionsGraph.ts";
+import type { StateGraphNode } from "./StateGraphNode.ts";
+import type { StateGraphEdge } from "./StateGraphEdge.ts";
+import { Padding } from "./Padding.ts";
+import { getPadding } from "../utils/getPadding.ts";
+import { Position } from "./Position.ts";
+import { Dimensions } from "./Dimensions.ts";
+import { getLodash, setLodash } from "../lodash-es/index.ts";
+
+/**
+ * Build graphs corresponding to the specified transitions.
+ * @param transitions - The transitions between states.
+ * @param newId - A function that generates unique ids for nodes and edges.
+ * @param getStateParams - A function that returns the dimensions of a state node.
+ * @param getTransitionParams - A function that returns the dimensions of a transition edge.
+ * @param initialStateKey - The key for the initial state.
+ * @param finalStateKey - The key for the final state.
+ * @param vertical - Whether the graph should be vertical.
+ * @returns {TransitionsGraph} - The graph with nodes and edges.
+ */
+
+export function buildFlatCharts({
+  lodash,
+  transitions,
+  newId,
+  getStateParams,
+  getTransitionParams,
+  padding = [5, 5],
+  initialStateKey = "<initial>",
+  finalStateKey = "<final>",
+  vertical = false,
+}: {
+  transitions: Transition[];
+  lodash: any;
+  newId: (prefix: string) => string;
+  initialStateKey?: string;
+  finalStateKey?: string;
+  vertical?: boolean;
+  padding?: Padding;
+} & GraphParamsProvider): TransitionsGraph {
+  let prevLodash = getLodash();
+  try {
+    setLodash(lodash);
+    const graph = new Graph({
+      directed: true,
+    })
+      .setGraph({ rankdir: vertical ? "tb" : "lr" })
+      .setDefaultEdgeLabel(() => ({}));
+
+    const nodesIndex: Record<string, string> = {};
+
+    const getStateNodeId = (key: string, state: string = key) => {
+      let id = nodesIndex[key];
+      if (!id) {
+        id = nodesIndex[key] = newId("s");
+        const params = getStateParams(key, state);
+        graph.setNode(id, { id, ...params });
+      }
+      return id;
+    };
+
+    for (const [fromState, event, toState] of transitions) {
+      const fromStateKey = fromState || initialStateKey;
+      const from = getStateNodeId(fromStateKey, fromState);
+      const toStateKey = toState || finalStateKey;
+      const to = getStateNodeId(toStateKey, toState);
+      const params = getTransitionParams(fromStateKey, event, toStateKey);
+      graph.setEdge(from, to, {
+        id: newId("t"),
+        ...params,
+      });
+    }
+    layout(graph, { rankdir: vertical ? "tb" : "lr" });
+
+    const [top, right, bottom, left] = getPadding(padding);
+
+    const nodes = graph.nodes().map((id: string) => {
+      const n = graph.node(id) as StateGraphNode;
+      n.x += -n.width / 2;
+      n.y += -n.height / 2;
+      return n;
+    });
+    const edges = graph
+      .edges()
+      .map(({ v, w, name }: { v: string; w: string; name: string }) => {
+        const e = graph.edge(v, w, name) as StateGraphEdge;
+        e.x += -e.width / 2;
+        e.y += -e.height / 2;
+        return e;
+      });
+
+    // Get the bounding box of the graph
+    let x = 0;
+    let y = 0;
+    let width = 0;
+    let height = 0;
+    const addCoords = (node: StateGraphNode | StateGraphEdge) => {
+      x = Math.min(x, node.x);
+      y = Math.min(y, node.y);
+      width = Math.max(width, node.x + node.width);
+      height = Math.max(height, node.y + node.height);
+    };
+    nodes.forEach(addCoords);
+    edges.forEach(addCoords);
+    edges.forEach((edge) => {
+      for (const point of edge.points) {
+        x = Math.min(x, edge.x);
+        y = Math.min(y, edge.y);
+        width = Math.max(width, point.x);
+        height = Math.max(height, point.y);
+      }
+    });
+
+    // Shift the graph to the origin taking into account the padding
+    // Invert coordinates.
+    width += left + right;
+    height += bottom + top;
+    const updateCoords = (node: Position) => {
+      node.x = Math.round(node.x + left);
+      node.y = Math.round(node.y + bottom);
+      // node.y = node.y + bottom;
+    };
+    const updateBox = (node: Position & Dimensions) => {
+      updateCoords(node);
+      node.y = Math.round(node.y + node.height);
+    };
+    nodes.forEach(updateBox);
+    edges.forEach(updateBox);
+    edges.forEach((edge) => {
+      edge.points.forEach(updateCoords);
+    });
+
+    return { x, y, width, height, nodes, edges };
+  } finally {
+    setLodash(prevLodash);
+  }
+}

package/src/layout/getGraphParamsProvider.ts

@@ -0,0 +1,63 @@
+import type { Dimensions } from "./Dimensions.ts";
+import { getLabelDimensions } from "./getLabelDimensions.ts";
+import { getPadding } from "../utils/getPadding.ts";
+import type { GraphParamsProvider } from "./GraphParamsProvider.ts";
+import type { Padding } from "./Padding.ts";
+
+/**
+ * Provides default functions measuring dimensions for state nodes and transition edges in the graph.
+ * @param fontSize - The font size for the state and transition labels.
+ * @param stateFontSize - The font size for the state labels.
+ * @param stateTextPadding - The padding around the state labels.
+ * @param transitionsFontSize - The font size for the transition labels.
+ * @param transitionsTextPadding - The padding around the transition labels.
+ */
+export function getGraphParamsProvider({
+  fontSize = 14,
+  stateFontSize = fontSize,
+  stateTextPadding = 0,
+  transitionsFontSize = fontSize,
+  transitionsTextPadding = 0,
+}: {
+  fontSize?: number;
+  stateFontSize?: number;
+  stateTextPadding?: Padding;
+  transitionsFontSize?: number;
+  transitionsTextPadding?: Padding;
+} = {}): GraphParamsProvider {
+  return {
+    getStateParams: (stateKey: string, state: string = stateKey) => {
+      const padding = getPadding(stateTextPadding);
+      const fontSize = stateFontSize;
+      return {
+        ...getLabelDimensions(state, {
+          padding,
+          fontSize,
+        }),
+        state,
+        key: stateKey,
+        padding,
+        fontSize,
+      };
+    },
+    getTransitionParams: (
+      fromStateKey: string,
+      event: string,
+      toStateKey: string
+    ): Dimensions & Record<string, any> => {
+      const padding = getPadding(transitionsTextPadding);
+      const fontSize = transitionsFontSize;
+      return {
+        ...getLabelDimensions(event, {
+          padding,
+          fontSize,
+        }),
+        from: fromStateKey,
+        event,
+        to: toStateKey,
+        padding,
+        fontSize,
+      };
+    },
+  };
+}

package/src/layout/getLabelDimensions.ts

@@ -0,0 +1,59 @@
+import type { Dimensions } from "./Dimensions.ts";
+import type { Padding } from "./Padding.ts";
+import { getPadding } from "../utils/getPadding.ts";
+
+export function getLabelDimensions(
+  label: string,
+  {
+    padding = 0,
+    fontSize = 14,
+    getCharWidth = () => fontSize / 1.61, // Golden ratio and all that jazz :-)
+    lineGap = fontSize * 0.2,
+  }: {
+    padding?: Padding;
+    fontSize?: number;
+    getCharWidth?: (char: string) => number;
+    lineGap?: number;
+  } = {}
+) {
+  const lines = [label]; // label.split("\n");
+  let dimensions: Dimensions = { width: 0, height: 0 };
+  let lineNumber = 0;
+  for (const line of lines) {
+    if (lineNumber++) dimensions.height += lineGap;
+    dimensions = expandBox(
+      dimensions,
+      getLineDimensions({
+        line,
+        fontSize,
+        getCharWidth,
+      })
+    );
+  }
+  const [top, right, bottom, left] = getPadding(padding);
+  return {
+    width: Math.round(dimensions.width + left + right),
+    height: Math.round(dimensions.height + top + bottom),
+  };
+  function expandBox(dim1: Dimensions, dim2: Dimensions) {
+    return {
+      width: Math.round(Math.max(dim1.width, dim2.width)),
+      height: Math.round(dim1.height + dim2.height),
+    };
+  }
+
+  function getLineDimensions({
+    line,
+    fontSize = 14,
+    getCharWidth = () => fontSize,
+  }: {
+    line: string;
+    fontSize?: number;
+    getCharWidth?: (char: string[1]) => number;
+  }) {
+    return {
+      width: line.split("").reduce((w, c) => (w += getCharWidth(c)), 0),
+      height: fontSize,
+    };
+  }
+}

package/src/layout/index.ts

@@ -0,0 +1,15 @@
+// Methods
+export * from "./buildFlatCharts.ts";
+export * from "./buildCharts.ts";
+export * from "./getGraphParamsProvider.ts";
+export * from "./getLabelDimensions.ts";
+
+// Types
+export * from "./Dimensions.ts";
+export * from "./GraphParamsProvider.ts";
+export * from "./Padding.ts";
+export * from "./Position.ts";
+export * from "./StateGraphEdge.ts";
+export * from "./StateGraphNode.ts";
+export * from "./Transition.ts";
+export * from "./TransitionsGraph.ts";