jssm_viz | JSSM, a JavaScript state machine

Index

References

Functions

References

build_time

Re-exports build_time

version

Re-exports version

Type Aliases

VizRenderOpts

VizRenderOpts: { engine?: string; footer?: string; hide_state_labels?: boolean }

Options for the dot/SVG render entry points.

hide_state_labels (default false) — when true, the rendered dot output omits the label= attribute on every state's node line. Graphviz then draws the box without any text inside. Useful for diagrams where shape, color, or layout alone carry the meaning (icon-only diagrams, tutorial graphics, presentation slides).
footer — verbatim dot source inserted just before the closing } of the generated dot source (e.g. labelloc="b"; label="caption";).
engine — graphviz layout engine for the SVG render path (e.g. dot, neato, circo); honored by fsl_to_svg_string.

Type declaration

Optional engine?: string
Optional footer?: string
Optional hide_state_labels?: boolean

Variables

Const _test

_test: { color8to6: ((color8: string) => string); image_for_state: (<T>(u_jssm: Machine<T>, state: string) => string | undefined); node_of: ((state: string, state_index: string[] | Map<string, number> | Map<string, string>) => string); shape_for_state: (<T>(u_jssm: Machine<T>, state: string) => string | undefined); slug_for: ((state: string) => string); slug_states: ((states: string[]) => Map<string, string>); style_for_state: (<T>(u_jssm: Machine<T>, state: string) => string); u_color8to6: ((color8?: string) => string | undefined); vc: ((col: string) => string) } = ...

internal: — test-only access to private helpers.

Type declaration

