Complete drafting API

website/docs/operations/01-run-code.mdx

@@ -39,7 +39,7 @@ These operations need special handling because they shouldn't be re-executed dur
 
 :::info
 
-Workflows4s currently supports onyl cats-effect IO. If you're interested in other effect systems, please check [here](https://github.com/business4s/workflows4s/issues/59).
+Workflows4s currently supports only cats-effect IO. If you're interested in other effect systems, please check [here](https://github.com/business4s/workflows4s/issues/59).
 
 :::
 
@@ -69,3 +69,10 @@ You can add descriptions to RunIO operations to provide additional context in di
 ```
 
 <OperationOutputs name="run-io-description"/>
+
+## Drafting support
+
+Executing logic comes with [drafting support](20-drafting.mdx).
+
+```scala file=./main/scala/workflows4s/example/docs/draft/DraftStepExample.scala start=start_doc end=end_doc
+```

website/docs/operations/02-await-signal.mdx

@@ -9,6 +9,15 @@ Signal handling is essential for workflows that need to pause and wait for exter
 
 <OperationOutputs name="handle-signal"/>
 
+## Drafting Support
+
+Awaiting signals come with [drafting support](20-drafting.mdx).
+
+```scala file=./main/scala/workflows4s/example/docs/draft/DraftSignalExample.scala start=start_draft end=end_draft
+```
+
+<OperationOutputs name="draft-signal"/>
+
 # Unhandled Signals
 
 The Workflows4s API allows arbitrary signals to be sent to a workflow instance. While this provides flexibility, it also

website/docs/operations/02.1-timers.mdx

@@ -12,3 +12,12 @@ This operation enables time-based coordination, allowing workflows to pause for
 ```
 
 <OperationOutputs name="timer"/>
+
+## Drafting Support
+
+Awaiting time comes with [drafting support](20-drafting.mdx).
+
+```scala file=./main/scala/workflows4s/example/docs/draft/DraftTimerExample.scala start=start_draft end=end_draft
+```
+
+<OperationOutputs name="draft-timer"/>

website/docs/operations/03-sequence-operations.mdx

