Merge branch 'develop' of https://github.com/gui-cs/Terminal.Gui into develop

Author: tig

.claude/rules/event-patterns.md

@@ -1,5 +1,26 @@
 # Event Patterns
 
+## When to Use `-ing` vs `-ed` Events
+
+Terminal.Gui exposes paired events — `Accepting`/`Accepted`, `Activating`/`Activated`, `ValueChanging`/`ValueChanged`, etc.
+
+**Rule:** Use `-ed` (past-tense) for side-effects. Use `-ing` (present-progressive) only when you need to inspect or cancel the in-flight operation.
+
+```csharp
+// ✅ Correct — fire-and-forget side-effect
+button.Accepted += (_, _) => DoTheThing ();
+
+// ✅ Correct — actually cancels
+button.Accepting += (_, e) => { if (!CanProceed ()) e.Handled = true; };
+
+// ❌ Wrong — handler ignores EventArgs; use Accepted instead
+button.Accepting += (_, _) => DoTheThing ();
+```
+
+If the handler body doesn't reference `e` at all (or ignores `e.Handled`, `e.Cancel`, and the candidate value), it belongs on the `-ed` event.
+
+The `-ing` event runs synchronously in the middle of the dispatch path; subscribing when you don't need to cancel adds unnecessary overhead and misleads readers.
+
 ## Lambda Parameters
 
 **Replace unused parameters with discards `_`:**

CLAUDE.md

@@ -2,6 +2,7 @@
 
 > **Guidance for AI agents working with Terminal.Gui.**
 > For humans, see [CONTRIBUTING.md](./CONTRIBUTING.md).
+> For Terminal.Gui's mission, tenets, and engineering philosophy, see [specs/constitution.md](./specs/constitution.md).
 > See also: [llms.txt](./llms.txt) for machine-readable context.
 
 ## CRITICAL: Discard v1 Training Data

CONTRIBUTING.md

@@ -1,6 +1,8 @@
 # Contributing to Terminal.Gui
 
 > **📘 This document is the single source of truth for all contributors (humans and AI agents) to Terminal.Gui.**
+>
+> For Terminal.Gui's product mission, design tenets, and engineering philosophy, see **[specs/constitution.md](./specs/constitution.md)**.
 
 Welcome! This guide provides everything you need to know to contribute effectively to Terminal.Gui, including project structure, build instructions, coding conventions, testing requirements, and CI/CD workflows.
 

Terminal.Gui/ViewBase/View.Command.cs

@@ -499,6 +499,16 @@ private void SetupCommands ()
     ///     <para>
     ///         See <see cref="View.RaiseAccepting"/> for more information.
     ///     </para>
+    ///     <para>
+    ///         <strong>When to use:</strong> Subscribe to <see cref="Accepting"/> only when you need to inspect or cancel the
+    ///         in-flight Accept operation (e.g., set <c>e.Handled = true</c> to prevent the accept). For simple side-effects
+    ///         that don't need to cancel, subscribe to <see cref="Accepted"/> instead — it is lighter-weight and communicates
+    ///         intent more clearly.
+    ///     </para>
+    ///     <para>
+    ///         <strong>Rule of thumb:</strong> If your handler doesn't read or set anything on <see cref="CommandEventArgs"/>
+    ///         (no <c>e.Handled</c>, no inspection of context), use <see cref="Accepted"/>.
+    ///     </para>
     /// </remarks>
     public event EventHandler<CommandEventArgs>? Accepting;
 
@@ -543,6 +553,19 @@ protected virtual void OnAccepted (ICommandContext? ctx) { }
     ///     <para>
     ///         See <see cref="RaiseAccepted"/> for more information.
     ///     </para>
+    ///     <para>
+    ///         <strong>When to use:</strong> Subscribe to <see cref="Accepted"/> for fire-and-forget side-effects — things that
+    ///         happen <em>after</em> the accept has completed and cannot be cancelled. This is the right choice for the vast
+    ///         majority of button-click–style handlers.
+    ///     </para>
+    ///     <para>
+    ///         <strong>Example:</strong>
+    ///         <code>
+    ///             button.Accepted += (_, _) =&gt; DoTheThing ();   // correct — side-effect only
+    ///             button.Accepting += (_, e) =&gt; { if (!CanProceed ()) e.Handled = true; }; // correct — cancels
+    ///             button.Accepting += (_, _) =&gt; DoTheThing (); // wrong — use Accepted instead
+    ///         </code>
+    ///     </para>
     /// </remarks>
     public event EventHandler<CommandEventArgs>? Accepted;
 
