iobroker.statechart 0.1.1 → 0.2.0

package/README.md

@@ -30,13 +30,14 @@ actions, timers and function blocks are drawn in the ioBroker admin and executed
 - Timers: `after(5, sec)`
 - Function blocks with your own JavaScript functions, usable in all conditions and actions
 - Inputs and outputs mapped to any ioBroker states
-- Live view: the active state is highlighted in the editor
+- Live view: the active state is highlighted in the editor, the current values of the variables are shown, taken
+  transitions light up, and a history shows when which transition was taken and why
 - Code editor with syntax highlighting, error checking (e.g. unknown variables) and completion
 - Several independent charts per instance
 - Import and export of charts as JSON files
 - Comments on states, transitions and function blocks, and notes on the canvas
 - Per input: wake up on every update or only on changes, filter by ack, debounce
-- Helper functions: setState, setStateDelayed, sendTo, isTimeBetween, isDaytime, astroTime
+- Helper functions: setState, setStateDelayed, sendTo, isTimeBetween, isDaytime, astroTime, change detection (hasChanged...)
 - Undo/redo (Ctrl+Z, Ctrl+Y), copy/cut/paste of states and function blocks (Ctrl+C, Ctrl+X, Ctrl+V), also between charts, and a warning about unsaved changes
 - **Show code**: the JavaScript generated from the chart, showing exactly how the adapter executes it
 
@@ -66,7 +67,10 @@ Requirements: Node.js 22 or newer, js-controller 6.0.11 or newer, admin 7.6.17 o
    - **Local**: only exists inside the chart, with an initial value
 4. Add states with **Add state**. The state marked with the dot and arrow is the initial state
    (can be changed in the properties of a state).
-5. Draw transitions by dragging from the border of a state to another state (or to itself).
+5. Draw transitions by dragging from the border of a state to another state (or to itself). The arrows start and
+   end where the states face each other and follow them when they are moved. To fix an end at another place,
+   select the transition and drag the round grip at the end along the border (double click: automatic again). To
+   move a transition to another state, drop the grip on that state: its label and all other properties are kept.
 6. Select a state or transition (or double click it) to edit its actions or label on the right.
 7. Click **Save**. New charts are paused: start the chart with ▶ in the chart list. After saving, the adapter
    restarts a running chart immediately.
@@ -156,11 +160,21 @@ In conditions, actions and function blocks:
 | `isTimeBetween("22:00", "06:00")` | true if the current time is in the range, also over midnight |
 | `isDaytime()` | true between sunrise and sunset |
 | `astroTime("sunset", offsetMinutes)` | time of an astro event today as `Date`: `sunrise`, `sunset`, `dawn`, `dusk`, `solarNoon`, ... |
+| `hasChanged(variable)` | true if the variable has changed, see below |
+| `hasChangedFrom(variable, value)` | true if the variable has changed and its previous value was `value` |
+| `hasChangedTo(variable, value)` | true if the variable has changed to `value`, e.g. `hasChangedTo(button, true)` for a rising edge |
 
 `isDaytime()` and `astroTime()` use the location of the ioBroker system settings. To read other states, add
 them as inputs: their variables are always up to date and wake up the chart. Time based functions do not wake up
 the chart by themselves, they are evaluated when it wakes up.
 
+**Change detection** works like in Stateflow: it compares the value of the variable at the start of the current
+wakeup with its value at the start of the previous wakeup. Inputs, outputs and locals can be checked. An update
+with the same value is no change, neither is a wakeup by another input or a timer, so `[hasChangedTo(button, true)]`
+is only true once per press of the button. On the wakeup after the start nothing has changed yet. A change of a
+local by an action is seen on the next wakeup, also in a super step. Objects and arrays are compared by their
+contents.
+
 ### Function blocks
 
 **Add function** creates a block for your own JavaScript. It is executed once when the chart starts,
@@ -186,6 +200,22 @@ Transition label: `[tooWarm(temperature)]{heating = false;}`
 Comments and notes have no influence on the execution. They are included in the generated code and in exported
 files, and changing them does not prevent restoring the state after a restart.
 
