finos / finos/architecture-as-code
calm-widgets: actor/sequence flow rendering, behaviour and draft visuals
- Dominant language
- TypeScript
- Stars
- 399
- Forks
- 138
- Avg merge
- 2d 14h
- Merged PRs (30d)
- 37
Description
## Feature Proposal
### Target Project:
`calm-widgets`
### Description of Feature:
Baseline rendering for the behaviour-driven architecture constructs, so docify output, the VSCode extension, and Hub UI all display them without requiring CALM Studio:
1. **Sequence widget** — renders a flow as a sequence diagram over its participating nodes (actor and system nodes as lifelines, transitions as ordered arrows). Works for business-level flows over coarse actor/system architectures (#1875) and technical flows alike.
2. **Behaviour rendering** — scenario badges on flows and transitions where behaviour decorators anchor them; a scenario table widget rendering Given/When/Then steps and data examples from a behaviour document (#2621).
3. **Draft styling** — constructs with `status: draft` (#2620) render visually distinct (dashed/de-emphasised) in existing and new widgets.
4. **Evidence status** — where a behaviour decorator carries an evidence pointer, render its status (proposed / implemented / passing / failing) as a badge.
### User Stories:
As a stakeholder reading docify output, I want flows rendered as sequence diagrams with their scenarios visible, so that I can review business behaviour without opening any tool.
As a reviewer, I want draft constructs visually distinct in generated documentation, so that proposals are never mistaken for committed design.
As a developer in VSCode, I want to see scenario and evidence badges on the components I'm building, so that behavioural expectations are visible where I work.
### Current Limitations:
- No sequence-diagram rendering of flows exists in calm-widgets.
- Behaviour documents and decorators have no rendering at all.
- Draft status has no visual treatment anywhere outside Studio (whose support is tracked separately).
### Proposed Implementation:
- New Handlebars-registered widgets following the existing widget conventions: `flow-sequence`, `behaviour-table`, plus badge partials reusable by existing widgets.
- Draft styling implemented in the shared rendering layer so every widget inherits it.
- Consumed by docify template bundles, the VSCode extension, and Hub UI.
### Alternatives Considered:
- **Studio-only rendering** — rejected: calm-widgets is the baseline path; the standard must be fully usable without Studio.
- **Extending the existing flow widget instead of a sequence widget** — considered; a sequence layout is a sufficiently different projection that a dedicated widget is cleaner, with shared data extraction.
### Testing Strategy:
- Vitest unit tests per widget with fixture documents (draft and accepted, anchored and unanchored behaviours).
- Snapshot tests for rendered output, following existing calm-widgets test patterns (see calm-widgets/AGENTS.md pitfalls).
### Documentation Requirements:
- Widget documentation and template-bundle examples for each new widget.
### Implementation Checklist:
- [ ] Design reviewed and approved
- [ ] Implementation completed
- [ ] Tests written and passing
- [ ] Documentation updated
- [ ] Relevant workflows updated (if needed)
- [ ] Performance impact assessed
### Additional Context:
Depends on the draft `2026-03` schema changes (#1875 transition `unique-id`, lifecycle status, behaviour documents); develops against the drafts. Part of the behaviour-driven architecture work — see the tracking issue finos/architecture-as-code#2627.
Contributor guide
Research direction
Start with calm-widgets/AGENTS.md and the existing flow widget conventions, then review current Vitest and snapshot test patterns. Implement the flow-sequence and behaviour-table widgets, reusable badges, and shared draft styling for the docify, VSCode, and Hub consumers; done means fixtures, snapshots, widget documentation, and template-bundle examples cover the listed states.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- handlebars, typescript, vscode
- Domain
- documentation, frontend, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100