fai/chain-studio-flow-editor
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Swappable inline YAML editor for F∆I Studio flows.
6 commits 1 branch 0 tags 1.2 MiB
Find a file
flemming-it dbd9a0004f feat(model): FlowGraph + LayoutStore foundation for WYSIWYG editor 
First piece of the v0.2.0 rewrite. The graph view, text view,
and run view will all share a single source of truth: the
YAML text. This commit introduces the parsing layer + the
sidecar that keeps layout metadata OUT of the YAML.

FlowGraph (lib/src/model/flow_graph.dart):
 - Parses + emits the F-Delta-I flow YAML shape (inputs +
   steps + outputs + leading comment block).
 - Recognises both inputs shorthand (`name: text`) and the
   expanded form (`name: { type: text, default: ..., hint: ... }`).
 - Detects edges by scanning step.with + outputs for
   $source.field references; understands both the short
   $x.y form (canonical) and the long ${{ x.y }} form (legacy).
 - Flags system.approval@ steps via FlowStep.isApproval so
   the graph can paint them with the human-gate styling.
 - Immutable update helpers (withStepUpdated, withStepAdded,
   withStepRemoved) used by the property panel + add-step
   button.
 - tryParse returns null on YAML syntax errors so the text
   tab can keep the last valid graph while the operator
   types.

LayoutStore + FlowLayout (lib/src/model/layout_store.dart):
 - Per-flow JSON sidecar at
   ~/.fai/data/flows/.layout/<name>.json. Atomic write via
   tmp + rename so a crash mid-save leaves the previous
   copy intact.
 - The YAML stays byte-identical to what `fai run` consumes
   — positions never bleed into the flow file.

AutoLayout (lib/src/model/auto_layout.dart):
 - Deterministic topological column layout for flows that
   have never been opened in the graph view before.
 - Steps with no $step refs sit in column 0; steps whose
   refs all point at column-0 steps sit in column 1; etc.
 - Cycles + dangling refs collapse to column 0 so nothing
   is ever invisible.

Tests (test/flow_graph_test.dart): 7 cases cover canonical
parsing, edge detection across both ref forms, approval-step
flagging, leading-comment round-trip, structural round-trip,
parser robustness on broken YAML, immutability invariant.
All pass.

Version 0.1.4 -> 0.2.0 (minor bump — significant new module
graph; public FlowEditorPage constructor API unchanged).

Signed-off-by: flemming-it <sf@flemming.it>
2026-06-01 00:37:19 +02:00
lib feat(model): FlowGraph + LayoutStore foundation for WYSIWYG editor 2026-06-01 00:37:19 +02:00
test feat(model): FlowGraph + LayoutStore foundation for WYSIWYG editor 2026-06-01 00:37:19 +02:00
.gitignore feat: initial scaffold — swappable flow editor 2026-05-30 14:33:03 +02:00
pubspec.yaml feat(model): FlowGraph + LayoutStore foundation for WYSIWYG editor 2026-06-01 00:37:19 +02:00
README.md feat: initial scaffold — swappable flow editor 2026-05-30 14:33:03 +02:00

README.md

fai_studio_flow_editor

Swappable inline YAML editor for F∆I Studio flows.

Public surface

import 'package:fai_studio_flow_editor/fai_studio_flow_editor.dart';

// Studio embeds the page as one of its destinations:
FlowEditorPage(
  initialFlowName: 'hello',                       // optional
  locale: FlowEditorLocale.de,                    // or .en
  onRun: (name) =>                                // optional callback
      HubService.instance.runSavedFlow(name: name),
)
  • initialFlowName — when set, the page loads that flow from ~/.fai/data/flows/<name>.yaml on first build. Used by Studio's Flows-page pencil → editor route push.
  • locale — picks EN or DE for the editor's internal string table. Studio passes its active locale through.
  • onRun — async callback that runs the named flow against the host hub and returns the typed outputs map. When null, the Run button is disabled (e.g. when the editor is embedded in a context without hub access).

Behaviour

  • File browser (left, 240 px) lists *.yaml in ~/.fai/data/flows/.
  • Code field (right) ships YAML syntax highlighting via flutter_code_editor + the highlight package's yaml grammar.
  • Save writes directly to disk via dart:io; the hub picks up the change on its next ListFlows / RunSavedFlow call.
  • Cmd+S / Ctrl+S — save. Cmd+Enter / Ctrl+Enter — run.

Swap it

Studio depends on this package via pubspec.yaml git reference:

dependencies:
  fai_studio_flow_editor:
    git:
      url: https://git.flemming.ai/fai/studio-flow-editor
      ref: main

To use a different editor:

  1. Fork this repo (or write your own from scratch).
  2. Keep the FlowEditorPage constructor signature (initialFlowName, locale, onRun) — that's the stable host contract.
  3. Point Studio's pubspec at your fork (or local-path during development): 
    fai_studio_flow_editor:
  git:
    url: https://your-host/your/flow-editor
    ref: main
  4. Rebuild Studio. Done.

The contract is intentionally minimal: a single page widget with three parameters. The package brings its own tokens, its own empty/error widgets, its own l10n table, so the host doesn't have to share internals. The trade-off is visual drift if Studio's design tokens change — that's the deal you accept for a swappable module.

Develop

flutter pub get
flutter analyze
flutter test

The package's own widget tests live in test/. End-to-end tests against a live hub stay in the host repo (Studio).

License

Apache-2.0. Same as the rest of the F∆I platform.