@@ -843,6 +866,18 @@ private void BubbleActivatedUp (ICommandContext? ctx, bool compositeOnly = false
     ///     Set CommandEventArgs.Handled to <see langword="true"/> to indicate the event was handled and processing should
     ///     stop.
     /// </summary>
+    /// <remarks>
+    ///     <para>
+    ///         <strong>When to use:</strong> Subscribe to <see cref="Activating"/> only when you need to inspect or cancel the
+    ///         in-flight Activate operation (e.g., set <c>e.Handled = true</c> to prevent the state change). For simple
+    ///         side-effects that don't need to cancel, subscribe to <see cref="Activated"/> instead — it is lighter-weight and
+    ///         communicates intent more clearly.
+    ///     </para>
+    ///     <para>
+    ///         <strong>Rule of thumb:</strong> If your handler doesn't read or set anything on <see cref="CommandEventArgs"/>
+    ///         (no <c>e.Handled</c>, no inspection of context), use <see cref="Activated"/>.
+    ///     </para>
+    /// </remarks>
     public event EventHandler<CommandEventArgs>? Activating;
 
     /// <summary>
@@ -913,6 +948,16 @@ protected virtual void OnActivated (ICommandContext? ctx) { }
     ///     Event raised when the user has performed an action (e.g. <see cref="Command.Activate"/>) causing the
     ///     View to change state or preparing it for interaction.
     /// </summary>
+    /// <remarks>
+    ///     <para>
+    ///         Unlike <see cref="Activating"/>, this event cannot be cancelled. It is raised after the View has activated.
+    ///     </para>
+    ///     <para>
+    ///         <strong>When to use:</strong> Subscribe to <see cref="Activated"/> for fire-and-forget side-effects — things
+    ///         that happen <em>after</em> the activation has completed and cannot be cancelled. This is the right choice for
+    ///         the vast majority of state-change–reaction handlers.
+    ///     </para>
+    /// </remarks>
     public event EventHandler<EventArgs<ICommandContext?>>? Activated;
 
     #endregion Activate

docfx/docs/events.md

@@ -42,6 +42,37 @@ Use this decision tree to choose the right pattern:
 | Simple notification (no cancel) | `EventHandler` | [Recipe 3](#recipe-3-simple-notification) |
 | Property notification (MVVM) | `INotifyPropertyChanged` | [Recipe 4](#recipe-4-mvvm-property-notification) |
 
+## When to Use `-ing` vs `-ed` Events
+
+Terminal.Gui exposes paired events on many surfaces — `Accepting`/`Accepted`, `Activating`/`Activated`, `ValueChanging`/`ValueChanged`, etc. Use this rule to choose:
+
+> **Use `-ed` (past-tense) events for side-effects. Use `-ing` (present-progressive) events only when you actually need to inspect or cancel the in-flight operation.**
+
+If your handler doesn't read or set anything on the `EventArgs` (no `e.Handled`, no `e.Cancel`, no inspection of the candidate value), you want the `-ed` event. The `-ing` event runs synchronously in the middle of the dispatch path and is heavier for both the framework and the reader of your code.
+
+### Concrete Examples
+
+```csharp
+// ✅ Correct — fire-and-forget side-effect belongs on the -ed event
+button.Accepted += (_, _) => DoTheThing ();
+
+// ✅ Correct — actually needs to cancel, so -ing is right
+button.Accepting += (_, e) => { if (!CanProceed ()) e.Handled = true; };
+
+// ❌ Wrong — handler ignores EventArgs; should use Accepted
+button.Accepting += (_, _) => DoTheThing ();
+```
+
+The same rule applies to every other paired event in the framework:
+
+| Use `-ed` (side-effect) | Use `-ing` (inspect / cancel) |
+|-------------------------|-------------------------------|
+| `Accepted` | `Accepting` |
+| `Activated` | `Activating` |
+| `ValueChanged` | `ValueChanging` |
+| `TextChanged` | `TextChanging` |
+| `TitleChanged` | `TitleChanging` |
+
 ## See Also
 
 * [Cancellable Work Pattern](cancellable-work-pattern.md) - Conceptual overview

specs/constitution.md

@@ -0,0 +1,110 @@
+# Terminal.Gui — Constitution
+
+> The tenets in each section are listed in **precedence order**. When two tenets conflict, the one higher in this document wins.
+
+This document is the single authoritative source for Terminal.Gui's product mission, non-goals, engineering philosophy, and design tenets. All other documents (`CONTRIBUTING.md`, `CLAUDE.md`, `.claude/rules/`, and the deep-dive docs in `docfx/docs/`) elaborate on these tenets; they do not supersede them.
+
+## Table of Contents
+
+- [I. Mission](#i-mission)
+- [II. Non-Goals](#ii-non-goals)
+- [III. Tenets](#iii-tenets)
+- [IV. Engineering Philosophy](#iv-engineering-philosophy)
+- [V. Code Style Tenets](#v-code-style-tenets)
+- [Relationship to Sub-Projects](#relationship-to-sub-projects)
+
+---
+
+## I. Mission
+
+Terminal.Gui is a **cross-platform UI toolkit for building sophisticated terminal UI (TUI) applications** on .NET. It is the standard by which TUI applications on .NET are measured.
+
+---
+
+## II. Non-Goals
+
+These were considered and rejected — do not accidentally pursue them:
+
+- **Terminal.Gui is not a web framework.** We do not pursue HTML/CSS layout models.
+- **Terminal.Gui is not a replacement for ncurses.** We target .NET developers, not C developers.
+- **Terminal.Gui is not a pixel renderer.** Width is measured in terminal cells, not pixels.
+- **Terminal.Gui is not opinionated about application architecture.** We provide building blocks; we do not mandate MVVM, MVC, or any other application pattern.
+- **Terminal.Gui does not own the terminal.** We share it with the host shell and must be good citizens (clean up on exit, respect terminal state).
+
+---
+
+## III. Tenets
+
+### Users Have Final Control
+
+Users choose the platform, the terminal, and the key bindings. Our defaults are consistent and sensible, but everything configurable must be configurable. We never hardcode behavior that the user or developer cannot override. See the [Keyboard deep dive](../docfx/docs/keyboard.md) and [Mouse deep dive](../docfx/docs/mouse.md).
+
+### Keyboard First; Mouse Optional
+
+Terminal users expect full functionality without a mouse. Anything that can be done with the mouse must also be doable with the keyboard. We avoid mouse-only features. See the [Mouse deep dive](../docfx/docs/mouse.md).
+
+### More Editor Than Command Line
+
+Once a Terminal.Gui app starts, the user is no longer using the command line. Users expect keyboard idioms consistent with GUI apps (VS Code, Vim, Emacs, etc.), not shell idioms. See the [Keyboard deep dive](../docfx/docs/keyboard.md).
+
+### Be Consistent With the User's Platform
+
+Users choose their platform. Terminal.Gui apps must respond to keyboard and mouse input in a way consistent with platform conventions. The source of truth for default key bindings is [Wikipedia's keyboard shortcuts table](https://en.wikipedia.org/wiki/Table_of_keyboard_shortcuts). See the [Keyboard deep dive](../docfx/docs/keyboard.md).
+
+### If It's Hot, It Works
+
+If a `View` with a `HotKey` is visible and the HotKey is shown, pressing that HotKey must invoke the defined behavior. We strive to ensure that modal contexts do not leave HotKeys appearing active when they are not. See the [Keyboard deep dive](../docfx/docs/keyboard.md).
+
+### Separation of Concerns
+
+Layout, focus, input, and drawing are cleanly decoupled. We resist the urge to merge them for short-term convenience. See the [v2 Architecture overview](../docfx/docs/newinv2.md) and [Layout deep dive](../docfx/docs/layout.md).
+
+### Testability First
+
+Views must be testable in isolation without global state. `Application.Init` is required only for integration tests. We maintain ≥80% test coverage and we never decrease it. See [Testing patterns](../.claude/rules/testing-patterns.md).
+
+### Performance Is a Feature
+
+We measure rendering and event-handling overhead. We never accept regressions in the hot path without a documented justification. See the [Drawing deep dive](../docfx/docs/drawing.md).
+
+### Documentation Is the Spec
+
+API documentation is the contract. When docs and code conflict, the code is wrong. See [api-documentation rules](../.claude/rules/api-documentation.md) and Code Style Tenet 5 in [CONTRIBUTING.md](../CONTRIBUTING.md).
+
+### Think in Graphemes, Not Runes
+
+Text measurement and rendering always operate on grapheme clusters, not `char` or `Rune` values. Always use `string.GetColumns()` for width; always iterate with `GraphemeHelper.GetGraphemes()` for rendering. See [Unicode/Grapheme rules](../.claude/rules/unicode-graphemes.md).
+
+---
+
+## IV. Engineering Philosophy
+
+Developers — AI agents and humans — working on Terminal.Gui strive to raise the bar as Principal Engineers. Principal Engineers are measured by how they live the [Amazon PE Community Tenets](https://www.amazon.jobs/content/en/teams/principal-engineering/tenets):
+
+1. **Exemplary practitioner** — set the standard through your own work.
+2. **Technically fearless** — tackle the hardest, most ambiguous problems.
+3. **Lead with empathy** — foster inclusion; be mindful of your impact.
+4. **Balanced and pragmatic** — neither dogmatic nor reckless.
+5. **Illuminate and clarify** — bring clarity to complexity; drive crisp decisions.
+6. **Flexible in approach** — adapt style and methods to the problem at hand.
+7. **Respect what came before** — appreciate existing systems; learn from the past.
+8. **Learn, educate, and advocate** — pursue continuous learning and teach others.
+9. **Have resounding impact** — results are the minimum; lasting impact is the bar.
+
+---
+
+## V. Code Style Tenets
+
+*(Source of truth: [CONTRIBUTING.md](../CONTRIBUTING.md))*
+
+1. **Six-Year-Old Reading Level** — Readability over terseness.
+2. **Consistency, Consistency, Consistency** — Follow existing patterns ruthlessly.
+3. **Don't Be Weird** — Follow Microsoft/.NET conventions.
+4. **Set and Forget** — Rely on automated tooling; don't fight the formatter.
+5. **Documentation Is the Spec** — API docs define the contract; implementation must match.
+
+---
+
+## Relationship to Sub-Projects
+
+Sub-projects (e.g., `Terminal.Gui.Text`) may extend this constitution. When a sub-project tenet conflicts with a tenet in this document, this document wins unless the sub-project explicitly documents the exception and the reason.