From f672e15b1db3e6d3359a2bf234f7b1e720f5a90f Mon Sep 17 00:00:00 2001
From: Tom <squid@stormwind.it>
Date: Mon, 29 Jun 2026 21:12:11 +0200
Subject: [PATCH 1/6] feat(tui): add DSL node model and layout/bind-mode enums

- Add BindMode enum (OneWay/TwoWay) under SquidStd.Tui.Types.Tui
- Add StackOrientation enum (Vertical/Horizontal) under SquidStd.Tui.Types.Tui
- Add abstract TuiNode<TViewModel> base class under SquidStd.Tui.Dsl
- Add LabelNode<TViewModel>: one-way string property binding
- Add TextFieldNode<TViewModel>: string property binding with BindMode
- Add ButtonNode<TViewModel>: caption + ICommand expression binding
- Add StackNode<TViewModel>: orientation + typed children list
- Add TuiNodeTests covering all four node types (4 tests, all green)
---
 src/SquidStd.Tui/Dsl/ButtonNode.cs            | 23 ++++++++
 src/SquidStd.Tui/Dsl/LabelNode.cs             | 17 ++++++
 src/SquidStd.Tui/Dsl/StackNode.cs             | 21 ++++++++
 src/SquidStd.Tui/Dsl/TextFieldNode.cs         | 22 ++++++++
 src/SquidStd.Tui/Dsl/TuiNode.cs               |  7 +++
 src/SquidStd.Tui/Types/Tui/BindMode.cs        | 11 ++++
 .../Types/Tui/StackOrientation.cs             | 11 ++++
 tests/SquidStd.Tests/Tui/Dsl/TuiNodeTests.cs  | 53 +++++++++++++++++++
 8 files changed, 165 insertions(+)
 create mode 100644 src/SquidStd.Tui/Dsl/ButtonNode.cs
 create mode 100644 src/SquidStd.Tui/Dsl/LabelNode.cs
 create mode 100644 src/SquidStd.Tui/Dsl/StackNode.cs
 create mode 100644 src/SquidStd.Tui/Dsl/TextFieldNode.cs
 create mode 100644 src/SquidStd.Tui/Dsl/TuiNode.cs
 create mode 100644 src/SquidStd.Tui/Types/Tui/BindMode.cs
 create mode 100644 src/SquidStd.Tui/Types/Tui/StackOrientation.cs
 create mode 100644 tests/SquidStd.Tests/Tui/Dsl/TuiNodeTests.cs

