jssm 5.80.1 → 5.81.0

package/dist/es6/jssm.d.ts

@@ -94,7 +94,7 @@ declare function arrow_right_kind(arrow: JssmArrow): JssmArrowKind;
  *  ```typescript
  *  import { sm } from 'jssm';
  *
- *  const switch = sm`on <=> off;`;
+ *  const lswitch = sm`on <=> off;`;
  *  ```
  *
  *  Method {@link from}:
@@ -149,7 +149,7 @@ declare function wrap_parse(input: string, options?: Object): any;
  *  ```typescript
  *  import { sm } from 'jssm';
  *
- *  const switch = sm`on <=> off;`;
+ *  const lswitch = sm`on <=> off;`;
  *  ```
  *
  *  Method {@link from}:
@@ -266,6 +266,7 @@ declare class Machine<mDT> {
     _terminal_state_style: JssmStateConfig;
     _start_state_style: JssmStateConfig;
     _end_state_style: JssmStateConfig;
+    _state_labels: Map<string, string>;
     constructor({ start_states, end_states, complete, transitions, machine_author, machine_comment, machine_contributor, machine_definition, machine_language, machine_license, machine_name, machine_version, state_declaration, property_definition, state_property, fsl_version, dot_preamble, arrange_declaration, arrange_start_declaration, arrange_end_declaration, theme, flow, graph_layout, instance_name, history, data, default_state_config, default_active_state_config, default_hooked_state_config, default_terminal_state_config, default_start_state_config, default_end_state_config }: JssmGenericConfig<mDT>);
     /********
      *
@@ -282,17 +283,32 @@ declare class Machine<mDT> {
      *  ```typescript
      *  import * as jssm from 'jssm';
      *
-     *  const switch = jssm.from('on <=> off;');
-     *  console.log( switch.state() );             // 'on'
+     *  const lswitch = jssm.from('on <=> off;');
+     *  console.log( lswitch.state() );             // 'on'
      *
-     *  switch.transition('off');
-     *  console.log( switch.state() );             // 'off'
+     *  lswitch.transition('off');
+     *  console.log( lswitch.state() );             // 'off'
      *  ```
      *
      *  @typeparam mDT The type of the machine data member; usually omitted
      *
      */
     state(): StateType;
+    /*********
+     *
+     *  Get the label for a given state, if any; return `undefined` otherwise.
+     *
+     *  ```typescript
+     *  import * as jssm from 'jssm';
+     *
+     *  const lswitch = jssm.from('a -> b; state a: { label: "Foo!"; };');
+     *  console.log( lswitch.label_for('a') );              // 'Foo!'
+     *  ```
+     *
+     *  @typeparam mDT The type of the machine data member; usually omitted
+     *
+     */
+    label_for(state: StateType): string;
     /*********
      *
      *  Get the current data of a machine.
@@ -300,8 +316,8 @@ declare class Machine<mDT> {
      *  ```typescript
      *  import * as jssm from 'jssm';
      *
-     *  const switch = jssm.from('on <=> off;', {data: 1});
-     *  console.log( switch.data() );              // 1
+     *  const lswitch = jssm.from('on <=> off;', {data: 1});
+     *  console.log( lswitch.data() );              // 1
      *  ```
      *
      *  @typeparam mDT The type of the machine data member; usually omitted
@@ -545,8 +561,8 @@ declare class Machine<mDT> {
      *  ```typescript
      *  import * as jssm from 'jssm';
      *
-     *  const switch = jssm.from('on <=> off;');
-     *  console.log( switch.states() );             // ['on', 'off']
+     *  const lswitch = jssm.from('on <=> off;');
+     *  console.log( lswitch.states() );             // ['on', 'off']
      *  ```
      *
      *  @typeparam mDT The type of the machine data member; usually omitted
@@ -561,10 +577,10 @@ declare class Machine<mDT> {
      *  ```typescript
      *  import * as jssm from 'jssm';
      *
-     *  const switch = jssm.from('on <=> off;');
+     *  const lswitch = jssm.from('on <=> off;');
      *
-     *  console.log( switch.has_state('off') );     // true
-     *  console.log( switch.has_state('dance') );   // false
+     *  console.log( lswitch.has_state('off') );     // true
+     *  console.log( lswitch.has_state('dance') );   // false
      *  ```
      *
      *  @typeparam mDT The type of the machine data member; usually omitted
@@ -1155,7 +1171,7 @@ declare class Machine<mDT> {
  *  ```typescript
  *  import * as jssm from 'jssm';
  *
- *  const switch = jssm.from('on <=> off;');
+ *  const lswitch = jssm.from('on <=> off;');
  *  ```
  *
  *  @typeparam mDT The type of the machine data member; usually omitted
@@ -1178,7 +1194,7 @@ declare function sm<mDT>(template_strings: TemplateStringsArray, ...remainder: a
  *  ```typescript
  *  import * as jssm from 'jssm';
  *
- *  const switch = jssm.from('on <=> off;');
+ *  const lswitch = jssm.from('on <=> off;');
  *  ```
  *
  *  @typeparam mDT The type of the machine data member; usually omitted

package/dist/es6/jssm.js

@@ -272,7 +272,7 @@ function makeTransition(this_se, from, to, isRight, _wasList, _wasIndex) {
  *  ```typescript
  *  import { sm } from 'jssm';
  *
- *  const switch = sm`on <=> off;`;
+ *  const lswitch = sm`on <=> off;`;
  *  ```
  *
  *  Method {@link from}:
@@ -424,7 +424,7 @@ function compile_rule_handler(rule) {
  *  ```typescript
  *  import { sm } from 'jssm';
  *
- *  const switch = sm`on <=> off;`;
+ *  const lswitch = sm`on <=> off;`;
  *  ```
  *
  *  Method {@link from}:
@@ -574,6 +574,9 @@ function transfer_state_properties(state_decl) {
             case 'background-color':
                 state_decl.backgroundColor = d.value;
                 break;
+            case 'state-label':
+                state_decl.stateLabel = d.value;
+                break;
             case 'border-color':
                 state_decl.borderColor = d.value;
                 break;
@@ -629,6 +632,12 @@ function state_style_condense(jssk) {
                     }
                     state_style.backgroundColor = key.value;
                     break;
+                case 'state-label':
+                    if (state_style.stateLabel !== undefined) {
+                        throw new JssmError(this, `cannot redefine 'state-label' in state_style_condense, already defined`);
+                    }
+                    state_style.stateLabel = key.value;
+                    break;
                 case 'border-color':
                     if (state_style.borderColor !== undefined) {
                         throw new JssmError(this, `cannot redefine 'border-color' in state_style_condense, already defined`);
@@ -731,6 +740,8 @@ class Machine {
         this._end_state_style = state_style_condense(default_end_state_config);
         this._history_length = history || 0;
         this._history = new circular_buffer(this._history_length);
+        this._state_labels = new Map();
+        // consolidate the state declarations
         if (state_declaration) {
             state_declaration.map((state_decl) => {
                 if (this._state_declarations.has(state_decl.state)) { // no repeats
@@ -739,6 +750,17 @@ class Machine {
                 this._state_declarations.set(state_decl.state, transfer_state_properties(state_decl));
             });
         }
+        // walk the decls for labels; aggregate them when found
+        [...this._state_declarations].map(sd => {
+            const [key, decl] = sd, labelled = decl.declarations.filter(d => d.key === 'state-label');
+            if (labelled.length > 1) {
+                throw new JssmError(this, `state ${key} may only have one state-label; has ${labelled.length}`);
+            }
+            if (labelled.length === 1) {
+                this._state_labels.set(key, labelled[0].value);
+            }
+        });
+        // walk the transitions
         transitions.map((tr) => {
             if (tr.from === undefined) {
                 throw new JssmError(this, `transition must define 'from': ${JSON.stringify(tr)}`);
@@ -890,11 +912,11 @@ class Machine {
      *  ```typescript
      *  import * as jssm from 'jssm';
      *
-     *  const switch = jssm.from('on <=> off;');
-     *  console.log( switch.state() );             // 'on'
+     *  const lswitch = jssm.from('on <=> off;');
+     *  console.log( lswitch.state() );             // 'on'
      *
-     *  switch.transition('off');
-     *  console.log( switch.state() );             // 'off'
+     *  lswitch.transition('off');
+     *  console.log( lswitch.state() );             // 'off'
      *  ```
      *
      *  @typeparam mDT The type of the machine data member; usually omitted
@@ -903,13 +925,23 @@ class Machine {
     state() {
         return this._state;
     }
-    /* whargarbl todo major
-       when we reimplement this, reintroduce this change to the is_final call
-  
-      is_changing(): boolean {
-        return true; // todo whargarbl
-      }
-    */
+    /*********
+     *
+     *  Get the label for a given state, if any; return `undefined` otherwise.
+     *
+     *  ```typescript
+     *  import * as jssm from 'jssm';
+     *
+     *  const lswitch = jssm.from('a -> b; state a: { label: "Foo!"; };');
+     *  console.log( lswitch.label_for('a') );              // 'Foo!'
+     *  ```
+     *
+     *  @typeparam mDT The type of the machine data member; usually omitted
+     *
+     */
+    label_for(state) {
+        return this._state_labels.get(state);
+    }
     /*********
      *
      *  Get the current data of a machine.
@@ -917,8 +949,8 @@ class Machine {
      *  ```typescript
      *  import * as jssm from 'jssm';
      *
-     *  const switch = jssm.from('on <=> off;', {data: 1});
-     *  console.log( switch.data() );              // 1
+     *  const lswitch = jssm.from('on <=> off;', {data: 1});
+     *  console.log( lswitch.data() );              // 1
      *  ```
      *
      *  @typeparam mDT The type of the machine data member; usually omitted
@@ -927,13 +959,6 @@ class Machine {
     data() {
         return this._data;
     }
-    /* whargarbl todo major
-       when we reimplement this, reintroduce this change to the is_final call
-  
-      is_changing(): boolean {
-        return true; // todo whargarbl
-      }
-    */
     // NEEDS_DOCS
     /*********
      *
@@ -1273,8 +1298,8 @@ class Machine {
      *  ```typescript
      *  import * as jssm from 'jssm';
      *
-     *  const switch = jssm.from('on <=> off;');
-     *  console.log( switch.states() );             // ['on', 'off']
+     *  const lswitch = jssm.from('on <=> off;');
+     *  console.log( lswitch.states() );             // ['on', 'off']
      *  ```
      *
      *  @typeparam mDT The type of the machine data member; usually omitted
@@ -1299,10 +1324,10 @@ class Machine {
      *  ```typescript
      *  import * as jssm from 'jssm';
      *
-     *  const switch = jssm.from('on <=> off;');
+     *  const lswitch = jssm.from('on <=> off;');
      *
-     *  console.log( switch.has_state('off') );     // true
-     *  console.log( switch.has_state('dance') );   // false
+     *  console.log( lswitch.has_state('off') );     // true
+     *  console.log( lswitch.has_state('dance') );   // false
      *  ```
      *
      *  @typeparam mDT The type of the machine data member; usually omitted
@@ -2543,7 +2568,7 @@ class Machine {
  *  ```typescript
  *  import * as jssm from 'jssm';
  *
- *  const switch = jssm.from('on <=> off;');
+ *  const lswitch = jssm.from('on <=> off;');
  *  ```
  *
  *  @typeparam mDT The type of the machine data member; usually omitted
@@ -2578,7 +2603,7 @@ function sm(template_strings, ...remainder /* , arguments */) {
  *  ```typescript
  *  import * as jssm from 'jssm';
  *
- *  const switch = jssm.from('on <=> off;');
+ *  const lswitch = jssm.from('on <=> off;');
  *  ```
  *
  *  @typeparam mDT The type of the machine data member; usually omitted

package/dist/es6/jssm_types.d.ts

@@ -106,6 +106,7 @@ declare type JssmStateDeclaration = {
     color?: JssmColor;
     corners?: JssmCorner;
     lineStyle?: JssmLineStyle;
+    stateLabel?: string;
     textColor?: JssmColor;
     backgroundColor?: JssmColor;
     borderColor?: JssmColor;
@@ -136,6 +137,10 @@ declare type JssmStateStyleLineStyle = {
     key: 'line-style';
     value: JssmLineStyle;
 };
+declare type JssmStateStyleStateLabel = {
+    key: 'state-label';
+    value: string;
+};
 declare type JssmStateStyleBackgroundColor = {
     key: 'background-color';
     value: JssmColor;
@@ -144,7 +149,7 @@ declare type JssmStateStyleBorderColor = {
     key: 'border-color';
     value: JssmColor;
 };
-declare type JssmStateStyleKey = JssmStateStyleShape | JssmStateStyleColor | JssmStateStyleTextColor | JssmStateStyleCorners | JssmStateStyleLineStyle | JssmStateStyleBackgroundColor | JssmStateStyleBorderColor;
+declare type JssmStateStyleKey = JssmStateStyleShape | JssmStateStyleColor | JssmStateStyleTextColor | JssmStateStyleCorners | JssmStateStyleLineStyle | JssmStateStyleBackgroundColor | JssmStateStyleStateLabel | JssmStateStyleBorderColor;
 declare type JssmStateStyleKeyList = JssmStateStyleKey[];
 declare type JssmGenericConfig<DataType> = {
     graph_layout?: JssmLayout;

package/dist/es6/version.js

@@ -1,2 +1,2 @@
-const version = "5.80.1";
+const version = "5.81.0";
 export { version };