docs: Update documentation for 145 files

Generated by AurionDocs Job ID: c99fff50-67a3-4294-b4df-3e73f4f12de9 Source commit: 4dcb480
2026-09-04 23:34:10 +02:00 · 2026-07-23 08:10:35 +02:00
parent 4dcb480d1d
commit f8f4e03ddd
145 changed files with 22779 additions and 0 deletions
@@ -0,0 +1,23 @@
+# AudioPlayerDialog
+
+> **File:** `src/EchoHub.Client/UI/Dialogs/AudioPlayerDialog.cs`  
+> **Kind:** class
+
+```csharp
+public sealed class AudioPlayerDialog
+```
+
+
+AudioPlayerDialog is a sealed class that presents a modal Audio Player UI within the application's terminal UI. It assembles a compact layout with the current file name, a wave-like block visualization, playback status, and simple volume and playback controls, all exposed via a single Show method that binds an IApplication and an AudioPlaybackService to the dialog's lifecycle.
+
+## Remarks
+By encapsulating layout, colors, and animation in one place, it provides a reusable, cohesive UX for audio playback that can be dropped into different screens without duplicating UI code. The class relies on themed attributes (e.g. WaveActiveAttr, WaveIdleAttr, FileNameAttr, Status*Attr) to ensure consistent appearance, and uses a timer-driven animation loop to render the wave pattern while playback is active.
+
+## Example
+```csharp
+AudioPlayerDialog.Show(app, audioService, "/path/to/song.mp3", "song.mp3");
+```
+
+## Notes
+- The waveform visualization uses Unicode block characters; ensure your terminal font supports these glyphs for correct rendering.
+- The dialog starts a background animation timer; dispose the dialog or stop the timer to avoid leaks when closing.
@@ -0,0 +1,23 @@
+# ChannelPasswordDialog
+
+> **File:** `src/EchoHub.Client/UI/Dialogs/ChannelPasswordDialog.cs`  
+> **Kind:** class
+
+```csharp
+public sealed class ChannelPasswordDialog
+```
+
+
+Prompts for a channel password when joining a protected channel and returns the entered password, or null if the user cancels. Use this helper whenever you need a consistent, modal password prompt instead of duplicating dialog boilerplate across join flows.
+
+## Remarks
+This class centralizes the user flow for joining password-protected channels. It presents a modal dialog titled Join #<channel>, collects the password, and returns it to the caller, ensuring a single, predictable contract. The UI avoids displaying the actual password text by using a redacted caption and automatically focusing the password field, while the dialog lifecycle is orchestrated through the application (app.Run and app.RequestStop).
+
+## Example
+```csharp
+string? password = ChannelPasswordDialog.Show(app, "mychannel", "Enter password to join #mychannel.");
+```
+
+## Notes
+- The method is synchronous and modal; it blocks the caller until the user completes the interaction.
+- A null return value indicates the user canceled the operation. If the user submits an empty password, a brief error dialog is shown and the prompt remains active until a non-empty password is provided.
@@ -0,0 +1,80 @@
+# ConnectDialog.cs
+
+> **Source:** `src/EchoHub.Client/UI/Dialogs/ConnectDialog.cs`
+
+## Contents
+
+- [ConnectDialog](#connectdialog)
+- [ConnectDialogResult](#connectdialogresult)
+
+---
+
+## ConnectDialog
+> **File:** `src/EchoHub.Client/UI/Dialogs/ConnectDialog.cs`  
+> **Kind:** class
+
+```csharp
+public sealed class ConnectDialog
+```
+
+
+ConnectDialog is a Terminal.Gui-based dialog that collects server connection details and authentication information for the application. When shown, it can display a list of SavedServer entries at the top if any saved servers are provided; in that case a Saved Servers section is rendered with a ListView of display names that indicate whether a session exists (the code appends a [session] marker when a RefreshToken is present). Below (or in place of it, when there are no saved servers), the dialog presents manual entry fields for Server URL (default http://localhost:5000), Username, and Password, along with UI hints such as a hidden password placeholder and a Remember me option. Additional fields include Display Name and, when relevant, an Invite Code for invite-gated registrations. The static Show method returns a ConnectDialogResult when the user completes the dialog, or null if the dialog is cancelled; the dialog height is adjusted depending on whether saved servers are shown.
+
+---
+
+## ConnectDialogResult
+> **File:** `src/EchoHub.Client/UI/Dialogs/ConnectDialog.cs`  
+> **Kind:** record
+
+```csharp
+public record ConnectDialogResult(
+    string ServerUrl, string Username, string Password,
+    bool IsRegister, bool RememberMe, string? SavedRefreshToken,
+    string? DisplayName = null, string? InviteCode = null)
+```
+
+**Parameters:**
+
+| Parameter | Type | Default |
+|-----------|------|---------|
+| `ServerUrl` | `string` | — |
+| `Username` | `string` | — |
+| `Password` | `string` | — |
+| `IsRegister` | `bool` | — |
+| `RememberMe` | `bool` | — |
+| `SavedRefreshToken` | `string?` | — |
+| `DisplayName` | `string?` | `null` |
+| [`InviteCode`](../../../EchoHub.Core/Models/InviteCode.cs.md) | `string?` | `null` |
+
+
+ConnectDialogResult encapsulates all user input gathered from the connect dialog as a single, immutable value. It is produced when the dialog completes and is consumed by the rest of the application to initiate a connection flow, passing the server URL, credentials, and onboarding flags as a single, strongly-typed package.
+
+## Remarks
+
+By collecting all related fields into a single record, this abstraction reduces coupling between the UI layer and the connection logic. It clearly expresses the intent of the user's action (login vs register) and whether credentials should be remembered, while allowing optional data (DisplayName, InviteCode) to participate in specialized flows without forcing callers to thread every field separately.
+
+## Example
+
+```csharp
+// Common usage: construct a result from values collected in UI
+var result = new ConnectDialogResult(
+    ServerUrl: "https://example.server/api",
+    Username: "alice",
+    Password: "P@ssw0rd",
+    IsRegister: false,
+    RememberMe: true,
+    SavedRefreshToken: null,
+    DisplayName: "Alice",
+    InviteCode: "INVITE-2024-ABCD"
+);
+```
+
+## Notes
+
+- DisplayName and InviteCode are nullable; omit them or pass null if not applicable.
+- Password should be treated as sensitive data: avoid logging it or persisting it longer than necessary, and ensure proper disposal or clearing after use.
+- SavedRefreshToken may be null; handle accordingly in login/refresh flows.
+- This record is intended for in-memory transfer between UI and authentication/connection logic; when persisting or transmitting, apply appropriate security measures and avoid leaking confidential fields.
+
+
+---
@@ -0,0 +1,74 @@
+# CreateChannelDialog.cs
+
+> **Source:** `src/EchoHub.Client/UI/Dialogs/CreateChannelDialog.cs`
+
+## Contents
+
+- [CreateChannelDialog](#createchanneldialog)
+- [CreateChannelResult](#createchannelresult)
+
+---
+
+## CreateChannelDialog
+> **File:** `src/EchoHub.Client/UI/Dialogs/CreateChannelDialog.cs`  
+> **Kind:** class
+
+```csharp
+public sealed class CreateChannelDialog
+```
+
+
+Displays a modal Create Channel dialog that collects the details needed to create a new channel: a name, an optional topic, a password, and a public visibility setting. The name is trimmed and normalized to lower case; if it is empty, the dialog reports an error and stays open. On Create, it builds a CreateChannelResult containing the name, topic (nullable), isPublic, and the password; on Cancel it returns null. The dialog runs via the provided IApplication instance and returns after the user makes a choice.
+
+## Remarks
+Encapsulates all UI logic for channel creation into a single entry point, enabling consistent behavior across the app and isolating rendering from business logic. The class acts as a small, self-contained UX widget that constructs the result object, ensuring callers need only handle the CreateChannelResult or null.
+
+## Notes
+- Name validation is minimal in code: the name is trimmed and lowercased, and non-empty; there is no explicit enforcement of length or allowed character patterns at runtime beyond what the UI hints suggest.
+- Password handling appears behind-the-scenes (the UI labels redact the password, yet the password value is captured and returned as part of the result); ensure secure handling and minimize exposure of the plaintext password.
+- The snippet references passwordField and publicCheckbox, which must exist in the full class scope; if you modify the UI composition, ensure these controls are present and wired consistently with the password retrieval and public visibility logic.
+
+---
+
+## CreateChannelResult
+> **File:** `src/EchoHub.Client/UI/Dialogs/CreateChannelDialog.cs`  
+> **Kind:** record
+
+```csharp
+public record CreateChannelResult(string Name, string? Topic, bool IsPublic, string? Password)
+```
+
+**Parameters:**
+
+| Parameter | Type | Default |
+|-----------|------|---------|
+| `Name` | `string` | — |
+| `Topic` | `string?` | — |
+| `IsPublic` | `bool` | — |
+| `Password` | `string?` | — |
+
+
+CreateChannelResult is an immutable data carrier that represents the outcome of creating a channel in the EchoHub client UI. It carries the channel's Name, an optional Topic, a flag IsPublic indicating whether the channel is public, and an optional Password.
+
+## Remarks
+As a record, CreateChannelResult participates in value-based equality, making comparisons straightforward without manual field checks. The positional constructor provides a concise, immutable payload that is easy to pass through layers (UI, services, or view models). You can deconstruct a result into its components, or derive a modified copy with a with-expression if you need a slightly different result without mutating the original. This type is intended to be produced by the channel-creation flow and consumed by UI code and downstream components.
+
+## Example
+```csharp
+// Common case: create a public channel with a topic and password
+var result = new CreateChannelResult("General", "Team discussions", true, "s3cr3t");
+
+// Access fields
+string name = result.Name;
+string? topic = result.Topic;
+bool isPublic = result.IsPublic;
+string? password = result.Password;
+
+// Deconstruct for convenience
+var (n, t, pub, pwd) = result;
+
+// Create a modified copy
+var updated = result with { Topic = "New topic" };
+```
+
+---
@@ -0,0 +1,64 @@
+# ProfileEditDialog.cs
+
+> **Source:** `src/EchoHub.Client/UI/Dialogs/ProfileEditDialog.cs`
+
+## Contents
+
+- [ProfileEditDialog](#profileeditdialog)
+- [ProfileEditResult](#profileeditresult)
+
+---
+
+## ProfileEditDialog
+> **File:** `src/EchoHub.Client/UI/Dialogs/ProfileEditDialog.cs`  
+> **Kind:** class
+
+```csharp
+public sealed class ProfileEditDialog
+```
+
+
+ProfileEditDialog provides a Terminal.Gui dialog for editing the user's profile. Its Show method presents a modal dialog titled "Edit Profile" with fields for Display Name, Bio, Nickname Color (with a hex input and a live color preview) and Avatar selection, plus notification preferences, returning a ProfileEditResult when the user accepts or null if cancelled.
+
+## Remarks
+ProfileEditDialog centralizes profile-edit UI in one reusable component, ensuring a consistent look and behavior whenever the user updates their profile. It wires up real-time color previews by updating the color swatch whenever the hex input changes, and it delegates color parsing to HexColorHelper to translate user input into a Color value. The Avatar field demonstrates integration with a file picker (OpenDialog) within a Terminal.Gui workflow, keeping file selection cohesive with the rest of the dialog.
+
+## Notes
+- The Show method accepts optional parameters for notificationSoundEnabled and notificationVolume, defaulting to false and 30 respectively.
+- If no avatar is selected, avatarField.Text remains empty.
+- The return type is ProfileEditResult?; callers should handle null to cover the cancel path.
+- This implementation relies on Terminal.Gui primitives (Label, TextField, Button, CheckBox, OpenDialog) and collaborator types (ProfileEditResult, HexColorHelper); ensure these types are available in the consuming project.
+
+---
+
+## ProfileEditResult
+> **File:** `src/EchoHub.Client/UI/Dialogs/ProfileEditDialog.cs`  
+> **Kind:** record
+
+```csharp
+public record ProfileEditResult(string? DisplayName, string? Bio, string? NicknameColor, string? AvatarPath, bool? NotificationSoundEnabled, byte? NotificationVolume)
+```
+
+**Parameters:**
+
+| Parameter | Type | Default |
+|-----------|------|---------|
+| `DisplayName` | `string?` | — |
+| `Bio` | `string?` | — |
+| `NicknameColor` | `string?` | — |
+| `AvatarPath` | `string?` | — |
+| `NotificationSoundEnabled` | `bool?` | — |
+| `NotificationVolume` | `byte?` | — |
+
+
+Represents the data returned from the profile edit dialog. It encapsulates the user\'s optional inputs for DisplayName, Bio, NicknameColor, AvatarPath, NotificationSoundEnabled, and NotificationVolume so the caller can apply changes in a single operation. Each property is nullable: a null value means no change for that field; a non-null value provides a new value to persist.
+
+## Remarks
+ProfileEditResult is an immutable value object used as the dialog\'s return type. Its nullable fields express a delta: non-null values indicate updates, while null indicates no change. As a record, it benefits from value-based equality, making comparisons and tests straightforward, and it cleanly separates UI input from downstream update logic.
+
+## Notes
+- Null values indicate no change; apply only non-null fields when updating the profile.
+- The type is immutable; to derive modifications, use a with-expression to create a new instance.
+
+
+---
@@ -0,0 +1,51 @@
+# ProfileViewDialog.cs
+
+> **Source:** `src/EchoHub.Client/UI/Dialogs/ProfileViewDialog.cs`
+
+## Contents
+
+- [ProfileViewDialog](#profileviewdialog)
+- [ProfileAction](#profileaction)
+
+---
+
+## ProfileViewDialog
+> **File:** `src/EchoHub.Client/UI/Dialogs/ProfileViewDialog.cs`  
+> **Kind:** class
+
+```csharp
+public sealed class ProfileViewDialog
+```
+
+
+ProfileViewDialog renders a dialog to view a user's server profile; when showing the current user's profile it also exposes action buttons (Edit Profile / Set Status) and returns the chosen ProfileAction, while viewing another user yields a read-only presentation.
+
+## Remarks
+ProfileViewDialog encapsulates all the layout and formatting decisions for a user profile in a single place. It dynamically switches between a read-only view and an ownership-aware view that surfaces actions, and it applies color theming to the status and nickname fields. By centralizing this UI behavior, the dialog remains consistent across the application and reduces duplication by isolating profile presentation from business logic. The component gracefully handles a missing profile by showing an error message and returning a Close action, which defines a clear contract for callers.
+
+## Notes
+- If invoked with a null profile, the dialog shows an error and returns ProfileAction.Close; callers should guard against null input or handle the Close result accordingly.
+- The dialog title differentiates ownership with "My Profile" for the current user and "Profile — {username}" for others, and it uses color-coding helpers to reflect status and nickname color for quick visual cues.
+
+---
+
+## ProfileAction
+> **File:** `src/EchoHub.Client/UI/Dialogs/ProfileViewDialog.cs`  
+> **Kind:** enum
+
+```csharp
+public enum ProfileAction
+{
+    Close,
+    EditProfile,
+    SetStatus
+}
+```
+
+
+ProfileAction defines the set of actions a user can select from their profile dialog: Close, EditProfile, and SetStatus. It provides a typed representation of user intent that downstream UI logic can handle in a deterministic way, rather than relying on magic strings or numeric codes.
+
+## Remarks
+ProfileAction represents the user’s chosen action from the profile dialog, allowing the UI layer to dispatch the appropriate workflow in a type-safe way. By enumerating possible intents, the code can exhaustively handle all cases in a switch or pattern-match, reducing errors from invalid values. The Close action also clarifies that the action is about dialog lifecycle control as opposed to in-dialog tasks such as editing or setting status. If new actions are required in the future, they should be added here with clear naming that maps to corresponding UI behaviors.
+
+---
@@ -0,0 +1,94 @@
+# SearchDialog.cs
+
+> **Source:** `src/EchoHub.Client/UI/Dialogs/SearchDialog.cs`
+
+## Contents
+
+- [SearchDialog](#searchdialog)
+- [SearchResult](#searchresult)
+- [SearchResultType](#searchresulttype)
+
+---
+
+## SearchDialog
+> **File:** `src/EchoHub.Client/UI/Dialogs/SearchDialog.cs`  
+> **Kind:** class
+
+```csharp
+public static class SearchDialog
+```
+
+
+SearchDialog is a command-palette style search dialog used to quickly navigate channels and trigger common app actions from a single, keyboard-driven interface. Use it when you want fast, non-mouse access to channels and actions by filtering a combined list and selecting with Enter.
+
+## Remarks
+SearchDialog composes a modal dialog that presents both channel names and a predefined set of actions, merged into a single searchable list via a SearchListSource. It returns the selected SearchResult and signals completion to the hosting application by invoking RequestStop on IApplication, keeping the dialog logic decoupled from the rest of the UI. This abstraction enables a reusable, consistent navigation surface across different parts of the app.
+
+## Example
+```csharp
+// Example
+IApplication app = /* obtain your app instance */;
+IReadOnlyList<string> channels = new[] { "general", "engineering" };
+var result = SearchDialog.Show(app, channels);
+if (result != null)
+{
+    // Handle the selected item (channel or action) here.
+}
+```
+
+## Notes
+- The dialog includes a hint, a text field for filtering, a list of results, and a Cancel button; selection is returned as a SearchResult, or null if cancelled.
+- Ctrl+K handling in both the dialog and the search field cancels the operation by requesting stop from the application, so be aware that this combo acts as a cancel gesture rather than an open/search trigger.
+- When items exist, the first item is pre-selected; filtering updates the source and may reset the selection.
+
+
+---
+
+## SearchResult
+> **File:** `src/EchoHub.Client/UI/Dialogs/SearchDialog.cs`  
+> **Kind:** record
+
+```csharp
+public record SearchResult(SearchResultType Type, string Key, string Label)
+```
+
+**Parameters:**
+
+| Parameter | Type | Default |
+|-----------|------|---------|
+| `Type` | `SearchResultType` | — |
+| `Key` | `string` | — |
+| `Label` | `string` | — |
+
+
+Represents a single entry in search results, encapsulating the result's category (Type), a key (Key), and a user-facing label (Label). As a positional-record, it is immutable and compared by value, which makes it convenient to pass around and render in the search UI.
+
+## Remarks
+Use SearchResult to model a single outcome returned by the search feature. Type communicates the kind of item (as defined by SearchResultType), Key is the stable identifier for navigation or lookup, and Label is the display text shown in the results list. Because it is a deconstructible record, you can conveniently extract its fields with deconstruction or pattern matching, and equality checks are based on the content rather than the instance identity.
+
+## Notes
+- Immutability: SearchResult uses a primary constructor; properties are read-only and a modified instance must be created with a with-expression or a new constructor.
+- Deconstruction: The positional constructor enables deconstruction: var (t, k, l) = result; or access via result.Type, result.Key, result.Label.
+- Type relies on the SearchResultType enum; when consuming code, prefer switching on Type rather than comparing display strings.
+
+---
+
+## SearchResultType
+> **File:** `src/EchoHub.Client/UI/Dialogs/SearchDialog.cs`  
+> **Kind:** enum
+
+```csharp
+public enum SearchResultType
+{
+    Channel,
+    Action
+}
+```
+
+
+Represents the category of a search result in the EchoHub client UI, distinguishing Channel results from Action results. Developers reach for this enum to branch rendering or navigation logic based on the result type, instead of using boolean flags or string comparisons.
+
+## Remarks
+Because it is a small discriminant, SearchResultType is typically consumed alongside a broader SearchResult structure. It enables simple pattern matching in switch expressions or if statements, guiding UI decisions such as which view to open or which icon to display when a user selects a result.
+
+---
@@ -0,0 +1,69 @@
+# StatusDialog.cs
+
+> **Source:** `src/EchoHub.Client/UI/Dialogs/StatusDialog.cs`
+
+## Contents
+
+- [StatusDialog](#statusdialog)
+- [StatusDialogResult](#statusdialogresult)
+
+---
+
+## StatusDialog
+> **File:** `src/EchoHub.Client/UI/Dialogs/StatusDialog.cs`  
+> **Kind:** class
+
+```csharp
+public sealed class StatusDialog
+```
+
+
+StatusDialog is a terminal-based UI component that presents a compact dialog for updating the current user's status and an optional status message. Its Show method renders the dialog initialized with the provided current status and message, and returns a StatusDialogResult when the user saves, or null if the user cancels.
+
+The dialog consists of a title 'Set Status', a status option selector pre-populated with the current status, a text field for the status message, and Save/Cancel actions. On Save, the selected status is captured (defaulting to Online if nothing is selected) and the message is trimmed; an empty message becomes null. The method returns a new StatusDialogResult with those values and stops the application loop via app.RequestStop(); Cancel returns null and stops the loop.
+
+Callers use the returned result to apply the updated status and message; otherwise, no changes are made.
+
+## Remarks
+StatusDialog encapsulates the presentation logic for updating user status, isolating UI concerns from business logic. It is a small, reusable piece that orchestrates Terminal.Gui controls (Dialog, Label, OptionSelector, TextField, Button) and relies on IApplication to drive the modal flow. The use of a default Online and trimming of the message ensures sane behavior even when fields are left blank.
+
+## Example
+```csharp
+var result = StatusDialog.Show(app, currentStatus, currentMessage);
+if (result != null)
+{
+    // Apply updates to the user's status and message
+    currentStatus = result.Status;
+    currentMessage = result.Message;
+}
+```
+
+## Notes
+- A null result indicates the user cancelled the dialog; callers should guard against applying changes in this case.
+- If the user leaves the Message field blank or whitespace, the message is stored as null.
+- The Save action is wired as the default action (IsDefault = true), and both Save and Cancel terminate the modal interaction by invoking app.RequestStop().
+
+---
+
+## StatusDialogResult
+> **File:** `src/EchoHub.Client/UI/Dialogs/StatusDialog.cs`  
+> **Kind:** record
+
+```csharp
+public record StatusDialogResult(UserStatus Status, string? StatusMessage)
+```
+
+**Parameters:**
+
+| Parameter | Type | Default |
+|-----------|------|---------|
+| `Status` | [`UserStatus`](../../../EchoHub.Core/Models/UserStatus.cs.md) | — |
+| `StatusMessage` | `string?` | — |
+
+
+StatusDialogResult is a minimal, immutable data carrier returned when the status dialog completes. It groups the chosen user status (Status) with an optional message (StatusMessage) into a single value that downstream logic can consume without inspecting the dialog UI directly. As a C# record, it benefits from value-based equality and straightforward deconstruction.
+
+## Remarks
+StatusDialogResult encapsulates the outcome of a UI interaction into a single semantic unit that can be passed through the application flow or stored for auditing. It separates presentation concerns from business logic: callers reason about the user's status and optional message rather than UI details. The nullable StatusMessage signals that extra context is optional; consumer code should handle the absence gracefully, typically by pattern matching on Status and checking for a non-null message. The record type also supports structural equality, making tests and comparisons concise.
+
+---
@@ -0,0 +1,14 @@
+# UpdateConfirmDialog
+
+> **File:** `src/EchoHub.Client/UI/Dialogs/UpdateConfirmDialog.cs`  
+> **Kind:** class
+
+```csharp
+public sealed class UpdateConfirmDialog
+```
+
+
+UpdateConfirmDialog is a sealed utility with a single static Show method that prompts the user to confirm an available update. It builds a small modal dialog titled “Update Available” showing the current and latest versions and offers two actions: Update (default) and Cancel; it returns true if the user chooses Update and false otherwise. The method runs the provided IApplication until the user makes a choice, using RequestStop to close the dialog and return the result.
+
+## Remarks
+It encapsulates the update-confirmation interaction as a reusable, modal prompt that coordinates with the host application's event loop, avoiding duplication of dialog boilerplate across the codebase.