diff --git a/src/SquidStd.Tui/Dsl/ButtonNode.cs b/src/SquidStd.Tui/Dsl/ButtonNode.cs
new file mode 100644
index 00000000..0ce44f00
--- /dev/null
+++ b/src/SquidStd.Tui/Dsl/ButtonNode.cs
@@ -0,0 +1,23 @@
+using System.Linq.Expressions;
+using System.Windows.Input;
+
+namespace SquidStd.Tui.Dsl;
+
+/// <summary>A button whose activation runs a command resolved from the ViewModel.</summary>
+public sealed class ButtonNode<TViewModel> : TuiNode<TViewModel>
+{
+    /// <summary>The button caption.</summary>
+    public string Caption { get; }
+
+    /// <summary>The source property providing the command to run.</summary>
+    public Expression<Func<TViewModel, ICommand>> Command { get; }
+
+    public ButtonNode(string caption, Expression<Func<TViewModel, ICommand>> command)
+    {
+        ArgumentException.ThrowIfNullOrEmpty(caption);
+        ArgumentNullException.ThrowIfNull(command);
+
+        Caption = caption;
+        Command = command;
+    }
+}
diff --git a/src/SquidStd.Tui/Dsl/LabelNode.cs b/src/SquidStd.Tui/Dsl/LabelNode.cs
new file mode 100644
index 00000000..b3686a1a
--- /dev/null
+++ b/src/SquidStd.Tui/Dsl/LabelNode.cs
@@ -0,0 +1,17 @@
+using System.Linq.Expressions;
+
+namespace SquidStd.Tui.Dsl;
+
+/// <summary>A label whose text is one-way bound to a string property.</summary>
+public sealed class LabelNode<TViewModel> : TuiNode<TViewModel>
+{
+    /// <summary>The source string property bound to the label text.</summary>
+    public Expression<Func<TViewModel, string>> Text { get; }
+
+    public LabelNode(Expression<Func<TViewModel, string>> text)
+    {
+        ArgumentNullException.ThrowIfNull(text);
+
+        Text = text;
+    }
+}
diff --git a/src/SquidStd.Tui/Dsl/StackNode.cs b/src/SquidStd.Tui/Dsl/StackNode.cs
new file mode 100644
index 00000000..336118ab
--- /dev/null
+++ b/src/SquidStd.Tui/Dsl/StackNode.cs
@@ -0,0 +1,21 @@
+using SquidStd.Tui.Types.Tui;
+
+namespace SquidStd.Tui.Dsl;
+
+/// <summary>A container that arranges its children vertically or horizontally.</summary>
+public sealed class StackNode<TViewModel> : TuiNode<TViewModel>
+{
+    /// <summary>The direction children are arranged.</summary>
+    public StackOrientation Orientation { get; }
+
+    /// <summary>The child nodes, in arrangement order.</summary>
+    public IReadOnlyList<TuiNode<TViewModel>> Children { get; }
+
+    public StackNode(StackOrientation orientation, IReadOnlyList<TuiNode<TViewModel>> children)
+    {
+        ArgumentNullException.ThrowIfNull(children);
+
+        Orientation = orientation;
+        Children = children;
+    }
+}
diff --git a/src/SquidStd.Tui/Dsl/TextFieldNode.cs b/src/SquidStd.Tui/Dsl/TextFieldNode.cs
new file mode 100644
index 00000000..b37dd35b
--- /dev/null
+++ b/src/SquidStd.Tui/Dsl/TextFieldNode.cs
@@ -0,0 +1,22 @@
+using System.Linq.Expressions;
+using SquidStd.Tui.Types.Tui;
+
+namespace SquidStd.Tui.Dsl;
+
+/// <summary>An editable text field bound to a string property (two-way by default).</summary>
+public sealed class TextFieldNode<TViewModel> : TuiNode<TViewModel>
+{
+    /// <summary>The source string property bound to the field text.</summary>
+    public Expression<Func<TViewModel, string>> Text { get; }
+
+    /// <summary>The binding direction.</summary>
+    public BindMode Mode { get; }
+
+    public TextFieldNode(Expression<Func<TViewModel, string>> text, BindMode mode)
+    {
+        ArgumentNullException.ThrowIfNull(text);
+
+        Text = text;
+        Mode = mode;
+    }
+}
diff --git a/src/SquidStd.Tui/Dsl/TuiNode.cs b/src/SquidStd.Tui/Dsl/TuiNode.cs
new file mode 100644
index 00000000..30a46f5c
--- /dev/null
+++ b/src/SquidStd.Tui/Dsl/TuiNode.cs
@@ -0,0 +1,7 @@
+namespace SquidStd.Tui.Dsl;
+
+/// <summary>Immutable description of a UI element bound to <typeparamref name="TViewModel" />.</summary>
+/// <typeparam name="TViewModel">The ViewModel the node's bindings target.</typeparam>
+public abstract class TuiNode<TViewModel>
+{
+}
diff --git a/src/SquidStd.Tui/Types/Tui/BindMode.cs b/src/SquidStd.Tui/Types/Tui/BindMode.cs
new file mode 100644
index 00000000..2f76fe67
--- /dev/null
+++ b/src/SquidStd.Tui/Types/Tui/BindMode.cs
@@ -0,0 +1,11 @@
+namespace SquidStd.Tui.Types.Tui;
+
+/// <summary>Binding direction for a DSL node that supports both.</summary>
+public enum BindMode
+{
+    /// <summary>Source-to-target only.</summary>
+    OneWay,
+
+    /// <summary>Source-to-target and target-to-source.</summary>
+    TwoWay
+}
diff --git a/src/SquidStd.Tui/Types/Tui/StackOrientation.cs b/src/SquidStd.Tui/Types/Tui/StackOrientation.cs
new file mode 100644
index 00000000..e0a0467d
--- /dev/null
+++ b/src/SquidStd.Tui/Types/Tui/StackOrientation.cs
@@ -0,0 +1,11 @@
+namespace SquidStd.Tui.Types.Tui;
+
+/// <summary>Direction a <c>Stack</c> arranges its children.</summary>
+public enum StackOrientation
+{
+    /// <summary>Children stacked top-to-bottom.</summary>
+    Vertical,
+
+    /// <summary>Children placed left-to-right.</summary>
+    Horizontal
+}
diff --git a/tests/SquidStd.Tests/Tui/Dsl/TuiNodeTests.cs b/tests/SquidStd.Tests/Tui/Dsl/TuiNodeTests.cs
new file mode 100644
index 00000000..72ea2eba
--- /dev/null
+++ b/tests/SquidStd.Tests/Tui/Dsl/TuiNodeTests.cs
@@ -0,0 +1,53 @@
+using System.Windows.Input;
+using CommunityToolkit.Mvvm.Input;
+using SquidStd.Tui.Dsl;
+using SquidStd.Tui.Internal;
+using SquidStd.Tui.Types.Tui;
+
+namespace SquidStd.Tests.Tui.Dsl;
+
+public class TuiNodeTests
+{
+    private sealed class SampleViewModel
+    {
+        public string Title { get; set; } = string.Empty;
+        public ICommand Save { get; } = new RelayCommand(() => { });
+    }
+
+    [Fact]
+    public void LabelNode_CapturesTextExpression()
+    {
+        var node = new LabelNode<SampleViewModel>(x => x.Title);
+
+        Assert.Equal(nameof(SampleViewModel.Title), PropertyPath.NameOf(node.Text));
+    }
+
+    [Fact]
+    public void TextFieldNode_DefaultsToTwoWay()
+    {
+        var node = new TextFieldNode<SampleViewModel>(x => x.Title, BindMode.TwoWay);
+
+        Assert.Equal(BindMode.TwoWay, node.Mode);
+        Assert.Equal(nameof(SampleViewModel.Title), PropertyPath.NameOf(node.Text));
+    }
+
+    [Fact]
+    public void ButtonNode_CapturesCaptionAndCommand()
+    {
+        var node = new ButtonNode<SampleViewModel>("Save", x => x.Save);
+
+        Assert.Equal("Save", node.Caption);
+        Assert.NotNull(node.Command);
+    }
+
+    [Fact]
+    public void StackNode_HoldsOrientationAndChildren()
+    {
+        var child = new LabelNode<SampleViewModel>(x => x.Title);
+        var node = new StackNode<SampleViewModel>(StackOrientation.Vertical, new TuiNode<SampleViewModel>[] { child });
+
+        Assert.Equal(StackOrientation.Vertical, node.Orientation);
+        Assert.Single(node.Children);
+        Assert.Same(child, node.Children[0]);
+    }
+}

