Add page-level key binding system (capture phase) (#105)

* Add page-level key binding system (capture phase) (#104)

Implement capture-phase input handling where pages intercept keys before
focused components, enabling reliable navigation key handling (Escape, Tab).

- Add PageKeyBindings class for registering page-level key handlers
- Add HandlePageInput method to IBindablePage interface
- Modify TerminaApplication.ProcessEvent() to call page handler first
- Update ReactivePage to expose KeyBindings property
- Update all gallery demo pages to use new KeyBindings pattern
- Add comprehensive tests for page-level input handling

Closes #104

* Add navigation capabilities to ReactivePage

Give Pages direct access to Navigate(), NavigateWithParams(), and Shutdown()
methods instead of requiring wrapper methods on ViewModels.

Framework changes:
- Add WireUpNavigation() to IBindablePage interface
- Add protected Navigate/NavigateWithParams/Shutdown methods to ReactivePage
- Update TerminaApplication to wire up navigation to pages

This is a cleaner framework design where:
- Pages use Navigate() for input-driven navigation (Escape key, etc.)
- ViewModels use Navigate() for business-logic-driven navigation

Documentation updates:
- Update input-handling.md with correct Page.Navigate() usage
- Update architecture.md with two-phase input routing model
- Update concepts index with new data flow diagram

* Fix ReactiveLayoutNode child invalidation propagation

ReactiveLayoutNode now properly subscribes to its child's Invalidated
observable and propagates those events upward. This fixes the issue where
animated nodes (like SpinnerNode) nested inside reactive layouts would
not trigger redraws because their invalidation events were lost at the
ReactiveLayoutNode boundary.

Changes:
- Added _childInvalidationSubscription field to track child subscriptions
- Added SubscribeToChildInvalidation helper method
- Subscribe to child invalidation when new child is set from observable
- Re-subscribe on OnActivate to handle reactivation after navigation
- Properly dispose child invalidation subscription in Dispose
- Applied same fix to both ReactiveLayoutNode and ReactiveLayoutNode<T>

* Add Spacebar handling to AnimationsGalleryPage

Register a page-level key binding for Spacebar that updates the spinner
preview based on the currently highlighted item. This provides the same
behavior as Enter for this single-select use case, making the UX more
intuitive.

* Rename third column to 'Scrolling List' in SelectionListGalleryPage

Highlight the scrollbar feature by renaming the column header and
updating the description to show visible rows configuration.

Author: Aaronontheweb

demos/Termina.Demo.Gallery/Pages/AnimationsGalleryPage.cs

@@ -24,6 +24,19 @@ public override void OnNavigatedTo()
     {
         base.OnNavigatedTo();
 
+        // Page-level key binding for navigation (capture phase)
+        KeyBindings.Register(ConsoleKey.Escape, () => Navigate("/menu"));
+
+        // Spacebar also updates the preview (same as Enter for this single-select use case)
+        KeyBindings.Register(ConsoleKey.Spacebar, () =>
+        {
+            var highlighted = _styleList.HighlightedItem;
+            if (highlighted != null)
+            {
+                ViewModel.SelectedStyle = highlighted.Value.Style;
+            }
+        });
+
         // When user selects a style with Enter, update the ViewModel
         _styleList.SelectionConfirmed
             .Subscribe(items =>

demos/Termina.Demo.Gallery/Pages/AnimationsGalleryViewModel.cs

@@ -1,8 +1,6 @@
 // Copyright (c) Petabridge, LLC. All rights reserved.
 // Licensed under the Apache 2.0 license. See LICENSE file in the project root for full license information.
 
-using System.Reactive.Linq;
-using Termina.Input;
 using Termina.Reactive;
 using Termina.Terminal;
 using LayoutSpinnerStyle = Termina.Layout.SpinnerStyle;
@@ -25,12 +23,4 @@ public partial class AnimationsGalleryViewModel : ReactiveViewModel
         new("Box", LayoutSpinnerStyle.Box, Color.Cyan, "Rotating box corners"),
         new("Circle", LayoutSpinnerStyle.Circle, Color.Red, "Rotating circle")
     };
-
-    public override void OnActivated()
-    {
-        Input.OfType<KeyPressed>()
-            .Where(k => k.KeyInfo.Key == ConsoleKey.Escape)
-            .Subscribe(_ => Navigate("/menu"))
-            .DisposeWith(Subscriptions);
-    }
 }

demos/Termina.Demo.Gallery/Pages/GalleryMenuPage.cs

@@ -22,6 +22,9 @@ public override void OnNavigatedTo()
     {
         base.OnNavigatedTo();
 
+        // Page-level key binding for quit (capture phase)
+        KeyBindings.Register(ConsoleKey.Q, () => Shutdown());
+
         _menuList.SelectionConfirmed
             .Subscribe(items =>
             {

demos/Termina.Demo.Gallery/Pages/GalleryMenuViewModel.cs

@@ -1,8 +1,6 @@
 // Copyright (c) Petabridge, LLC. All rights reserved.
 // Licensed under the Apache 2.0 license. See LICENSE file in the project root for full license information.
 
-using System.Reactive.Linq;
-using Termina.Input;
 using Termina.Reactive;
 
 namespace Termina.Demo.Gallery.Pages;
@@ -20,14 +18,6 @@ public partial class GalleryMenuViewModel : ReactiveViewModel
         new("Animations", "Spinners, streaming text, progress indicators", "/animations")
     };
 
-    public override void OnActivated()
-    {
-        Input.OfType<KeyPressed>()
-            .Where(k => k.KeyInfo.Key == ConsoleKey.Q)
-            .Subscribe(_ => Shutdown())
-            .DisposeWith(Subscriptions);
-    }
-
     public void NavigateToGallery(string route)
     {
         Navigate(route);

demos/Termina.Demo.Gallery/Pages/LayoutGalleryPage.cs

@@ -16,6 +16,14 @@ namespace Termina.Demo.Gallery.Pages;
 /// </summary>
 public class LayoutGalleryPage : ReactivePage<LayoutGalleryViewModel>
 {
+    public override void OnNavigatedTo()
+    {
+        base.OnNavigatedTo();
+
+        // Page-level key binding for navigation (capture phase)
+        KeyBindings.Register(ConsoleKey.Escape, () => Navigate("/menu"));
+    }
+
     public override ILayoutNode BuildLayout()
     {
         return Layouts.Vertical()

demos/Termina.Demo.Gallery/Pages/LayoutGalleryViewModel.cs

@@ -1,8 +1,6 @@
 // Copyright (c) Petabridge, LLC. All rights reserved.
 // Licensed under the Apache 2.0 license. See LICENSE file in the project root for full license information.
 
-using System.Reactive.Linq;
-using Termina.Input;
 using Termina.Reactive;
 
 namespace Termina.Demo.Gallery.Pages;
@@ -12,11 +10,4 @@ namespace Termina.Demo.Gallery.Pages;
 /// </summary>
 public partial class LayoutGalleryViewModel : ReactiveViewModel
 {
-    public override void OnActivated()
-    {
-        Input.OfType<KeyPressed>()
-            .Where(k => k.KeyInfo.Key == ConsoleKey.Escape)
-            .Subscribe(_ => Navigate("/menu"))
-            .DisposeWith(Subscriptions);
-    }
 }

demos/Termina.Demo.Gallery/Pages/SelectionListGalleryPage.cs

@@ -29,6 +29,11 @@ public override void OnNavigatedTo()
     {
         base.OnNavigatedTo();
 
+        // Page-level key bindings (capture phase - intercepts before focused components)
+        // This is the new recommended pattern for page navigation keys
+        KeyBindings.Register(ConsoleKey.Escape, () => Navigate("/menu"));
+        KeyBindings.Register(ConsoleKey.Tab, CycleFocus);
+
         // Subscribe to selection events
         _singleSelectList.SelectionConfirmed
             .Subscribe(items => ViewModel.OnSingleSelection(items.FirstOrDefault() ?? ""))
@@ -46,24 +51,6 @@ public override void OnNavigatedTo()
             .Subscribe(items => ViewModel.OnNumberedSelection(items.FirstOrDefault() ?? ""))
             .DisposeWith(Subscriptions);
 
-        // Subscribe to Cancelled (Escape key) on all lists - navigate back to menu
-        _singleSelectList.Cancelled
-            .Subscribe(_ => ViewModel.NavigateToMenu())
-            .DisposeWith(Subscriptions);
-
-        _multiSelectRichList.Cancelled
-            .Subscribe(_ => ViewModel.NavigateToMenu())
-            .DisposeWith(Subscriptions);
-
-        _numberedList.Cancelled
-            .Subscribe(_ => ViewModel.NavigateToMenu())
-            .DisposeWith(Subscriptions);
-
-        // Subscribe to Tab key to cycle focus between lists
-        ViewModel.TabPressed
-            .Subscribe(_ => CycleFocus())
-            .DisposeWith(Subscriptions);
-
         // Default focus to first list
         _focusedListIndex = 0;
         Focus.PushFocus(_singleSelectList);
@@ -111,7 +98,7 @@ public override ILayoutNode BuildLayout()
             .WithHighlightColors(Color.Black, Color.Yellow)
             .WithVisibleRows(8);
 
-        // Numbered list with 12 items - demonstrates Issue #101 fix
+        // Scrolling list with 12 items in 6 visible rows
         _numberedList = Layouts.SelectionList(
             Enumerable.Range(1, 12).Select(i => $"Item number {i}"))
             .WithMode(SelectionMode.Single)
@@ -176,16 +163,16 @@ private GridNode BuildDemoGrid()
                         .Height(2))
                 .WithChild(_multiSelectRichList));
 
-        // Column 3: Numbered list (12 items)
+        // Column 3: Scrolling numbered list (12 items)
         grid.SetCell(0, 2,
             Layouts.Vertical()
                 .WithChild(
-                    new TextNode("12+ Items (Issue #101)")
+                    new TextNode("Scrolling List")
                         .WithForeground(Color.BrightCyan)
                         .Bold()
                         .Height(1))
                 .WithChild(
-                    new TextNode("All items show numbers!")
+                    new TextNode("12 items in 6 visible rows")
                         .WithForeground(Color.DarkGray)
                         .Height(2))
                 .WithChild(_numberedList));

demos/Termina.Demo.Gallery/Pages/SelectionListGalleryViewModel.cs

@@ -1,11 +1,6 @@
 // Copyright (c) Petabridge, LLC. All rights reserved.
 // Licensed under the Apache 2.0 license. See LICENSE file in the project root for full license information.
 
-using System.Reactive;
-using System.Reactive.Linq;
-using System.Reactive.Subjects;
-using Termina.Extensions;
-using Termina.Input;
 using Termina.Reactive;
 
 namespace Termina.Demo.Gallery.Pages;
@@ -15,12 +10,8 @@ namespace Termina.Demo.Gallery.Pages;
 /// </summary>
 public partial class SelectionListGalleryViewModel : ReactiveViewModel
 {
-    private readonly Subject<Unit> _tabPressed = new();
-
     [Reactive] private string _statusMessage = "Select items and explore different SelectionList features";
 
-    public IObservable<Unit> TabPressed => _tabPressed.AsObservable();
-
     public IReadOnlyList<ServerInfo> Servers { get; } = new List<ServerInfo>
     {
         new("prod-us-east-1", "US East", "Online", 45),
@@ -33,20 +24,6 @@ public partial class SelectionListGalleryViewModel : ReactiveViewModel
 
     private static readonly string[] ListNames = { "Single Select", "Multi-Select", "Numbered List" };
 
-    public override void OnActivated()
-    {
-        // Handle Tab key to cycle focus between lists
-        Input.OfType<KeyPressed>()
-            .Where(k => k.KeyInfo.Key == ConsoleKey.Tab)
-            .Subscribe(_ => _tabPressed.OnNext(Unit.Default))
-            .DisposeWith(Subscriptions);
-    }
-
-    public void NavigateToMenu()
-    {
-        Navigate("/menu");
-    }
-
     public void OnFocusChanged(int listIndex)
     {
         StatusMessage = $"Focus: {ListNames[listIndex]} - Use Tab to switch lists";

demos/Termina.Demo.Gallery/Pages/TextInputGalleryPage.cs

@@ -18,10 +18,16 @@ public class TextInputGalleryPage : ReactivePage<TextInputGalleryViewModel>
     private TextInputNode _basicInput = null!;
     private TextInputNode _placeholderInput = null!;
 
+    private int _focusedInputIndex;
+
     public override void OnNavigatedTo()
     {
         base.OnNavigatedTo();
 
+        // Page-level key bindings (capture phase)
+        KeyBindings.Register(ConsoleKey.Escape, () => Navigate("/menu"));
+        KeyBindings.Register(ConsoleKey.Tab, CycleFocus);
+
         _basicInput.Submitted
             .Subscribe(text => ViewModel.OnBasicInputSubmitted(text))
             .DisposeWith(Subscriptions);
@@ -30,9 +36,17 @@ public override void OnNavigatedTo()
             .Subscribe(text => ViewModel.OnPlaceholderInputSubmitted(text))
             .DisposeWith(Subscriptions);
 
+        _focusedInputIndex = 0;
         Focus.PushFocus(_basicInput);
     }
 
+    private void CycleFocus()
+    {
+        _focusedInputIndex = (_focusedInputIndex + 1) % 2;
+        var targetInput = _focusedInputIndex == 0 ? _basicInput : _placeholderInput;
+        Focus.PushFocus(targetInput);
+    }
+
     public override ILayoutNode BuildLayout()
     {
         _basicInput = new TextInputNode();

demos/Termina.Demo.Gallery/Pages/TextInputGalleryViewModel.cs

@@ -1,8 +1,6 @@
 // Copyright (c) Petabridge, LLC. All rights reserved.
 // Licensed under the Apache 2.0 license. See LICENSE file in the project root for full license information.
 
-using System.Reactive.Linq;
-using Termina.Input;
 using Termina.Reactive;
 
 namespace Termina.Demo.Gallery.Pages;
@@ -14,14 +12,6 @@ public partial class TextInputGalleryViewModel : ReactiveViewModel
 {
     [Reactive] private string _statusMessage = "Type in the input fields and press Enter to submit";
 
-    public override void OnActivated()
-    {
-        Input.OfType<KeyPressed>()
-            .Where(k => k.KeyInfo.Key == ConsoleKey.Escape)
-            .Subscribe(_ => Navigate("/menu"))
-            .DisposeWith(Subscriptions);
-    }
-
     public void OnBasicInputSubmitted(string text)
     {
         StatusMessage = $"Basic input submitted: \"{text}\"";