+### Watching a running chart
+
+While a chart runs, the editor shows what it does:
+
+- The **active states** have a green border.
+- **Live values** (panel at the top left of the canvas, switched on and off with the last icon in the toolbar):
+  the current values of all variables. They are also shown below each variable in the tab **Variables**.
+- A **transition lights up** for a moment when the chart takes it.
+- The tab **History** lists the starts of the chart and the transitions taken, newest first: when, from which state
+  to which, triggered by which input or by a timer (`after`), and which states were active afterwards. Click a
+  transition to select it in the chart. The adapter keeps the last 200 events, also when the editor is closed and
+  after a restart. **Clear history** removes them.
+
+The live values and the history come from the running chart, so they refer to the saved chart, not to unsaved
+changes in the editor.
+
 ### Import and export
 
 - **Export chart** (last icon in the toolbar of the editor) saves the chart as JSON file, including unsaved changes.
@@ -205,6 +235,8 @@ For every chart, the adapter creates below `statechart.<instance>.charts.<chart>
 | `activeState` | Name of the active state, nested states as `Parent.Child` |
 | `activeStateIds` | IDs of all active states as JSON |
 | `snapshot` | Stored state of the chart (active states, when they were entered, locals), see below |
+| `values` | Current values of all variables as JSON, `{}` if the chart does not run |
+| `history` | The last 200 events (starts and transitions taken) as JSON. Writing it without ack clears it |
 
 The chart itself is stored in the object `statechart.<instance>.charts.<chart>`.
 
@@ -213,6 +245,8 @@ The chart itself is stored in the object `statechart.<instance>.charts.<chart>`.
 After a restart of the adapter or of ioBroker, every chart continues in the states which were active
 before, with its local variables. The entry actions are not executed again, and timers continue with
 their remaining time. A timer which expired while the adapter was stopped is taken right after the start.
+Like after every start, the chart then wakes up once, so changes of the inputs during the stop are
+noticed.
 
 The chart starts in its initial state instead if it was changed meanwhile (positions in the editor do not
 count), after saving it in the editor, after pausing it, and if the option **Restore the state after a
@@ -221,7 +255,14 @@ restart** in the chart properties is switched off. Variables declared in functio
 ### Execution model and differences to other statechart tools
 
 - The adapter uses [XState](https://stately.ai/docs/xstate) to execute the charts.
-- Every change of an input wakes up the chart once. Transitions without event are checked on every wakeup.
+- Every change of an input wakes up the chart once, as well as an expiring `after(...)` and the start of the chart
+  (also after restoring it). Transitions without event, e.g. without label, are checked on every wakeup, so they
+  are taken right after the start if their condition is true.
+- By default, only one transition is taken per wakeup, a following one waits for the next wakeup. With the
+  chart option **Take transitions until none is valid (super step)**, the chart is checked again right after a
+  transition, until no transition is valid anymore, like the super step semantics of Stateflow. The event of an
+  input only counts for the first transition of a wakeup, during actions may run several times. To protect against
+  loops, at most 100 transitions are taken per wakeup, then a warning is logged.
 - `{action}` is executed while the transition is taken, i.e. after `exit` of the old and before `entry` of
   the new state. A separate condition action and `/action` are not supported (yet).
 - Transitions are selected like in Stateflow (outer before inner, see above), XState only executes them.
@@ -257,13 +298,14 @@ Adapter ausgeführt.
 - Timer: `after(5, sec)`
 - Funktionsblöcke mit eigenen JavaScript-Funktionen, nutzbar in allen Bedingungen und Aktionen
 - Eingänge und Ausgänge, die mit beliebigen ioBroker-Datenpunkten verbunden sind
-- Live-Ansicht: Der aktive Zustand wird im Editor hervorgehoben
+- Live-Ansicht: Der aktive Zustand wird im Editor hervorgehoben, die aktuellen Werte der Variablen werden angezeigt,
+  genommene Übergänge leuchten auf, und ein Verlauf zeigt, wann welcher Übergang genommen wurde und warum
 - Code-Editor mit Syntax-Hervorhebung, Fehlerprüfung (z.B. unbekannte Variablen) und Autovervollständigung
 - Mehrere unabhängige Charts pro Instanz
 - Import und Export von Charts als JSON-Dateien
 - Kommentare zu Zuständen, Übergängen und Funktionsblöcken sowie Notizen auf der Zeichenfläche
 - Pro Eingang: Aufwecken bei jeder Aktualisierung oder nur bei Änderung, Filter nach ack, Entprellen
-- Hilfsfunktionen: setState, setStateDelayed, sendTo, isTimeBetween, isDaytime, astroTime
+- Hilfsfunktionen: setState, setStateDelayed, sendTo, isTimeBetween, isDaytime, astroTime, Änderungserkennung (hasChanged...)
 - Rückgängig/Wiederholen (Strg+Z, Strg+Y), Kopieren/Ausschneiden/Einfügen von Zuständen und Funktionsblöcken (Strg+C, Strg+X, Strg+V), auch zwischen Charts, und eine Warnung bei ungespeicherten Änderungen
 - **Code anzeigen**: das aus dem Chart generierte JavaScript, das genau zeigt, wie der Adapter es ausführt
 
@@ -293,7 +335,11 @@ Voraussetzungen: Node.js 22 oder neuer, js-controller 6.0.11 oder neuer, Admin 7
    - **Lokal**: gibt es nur im Chart, mit einem Startwert
 4. Mit **Zustand hinzufügen** Zustände anlegen. Der Zustand mit Punkt und Pfeil ist der Startzustand
    (änderbar in den Eigenschaften eines Zustands).
-5. Übergänge zeichnen: vom Rand eines Zustands zu einem anderen Zustand (oder zu sich selbst) ziehen.
+5. Übergänge zeichnen: vom Rand eines Zustands zu einem anderen Zustand (oder zu sich selbst) ziehen. Die Pfeile
+   beginnen und enden dort, wo sich die Zustände gegenüberliegen, und folgen ihnen beim Verschieben. Um ein Ende
+   an einer anderen Stelle festzulegen, den Übergang auswählen und den runden Griff am Ende am Rand entlang ziehen
+   (Doppelklick: wieder automatisch). Um einen Übergang an einen anderen Zustand umzuhängen, den Griff auf diesen
+   Zustand ziehen: Beschriftung und alle anderen Eigenschaften bleiben erhalten.
 6. Einen Zustand oder Übergang anklicken (oder doppelklicken), um rechts seine Aktionen bzw. seine
    Beschriftung zu bearbeiten.
 7. **Speichern** klicken. Neue Charts sind angehalten: Starte das Chart mit ▶ in der Chart-Liste. Nach dem
@@ -386,11 +432,21 @@ In Bedingungen, Aktionen und Funktionsblöcken:
 | `isTimeBetween("22:00", "06:00")` | wahr, wenn die aktuelle Uhrzeit im Bereich liegt, auch über Mitternacht |
 | `isDaytime()` | wahr zwischen Sonnenaufgang und Sonnenuntergang |
 | `astroTime("sunset", minuten)` | Zeitpunkt eines Astro-Ereignisses heute als `Date`: `sunrise`, `sunset`, `dawn`, `dusk`, `solarNoon`, ... |
+| `hasChanged(variable)` | wahr, wenn sich die Variable geändert hat, siehe unten |
+| `hasChangedFrom(variable, wert)` | wahr, wenn sich die Variable geändert hat und vorher `wert` war |
+| `hasChangedTo(variable, wert)` | wahr, wenn sich die Variable auf `wert` geändert hat, z.B. `hasChangedTo(taster, true)` für eine steigende Flanke |
 
 `isDaytime()` und `astroTime()` nutzen den Standort aus den ioBroker-Systemeinstellungen. Andere Datenpunkte liest
 man über Eingänge: Ihre Variablen sind immer aktuell und wecken das Chart. Zeitabhängige Funktionen wecken das
 Chart nicht von selbst, sie werden beim Aufwecken ausgewertet.
 
+Die **Änderungserkennung** funktioniert wie in Stateflow: Sie vergleicht den Wert der Variablen zu Beginn des
+aktuellen Aufweckens mit ihrem Wert zu Beginn des vorherigen. Eingänge, Ausgänge und lokale Variablen lassen sich
+prüfen. Eine Aktualisierung mit demselben Wert ist keine Änderung, ebenso wenig ein Aufwecken durch einen anderen
+Eingang oder einen Timer. `[hasChangedTo(taster, true)]` ist also nur einmal pro Tastendruck wahr. Beim Aufwecken
+nach dem Start hat sich noch nichts geändert. Ändert eine Aktion eine lokale Variable, sieht man das erst beim
+nächsten Aufwecken, auch im Super-Step. Objekte und Arrays werden nach ihrem Inhalt verglichen.
+
 ### Funktionsblöcke
 
 **Funktion hinzufügen** legt einen Block für eigenes JavaScript an. Er wird beim Start des Charts
@@ -418,6 +474,22 @@ Beschriftung eines Übergangs: `[zuWarm(temperatur)]{heizung = false;}`
 Kommentare und Notizen haben keinen Einfluss auf die Ausführung. Sie stehen im generierten Code und in exportierten
 Dateien, und wenn sie sich ändern, wird der Zustand nach einem Neustart trotzdem wiederhergestellt.
 
+### Ein laufendes Chart beobachten
+
+Während ein Chart läuft, zeigt der Editor, was es tut:
+
+- Die **aktiven Zustände** haben einen grünen Rahmen.
+- **Live-Werte** (Tafel oben links auf der Zeichenfläche, ein- und ausgeschaltet mit dem letzten Symbol der
+  Werkzeugleiste): die aktuellen Werte aller Variablen. Sie stehen auch unter jeder Variable im Reiter **Variablen**.
+- Ein **Übergang leuchtet kurz auf**, wenn das Chart ihn nimmt.
+- Der Reiter **Verlauf** listet die Starts des Charts und die genommenen Übergänge, der neueste zuerst: wann, von
+  welchem Zustand zu welchem, ausgelöst durch welchen Eingang oder einen Timer (`after`), und welche Zustände danach
+  aktiv waren. Ein Klick auf einen Übergang wählt ihn im Chart aus. Der Adapter behält die letzten 200 Ereignisse,
+  auch bei geschlossenem Editor und über einen Neustart hinweg. **Verlauf leeren** löscht sie.
+
+Live-Werte und Verlauf kommen vom laufenden Chart. Sie beziehen sich also auf das gespeicherte Chart, nicht auf
+ungespeicherte Änderungen im Editor.
+
 ### Import und Export
 
 - **Chart exportieren** (letztes Symbol in der Werkzeugleiste des Editors) speichert das Chart als JSON-Datei, mit
@@ -439,6 +511,8 @@ Für jedes Chart legt der Adapter unter `statechart.<instanz>.charts.<chart>` an
 | `activeState` | Name des aktiven Zustands, verschachtelte Zustände als `Eltern.Kind` |
 | `activeStateIds` | IDs aller aktiven Zustände als JSON |
 | `snapshot` | Gespeicherter Zustand des Charts (aktive Zustände, wann sie betreten wurden, lokale Variablen), siehe unten |
+| `values` | Aktuelle Werte aller Variablen als JSON, `{}` wenn das Chart nicht läuft |
+| `history` | Die letzten 200 Ereignisse (Starts und genommene Übergänge) als JSON. Schreiben ohne ack leert ihn |
 
 Das Chart selbst ist im Objekt `statechart.<instanz>.charts.<chart>` gespeichert.
 
@@ -447,7 +521,8 @@ Das Chart selbst ist im Objekt `statechart.<instanz>.charts.<chart>` gespeichert
 Nach einem Neustart des Adapters oder von ioBroker macht jedes Chart in den Zuständen weiter, die
 vorher aktiv waren, mit seinen lokalen Variablen. Die entry-Aktionen laufen nicht noch einmal, und Timer
 laufen mit ihrer Restzeit weiter. Ein Timer, der abgelaufen ist, während der Adapter gestoppt war, greift
-gleich nach dem Start.
+gleich nach dem Start. Wie nach jedem Start wacht das Chart dann einmal auf, so werden Änderungen der
+Eingänge während des Stopps bemerkt.
 
 Im Startzustand beginnt das Chart stattdessen, wenn es zwischendurch geändert wurde (Positionen im
 Editor zählen nicht), nach dem Speichern im Editor, nach dem Anhalten und wenn die Option **Zustand nach
@@ -457,7 +532,14 @@ Funktionsblöcken deklariert sind, werden nicht wiederhergestellt.
 ### Ausführung und Unterschiede zu anderen Statechart-Werkzeugen
 
 - Der Adapter führt die Charts mit [XState](https://stately.ai/docs/xstate) aus.
-- Jede Änderung eines Eingangs weckt das Chart einmal auf. Übergänge ohne Event werden bei jedem Aufwecken geprüft.
+- Jede Änderung eines Eingangs weckt das Chart einmal auf, ebenso ein ablaufendes `after(...)` und der Start des
+  Charts (auch nach dem Wiederherstellen). Übergänge ohne Event, z.B. ohne Beschriftung, werden bei jedem Aufwecken
+  geprüft und greifen deshalb direkt nach dem Start, wenn ihre Bedingung wahr ist.
+- Standardmäßig wird pro Aufwecken nur ein Übergang genommen, ein folgender wartet auf das nächste Aufwecken. Mit der
+  Chart-Option **Weiterschalten, bis kein Übergang mehr gilt (Super-Step)** wird das Chart nach einem Übergang sofort
+  erneut geprüft, bis kein Übergang mehr gilt, wie bei der Super-Step-Semantik von Stateflow. Das Event eines
+  Eingangs zählt nur für den ersten Übergang eines Aufweckens, during-Aktionen können mehrmals laufen. Zum Schutz vor
+  Schleifen werden pro Aufwecken höchstens 100 Übergänge genommen, danach wird eine Warnung geloggt.
 - `{aktion}` wird während des Übergangs ausgeführt, also nach `exit` des alten und vor `entry` des
   neuen Zustands. Eine eigene Condition Action und `/aktion` werden (noch) nicht unterstützt.
 - Übergänge werden wie bei Stateflow ausgewählt (außen vor innen, siehe oben), XState führt sie nur aus.
@@ -480,35 +562,51 @@ Funktionsblöcken deklariert sind, werden nicht wiederhergestellt.
 
 ```bash
 npm install