From be4b12b158070e332e69341812bceade3f8bbfb6 Mon Sep 17 00:00:00 2001
From: Tom <squid@stormwind.it>
Date: Mon, 29 Jun 2026 21:17:00 +0200
Subject: [PATCH 2/6] feat(tui): add UiFactory for building DSL nodes from
 typed lambdas

---
 src/SquidStd.Tui/Dsl/UiFactory.cs             | 43 +++++++++++++++
 .../SquidStd.Tests/Tui/Dsl/UiFactoryTests.cs  | 54 +++++++++++++++++++
 2 files changed, 97 insertions(+)
 create mode 100644 src/SquidStd.Tui/Dsl/UiFactory.cs
 create mode 100644 tests/SquidStd.Tests/Tui/Dsl/UiFactoryTests.cs

diff --git a/src/SquidStd.Tui/Dsl/UiFactory.cs b/src/SquidStd.Tui/Dsl/UiFactory.cs
new file mode 100644
index 00000000..e6ad22ea
--- /dev/null
+++ b/src/SquidStd.Tui/Dsl/UiFactory.cs
@@ -0,0 +1,43 @@
+using System.Linq.Expressions;
+using System.Windows.Input;
+using SquidStd.Tui.Types.Tui;
+
+namespace SquidStd.Tui.Dsl;
+
+/// <summary>
+/// Builds DSL nodes from typed lambdas. The ViewModel type is fixed by the factory instance so the
+/// member-expression lambdas (<c>x =&gt; x.Property</c>) infer without annotations.
+/// </summary>
+/// <typeparam name="TViewModel">The ViewModel the built nodes bind to.</typeparam>
+public sealed class UiFactory<TViewModel>
+{
+    /// <summary>A label one-way bound to a string property.</summary>
+    public LabelNode<TViewModel> Label(Expression<Func<TViewModel, string>> text)
+    {
+        return new LabelNode<TViewModel>(text);
+    }
+
+    /// <summary>A text field bound to a string property (two-way by default).</summary>
+    public TextFieldNode<TViewModel> TextField(Expression<Func<TViewModel, string>> text, BindMode mode = BindMode.TwoWay)
+    {
+        return new TextFieldNode<TViewModel>(text, mode);
+    }
+
+    /// <summary>A button that runs the command resolved from the ViewModel.</summary>
+    public ButtonNode<TViewModel> Button(string caption, Expression<Func<TViewModel, ICommand>> command)
+    {
+        return new ButtonNode<TViewModel>(caption, command);
+    }
+
+    /// <summary>A vertical stack of child nodes.</summary>
+    public StackNode<TViewModel> VStack(params TuiNode<TViewModel>[] children)
+    {
+        return new StackNode<TViewModel>(StackOrientation.Vertical, children);
+    }
+
+    /// <summary>A horizontal stack of child nodes.</summary>
+    public StackNode<TViewModel> HStack(params TuiNode<TViewModel>[] children)
+    {
+        return new StackNode<TViewModel>(StackOrientation.Horizontal, children);
+    }
+}
diff --git a/tests/SquidStd.Tests/Tui/Dsl/UiFactoryTests.cs b/tests/SquidStd.Tests/Tui/Dsl/UiFactoryTests.cs
new file mode 100644
index 00000000..7d897068
--- /dev/null
+++ b/tests/SquidStd.Tests/Tui/Dsl/UiFactoryTests.cs
@@ -0,0 +1,54 @@
+using System.Windows.Input;
+using CommunityToolkit.Mvvm.Input;
+using SquidStd.Tui.Dsl;
+using SquidStd.Tui.Internal;
+using SquidStd.Tui.Types.Tui;
+
+namespace SquidStd.Tests.Tui.Dsl;
+
+public class UiFactoryTests
+{
+    private sealed class SampleViewModel
+    {
+        public string Title { get; set; } = string.Empty;
+        public string Name { get; set; } = string.Empty;
+        public ICommand Save { get; } = new RelayCommand(() => { });
+    }
+
+    private readonly UiFactory<SampleViewModel> _ui = new();
+
+    [Fact]
+    public void Label_ProducesLabelNode()
+    {
+        var node = _ui.Label(x => x.Title);
+
+        Assert.Equal(nameof(SampleViewModel.Title), PropertyPath.NameOf(node.Text));
+    }
+
+    [Fact]
+    public void TextField_DefaultsToTwoWay_AndOneWayIsExplicit()
+    {
+        Assert.Equal(BindMode.TwoWay, _ui.TextField(x => x.Name).Mode);
+        Assert.Equal(BindMode.OneWay, _ui.TextField(x => x.Name, BindMode.OneWay).Mode);
+    }
+
+    [Fact]
+    public void Button_ProducesButtonNode()
+    {
+        var node = _ui.Button("Save", x => x.Save);
+
+        Assert.Equal("Save", node.Caption);
+    }
+
+    [Fact]
+    public void VStack_And_HStack_SetOrientationAndChildren()
+    {
+        var v = _ui.VStack(_ui.Label(x => x.Title), _ui.Label(x => x.Name));
+        var h = _ui.HStack(_ui.Label(x => x.Title));
+
+        Assert.Equal(StackOrientation.Vertical, v.Orientation);
+        Assert.Equal(2, v.Children.Count);
+        Assert.Equal(StackOrientation.Horizontal, h.Orientation);
+        Assert.Single(h.Children);
+    }
+}

