finos / finos/architecture-as-code

calm-widgets: actor/sequence flow rendering, behaviour and draft visuals

Open
#2,625 1 comment 0 reactions 0 assignees View on GitHub
bdd
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.