color8to6: ((color8: string) => string)
- - (color8: string): string
  - Convert an 8-channel hex color (#RRGGBBAA) to a 6-channel hex color (#RRGGBB), discarding the alpha channel. Throws if the input is not a 9-character #-prefixed string.
    
    Graphviz dot does not support alpha; this is a lossy projection.
    
    internal
    Parameters
    - color8: string
    Returns string
image_for_state: (<T>(u_jssm: Machine<T>, state: string) => string | undefined)
- - <T>(u_jssm: Machine<T>, state: string): string | undefined
  - Read the image filename for a state through jssm.Machine.style_for, so theme-supplied images are honoured along with per-state declarations. Returns undefined if neither a theme nor a state declaration supplies an image.
    
    internal
    Type Parameters
    - T
    Parameters
    - u_jssm: Machine<T>
    - state: string
    Returns string | undefined
node_of: ((state: string, state_index: string[] | Map<string, number> | Map<string, string>) => string)
- - (state: string, state_index: string[] | Map<string, number> | Map<string, string>): string
  - Build a graphviz-safe node identifier for a state. Accepts either a string[] (legacy test-only path; returns an index-based n0/n1 identifier via indexOf), or a precomputed Map<state, slug> produced by slug_states (used by all rendering hot paths).
    When a slug map is supplied, the identifier is the slug wrapped in double quotes — dot allows quoted identifiers, and the slug alphabet (lowercase alphanumerics + -) requires quoting because bare dot IDs may not contain -. Graphviz round-trips the quoted form through to the SVG <title> element and uses the slug as a stable basis for the generated SVG element id attribute.
    
    node_of('Red Light', new Map([['Red Light', 'red-light']])); // '"red-light"'
    internal
    Parameters
    - state: string
    - state_index: string[] | Map<string, number> | Map<string, string>
    Returns string
shape_for_state: (<T>(u_jssm: Machine<T>, state: string) => string | undefined)
- - <T>(u_jssm: Machine<T>, state: string): string | undefined
  - Read the graphviz shape for a state through jssm.Machine.style_for, so theme-supplied shapes are honoured along with per-state declarations. Returns undefined if neither a theme nor a state declaration supplies a shape.
    
    internal
    Type Parameters
    - T
    Parameters
    - u_jssm: Machine<T>
    - state: string
    Returns string | undefined
slug_for: ((state: string) => string)
- - (state: string): string
  - Convert a state name into a URL-friendly slug suitable for use as the body of a dot/SVG node identifier. The transformation is:
    Lowercase
    
    Any run of characters outside [a-z0-9] (after lowercasing) becomes a single -
    
    Leading and trailing - are trimmed
    
    If the result is empty (e.g. for a state named "!!!"), the empty string is returned — callers are expected to fall back to an indexed placeholder like node-N. See slug_states for the collision- resolving wrapper that consumes this helper.
    
    slug_for('Green Light'); // 'green-light' slug_for('!!!'); // '' slug_for(' Foo Bar '); // 'foo-bar'
    internal
    Parameters
    - state: string
      
      The state name to slugify.
    Returns string
    The lowercase hyphen-separated slug, or empty string if none of the characters were retainable.
slug_states: ((states: string[]) => Map<string, string>)
- - (states: string[]): Map<string, string>
  - Build a Map<state, slug> assigning every state in states a unique, deterministic, URL-safe slug used as its dot/SVG node identifier.
    Algorithm:
    
    Slug each state via slug_for. States whose slug comes out empty fall back to node-N, where N is the state's declaration index (1-based, to match user-visible numbering).
    
    Walk the state list in declaration order, tracking how many times each base slug has already been used. The first occurrence keeps the base slug; subsequent collisions get -2, -3, … suffixes. If the proposed suffixed slug itself collides with a base slug used later, the counter advances until a free slot is found.
    
    This yields a deterministic mapping given the state-declaration order, so output is stable across runs.
    
    slug_states(['Red Light', 'red-light']); // Map { 'Red Light' => 'red-light', 'red-light' => 'red-light-2' } slug_states(['!!!', '???']); // Map { '!!!' => 'node-1', '???' => 'node-2' }
    internal
    Parameters
    - states: string[]
      
      States in declaration order.
    Returns Map<string, string>
    A Map from each state name to its unique slug.
style_for_state: (<T>(u_jssm: Machine<T>, state: string) => string)
- - <T>(u_jssm: Machine<T>, state: string): string
  - Compose a graphviz style string for a state by looking up its merged style via jssm.Machine.style_for, then delegating to {@link compose_style_string}. Theme-supplied corners and lineStyle are honoured along with per-state declarations.
    
    internal
    Type Parameters
    - T
    Parameters
    - u_jssm: Machine<T>
    - state: string
    Returns string
u_color8to6: ((color8?: string) => string | undefined)
- - (color8?: string): string | undefined
  - Variant of color8to6 that passes undefined through.
    
    internal
    Parameters
    - Optional color8: string
    Returns string | undefined
vc: ((col: string) => string)
- - (col: string): string
  - Look up a color from the default viz palette by key, returning empty string if the key is unknown (so it disappears in feature concatenation).
    
    internal
    Parameters
    - col: string
    Returns string

Functions

configure

configure(opts: { DOMParser?: { prototype: <internal>.DOMParser } }): void

- Defined in src/ts/jssm_viz.ts:70
Inject runtime configuration for jssm/viz. Currently only accepts a custom DOMParser constructor for use by *_svg_element functions in environments that do not provide one globally (e.g. Node + jsdom).
Idempotent — last call wins. No-op if called with no recognized keys.
```
// Node, with jsdom:
import { JSDOM } from 'jsdom';
import { configure, fsl_to_svg_element } from 'jssm/viz';

configure({ DOMParser: new JSDOM().window.DOMParser });
const el = await fsl_to_svg_element('a -> b;');
```
throws
{JssmError} if DOMParser is provided and is not a constructor.
Parameters
- opts: { DOMParser?: { prototype: <internal>.DOMParser } }
  
  Configuration overrides.
  - Optional DOMParser?: { prototype: <internal>.DOMParser }
    
    Constructor compatible with the WHATWG DOMParser interface. Used as a fallback when globalThis.DOMParser is undefined.
    - prototype: <internal>.DOMParser
Returns void

dot

dot<T>(machine: Machine<T>): string

- Defined in src/ts/jssm_viz.ts:907
Compatibility wrapper for machine_to_dot, retained from jssm-viz. Will be removed in the next major.

deprecated
Use machine_to_dot instead.

Type Parameters
- T
Parameters
- machine: Machine<T>
Returns string

dot_to_svg

dot_to_svg(dot: string, options?: { engine?: string }): Promise<string>

- Defined in src/ts/jssm_viz.ts:794
Render a graphviz dot source string to SVG using @viz-js/viz. The underlying viz instance is lazy-initialized on first call and cached for the lifetime of the module.
```
const svg = await dot_to_svg('digraph G { a -> b }');
const svg_neato = await dot_to_svg('digraph G { a -> b }', { engine: 'neato' });
```
Parameters
- dot: string
  
  Graphviz dot source.
- Optional options: { engine?: string }
  
  Optional renderer overrides.
  - Optional engine?: string
    
    Graphviz layout engine to use (e.g. 'dot', 'neato', 'circo'). Unrecognized engine names cause @viz-js/viz to throw at render time.
Returns Promise<string>
A promise resolving to an SVG XML string.

fsl_to_dot

fsl_to_dot(fsl: string, opts?: VizRenderOpts): string

Render an FSL string directly to graphviz dot source.

import { fsl_to_dot } from 'jssm/viz';
const dot = fsl_to_dot('a -> b;');

// suppress state-name labels
const dot2 = fsl_to_dot('a -> b;', { hide_state_labels: true });

const dot_with_footer = fsl_to_dot('a -> b;', { footer: 'label="caption";' });
// 'digraph G { ... label="caption"; }'

Parameters

fsl: string

The FSL source.
opts: VizRenderOpts = {}

Optional render flags. See VizRenderOpts.

Returns string

A complete graphviz dot source string.

fsl_to_svg_element

fsl_to_svg_element(fsl: string, opts?: VizRenderOpts): Promise<<internal>.SVGSVGElement>

- Defined in src/ts/jssm_viz.ts:879
Render an FSL string directly to a parsed SVGSVGElement.

throws
{JssmError} if no DOMParser is available (Node without configure).

Parameters
- fsl: string
  
  The FSL source.
- opts: VizRenderOpts = {}
  
  Optional render flags. See VizRenderOpts.
Returns Promise<<internal>.SVGSVGElement>
A promise resolving to a parsed SVGSVGElement.

fsl_to_svg_string

fsl_to_svg_string(fsl: string, opts?: VizRenderOpts): Promise<string>

- Defined in src/ts/jssm_viz.ts:814
Render an FSL string directly to SVG.
```
const svg = await fsl_to_svg_string('a -> b;');
const svg_neato = await fsl_to_svg_string('a -> b;', { engine: 'neato' });
```
Parameters
- fsl: string
  
  The FSL source.
- opts: VizRenderOpts = {}
  
  Optional render flags. See VizRenderOpts.
Returns Promise<string>
A promise resolving to an SVG XML string.

machine_to_dot

machine_to_dot<T>(u_jssm: Machine<T>, opts?: VizRenderOpts): string

- Defined in src/ts/jssm_viz.ts:731
Render a jssm.Machine as a graphviz dot string.
An optional footer may be supplied via opts.footer; it is emitted verbatim just before the closing } of the dot source, after all arrange declarations. This is a function-argument-only feature for the moment — a machine-attribute equivalent is planned as a follow-up.
```
import { sm } from 'jssm';
import { machine_to_dot } from 'jssm/viz';

const dot = machine_to_dot(sm`a -> b;`);
// 'digraph G { ... }'

// suppress state-name labels (boxes only, no text inside)
const dot2 = machine_to_dot(sm`a -> b;`, { hide_state_labels: true });

const dot_with_footer = machine_to_dot(sm`a -> b;`, { footer: 'labelloc="b"; label="caption";' });
// 'digraph G { ... labelloc="b"; label="caption"; }'
```
Type Parameters
- T
Parameters
- u_jssm: Machine<T>
  
  The machine to render.