From 1e05947fbc84213437b3a1a742be5b7795b954b8 Mon Sep 17 00:00:00 2001
From: Tom <squid@stormwind.it>
Date: Mon, 29 Jun 2026 21:19:09 +0200
Subject: [PATCH 3/6] refactor(tui): add OnInitialize hook to TuiView for
 declarative composition

---
 src/SquidStd.Tui/TuiView.cs | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/src/SquidStd.Tui/TuiView.cs b/src/SquidStd.Tui/TuiView.cs
index 02926395..e7b1a306 100644
--- a/src/SquidStd.Tui/TuiView.cs
+++ b/src/SquidStd.Tui/TuiView.cs
@@ -30,9 +30,18 @@ void ITuiView.Bind(object viewModel)
     }
 
     void ITuiView.Initialize()
+    {
+        OnInitialize(_binder);
+    }
+
+    /// <summary>
+    /// Builds the view. The default runs <see cref="BuildLayout" /> then <see cref="Bind" />; the
+    /// declarative base overrides this to materialise a node tree instead.
+    /// </summary>
+    protected virtual void OnInitialize(ViewBinder binder)
     {
         BuildLayout();
-        Bind(_binder);
+        Bind(binder);
     }
 
     /// <summary>Creates the Terminal.Gui widgets for this view.</summary>