@@ -28,3 +28,7 @@ Dynamic steps cannot be rendered statically. Consider using [Forks](/docs/operat
 ```
 
 <OperationOutputs name="flat-map"/>
+
+## Drafting Support
+
+For Sequencing Operations, no dedicated draft API is required. Drafting can be done using the standard API.

website/docs/operations/04-handle-errors.mdx

@@ -12,3 +12,7 @@ Errors defined and handled should be domain errors and not technical ones. Domai
 ```
 
 <OperationOutputs name="handle-error-with"/>
+
+## Drafting Support
+
+For Error Handling, no dedicated draft API is required. Drafting can be done using the standard API.

website/docs/operations/9-for-each.mdx → website/docs/operations/05-for-each.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 9.1
+sidebar_position: 5.1
 ---
 import OperationOutputs from '@site/src/components/OperationOutputs';
 
@@ -23,9 +23,9 @@ This element is one of the most complicated ones and requires you to configure q
 <OperationOutputs name="for-each"/>
 
 
-### Draft Mode
+## Drafting Support
 
-For quick prototyping, you can use the draft API:
+Iterating comes with [drafting support](20-drafting.mdx).
 
 ```scala file=./main/scala/workflows4s/example/docs/ForEachExample.scala start=draft_start end=draft_end
 ```

website/docs/operations/05-loops.mdx

@@ -17,3 +17,12 @@ In the future this will be detected by the [linter](https://github.com/business4
 ```
 
 <OperationOutputs name="loop"/>
+
+## Drafting Support
+
+Loops come with [drafting support](20-drafting.mdx).
+
+```scala file=./main/scala/workflows4s/example/docs/draft/DraftLoopExample.scala start=start_draft end=end_draft
+```
+
+<OperationOutputs name="draft-loop"/>

website/docs/operations/06-fork.mdx

@@ -9,3 +9,12 @@ It's equivalent to `if` instructions but allow for static rendering of the workf
 ```
 
 <OperationOutputs name="fork"/>
+
+## Drafting Support
+
+Branching comes with [drafting support](20-drafting.mdx).
+
+```scala file=./main/scala/workflows4s/example/docs/draft/DraftForkExample.scala start=start_draft end=end_draft
+```
+
+<OperationOutputs name="draft-choice"/>

website/docs/operations/07-Interrupting.mdx

@@ -9,3 +9,12 @@ This allows selecting an alternative path based on such a signal.
 ```
 
 <OperationOutputs name="interruption-signal"/>
+
+## Drafting Support
+
+Interruptions come with [drafting support](20-drafting.mdx).
+
+```scala file=./main/scala/workflows4s/example/docs/draft/DraftInterruptionExample.scala start=start_draft end=end_draft
+```
+
+<OperationOutputs name="draft-interruption"/>

website/docs/operations/08-parallel.mdx

@@ -12,4 +12,13 @@ Workflow's state is continously updated after each step completion (doesn't wait
 ```scala file=./main/scala/workflows4s/example/docs/ParallelExample.scala start=start_doc end=end_doc
 ```
 
-<OperationOutputs name="parallel"/>
+<OperationOutputs name="parallel"/>
+
+## Drafting Support
+
+Parallel flows come with [drafting support](20-drafting.mdx).
+
+```scala file=./main/scala/workflows4s/example/docs/draft/DraftParallelExample.scala start=start_draft end=end_draft
+```
+
+<OperationOutputs name="draft-parallel"/>

website/docs/operations/10-checkpoints.mdx

@@ -49,4 +49,18 @@ In practice, checkpointing and recovery are often used together to enable workfl
 
 1. Version 1 of a workflow includes a segment that is checkpointed
 2. Version 2 of the workflow removes that segment but includes a recovery mechanism
-3. When a workflow instance created with version 1 is resumed using version 2, the recovery mechanism processes the checkpoint event, allowing the workflow to continue without the removed segment
+3. When a workflow instance created with version 1 is resumed using version 2, the recovery mechanism processes the checkpoint event, allowing the workflow to continue without the removed segment
+
+## Drafting Support
+
+Checkpointing and recovery come with [drafting support](20-drafting.mdx).
+
+### Draft Checkpoint
+```scala file=./main/scala/workflows4s/example/docs/draft/DraftCheckpointExample.scala start=start_draft_checkpoint end=end_draft_checkpoint
+```
+<OperationOutputs name="draft-checkpoint" showBpmn={false}/>
+
+### Draft Checkpoint
+```scala file=./main/scala/workflows4s/example/docs/draft/DraftCheckpointExample.scala start=start_draft_recovery end=end_draft_recovery
+```
+<OperationOutputs name="draft-recovery" showBpmn={false}/>

website/docs/operations/11-retry.mdx

@@ -57,4 +57,12 @@ If you see it as a major limitation, please reach out.
 
 Use workflow-level retries for retry schedules spanning **minutes to hours or days**
 
-For short-lived retries (e.g., retrying within milliseconds or seconds), prefer handling them directly inside the `IO` operation using libraries like [`cats-retry`](https://github.com/cats-effect/cats-retry).
+For short-lived retries (e.g., retrying within milliseconds or seconds), prefer handling them directly inside the `IO` operation using libraries like [`cats-retry`](https://github.com/cats-effect/cats-retry).
+
+## Drafting Support
+
+Retries come with [drafting support](20-drafting.mdx).
+
+```scala file=./main/scala/workflows4s/example/docs/draft/DraftRetryExample.scala start=start_draft end=end_draft
+```
+<OperationOutputs name="draft-retry"/>

website/docs/operations/20-drafting.mdx

@@ -0,0 +1,20 @@
+# Drafting
+
+Workflows4s comes with a dedicated API for creating renderable but NOT runnable workflow definitions.
+Its goal is to allow defining the structure of a workflow that can be discussed with the team or stakeholders,
+before committing more time to the actual implementation.
+
+The entire drafting API is exposed under `WIO.draft` and documented alongside specific operations.
+
+## Details
+
+Drafts use exactly the same model under the hood as real definitions, but filled with dummy logic.
+
+The drafting support simplifies the API in the following ways:
+
+* Not requiring type parameters
+* Not requiring event handling
+* Not requiring run logic
+* Automatically generating names from the context if not provided explicitly
+* Making as many parameters as possible optional
+

workflows4s-core/src/main/scala/workflows4s/wio/builders/DraftBuilder.scala

@@ -13,19 +13,20 @@ object DraftBuilder {
 
   trait Step0[Ctx <: WorkflowContext]() {
 
-    def draft: DraftBuilderStep1 = DraftBuilderStep1()
+    val draft: DraftBuilderStep1.type = DraftBuilderStep1
 
-    class DraftBuilderStep1 {
-      def signal(name: String = null, error: String = null)(using autoName: sourcecode.Name): WIO.Draft[Ctx]                                  = WIO.HandleSignal(
-        draftSignal,
-        SignalHandler[Unit, Unit, Any]((_, _) => ???),
-        dummyEventHandler,
-        WIO.HandleSignal.Meta(
-          Option(error).map(ErrorMeta.Present(_)).getOrElse(ErrorMeta.noError),
-          getEffectiveName(name, autoName),
-          None,
-        ),
-      )
+    object DraftBuilderStep1 {
+      def signal(name: String = null, error: String = null)(using autoName: sourcecode.Name): WIO.Draft[Ctx]                                  =
+        WIO.HandleSignal(
+          draftSignal,
+          SignalHandler[Unit, Unit, Any]((_, _) => ???),
+          dummyEventHandler,
+          WIO.HandleSignal.Meta(
+            Option(error).map(ErrorMeta.Present(_)).getOrElse(ErrorMeta.noError),
+            getEffectiveName(name, autoName),
+            None,
+          ),
+        )
       def timer(name: String = null, duration: FiniteDuration = null)(using autoName: sourcecode.Name): WIO.Timer[Ctx, Any, Nothing, Nothing] =
         WIO.Timer(
           Option(duration) match {
@@ -47,6 +48,13 @@ object DraftBuilder {
         ),
       )
 
+      def choice(name: String = null)(branches: (String, WIO.Draft[Ctx])*)(using autoName: sourcecode.Name): WIO.Draft[Ctx] = {
+        val branchWios = branches.map { case (branchName, wio) =>
+          WIO.Branch(_ => None, wio, Some(branchName))
+        }
+        WIO.Fork(branchWios.toVector, getEffectiveName(name, autoName).some, None)
+      }
+
       def forEach(forEach: WIO.Draft[Ctx], name: String = null)(using autoName: sourcecode.Name): WIO.Draft[Ctx] = {
         val effName = getEffectiveName(name, autoName).some
         WIO.ForEach(_ => ???, forEach, () => ???, null, _ => ???, (_, _, _) => ???, (_, _) => ???, None, null, WIOMeta.ForEach(effName))
@@ -63,6 +71,80 @@ object DraftBuilder {
         base.transformInput((_: Any) => ???).map(_ => ???)
       }
 
+      def parallel(elements: WIO.Draft[Ctx]*): WIO.Draft[Ctx] = {
+        val parallelElements = elements.map { element =>
+          WIO.Parallel.Element(element.map(_ => ???), (interimState: WCState[Ctx], _: WCState[Ctx]) => interimState)
+        }
+        WIO
+          .Parallel[Ctx, Any, Nothing, WCState[Ctx], WCState[Ctx]](
+            elements = parallelElements,
+            formResult = _ => ???,
+            initialInterimState = (_: Any) => ???,
+          )
+          .transformInput((_: Any) => ???)
+          .map(_ => ???)
+      }
+
+      def recovery: WIO.Draft[Ctx] = WIO.Recovery(dummyEventHandler)
+
+      def interruptionSignal(
+          signalName: String = null,
+          operationName: String = null,
+          error: String = null,
+      )(using autoName: sourcecode.Name): WIO.Interruption[Ctx, Nothing, Nothing] = {
+        val draftSignalHandling = WIO
+          .HandleSignal(
+            draftSignal,
+            SignalHandler[Unit, Unit, WCState[Ctx]]((_, _) => ???),
+            dummyEventHandler[WCEvent[Ctx], Unit],
+            WIO.HandleSignal.Meta(
+              Option(error).map(ErrorMeta.Present(_)).getOrElse(ErrorMeta.noError),
+              Option(signalName).getOrElse(getEffectiveName(null, autoName)),
+              Option(operationName),
+            ),
+          )
+          .transformInput((_: WCState[Ctx]) => ???)
+          .map(_ => ???)
+        WIO.Interruption(draftSignalHandling, WIO.HandleInterruption.InterruptionType.Signal)
+      }
+
+      def interruptionTimeout(
+          timerName: String = null,
+          duration: FiniteDuration = null,
+      )(using autoName: sourcecode.Name): WIO.Interruption[Ctx, Nothing, Nothing] = {
+        val draftTimer = WIO
+          .Timer(
+            Option(duration) match {
+              case Some(value) => WIO.Timer.DurationSource.Static(value.toJava)
+              case None        => WIO.Timer.DurationSource.Dynamic(_ => ???)
+            },
+            dummyEventHandler[WCEvent[Ctx], WIO.Timer.Started],
+            Option(timerName).orElse(getEffectiveName(null, autoName).some),
+            dummyEventHandler[WCEvent[Ctx], WIO.Timer.Released],
+          )
+          .transformInput((_: WCState[Ctx]) => ???)
+          .map(_ => ???)
+        WIO.Interruption(draftTimer, WIO.HandleInterruption.InterruptionType.Timer)
+      }
+
+      def retry(base: WIO.Draft[Ctx]): WIO.Draft[Ctx]      = {
+        WIO
+          .Retry(
+            base,
+            (_: Throwable, _: WCState[Ctx], _: java.time.Instant) => ???,
+          )
+          .transformInput((_: Any) => ???)
+          .map(_ => ???)
+      }
+      def checkpoint(base: WIO.Draft[Ctx]): WIO.Draft[Ctx] = WIO.Checkpoint(base, (_, _) => ???, dummyEventHandler)
+
+      object syntax {
+        extension (base: WIO.Draft[Ctx]) {
+          def draftCheckpointed: WIO.Draft[Ctx] = checkpoint(base)
+          def draftRetry: WIO.Draft[Ctx]        = retry(base)
+        }
+      }
+
     }
 
   }

workflows4s-core/src/test/scala/workflows4s/wio/WIODraftTest.scala

@@ -88,5 +88,42 @@ class WIODraftTest extends AnyFreeSpec with Matchers with OptionValues with Eith
         case _                        => fail("Expected Sequence model")
       }
     }
+
+    "should create a fork with correct branches" in {
+      val approve = WIO.draft.step("Approve")
+      val reject  = WIO.draft.step("Reject")
+      val wio     = WIO.draft.choice("Review")(
+        "Approved" -> approve,
+        "Rejected" -> reject,
+      )
+      val model   = wio.toProgress.toModel
+
+      model match {
+        case WIOModel.Fork(branches, meta) =>
+          meta.name shouldBe Some("Review")
+          branches.length shouldBe 2
+
+          branches.head shouldBe WIOModel.RunIO(WIOMeta.RunIO(Some("Approve"), None, None))
+          branches(1) shouldBe WIOModel.RunIO(WIOMeta.RunIO(Some("Reject"), None, None))
+        case _                             => fail("Expected Fork model")
+      }
+    }
+
+    "should create a parallel step with multiple elements" in {
+      val step1: Draft[Ctx]    = WIO.draft.step("task1")
+      val step2: Draft[Ctx]    = WIO.draft.step("task2")
+      val step3: Draft[Ctx]    = WIO.draft.step("task3")
+      val parallel: Draft[Ctx] = WIO.draft.parallel(step1, step2, step3)
+      val model                = parallel.toProgress.toModel
+
+      model match {
+        case WIOModel.Parallel(elements) =>
+          elements.length shouldBe 3
+          elements(0) shouldBe WIOModel.RunIO(WIOMeta.RunIO(Some("task1"), None, None))
+          elements(1) shouldBe WIOModel.RunIO(WIOMeta.RunIO(Some("task2"), None, None))
+          elements(2) shouldBe WIOModel.RunIO(WIOMeta.RunIO(Some("task3"), None, None))
+        case _                           => fail("Expected Parallel model")
+      }
+    }
   }
 }

workflows4s-example/src/main/scala/workflows4s/example/docs/draft/DraftCheckpointExample.scala

@@ -0,0 +1,20 @@
+package workflows4s.example.docs.draft
+
+import workflows4s.wio.DraftWorkflowContext.*
+
+object DraftCheckpointExample {
+
+  // start_draft_checkpoint
+  val base = WIO.draft.step()
+
+  val checkpointed = WIO.draft.checkpoint(base)
+
+  // or with a postfix application
+  import WIO.draft.syntax.*
+  val checkpointed2 = base.draftCheckpointed
+  // end_draft_checkpoint
+
+  // start_draft_recovery
+  val recovery = WIO.draft.recovery
+  // end_draft_recovery
+}