- opts: VizRenderOpts = {}
  
  Optional render flags. See VizRenderOpts.
Returns string
A complete graphviz dot source string.

machine_to_svg_element

machine_to_svg_element<T>(u_jssm: Machine<T>, opts?: VizRenderOpts): Promise<<internal>.SVGSVGElement>

- Defined in src/ts/jssm_viz.ts:894
Render a jssm.Machine to a parsed SVGSVGElement.

throws
{JssmError} if no DOMParser is available (Node without configure).

Type Parameters
- T
Parameters
- u_jssm: Machine<T>
  
  The machine to render.
- opts: VizRenderOpts = {}
  
  Optional render flags. See VizRenderOpts.
Returns Promise<<internal>.SVGSVGElement>
A promise resolving to a parsed SVGSVGElement.

machine_to_svg_string

machine_to_svg_string<T>(u_jssm: Machine<T>, opts?: VizRenderOpts): Promise<string>

- Defined in src/ts/jssm_viz.ts:828
Render a jssm.Machine to SVG.

Type Parameters
- T
Parameters
- u_jssm: Machine<T>
  
  The machine to render.
- opts: VizRenderOpts = {}
  
  Optional render flags. See VizRenderOpts.
Returns Promise<string>
A promise resolving to an SVG XML string.

Index

References

Namespaces

Type Aliases

Variables

Functions

References

build_time

version

Type Aliases

VizRenderOpts

Type declaration

Optional engine?: string

Optional footer?: string

Optional hide_state_labels?: boolean

Variables

Const _test

Type declaration

color8to6: ((color8: string) => string)

Parameters

color8: string

Returns string

image_for_state: (<T>(u_jssm: Machine<T>, state: string) => string | undefined)

Type Parameters

T

Parameters

u_jssm: Machine<T>

state: string

Returns string | undefined

node_of: ((state: string, state_index: string[] | Map<string, number> | Map<string, string>) => string)

Parameters

state: string

state_index: string[] | Map<string, number> | Map<string, string>

Returns string

shape_for_state: (<T>(u_jssm: Machine<T>, state: string) => string | undefined)

Type Parameters

T

Parameters

u_jssm: Machine<T>

state: string

Returns string | undefined

slug_for: ((state: string) => string)

Parameters

state: string

Returns string

slug_states: ((states: string[]) => Map<string, string>)

Parameters

states: string[]

Returns Map<string, string>

style_for_state: (<T>(u_jssm: Machine<T>, state: string) => string)

Type Parameters

T

Parameters

u_jssm: Machine<T>

state: string

Returns string

u_color8to6: ((color8?: string) => string | undefined)

Parameters

Optional color8: string

Returns string | undefined

vc: ((col: string) => string)

Parameters

col: string

Returns string

Functions

configure

Parameters

opts: { DOMParser?: { prototype: <internal>.DOMParser } }

Optional DOMParser?: { prototype: <internal>.DOMParser }

prototype: <internal>.DOMParser

Returns void

dot

Type Parameters

T

Parameters

machine: Machine<T>

Returns string

dot_to_svg

Parameters

dot: string