Proposal: Compile-time XAML-like UI for Terminal.Gui v2

[ccoulioufr]

Hi Terminal.Gui maintainers,

I’d like to start a discussion around an experimental side project related to Terminal.Gui v2, and get your feedback before going any further.

---

Context

Historically, there has been interest around describing Terminal.Gui UIs declaratively (for example with ReillyDigital.Terminal.Gui.Xaml). However:

• that approach relies on runtime XAML parsing + reflection
• it is not compatible with Terminal.Gui v2
• it is not AOT- or trimming-friendly

At the same time, modern .NET UI stacks (MAUI, WinUI) have clearly moved toward compile-time UI generation, even though they still rely on runtime binding for value updates.

This led me to explore a similar idea for Terminal.Gui v2, but adapted to a TUI context.

---

The project

I created a small library named:

t2t-terminal-gui-xamllike

👉 https://github.com/tool2team/t2t-terminal-gui-xamllike

Key ideas:

• XML XAML-like syntax, but not System.Xaml and not WPF-compatible
• UI is generated at build time, not runtime
• Implemented as a Roslyn source generator using IIncrementalGenerator (not ISourceGenerator)
• Generates plain, readable C# (InitializeComponent() style)
• Targets Terminal.Gui v2 APIs only
• No runtime loader, no reflection, no dynamic parsing

Example goals:

• describe layout declaratively
• keep all logic explicit and debuggable
• stay compatible with AOT / trimming

---

Binding & refresh model (important distinction)

This project does not attempt to reproduce a MAUI/WPF binding engine.

Instead:

• the visual tree is static (compile-time)
• bindings are instructions for code generation, not runtime objects
• updates are wired explicitly via INotifyPropertyChanged
• no dependency on BindableProperty or a runtime binding engine

Supported concepts:

• OneWay bindings (VM → UI)
• Limited TwoWay bindings (e.g. TextField.Text ↔ VM.Property)

The intent is closer to compiled XAML than to runtime XAML or dynamic UI loading, adapted to a TUI context.

---

Why I’m opening a discussion

At this stage, I’m not proposing a PR and I’m not assuming this belongs in the core repo.

What I’d like is:

• your opinion on whether this approach makes sense in the Terminal.Gui ecosystem

• feedback on API alignment with v2

• guidance on whether this should:

  • remain a fully external project
  • live as an optional/"blessed" extension
  • or potentially evolve toward closer integration

I’m fully aware this is an additional abstraction layer, and I don’t want to push something that conflicts with the project’s philosophy.

---

Current status

• early but functional prototype
• intentionally minimal feature set
• focused on correctness, explicitness, and maintainability
• open to significant changes based on feedback

---

Thanks for taking the time to read this. Even a short “yes/no/why” reaction would already be extremely valuable.

I’m happy to adapt the project, clarify details, or drop the idea entirely if it doesn’t align with Terminal.Gui’s direction.

Best regards,

Cédric — tool2team

[tig]

I think this is a wonderful concept and I strongly encourage you to pursue it.

From my perspective at the very minimum something like this will either validate or invalidate a ton of the work that has gone into V2 around consistency and correctness across the API.

I think just that would be wonderful.

I've never really been one for hand coding markup to create apps and so I don't fully understand why someone want to use a layer like this without a designer. But that's just a personal preference.

I'd like to see this as an add-on to the core framework like the designer and templates are. It would be great if this was just part of the gui-cs organization.

I don't have much bandwidth right now to dive deep and do what you've done so far but as we approach beta, I'd be very curious to know if you have anything that you think will require a deep breaking change in the API.

I'm working really hard right now trying to get the last big thing that's gonna impact the core API finished (command binding and routing) so we can declare beta. After that, I'd like us to hold a really high bar until 2.0 is released.

[ccoulioufr]

Hi,

Thank you for the encouragement — I appreciate it.

I’m closely following the evolution of Terminal.Gui v2, and I’ve made solid progress on the code generation side of the project. My goal is to keep it aligned with the current API direction and avoid pushing it in a way that would constrain or complicate the core.

Regarding the interest in markup without a designer: for me, the main value is structural consistency.

Describing the interface in markup helps:

• keep a clear and predictable UI hierarchy
• separate structure from behavior
• make large views easier to review and reason about
• reduce visual noise in application code

The generator then acts as a safety net. Instead of hand-writing repetitive layout and wiring code (which is easy to get subtly wrong), the structure is validated at build time and translated into explicit C#.

Importantly, the generated code is fully debuggable:

• it’s plain C#
• it’s readable
• you can step through it in the debugger
• there’s no hidden runtime engine or reflection layer

So the intent is less about adding abstraction, and more about:

• enforcing structural consistency
• reducing implementation mistakes
• validating API consistency in v2 through a stricter declarative layer

As you approach beta, I’ll keep an eye out for anything that feels like it would require a deep or breaking change in the core API. If I run into something that looks structural rather than incidental, I’ll raise it explicitly.

I understand the importance of stabilizing the API before 2.0, so I’ll treat this project as exploratory and adaptable to whatever direction v2 ultimately settles on.

Thanks again for the feedback.

[tznind]

I take it you have seen TerminalGuiDesigner? You might be able to reuse parts of it around how to code gen for given types (Dim/Pos etc).

It uses Roslyn for compilation and code dom for code gen so may not be your exact stack if you are doing code gen analyzer.

The fluent tests in core repo also do codegen but thats quite self contained and limited so probably less helpful to you.

[ccoulioufr]

TerminalGuiDesigner is a nice tool especially the feature that reloads TUI from code.
From my experience (Qt, Winforms), generated code is dangerous when it can be modified manually.
The ReillyDigital.Terminal.Gui.Xaml works with XAML loaded at runtime so it can't be debugged like sources from a source generator.
I think this proposal will be a great tool for professional using.