Add simulators

Author: rmcdaniel

docs/features/queries.md

@@ -2,6 +2,8 @@
 sidebar_position: 2
 ---
 
+import QuerySimulator from '@site/src/components/QuerySimulator';
+
 # Queries
 
 Queries allow you to retrieve information about the current state of a workflow without affecting its execution. This is useful for monitoring and debugging purposes.
@@ -34,4 +36,6 @@ $workflow = WorkflowStub::load($workflowId);
 $ready = $workflow->getReady();
 ```
 
+<QuerySimulator />
+
 **Note:** Querying a workflow does not advance its execution, unlike signals.

docs/features/signal+timer.md

@@ -18,7 +18,7 @@ class MyWorkflow extends Workflow
     #[SignalMethod]
     public function setReady($ready)
     {
-        $this->ready = $ready
+        $this->ready = $ready;
     }
 
     public function execute()
@@ -28,6 +28,10 @@ class MyWorkflow extends Workflow
 }
 ```
 
+import SignalTimerSimulator from '@site/src/components/SignalTimerSimulator';
+
+<SignalTimerSimulator />
+
 The workflow will reach the call to `awaitWithTimeout()` and then hibernate until either some external code signals the workflow like this.
 
 ```php

docs/features/signals.md

@@ -2,6 +2,8 @@
 sidebar_position: 1
 ---
 
+import SignalSimulator from '@site/src/components/SignalSimulator';
+
 # Signals
 
 Signals allow you to trigger events in a workflow from outside the workflow. This can be useful for reacting to external events, enabling *human-in-the-loop* interventions, or for signaling the completion of an external task.
@@ -58,4 +60,6 @@ class MyWorkflow extends Workflow
 }
 ```
 
+<SignalSimulator />
+
 **Important:** The `await()` function should only be used in a workflow, not an activity.

docs/features/timers.md

@@ -2,6 +2,8 @@
 sidebar_position: 3
 ---
 
+import TimerSimulator from '@site/src/components/TimerSimulator';
+
 # Timers
 
 Laravel Workflow provides the ability to suspend the execution of a workflow and resume at a later time. These are durable timers, meaning they survive restarts and failures while remaining consistent with workflow replay semantics. This can be useful for implementing delays, retry logic, or timeouts.
