@solidxai/core 0.1.13-beta.2 → 0.1.13-beta.4

package/docs/workflow/foreach-example-notes.md

@@ -0,0 +1,187 @@
+# ForEach Example Notes
+
+## Purpose
+
+This document captures a reference workflow for loop-based control flow using `ForEach`. It fills an important gap in the example set by showing how repeated execution over a list of values should be represented in topology and editor views.
+
+---
+
+## Example Workflow YAML
+
+```yaml
+id: foreach_example
+namespace: my.namespace
+
+tasks:
+  - id: for_each_loop
+    type: io.kestra.core.tasks.flows.ForEach
+    values: ["item_1", "item_2", "item_3"]
+    tasks:
+      - id: print_value
+        type: io.kestra.core.tasks.scripts.Bash
+        commands:
+          - echo "Current loop value is {{ taskrun.value }}"
+```
+
+---
+
+## What This Example Adds
+
+This example is useful because it shows:
+
+- iterative control flow
+- a loop container node
+- child tasks executed once per loop item
+- loop-scoped runtime values such as `taskrun.value`
+
+It is the cleanest reference for repeated execution semantics in the workflow DSL.
+
+---
+
+## High-Level Structure
+
+```text
+Start
+  |
+  v
+for_each_loop
+  |
+  v
+print_value
+  |
+  v
+End
+```
+
+Conceptually, the structure is:
+
+```text
+Workflow
+└── for_each_loop
+    └── print_value
+```
+
+Runtime interpretation:
+
+```text
+for_each_loop over ["item_1", "item_2", "item_3"]
+  - run print_value with taskrun.value = "item_1"
+  - run print_value with taskrun.value = "item_2"
+  - run print_value with taskrun.value = "item_3"
+```
+
+---
+
+## Main Note
+
+### Example With `ForEach`
+
+This is the key purpose of the example.
+
+It shows that a loop is not just a visual group. It represents repeated execution of its child tasks across a collection of values.
+
+For SolidX, the topology should communicate:
+
+- the loop container
+- the loop body
+- that child tasks belong to the repeated block
+
+The canvas does not need to simulate every repeated instance visually. It should represent the structural loop definition cleanly.
+
+---
+
+## Topology Notes
+
+The screenshot suggests:
+
+- `ForEach` appears as a grouped/container region
+- the loop node is rendered inside that region
+- the child task appears within the same grouped flow area
+- the overall sequence still remains vertical and directional
+
+This means the renderer should support a loop-specific grouped layout similar to other control-flow containers, but with loop semantics instead of branch semantics.
+
+---
+
+## Loop Semantics Notes
+
+This example is important because it introduces loop-local context:
+
+- `taskrun.value`
+
+That means the editor and docs system will eventually need to help users understand:
+
+- which context values are available inside loops
+- that those values only exist within the loop body
+- how expressions differ between workflow scope and loop scope
+
+This is a documentation and autocomplete concern as much as a topology concern.
+
+---
+
+## Implications For SolidX Flow Modeling
+
+This example implies the flow model should support a distinct category for loop containers.
+
+Useful structural categories now include:
+
+- simple task node
+- trigger group
+- branch/control-flow container
+- nested/group container
+- loop container
+
+For `ForEach` specifically, the model should preserve:
+
+- loop source values
+- child task list
+- loop-local expression scope
+
+---
+
+## Editor Notes
+
+This example is a good reminder that the editor should remain DSL-driven.
+
+For a loop:
+
+- the source of truth is the `ForEach` node definition
+- the canvas should reflect loop structure
+- the user should edit loop configuration from metadata/schema, not by drawing repeated paths manually
+
+This fits well with the current direction:
+
+- code + flow are the primary surfaces
+- node editing is modal
+- docs are contextual
+
+---
+
+## Future UX Notes
+
+This example points to a few future needs:
+
+- loop-aware docs for `taskrun.value`
+- loop-container editing modal
+- schema-driven configuration for `values`
+- clear distinction between loop definition and loop runtime iterations
+
+---
+
+## Screenshot References
+
+This screenshot informed the notes above:
+
+- `/var/folders/z_/h0rqj1693gs4cxm3k_vks86c0000gn/T/TemporaryItems/NSIRD_screencaptureui_ptomjl/Screenshot 2026-07-10 at 17.17.48.png`
+
+---
+
+## Recommended Follow-On Use
+
+This example should be used as a reference for:
+
+1. `ForEach` node rendering
+2. loop-container layout rules
+3. loop-local expression awareness
+4. schema-driven loop configuration UX
+5. future autocomplete help for loop scope values

package/docs/workflow/hello-world-example-notes.md