From 01da1b4516fdd3eb23ea1817fcddbb5d4e0f6c65 Mon Sep 17 00:00:00 2001
From: Tom <squid@stormwind.it>
Date: Mon, 29 Jun 2026 21:28:08 +0200
Subject: [PATCH 4/6] feat(tui): add materializer turning DSL nodes into bound
 Terminal.Gui views
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- add TuiNodeMaterializer in SquidStd.Tui.Dsl; walks TuiNode<TViewModel> trees and produces View graphs
- wire LabelNode via binder.OneWayText, TextFieldNode via TwoWay/OneWay binder overloads, ButtonNode via binder.Command
- StackNode (Vertical/Horizontal) produces a container View using Pos.Bottom/Pos.Right and Dim.Fill for layout
- TViewModel constrained to INotifyPropertyChanged so existing binder overloads resolve without new binding logic
- add TuiNodeMaterializerTests covering VStack+Label one-way propagation and TextField two-way VM→widget; both pass headless
- outer test class marked partial because nested ObservableObject partial class requires it (CommunityToolkit source generator)
---
 src/SquidStd.Tui/Dsl/TuiNodeMaterializer.cs   | 92 +++++++++++++++++++
 .../Tui/Dsl/TuiNodeMaterializerTests.cs       | 49 ++++++++++
 2 files changed, 141 insertions(+)
 create mode 100644 src/SquidStd.Tui/Dsl/TuiNodeMaterializer.cs
 create mode 100644 tests/SquidStd.Tests/Tui/Dsl/TuiNodeMaterializerTests.cs