@@ -25,6 +27,8 @@ class MyWorkflow extends Workflow
 }
 ```
 
+<TimerSimulator />
+
 You can specify the `$duration` as an integer number of seconds or as a string e.g. '5 seconds', '30 minutes' or even '3 days'. Laravel Workflow can handle any duration.
 
 **Important:** Inside of a workflow, never use `Carbon::now()` or Laravel's `now()` to get the current time. Instead, use `Workflow\now()`, which returns the current time as seen by the workflow system. This is crucial because the actual time may not match your application's system clock.

src/components/QuerySimulator/index.js

@@ -0,0 +1,223 @@
+import React, { useState, useEffect, useRef } from 'react';
+import styles from './styles.module.css';
+
+const ExecutionState = {
+  IDLE: 'idle',
+  RUNNING: 'running',
+  WAITING: 'waiting',
+  COMPLETED: 'completed',
+};
+
+export default function QuerySimulator({
+  code = `use function Workflow\\await;
+use Workflow\\QueryMethod;
+use Workflow\\SignalMethod;
+use Workflow\\Workflow;
+
+class MyWorkflow extends Workflow
+{
+    private bool $ready = false;
+
+    #[QueryMethod]
+    public function getReady(): bool
+    {
+        return $this->ready;
+    }
+
+    #[SignalMethod]
+    public function setReady($ready)
+    {
+        $this->ready = $ready;
+    }
+
+    public function execute()
+    {
+        yield await(fn () => $this->ready);
+    }
+}`,
+  title = "Query & Signal Simulator",
+}) {
+  const [isExpanded, setIsExpanded] = useState(false);
+  const [executionState, setExecutionState] = useState(ExecutionState.IDLE);
+  const [currentLine, setCurrentLine] = useState(-1);
+  const [waitingTime, setWaitingTime] = useState(0);
+  const [readyValue, setReadyValue] = useState(false);
+  const [queryResult, setQueryResult] = useState(null);
+  const [queryFlash, setQueryFlash] = useState(false);
+  const waitingIntervalRef = useRef(null);
+  const animationRef = useRef(null);
+
+  const codeLines = code.split('\n');
+
+  const resetSimulation = () => {
+    setExecutionState(ExecutionState.IDLE);
+    setCurrentLine(-1);
+    setWaitingTime(0);
+    setReadyValue(false);
+    setQueryResult(null);
+    setQueryFlash(false);
+    if (waitingIntervalRef.current) {
+      clearInterval(waitingIntervalRef.current);
+    }
+    if (animationRef.current) {
+      cancelAnimationFrame(animationRef.current);
+    }
+  };
+
+  const runSimulation = () => {
+    resetSimulation();
+    setExecutionState(ExecutionState.WAITING);
+    setCurrentLine(24); // yield await line
+    
+    // Start counting waiting time
+    const startTime = Date.now();
+    waitingIntervalRef.current = setInterval(() => {
+      setWaitingTime(Math.floor((Date.now() - startTime) / 1000));
+    }, 1000);
+  };
+
+  const sendSignal = () => {
+    if (executionState !== ExecutionState.WAITING) return;
+    
+    // Clear waiting interval
+    if (waitingIntervalRef.current) {
+      clearInterval(waitingIntervalRef.current);
+    }
+    
+    // Flash the signal handler line
+    setCurrentLine(19); // $this->ready = $ready line
+    setReadyValue(true);
+    setExecutionState(ExecutionState.RUNNING);
+    
+    setTimeout(() => {
+      setCurrentLine(24); // Back to await line briefly
+      setTimeout(() => {
+        setExecutionState(ExecutionState.COMPLETED);
+        setCurrentLine(-1);
+      }, 500);
+    }, 300);
+  };
+
+  const queryWorkflow = () => {
+    // Flash the query method
+    setQueryFlash(true);
+    setQueryResult(readyValue);
+    
+    setTimeout(() => {
+      setQueryFlash(false);
+    }, 500);
+  };
+
+  useEffect(() => {
+    return () => {
+      if (waitingIntervalRef.current) {
+        clearInterval(waitingIntervalRef.current);
+      }
+      if (animationRef.current) {
+        cancelAnimationFrame(animationRef.current);
+      }
+    };
+  }, []);
+
+  return (
+    <div className={styles.simulatorWrapper}>
+      <button
+        className={`${styles.expandButton} ${isExpanded ? styles.expanded : ''}`}
+        onClick={() => setIsExpanded(!isExpanded)}
+      >
+        <span className={styles.expandIcon}>{isExpanded ? '▼' : '▶'}</span>
+        <span>Try it out!</span>
+      </button>
+
+      {isExpanded && (
+        <div className={styles.simulatorContainer}>
+          <div className={styles.simulatorHeader}>
+            <h4 className={styles.simulatorTitle}>{title}</h4>
+            <div className={styles.controls}>
+              <button
+                className={styles.playButton}
+                onClick={runSimulation}
+                disabled={executionState === ExecutionState.RUNNING || executionState === ExecutionState.WAITING}
+              >
+                {executionState === ExecutionState.RUNNING ? '⏳ Running...' : 
+                 executionState === ExecutionState.WAITING ? '⏸️ Waiting...' : '▶ Play'}
+              </button>
+              <button
+                className={styles.resetButton}
+                onClick={resetSimulation}
+                disabled={executionState === ExecutionState.RUNNING}
+              >
+                🔄 Reset
+              </button>
+            </div>
+          </div>
+
+          <div className={styles.codeContainer}>
+            <pre className={styles.codeBlock}>
+              {codeLines.map((line, index) => {
+                const lineNumber = index + 1;
+                const isHighlighted = currentLine === lineNumber;
+                const isWaitingLine = isHighlighted && executionState === ExecutionState.WAITING;
+                const isQueryLine = queryFlash && (lineNumber >= 10 && lineNumber <= 14);
+                
+                return (
+                  <div
+                    key={index}
+                    className={`${styles.codeLine} ${isHighlighted ? styles.highlighted : ''} ${isWaitingLine ? styles.waiting : ''} ${isQueryLine ? styles.queryHighlight : ''}`}
+                  >
+                    <span className={styles.lineNumber}>{lineNumber}</span>
+                    <span className={styles.lineContent}>{line || ' '}</span>
+                    {isWaitingLine && (
+                      <span className={styles.waitingBadge}>⏳ {waitingTime}s</span>
+                    )}
+                  </div>
+                );
+              })}
+            </pre>
+          </div>
+
+          <div className={styles.actionsRow}>
+            {(executionState === ExecutionState.WAITING || executionState === ExecutionState.COMPLETED) && (
+              <div className={styles.querySection}>
+                <button
+                  className={styles.queryButton}
+                  onClick={queryWorkflow}
+                >
+                  🔍 Query: <code>getReady()</code>
+                </button>
+                {queryResult !== null && (
+                  <span className={styles.queryResultInline}>
+                    → <code>{queryResult ? 'true' : 'false'}</code>
+                  </span>
+                )}
+              </div>
+            )}
+
+            {executionState === ExecutionState.WAITING && (
+              <div className={styles.signalSection}>
+                <button
+                  className={styles.signalButton}
+                  onClick={sendSignal}
+                >
+                  📤 Send Signal: <code>setReady(true)</code>
+                </button>
+              </div>
+            )}
+          </div>
+
+          <div className={styles.statusBar}>
+            <span className={`${styles.statusIndicator} ${styles[executionState]}`}>
+              {executionState === ExecutionState.IDLE && '⏸️ Ready'}
+              {executionState === ExecutionState.RUNNING && '▶️ Running'}
+              {executionState === ExecutionState.WAITING && '⏳ Waiting for Signal'}
+              {executionState === ExecutionState.COMPLETED && '✅ Workflow Completed'}
+            </span>
+            <span className={styles.stateDisplay}>
+              $ready = <code>{readyValue ? 'true' : 'false'}</code>
+            </span>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}