@@ -0,0 +1,271 @@
+# Hello World Example Notes
+
+## Purpose
+
+This document captures a simple reference workflow with:
+
+- a disabled schedule trigger
+- one workflow input
+- a linear task sequence
+- cross-task output references in the final log message
+
+Compared with the other examples, this one is intentionally simple and is useful as the baseline topology for a trigger-driven sequential workflow.
+
+---
+
+## Example Workflow YAML
+
+```yaml
+id: hello-world
+namespace: tutorial
+labels:
+  name: Hello World
+
+triggers:
+  - id: daily
+    type: io.kestra.plugin.core.trigger.Schedule
+    cron: 0 9 * * *
+    disabled: true
+
+inputs:
+  - id: user
+    type: STRING
+    defaults: Rick Astley
+
+tasks:
+  - id: first_task
+    type: io.kestra.plugin.core.output.OutputValues
+    description: Return a value used later in the logged greeting.
+    values:
+      message: "thrilled"
+
+  - id: second_task
+    type: io.kestra.plugin.scripts.shell.Commands
+    description: Run quick shell commands and expose a value as output.
+    commands:
+      - sleep 0.42
+      - echo '::{"outputs":{"returned_data":"mydata"}}::'
+
+  - id: hello_world
+    type: io.kestra.plugin.core.log.Log
+    description: Log a welcome message using the inputs and earlier outputs.
+    message: |
+      Welcome to Kestra, {{ inputs.user }}! 
+      We are {{ outputs.first_task.values.message }} to have you. Here is your output from the second task: {{outputs.second_task.vars}}.
+
+description: |
+  **Use case:** Intro to Kestra that collects a `user` input and writes a friendly log.
+  **Trigger:** Disabled daily run at 09:00, left in place to show how scheduling works.
+  **Highlights:**
+  - Emit sample values to demonstrate how outputs travel between tasks.
+  - Run a shell command and surface its output for downstream use.
+  - Log the combined greeting using both inputs and prior outputs.
+```
+
+---
+
+## What This Example Adds
+
+This example is useful because it is the cleanest reference for:
+
+- a simple trigger group
+- a simple top-level input
+- a purely linear task flow
+- output propagation across multiple tasks
+- a beginner-friendly workflow shape
+
+It is a good baseline workflow to validate that the editor handles the most common happy path before layering in control flow and nested groups.
+
+---
+
+## High-Level Structure
+
+```text
+Triggers
+└── daily
+
+Main Flow
+first_task
+  |
+  v
+second_task
+  |
+  v
+hello_world
+```
+
+Another useful linear representation:
+
+```text
+Start
+  |
+  v
+[trigger group: daily]
+  |
+  v
+first_task
+  |
+  v
+second_task
+  |
+  v
+hello_world
+  |
+  v
+End
+```
+
+---
+
+## Main Note
+
+### Example With Trigger
+
+This is the key point of this example.
+
+It confirms the simpler trigger case:
+
+- one schedule trigger
+- one straight-line task chain
+- no branching
+- no nested control-flow container
+
+This makes it a strong baseline reference for trigger-aware topology rendering.
+
+---
+
+## Trigger Notes
+
+The screenshots again reinforce the trigger-group treatment:
+
+- triggers appear in a dedicated grouped region
+- they are visually distinct from normal tasks
+- the group connects into the main workflow sequence
+- disabled triggers are still shown
+
+For SolidX:
+
+- the trigger group should remain visible in both topology and edit views
+- disabled state should be preserved in the rendered metadata
+- trigger visualization should not require trigger editing to be complete
+
+---
+
+## Inputs Notes
+
+This example includes one top-level input:
+
+- `user`
+
+That makes it useful as a lightweight reference for workflow-level inputs without the extra complexity of multiple configurable runtime endpoints.
+
+The workflow editor will eventually need to support:
+
+- displaying workflow inputs clearly
+- editing them through code first
+- later, optionally surfacing them in a schema-driven workflow settings experience
+
+---
+
+## Output Propagation Notes
+
+This example is also a nice reference for how outputs flow between tasks.
+
+### Output Usage Pattern
+
+- `first_task` emits `values.message`
+- `second_task` emits shell-derived output data
+- `hello_world` consumes both
+
+This is useful for docs and UI because it demonstrates:
+
+- task outputs are part of the workflow authoring experience
+- users need help understanding available upstream outputs
+- code completion and docs should eventually assist with these references
+
+The final log task is effectively a small example of expression-aware authoring.
+
+---
+
+## Topology Notes
+
+The topology for this workflow is intentionally minimal:
+
+- trigger group at the top
+- one vertical line of tasks
+- no branches
+- no nested containers
+
+This means it should be treated as the baseline layout contract for simple workflows.
+
+If this example renders poorly, the editor is not yet ready for the more advanced ones.
+
+---
+
+## Edit View Notes
+
+The edit screenshot again supports the same basic composition:
+
+- left: code
+- right: flow
+
+This example is especially useful here because the structure is easy to visually verify against the YAML without much interpretation.
+
+That makes it a good smoke-test workflow for:
+
+- YAML-to-flow transformation
+- trigger rendering
+- icon mapping
+- sequential node spacing
+- add/edit/delete affordances
+
+---
+
+## Implications For SolidX
+
+This example should be used as the default sanity-check workflow for the editor because it combines:
+
+- trigger presence
+- inputs
+- outputs
+- sequential task chaining
+
+without introducing:
+
+- branching
+- grouping containers
+- nested child tasks
+
+So it is likely the best first example for verifying the full authoring loop.
+
+---
+
+## Pending Feature Notes
+
+This example highlights a few future UX improvements:
+
+- workflow-level input editing surface
+- output reference assistance in code editing
+- trigger-specific docs and status rendering
+- task output discovery in the docs side panel or schema editor
+
+---
+
+## Screenshot References
+
+These screenshots informed the notes above:
+
+- `/Users/harishpatel/Desktop/Screenshot 2026-07-10 at 17.14.06.png`
+- `/Users/harishpatel/Desktop/Screenshot 2026-07-10 at 17.14.19.png`
+
+---
+
+## Recommended Follow-On Use
+
+This example should be used as a reference for:
+
+1. simple trigger-group rendering
+2. linear workflow layout validation
+3. workflow input handling
+4. output-reference awareness in authoring
+5. smoke-testing the end-to-end code-to-flow editor behavior