diff --git a/src/SquidStd.Tui/Dsl/TuiNodeMaterializer.cs b/src/SquidStd.Tui/Dsl/TuiNodeMaterializer.cs
new file mode 100644
index 00000000..b9abeba6
--- /dev/null
+++ b/src/SquidStd.Tui/Dsl/TuiNodeMaterializer.cs
@@ -0,0 +1,92 @@
+using System.ComponentModel;
+using SquidStd.Tui.Binding;
+using SquidStd.Tui.Types.Tui;
+using Terminal.Gui.ViewBase;
+using Terminal.Gui.Views;
+
+namespace SquidStd.Tui.Dsl;
+
+/// <summary>Turns a <see cref="TuiNode{TViewModel}" /> tree into a Terminal.Gui view graph, wiring each
+/// node's binding through the supplied <see cref="ViewBinder" />.</summary>
+public sealed class TuiNodeMaterializer
+{
+    /// <summary>Materialises <paramref name="node" /> against <paramref name="viewModel" />, registering
+    /// bindings on <paramref name="binder" />, and returns the produced view.</summary>
+    public View Materialize<TViewModel>(TuiNode<TViewModel> node, TViewModel viewModel, ViewBinder binder)
+        where TViewModel : INotifyPropertyChanged
+    {
+        ArgumentNullException.ThrowIfNull(node);
+        ArgumentNullException.ThrowIfNull(viewModel);
+        ArgumentNullException.ThrowIfNull(binder);
+
+        switch (node)
+        {
+            case LabelNode<TViewModel> labelNode:
+                var label = new Label();
+                binder.OneWayText(viewModel, labelNode.Text, label);
+
+                return label;
+
+            case TextFieldNode<TViewModel> fieldNode:
+                var field = new TextField();
+
+                if (fieldNode.Mode == BindMode.TwoWay)
+                {
+                    binder.TwoWay(viewModel, fieldNode.Text, field);
+                }
+                else
+                {
+                    binder.OneWay(viewModel, fieldNode.Text, field, f => f.Text);
+                }
+
+                return field;
+
+            case ButtonNode<TViewModel> buttonNode:
+                var button = new Button { Text = buttonNode.Caption };
+                binder.Command(button, buttonNode.Command.Compile()(viewModel));
+
+                return button;
+
+            case StackNode<TViewModel> stackNode:
+                return MaterializeStack(stackNode, viewModel, binder);
+
+            default:
+                throw new NotSupportedException($"Unsupported node type '{node.GetType().Name}'.");
+        }
+    }
+
+    private View MaterializeStack<TViewModel>(StackNode<TViewModel> stack, TViewModel viewModel, ViewBinder binder)
+        where TViewModel : INotifyPropertyChanged
+    {
+        var container = new View
+        {
+            Width = Dim.Fill(),
+            Height = Dim.Fill()
+        };
+
+        View? previous = null;
+
+        foreach (var childNode in stack.Children)
+        {
+            var child = Materialize(childNode, viewModel, binder);
+
+            if (stack.Orientation == StackOrientation.Vertical)
+            {
+                child.X = 0;
+                child.Y = previous is null ? 0 : Pos.Bottom(previous);
+                child.Width = Dim.Fill();
+            }
+            else
+            {
+                child.X = previous is null ? 0 : Pos.Right(previous);
+                child.Y = 0;
+                child.Height = Dim.Fill();
+            }
+
+            container.Add(child);
+            previous = child;
+        }
+
+        return container;
+    }
+}
diff --git a/tests/SquidStd.Tests/Tui/Dsl/TuiNodeMaterializerTests.cs b/tests/SquidStd.Tests/Tui/Dsl/TuiNodeMaterializerTests.cs
new file mode 100644
index 00000000..72f367cc
--- /dev/null
+++ b/tests/SquidStd.Tests/Tui/Dsl/TuiNodeMaterializerTests.cs
@@ -0,0 +1,49 @@
+using CommunityToolkit.Mvvm.ComponentModel;
+using SquidStd.Tui.Binding;
+using SquidStd.Tui.Dsl;
+using Terminal.Gui.Views;
+
+namespace SquidStd.Tests.Tui.Dsl;
+
+public partial class TuiNodeMaterializerTests
+{
+    private sealed partial class SampleViewModel : ObservableObject
+    {
+        [ObservableProperty]
+        private string _title = "start";
+
+        [ObservableProperty]
+        private string _name = string.Empty;
+    }
+
+    [Fact]
+    public void Materialize_VStack_ProducesChildrenAndAppliesOneWay()
+    {
+        var ui = new UiFactory<SampleViewModel>();
+        var vm = new SampleViewModel();
+        var binder = new ViewBinder();
+        var materializer = new TuiNodeMaterializer();
+
+        var root = materializer.Materialize(ui.VStack(ui.Label(x => x.Title)), vm, binder);
+
+        var label = Assert.IsType<Label>(Assert.Single(root.SubViews));
+        Assert.Equal("start", label.Text);
+
+        vm.Title = "changed";
+        Assert.Equal("changed", label.Text);
+    }
+
+    [Fact]
+    public void Materialize_TextField_TwoWay_WritesBackToViewModel()
+    {
+        var ui = new UiFactory<SampleViewModel>();
+        var vm = new SampleViewModel();
+        var binder = new ViewBinder();
+        var materializer = new TuiNodeMaterializer();
+
+        var field = Assert.IsType<TextField>(materializer.Materialize(ui.TextField(x => x.Name), vm, binder));
+
+        vm.Name = "from-vm";
+        Assert.Equal("from-vm", field.Text);
+    }
+}

