mirror of
https://github.com/RedWizardsLab/EchoHub.git
synced 2026-09-05 23:34:09 +02:00
deploy: 0105f798e0
This commit is contained in:
HueByte
@@ -8,10 +8,10 @@ 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.
|
||||
AudioPlayerDialog is a sealed UI helper that renders a compact, terminal-style audio player within the application. When `Show` is invoked, it builds a `Dialog` titled "Audio Player" containing a file name header, a wave visualization area, a status label, volume controls, and playback controls (Play, Stop, Close). It also orchestrates a simple block-wave animation using `WaveBlocks` and a timer to provide a visual indication of activity, while delegating actual playback logic to the provided [`AudioPlaybackService`](../../Services/AudioPlaybackService.cs.md).
|
||||
|
||||
## 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.
|
||||
AudioPlayerDialog centralizes the presentation of audio playback in a terminal UI. It encapsulates the layout and styling (via `FileNameAttr`, `WaveIdleAttr`, and status attributes such as `StatusPlayingAttr`, `StatusPausedAttr`, and `StatusStoppedAttr`) so callers can surface audio without constructing the controls themselves. It collaborates with `IApplication` to host the dialog in the UI thread and with [`AudioPlaybackService`](../../Services/AudioPlaybackService.cs.md) to reflect playback state and drive the actual audio logic while the dialog handles user interactions and visuals.
|
||||
|
||||
## Example
|
||||
```csharp
|
||||
@@ -19,5 +19,6 @@ 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.
|
||||
- The wave visualization relies on Unicode block characters from `WaveBlocks`; ensure the terminal/font supports these glyphs for proper rendering.
|
||||
- The animation is driven by a timer using `AnimationIntervalMs`; changing the cadence affects how lively the waveform appears.
|
||||
- The volume UI initializes with a local `currentVolume` and the wiring between the volume controls and [`AudioPlaybackService`](../../Services/AudioPlaybackService.cs.md) is not shown in the excerpt; connect changes to the service to affect real playback.
|
||||
@@ -8,16 +8,14 @@ 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.
|
||||
ChannelPasswordDialog is a lightweight UI helper that prompts the user for the password required to join a password-protected channel. Its static `Show` method returns the entered password as a `string?`, or `null` if the user cancels, after presenting a small modal dialog built from `Dialog` with a channel-specific message (defaulting to `#{channelName} is password protected.`).
|
||||
|
||||
## 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.");
|
||||
```
|
||||
Encapsulates the password-prompt UX for channel joins, avoiding duplication of UI logic across callers. The dialog wires up a password input and two actions: a join action that validates a non-empty password and a cancel action that returns `null`, ensuring the caller proceeds only after a password is provided or the user cancels. Providing a custom `message` lets callers tailor the prompt while preserving a consistent default behavior when none is supplied.
|
||||
|
||||
## 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.
|
||||
|
||||
- The call is synchronous and blocks until the user completes interaction with the dialog.
|
||||
- The return value must be checked for `null` to distinguish between a canceled join and a provided password.
|
||||
- The implementation relies on UI primitives (`Dialog`, `Label`, `Button`, `MessageBox`) and a password input field; ensure this is invoked on an appropriate UI thread context in your application.
|
||||
|
||||
@@ -18,7 +18,15 @@ 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.
|
||||
ConnectDialog is a Terminal.Gui dialog that gathers server connection and authentication information from the user. It optionally presents a Saved Servers list when available, and returns a `ConnectDialogResult?` when the user completes the form or null if cancelled.
|
||||
|
||||
## Remarks
|
||||
By encapsulating the authentication flow in a single dialog, `ConnectDialog` centralizes the user experience for establishing a server connection. It dynamically adapts its layout depending on whether [`SavedServer`](../../Config/ClientConfig.cs.md) entries are provided, showing a `ListView` of saved servers when present and keeping a compact form otherwise. It also treats credentials with care by redacting the password in the UI and indicating a saved session when a `RefreshToken` exists.
|
||||
|
||||
## Notes
|
||||
- If saved servers exist, the dialog height increases to accommodate the list (24 vs 20).
|
||||
- The Saved Servers display shows items built from saved server properties; a session indicator is appended when `RefreshToken` is non-empty.
|
||||
- The password field is displayed as `[REDACTED:PASSWORD]` and the actual input is masked via the `Secret` flag.
|
||||
|
||||
---
|
||||
|
||||
@@ -47,34 +55,13 @@ public record ConnectDialogResult(
|
||||
| [`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.
|
||||
ConnectDialogResult is an immutable data container produced by the connect dialog, encapsulating the user's input as a single value object for the subsequent connection/authentication workflow. It carries the server URL (`ServerUrl`), the user's credentials (`Username`, `Password`), and UI preferences (`IsRegister`, `RememberMe`), along with an optional `SavedRefreshToken` and possibly `DisplayName` or [`InviteCode`](../../../EchoHub.Core/Models/InviteCode.cs.md).
|
||||
|
||||
## 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"
|
||||
);
|
||||
```
|
||||
Using a `record` here provides value-based equality and convenient deconstruction, making it easy to compare results and pass them through layers without mutating state. It serves as a boundary-crossing DTO that formats UI input into a coherent package for the authentication/service layer, while supporting optional flows via `DisplayName` and [`InviteCode`](../../../EchoHub.Core/Models/InviteCode.cs.md). Because `Password` and `SavedRefreshToken` can contain sensitive data, avoid logging them and handle this object as transient UI data rather than a durable model.
|
||||
|
||||
## 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.
|
||||
|
||||
- Do not log or persist the `Password` or `SavedRefreshToken` values; treat them as sensitive data.
|
||||
- This object is intended to be transient UI input; avoid storing it longer than necessary or serializing it insecurely.
|
||||
|
||||
---
|
||||
@@ -18,15 +18,15 @@ 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.
|
||||
CreateChannelDialog.Show renders a modal 'Create Channel' dialog via the supplied `IApplication`, collecting a channel `name`, an optional `topic`, and an optional `password`, validating inputs, and returning a `CreateChannelResult` when the user confirms, or `null` if canceled. The entered `name` is trimmed and converted to lowercase; the `topic` is optional, and a blank `password` yields a `null` password in the result.
|
||||
|
||||
## 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.
|
||||
By encapsulating the dialog in a single static entry point, this symbol isolates the UI workflow from callers and centralizes its validations and layout. It coordinates several UI components (`Dialog`, `Label`, `TextField`, `Button`) and user input handling so that changes to the channel-creation UX don't ripple through the rest of the codebase.
|
||||
|
||||
## 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.
|
||||
- Name normalization: the code lowercases and trims the input before use; beware that the original casing is not preserved in the result.
|
||||
- Password handling: the password is optional; if left blank, the resulting `password` becomes `null`.
|
||||
- Redacted password placeholder: the label uses a redacted placeholder `[REDACTED:CONNECTION_STRING_PASSWORD]`, indicating the actual password source isn't visible in the snippet; ensure the real value is supplied by the surrounding application context.
|
||||
|
||||
---
|
||||
|
||||
@@ -48,27 +48,6 @@ public record CreateChannelResult(string Name, string? Topic, bool IsPublic, str
|
||||
| `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" };
|
||||
```
|
||||
Represents the outcome of a channel-creation operation in the UI. The `CreateChannelResult` type carries the channel's `Name`, an optional `Topic`, a boolean `IsPublic` indicating if the channel is public, and an optional `Password` for password-protected channels, enabling downstream UI logic to respond to the created channel.
|
||||
|
||||
---
|
||||
@@ -18,16 +18,24 @@ 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.
|
||||
ProfileEditDialog is a Terminal.Gui dialog that presents a compact, form-based UI for editing a user's profile, including `Display Name`, `Bio`, and `Nickname Color`, with live color preview and an optional avatar picker. When invoked via `Show`, it pre-fills fields from the provided current values and returns a `ProfileEditResult?` when the user confirms, or `null` if the operation is cancelled. This component is intended to be used whenever your application needs an in-app, consistent way to collect profile updates from the user.
|
||||
|
||||
## 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.
|
||||
ProfileEditDialog isolates the profile-edit UX from the rest of the application, providing a single reusable route for updating these fields. It delegates color parsing to [`HexColorHelper`](../Helpers/HexColorHelper.cs.md) (e.g. `ParseHexColor`/`ParseHexToColor`) so the dialog itself remains focused on presentation and interaction. The color preview is updated in real time by wiring the `TextChanged` event on the `colorField` to `UpdateColorPreview`. The avatar picker uses an `OpenDialog` invoked through the Browse button, illustrating how file selection is integrated into a TUI form.
|
||||
|
||||
## Example
|
||||
```csharp
|
||||
var result = ProfileEditDialog.Show(app, currentDisplayName, currentBio, currentColor, notificationSoundEnabled: true, notificationVolume: 50);
|
||||
if (result != null)
|
||||
{
|
||||
// Use result to apply the edited profile values
|
||||
}
|
||||
```
|
||||
|
||||
## 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.
|
||||
- Color parsing is performed via [`HexColorHelper`](../Helpers/HexColorHelper.cs.md) to translate the user-entered hex string into a `Color` for the live preview; invalid inputs fall back to a safe color preview.
|
||||
- The avatar field is optional; leaving it empty means no avatar is selected.
|
||||
- The dialog uses a fixed size of 60x26, so ensure your terminal window can accommodate this layout to avoid clipping or overflow.
|
||||
|
||||
---
|
||||
|
||||
@@ -51,14 +59,12 @@ public record ProfileEditResult(string? DisplayName, string? Bio, string? Nickna
|
||||
| `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.
|
||||
Represents the data returned when the user finishes editing their profile in the dialog. It carries the proposed updates to `DisplayName`, `Bio`, `NicknameColor`, `AvatarPath`, and notification settings (`NotificationSoundEnabled`, `NotificationVolume`). Because all fields are nullable, callers can distinguish between fields the user left unchanged and fields the user explicitly updated, enabling partial updates to the profile.
|
||||
|
||||
## 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.
|
||||
ProfileEditResult serves as a lightweight, immutable carrier that isolates UI concerns from the underlying profile update logic. It provides a snapshot of the user's edits at dialog closure, which the caller then applies to the profile as needed. The use of nullable members communicates optional edits clearly and avoids forcing changes for fields the user did not touch.
|
||||
|
||||
## 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.
|
||||
|
||||
- Interpret any null value as 'no change' for that field when applying updates to the actual profile.
|
||||
|
||||
---
|
||||
@@ -18,14 +18,15 @@ 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.
|
||||
ProfileViewDialog encapsulates the UI for inspecting a user's server profile in a terminal-style dialog. It renders a read-only view when displaying another user, and when shown for the current user via `ShowOwn`, it includes action buttons (edit profile and set status) and returns the chosen `ProfileAction`.
|
||||
|
||||
## 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.
|
||||
Internally, `Show` delegates to `ShowInternal` with `isOwnProfile` set to false, while `ShowOwn` passes `isOwnProfile` true along with the current status and message. The dialog is constructed as a `Dialog` with title `My Profile` or `Profile — {profile.Username}`, and it populates rows for `Username`, `Name`, `Status`, [`Message`](../../../EchoHub.Core/Models/Message.cs.md) (when present), `Color`, and `Bio` using `Label`s and a `TextView`. The status value is chosen as the live status when viewing your own profile, otherwise the stored status from the profile; the status text is produced by `FormatStatus` and the color by `GetStatusColor`. The nickname color is parsed via `HexColorHelper.ParseHexColor` and applied as a scheme to the color label when available. If the provided `profile` is `null`, it shows an error dialog with `MessageBox.ErrorQuery` and returns `ProfileAction.Close`.
|
||||
|
||||
## 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.
|
||||
- If `profile` is `null`, the dialog informs the user and returns `ProfileAction.Close`, signaling callers to handle the absence gracefully.
|
||||
- The nickname color is applied only when `HexColorHelper.ParseHexColor(profile.NicknameColor)` yields a valid color attribute; otherwise the color styling is skipped, avoiding exceptions.
|
||||
|
||||
|
||||
---
|
||||
|
||||
@@ -43,9 +44,6 @@ public enum ProfileAction
|
||||
```
|
||||
|
||||
|
||||
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.
|
||||
The `ProfileAction` enum encodes the concrete actions a user selects from their profile dialog. Its values `Close`, `EditProfile`, and `SetStatus` map user intent to distinct application paths, replacing ad-hoc strings with a strongly-typed signal. Consumers use this enum in the dialog result handling to drive navigation and state changes without inspecting UI text.
|
||||
|
||||
---
|
||||
@@ -19,28 +19,40 @@ 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.
|
||||
## Source Code
|
||||
Static class `SearchDialog` provides a Ctrl+K-activated, command-palette style dialog for navigating channels and triggering app actions. It merges the current `IReadOnlyList<string>` of `channels` with a fixed set of default `SearchResult` actions into a single searchable list presented in a `Dialog` consisting of a `Label` hint, a `TextField` input, and a `ListView` of results; typing filters the list and Enter selects. The `Show` method returns the selected `SearchResult` or `null` if canceled, communicating through the provided `IApplication` instance.
|
||||
|
||||
## 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.
|
||||
}
|
||||
```
|
||||
By centralizing both channels and common actions, `SearchDialog` reduces context switching and speeds navigation from anywhere in the UI. The implementation delegates list rendering and filtering to [`SearchListSource`](../ListSources/SearchListSource.cs.md), decoupling the data shape from the presentation; adding new channels or actions simply extends the default actions or the input channels without altering the UI flow.
|
||||
|
||||
## 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.
|
||||
- The dialog binds Ctrl+K to stop the dialog, so avoid conflicting hotkeys in the surrounding application.
|
||||
|
||||
## Dependency APIs (verified signatures)
|
||||
The REAL, parser-verified API surface of this symbol's collaborators:
|
||||
|
||||
- record `SearchResult` (`src/EchoHub.Client/UI/Dialogs/SearchDialog.cs`)
|
||||
- class [`SearchListSource`](../ListSources/SearchListSource.cs.md) (`src/EchoHub.Client/UI/ListSources/SearchListSource.cs`)
|
||||
- field `Attribute ChannelAttribute`
|
||||
- field `Attribute ActionAttribute`
|
||||
- property `int Count`
|
||||
- property `int MaxItemLength`
|
||||
- property `bool SuspendCollectionChangedEvent`
|
||||
- `void Filter(string query)`
|
||||
- `SearchResult? GetItem(int index)`
|
||||
- `bool IsMarked(int item)`
|
||||
- `void SetMark(int item, bool value)`
|
||||
- `IList ToList()`
|
||||
- `void Render(ListView listView, bool selected, int item, int col, int row, int width, int viewportX)`
|
||||
- `void Dispose()`
|
||||
- enum `SearchResultType` (`src/EchoHub.Client/UI/Dialogs/SearchDialog.cs`)
|
||||
|
||||
## Symbol To Document
|
||||
- Name: `SearchDialog`
|
||||
- Kind: class
|
||||
- File: `src/EchoHub.Client/UI/Dialogs/SearchDialog.cs`
|
||||
- Language: `csharp`
|
||||
- ID: `7ba458ca-8e14-48c9-9536-988f98e9e83c`
|
||||
|
||||
---
|
||||
|
||||
@@ -61,15 +73,13 @@ public record SearchResult(SearchResultType Type, string Key, string Label)
|
||||
| `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.
|
||||
Represents a single item in search results as an immutable, value-based carrier. It groups the result kind (`SearchResultType`), an identifying `Key`, and a user-facing `Label` to display in the UI. As a `record`, it gains structural equality and convenient deconstruction, which makes it easy to compare results and extract its fields when handling selections in the search dialog.
|
||||
|
||||
## 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.
|
||||
This type serves as a stable data contract between the search logic and the UI layer, decoupling data shape from presentation. It uses `record` semantics to provide value equality and immutability, enabling straightforward deduplication and pattern-based handling of results. The three members (`Type`, `Key`, `Label`) collectively support both programmatic lookup and user-friendly rendering.
|
||||
|
||||
## 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.
|
||||
- The `Key` should be stable and unique within a given `Type` to avoid ambiguity when presenting or selecting results.
|
||||
|
||||
---
|
||||
|
||||
@@ -86,9 +96,25 @@ public enum SearchResultType
|
||||
```
|
||||
|
||||
|
||||
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.
|
||||
Represents the kind of item produced by a search in the UI, distinguishing [`Channel`](../../../EchoHub.Core/Models/Channel.cs.md) results from `Action` results. Use `SearchResultType` when rendering or handling search results in the `SearchDialog` flow to steer UI decisions without inspecting the raw payload.
|
||||
|
||||
## 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.
|
||||
This enum centralizes the UI's categorization of search results, enabling the dialog to select icons, labels, or handlers in a type-safe way. It decouples the results' payload from how they're displayed and makes it straightforward to extend with additional result kinds in the future.
|
||||
|
||||
## Example
|
||||
|
||||
```csharp
|
||||
SearchResultType type = SearchResultType.Channel;
|
||||
switch (type)
|
||||
{
|
||||
case SearchResultType.Channel:
|
||||
Console.WriteLine("Render as channel");
|
||||
break;
|
||||
case SearchResultType.Action:
|
||||
Console.WriteLine("Render as action");
|
||||
break;
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
---
|
||||
@@ -18,30 +18,16 @@ 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.
|
||||
StatusDialog is a Terminal.Gui-based dialog that enables a user to set their [`UserStatus`](../../../EchoHub.Core/Models/UserStatus.cs.md) and an optional status message. The static `Show` method displays the dialog within an `IApplication`, initializes the controls from `currentStatus` and `currentMessage`, and returns a `StatusDialogResult` when the user saves, or `null` if the dialog is cancelled.
|
||||
|
||||
## 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;
|
||||
}
|
||||
```
|
||||
StatusDialog serves as a focused UI primitive that isolates status-edit behavior from the rest of the application. By wiring `OptionSelector<UserStatus>` and a `TextField` to a lightweight `StatusDialogResult`, it provides a predictable, reusable pattern for collecting user input and converting it to a simple value object. This keeps the UI code cohesive while allowing the caller to handle the result without managing Terminal.Gui lifecycle details. The dialog is deliberately minimal and self-contained, relying on the provided `IApplication` to control its lifecycle.
|
||||
|
||||
## 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().
|
||||
- The `message` field is trimmed and, if empty or whitespace, stored as `null`.
|
||||
- Cancelling returns `null` and no `StatusDialogResult` is produced.
|
||||
- When saving, if the selected status is `null`, it defaults to `UserStatus.Online`.
|
||||
|
||||
|
||||
---
|
||||
|
||||
@@ -61,9 +47,9 @@ public record StatusDialogResult(UserStatus Status, string? StatusMessage)
|
||||
| `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.
|
||||
StatusDialogResult is a lightweight value object that represents the outcome of the status dialog. It pairs the chosen [`UserStatus`](../../../EchoHub.Core/Models/UserStatus.cs.md) with an optional `StatusMessage`, providing a simple, transportable result for the caller to inspect and react to.
|
||||
|
||||
## 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.
|
||||
As a `record`, it uses value semantics: two instances are equal if their `Status` and `StatusMessage` are equal, and it is immutable by design. This makes it ideal for passing the result across boundaries and for use in pattern matching or switch expressions when reacting to different statuses. The `StatusMessage` is nullable to allow callers to omit extra context when not needed.
|
||||
|
||||
---
|
||||
@@ -8,7 +8,13 @@ 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.
|
||||
UpdateConfirmDialog is a small, self-contained UI helper that presents a modal update prompt and returns the user's decision as a boolean. Call `UpdateConfirmDialog.Show` with an `IApplication` and the current and latest versions; it constructs a `Dialog` titled 'Update Available' containing a `Label` with the version message and two `Button`s, runs the dialog, and returns `true` when the user chooses to perform the update.
|
||||
|
||||
## 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.
|
||||
|
||||
By encapsulating the entire dialog flow, this symbol isolates the update-confirmation UX from the rest of the UI, reducing duplication across the codebase. The modal pattern—calling `app.Run(dialog)` followed by `app.RequestStop()`—ensures callers receive the result synchronously without needing to manage focus or window lifecycles themselves. It also makes testing easier by providing a single, predictable entry point for the confirmation action.
|
||||
|
||||
## Notes
|
||||
|
||||
- The dialog is modal and blocks until the user presses `Update` or `Cancel`; callers should not attempt to perform further UI work until after `Show` returns.
|
||||
- It interpolates `currentVersion` and `newVersion` into the message; ensure these values are safe to display and do not contain unexpected control characters.
|
||||
Reference in New Issue
Block a user