-npm run build                # build the admin tab
+npm run build                # build the adapter (src/ to build/) and the admin tab
 npm run dev-server setup     # once: local ioBroker test instance in .dev-server/
-npm run dev-server watch     # run it, admin on http://127.0.0.1:8081/
+npm run dev-server watch     # run it, admin on http://127.0.0.1:8081/, rebuilds the adapter on changes
 npm run upload:tab           # in a second terminal: upload the tab into the test instance
 ```
 
+The adapter and the editor are written in TypeScript. The editor imports the chart model, the validation
+and the code generator directly from `src/lib/`, so they are shared by both.
+
 | Script | Description |
 |---|---|
 | `dev-server` | Runs [`dev-server`](https://github.com/ioBroker/dev-server) with the given command. Before, it applies the patches in `patches/`: the dev-server uses `wmic.exe` to find the adapter process, which no longer exists in Windows 11 25H2 |
-| `build` / `watch` | Build the React sources of the tab (`admin/src`) to `admin/build` |
+| `build` / `watch` | Build the adapter (`src` to `build`) and the tab (`admin/src` to `admin/build`), with type check |
+| `build:ts` / `watch:ts` | Build only the adapter |
+| `build:react` / `watch:react` | Build only the tab |
 | `upload:tab` | Build the tab and write the admin files into the running dev-server instance (works while `dev-server watch` runs) |
-| `test` | Unit tests (`lib/**/*.test.js`) and package tests |
-| `check` | Type check of the adapter (`npx tsc -p admin/tsconfig.json --noEmit` for the tab) |
+| `test` | Unit tests (`src/**/*.test.ts`) and package tests |
+| `check` | Type check of the adapter and the tab |
 | `lint` | ESLint |
 | `translate` | Translate the texts of the adapter |
 | `release` | Create a new release |
 
 After changes of `io-package.json`, run `npm run dev-server upload` and restart `npm run dev-server watch`.
 
-**The built tab (`admin/build`) is committed**, because installations from GitHub do not run a build.
-After changes in `admin/src`, run `npm run build` and commit `admin/build` as well. The workflow job
-`check-admin-build` fails if it is outdated. The source maps (`admin/build/*.map`) are not committed.
+**The built adapter (`build`) and tab (`admin/build`) are committed**, because installations from GitHub do
+not run a build. After changes in `src` or `admin/src`, run `npm run build` and commit `build` and
+`admin/build` as well. The workflow job `check-build` fails if they are outdated. The source maps are not
+committed.
+
+**Dependabot** proposes updates monthly. Patch updates (and minor updates of development dependencies) are
+merged automatically when the checks pass, which are required for `main`. Dependabot cannot rebuild the
+committed build, so `check-build` does not compare it in Dependabot pull requests. Instead, after every push to
+`main`, it rebuilds `build` and `admin/build` and commits them if they changed. The workflows need the secret
+`AUTO_MERGE_TOKEN`, a fine-grained personal access token for this repository with the permissions
+"Contents" and "Pull requests" (read and write). Major updates of MUI, React and
+`@types/node` are ignored: `@iobroker/adapter-react-v5` requires MUI 6 and React 18, and the adapter supports
+Node.js 22.
 
 | Path | Content |
 |---|---|
-| `main.js` | Adapter: loads the charts, subscribes the inputs, restarts a chart when it is saved |
-| `lib/chart-model.js` | Chart model (shared by adapter and editor) and parser of the transition labels |
-| `lib/chart-runtime.js` | Execution of a chart with XState |
-| `lib/chart-validation.js` | Checks of conditions, actions and function blocks |
+| `src/main.ts` | Adapter: loads the charts, subscribes the inputs, restarts a chart when it is saved |
+| `src/lib/chart-model.ts` | Chart model (shared by adapter and editor) and parser of the transition labels |
+| `src/lib/chart-runtime.ts` | Execution of a chart with XState |
+| `src/lib/chart-validation.ts` | Checks of conditions, actions and function blocks |
+| `src/lib/chart-codegen.ts` | Code shown by "Show code" in the editor |
 | `admin/src/` | Editor (React, React Flow, CodeMirror) |
 | `admin/jsonConfig.json` | Instance settings |
 
@@ -522,6 +620,17 @@ with, endorsed or sponsored by The MathWorks, Inc.
     Placeholder for the next version (at the beginning of the line):
     ### **WORK IN PROGRESS**
 -->
+### 0.2.0 (2026-11-01)
+* (Igge) the adapter and the editor are written in TypeScript now, no changes of the behavior
+* (Igge) live values of the variables in the editor
+* (Igge) taken transitions light up in the editor
+* (Igge) history of the starts and the transitions taken (tab "History", state `charts.<chart>.history`)
+* (Igge) a chart wakes up once right after the start, so transitions without label are taken without waiting for a change of an input
+* (Igge) chart option "super step": take transitions until none is valid anymore
+* (Igge) the arrows of transitions start and end where the states face each other (floating edges), their ends can be dragged along the border of the states or onto another state to move the transition there
+* (Igge) change detection: `hasChanged`, `hasChangedFrom` and `hasChangedTo`, e.g. `hasChangedTo(button, true)` for edges
+* (Igge) suncalc 2: `isDaytime()` is true all day during the midnight sun, `astroTime()` reports events which do not happen on a day (polar regions)
+
 ### 0.1.1 (2026-10-25)
 * (Igge) renamed from "state-machine" to "statechart", because npm does not accept the old name (too similar to an existing package)