From a041ab4b6b2704b567a3532d26738d9bd9d7e441 Mon Sep 17 00:00:00 2001
From: Tom <squid@stormwind.it>
Date: Mon, 29 Jun 2026 21:31:58 +0200
Subject: [PATCH 5/6] feat(tui): add TuiComposedView base for declarative DSL
 views

---
 src/SquidStd.Tui/TuiComposedView.cs | 36 +++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)
 create mode 100644 src/SquidStd.Tui/TuiComposedView.cs

diff --git a/src/SquidStd.Tui/TuiComposedView.cs b/src/SquidStd.Tui/TuiComposedView.cs
new file mode 100644
index 00000000..85c26c7d
--- /dev/null
+++ b/src/SquidStd.Tui/TuiComposedView.cs
@@ -0,0 +1,36 @@
+using SquidStd.Tui.Binding;
+using SquidStd.Tui.Dsl;
+
+namespace SquidStd.Tui;
+
+/// <summary>
+/// Declarative view base: implement <see cref="Compose" /> to return a node tree built with <see cref="Ui" />.
+/// The tree is materialised into widgets and bindings during initialisation. For imperative views use
+/// <see cref="TuiView{TViewModel}" /> directly.
+/// </summary>
+/// <typeparam name="TViewModel">The ViewModel type for this view.</typeparam>
+public abstract class TuiComposedView<TViewModel> : TuiView<TViewModel>
+    where TViewModel : TuiViewModel
+{
+    private readonly TuiNodeMaterializer _materializer = new();
+
+    /// <summary>Factory for building the node tree from typed lambdas.</summary>
+    protected UiFactory<TViewModel> Ui { get; } = new();
+
+    /// <summary>Returns the declarative node tree for this view.</summary>
+    protected abstract TuiNode<TViewModel> Compose();
+
+    protected sealed override void BuildLayout()
+    {
+    }
+
+    protected sealed override void Bind(ViewBinder binder)
+    {
+    }
+
+    protected override void OnInitialize(ViewBinder binder)
+    {
+        var root = _materializer.Materialize(Compose(), ViewModel, binder);
+        Add(root);
+    }
+}

From f4796c35d8915badbad9c230b7ed96acbee5640f Mon Sep 17 00:00:00 2001
From: Tom <squid@stormwind.it>
Date: Mon, 29 Jun 2026 21:33:39 +0200
Subject: [PATCH 6/6] build(tui): port Counter sample to the declarative DSL
 and document it

---
 .../CounterComposedView.cs                    | 15 +++++++++++
 samples/SquidStd.Samples.Tui/CounterView.cs   | 25 -------------------
 samples/SquidStd.Samples.Tui/Program.cs       |  2 +-
 src/SquidStd.Tui/README.md                    | 20 +++++++++++++++
 4 files changed, 36 insertions(+), 26 deletions(-)
 create mode 100644 samples/SquidStd.Samples.Tui/CounterComposedView.cs
 delete mode 100644 samples/SquidStd.Samples.Tui/CounterView.cs

diff --git a/samples/SquidStd.Samples.Tui/CounterComposedView.cs b/samples/SquidStd.Samples.Tui/CounterComposedView.cs
new file mode 100644
index 00000000..90ff2679
--- /dev/null
+++ b/samples/SquidStd.Samples.Tui/CounterComposedView.cs
@@ -0,0 +1,15 @@
+using SquidStd.Tui;
+using SquidStd.Tui.Dsl;
+
+namespace SquidStd.Samples.Tui;
+
+public sealed class CounterComposedView : TuiComposedView<CounterViewModel>
+{
+    protected override TuiNode<CounterViewModel> Compose()
+    {
+        return Ui.VStack(
+            Ui.Label(x => x.Title),
+            Ui.Label(x => x.Value),
+            Ui.Button("+1", x => x.IncrementCommand));
+    }
+}
diff --git a/samples/SquidStd.Samples.Tui/CounterView.cs b/samples/SquidStd.Samples.Tui/CounterView.cs
deleted file mode 100644
index ec702153..00000000
--- a/samples/SquidStd.Samples.Tui/CounterView.cs
+++ /dev/null
@@ -1,25 +0,0 @@
-using SquidStd.Tui;
-using SquidStd.Tui.Binding;
-using Terminal.Gui.Views;
-
-namespace SquidStd.Samples.Tui;
-
-public sealed class CounterView : TuiView<CounterViewModel>
-{
-    private Label _value = null!;
-    private Button _increment = null!;
-
-    protected override void BuildLayout()
-    {
-        _value = new Label { X = 1, Y = 1 };
-        _increment = new Button { X = 1, Y = 3, Text = "_Increment" };
-        Add(_value, _increment);
-    }
-
-    protected override void Bind(ViewBinder binder)
-    {
-        binder.OneWayTitle(ViewModel, x => x.Title, this);
-        binder.OneWayText(ViewModel, x => x.Value, _value);
-        binder.Command(_increment, ViewModel.IncrementCommand);
-    }
-}
diff --git a/samples/SquidStd.Samples.Tui/Program.cs b/samples/SquidStd.Samples.Tui/Program.cs
index 06339c6f..9396570b 100644
--- a/samples/SquidStd.Samples.Tui/Program.cs
+++ b/samples/SquidStd.Samples.Tui/Program.cs
@@ -5,6 +5,6 @@
 
 var container = new Container();
 container.RegisterTui();
-container.RegisterView<CounterView, CounterViewModel>();
+container.RegisterView<CounterComposedView, CounterViewModel>();
 
 await container.Resolve<TuiApplicationHost>().RunAsync<CounterViewModel>();
diff --git a/src/SquidStd.Tui/README.md b/src/SquidStd.Tui/README.md
index cda531ff..3452b06e 100644
--- a/src/SquidStd.Tui/README.md
+++ b/src/SquidStd.Tui/README.md
@@ -48,6 +48,26 @@ container.RegisterView<CounterView, CounterViewModel>();
 await container.Resolve<TuiApplicationHost>().RunAsync<CounterViewModel>();
 ```
 
+## Declarative UI (DSL)
+
+Instead of imperative `BuildLayout` + `Bind`, derive from `TuiComposedView<TViewModel>` and return a node
+tree from `Compose()`. One node = widget + binding; direction is inferred (Label one-way, TextField
+two-way, Button command) and bindings are typed lambdas — no magic strings.
+
+```csharp
+public sealed class CounterView : TuiComposedView<CounterViewModel>
+{
+    protected override TuiNode<CounterViewModel> Compose() =>
+        Ui.VStack(
+            Ui.Label(x => x.Title),
+            Ui.Label(x => x.Value),
+            Ui.Button("+1", x => x.IncrementCommand));
+}
+```
+
+`Ui.VStack`/`Ui.HStack` arrange children automatically; `Ui.TextField(x => x.Name)` is two-way by default
+(pass `BindMode.OneWay` to override).
+
 ## Key types
 
 | Type | Purpose |