docs: Update documentation for 145 files

Generated by AurionDocs Job ID: c99fff50-67a3-4294-b4df-3e73f4f12de9 Source commit: 4dcb480
2026-09-04 16:46:08 +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,19 @@
+# ChatColors
+
+> **File:** `src/EchoHub.Client/UI/Chat/ChatColors.cs`  
+> **Kind:** class
+
+```csharp
+public static partial class ChatColors
+```
+
+
+Shared color attributes and a small parsing helper for chat rendering. Use this class when rendering chat UI elements (timestamps, system messages, mentions, channel references, embeds, attachments, etc.) so all parts of the UI use a consistent set of Attribute values. Call SplitMentions when you need to break a message into colored segments so mentions (@user) and channel references (#channel) can be rendered with their accent colors while non-special text uses a supplied default.
+
+## Remarks
+ChatColors centralizes the visual styling for chat components and includes a utility to split text into ChatSegment pieces that carry color information. SplitMentions performs a two-pass parse: first it finds @mentions (avoiding emails by requiring no preceding word character) and marks them with MentionTextAttr; then it examines the remaining, non-mention segments to find #channel references (the regex requires at least one letter to avoid matching hex colors or numeric issue references) and marks those with ChannelRefAttr. All Attribute instances are readonly and intended as shared, immutable style tokens that renderers can reuse.
+
+## Notes
+- The mention regex uses a negative lookbehind (?<!\w) so strings like "me@domain" are not treated as @mentions.  
+- The channel regex requires at least one ASCII letter to avoid matching plain hex colors or purely numeric tokens.  
+- SplitMentions accepts a nullable defaultColor; callers should handle null when rendering (null means "no explicit attribute supplied").
@@ -0,0 +1,120 @@
+# ChatLine.cs
+
+> **Source:** `src/EchoHub.Client/UI/Chat/ChatLine.cs`
+
+## Contents
+
+- [ChatLine](#chatline)
+- [AttachmentActionSpan](#attachmentactionspan)
+- [AttachmentAction](#attachmentaction)
+
+---
+
+## ChatLine
+> **File:** `src/EchoHub.Client/UI/Chat/ChatLine.cs`  
+> **Kind:** class
+
+```csharp
+public partial class ChatLine
+```
+
+
+Represents a single rendered chat line made up of colored ChatSegment pieces and associated display metadata. Use ChatLine when preparing or manipulating a line for rendering in the chat view (layout, wrapping, attachment actions, separators, mention/highlight state) rather than working with raw strings or segments directly.
+
+## Remarks
+ChatLine is the view-level unit for a message or a rule separator: it aggregates ChatSegment instances (text + color), stores metadata such as MessageId, sender, attachment info and clickable action spans, and exposes logic to break the line into multiple display lines that fit a viewport width. It centralizes presentation concerns (continuation indentation, colored continuation prefixes, non-wrapping rule lines, and unread-marker behavior) so the chat rendering layer can ask a ChatLine to produce the wrapped pieces it needs rather than implementing wrapping and metadata handling itself.
+
+## Example
+```csharp
+// Construct from plain text
+var line = new ChatLine("Hello, world!");
+// Optional metadata
+line.MessageId = Guid.NewGuid();
+line.SenderUsername = "alice";
+
+// Wrap to a viewport width of 40 columns, with a 4-space continuation indent
+var wrapped = line.Wrap(40, continuationIndent: 4);
+
+// Construct from explicit segments (preserves per-segment color attributes)
+var segments = new List<ChatSegment>
+{
+    new ChatSegment("[alice] ", ChatColors.RailAttr),
+    new ChatSegment("This is a message", null)
+};
+var coloredLine = new ChatLine(segments);
+```
+
+## Notes
+- RuleLabel makes the line a separator rule; such lines are not word-wrapped and are regenerated to the viewport width by the view.
+- If ContinuationPrefixSegments is set, it overrides ContinuationIndent: continuation lines use the prefix segments' column width instead of plain-space indentation.
+- ActionSpans (when present) are column positions relative to the unwrapped line; only the first wrapped line preserves those spans — subsequent wrapped continuation lines do not.
+- Wrapping respects grapheme clusters and column widths (uses GetGraphemes and GetColumns), so wide characters and combining sequences are handled when measuring width. If width <= 0 or the line already fits, Wrap returns the original line in a single-element list.
+
+---
+
+## AttachmentActionSpan
+> **File:** `src/EchoHub.Client/UI/Chat/ChatLine.cs`  
+> **Kind:** record
+
+```csharp
+public readonly record struct AttachmentActionSpan(int StartCol, int EndCol, AttachmentAction Action)
+```
+
+**Parameters:**
+
+| Parameter | Type | Default |
+|-----------|------|---------|
+| `StartCol` | `int` | — |
+| `EndCol` | `int` | — |
+| `Action` | `AttachmentAction` | — |
+
+
+It encodes an inclusive horizontal span on a chat line that maps to an AttachmentAction when clicked. This readonly record struct pairs StartCol and EndCol (both inclusive) with an Action to designate a specific clickable region that triggers an attachment operation.
+
+## Remarks
+Because it's a value type with immutable fields, AttachmentActionSpan is cheap to copy and compare, which helps with hit-testing and rendering across frames. It expresses the intent of interactive regions alongside their coordinates and associated action, keeping the UI layer decoupled from how actions are executed. This symbol complements other line-rendering data structures that describe clickable spans, enabling straightforward collection, filtering, and application during rendering.
+
+## Notes
+- EndCol is inclusive; ensure range checks treat EndCol as inclusive to avoid off-by-one errors.
+- Overlapping spans may require careful resolution logic at render or hit-test time to determine which action should fire.
+
+---
+
+## AttachmentAction
+> **File:** `src/EchoHub.Client/UI/Chat/ChatLine.cs`  
+> **Kind:** enum
+
+```csharp
+public enum AttachmentAction
+{
+    OpenImage,
+    SaveImage,
+}
+```
+
+
+An enum that represents the action a click on an attachment line can trigger in the chat UI. It lets the click handler distinguish between opening the image for viewing and saving the image to disk, promoting explicit, testable logic rather than ad-hoc behavior.
+
+## Remarks
+By codifying the possible outcomes as an enum, AttachmentAction defines a clear contract for how attachment clicks should be handled. It decouples the UI event from the concrete actions, making it easy to extend with new options (for example, ShareImage) without changing call sites. This abstraction supports consistent behavior across different chat lines and simplifies testing by allowing mocks or verifications based on the enum value.
+
+## Example
+```csharp
+AttachmentAction action = /* determined by UI context */;
+switch (action)
+{
+    case AttachmentAction.OpenImage:
+        // Open the image in a viewer
+        break;
+    case AttachmentAction.SaveImage:
+        // Persist the image to disk
+        break;
+}
+```
+
+## Notes
+- If you later add actions to the enum, remember to handle them in all switch expressions and tests.
+- Prefer explicit enum-based logic over string-based representations to avoid misinterpretation.
+- Ensure UI-to-action mappings are consistent across chat lines to prevent user confusion.
+
+---
@@ -0,0 +1,19 @@
+# ChatListSource
+
+> **File:** `src/EchoHub.Client/UI/Chat/ChatListSource.cs`  
+> **Kind:** class
+
+```csharp
+public class ChatListSource : IListDataSource
+```
+
+
+A list-backed data source for chat messages that implements IListDataSource and performs grapheme-aware rendering with per-segment coloring, mention-background highlighting, and a focus-based full-row highlight. Use this when supplying chat messages to a ListView-like control that expects the data source to manage items, raise collection-change notifications, and draw each row with segment-level attributes and correct column clipping.
+
+## Remarks
+ChatListSource maintains an internal `List<ChatLine>`, tracks the longest item via MaxItemLength, and raises a CollectionChanged (Reset) event whenever the collection is modified unless SuspendCollectionChangedEvent is set. Its Render implementation is grapheme-aware (uses GraphemeHelper.GetGraphemes and each grapheme's column width) and applies attributes per ChatSegment: a Focus attribute (when the row is selected and the list has focus) or the segment's color with fallbacks for missing backgrounds. If a ChatLine.IsMention is true the renderer uses ChatColors.MentionHighlightAttr.Background to override segment backgrounds and to fill the remainder of the row.
+
+## Notes
+- GetLine returns null for out-of-range indices; callers should validate the index first.
+- IsMarked/SetMark are intentionally no-ops in this implementation and Dispose is a no-op — no per-item mark state or unmanaged cleanup is performed.
+- MaxItemLength is updated only when lines are added/inserted; mutating a ChatLine.TextLength after insertion will not update MaxItemLength automatically. Use SuspendCollectionChangedEvent to batch updates and suppress the Reset event during bulk changes.
@@ -0,0 +1,26 @@
+# ChatSegment
+
+> **File:** `src/EchoHub.Client/UI/Chat/ChatSegment.cs`  
+> **Kind:** record
+
+```csharp
+public record ChatSegment(string Text, Attribute? Color)
+```
+
+**Parameters:**
+
+| Parameter | Type | Default |
+|-----------|------|---------|
+| `Text` | `string` | — |
+| `Color` | `Attribute?` | — |
+
+
+ChatSegment represents a colored fragment of text within a chat line. It pairs the displayed text with an optional color attribute, enabling the UI to render parts of a message with varying styling without altering the textual content. As a record, ChatSegment is immutable and supports value-based equality, making it convenient to compose a full line by aggregating multiple segments in a deterministic way.
+
+## Remarks
+ChatSegment exists to separate content from presentation. By modeling a line as a sequence of segments, the rendering layer can apply different colors or styles to each piece while preserving the original order. The record-like semantics also ease comparisons, caching, and deduplication of segments across messages.
+
+## Notes
+- Color is stored as a nullable Attribute; a null Color means no special styling is requested for this segment. 
+- `Attribute` is a general metadata type; downstream renderers interpret it to apply styling. The exact meaning of the Color value depends on the consuming UI.
+- Because ChatSegment is a two-property record, equality includes both Text and Color; changes to either produce a distinct segment, which is important when deduplicating or comparing segments.
@@ -0,0 +1,11 @@
+# RenderHelpers
+
+> **File:** `src/EchoHub.Client/UI/Chat/RenderHelpers.cs`  
+> **Kind:** class
+
+```csharp
+static class RenderHelpers
+```
+
+
+RenderHelpers is a small, shared utility for rendering IListDataSource content. Its WriteText method writes text to a ListView grapheme-by-grapheme while respecting a maximum width, returning the updated count of drawn columns. It iterates over grapheme clusters obtained from GraphemeHelper.GetGraphemes(text); for each grapheme, it computes the display width with GetColumns() (falling back to 1 if necessary). If adding the grapheme would exceed maxWidth, rendering stops. Otherwise, it appends the grapheme to the ListView via lv.AddStr(grapheme) and increments the drawn count. This centralizes grapheme-aware rendering logic so multiple IListDataSource implementations share consistent width handling and avoid duplicating rendering concerns.
@@ -0,0 +1,24 @@
+# WelcomeBanner
+
+> **File:** `src/EchoHub.Client/UI/Chat/WelcomeBanner.cs`  
+> **Kind:** class
+
+```csharp
+internal static class WelcomeBanner
+```
+
+
+Renders a MOTD-style splash in the chat pane when no channel is selected — a gold-gradient ASCII logo accompanied by a version tagline and quick usage hints, evoking classic IRC greetings. Use WelcomeBanner.Build to generate the banner lines for a given viewport width and version string, then feed those lines into the chat UI.
+
+## Remarks
+WelcomeBanner encapsulates the presentation of the welcome banner: centering, padding, colorization, and the two-logo strategy are all handled here so the rest of the chat UI can simply render a sequence of lines. It selects between a full-width BigLogo and a compact SmallLogo based on the viewport width, scales the gradient across the chosen logo, and appends a version tagline plus a set of user hints. This keeps branding consistent across sizes and isolates banner-specific formatting from the broader rendering pipeline.
+
+## Example
+```csharp
+var lines = WelcomeBanner.Build(80, "1.2.3");
+// integrate 'lines' into the chat pane
+```
+
+## Notes
+- The logo variant is chosen based on the provided width; very small panes will display SmallLogo to preserve legibility.
+- The color attributes (Attributes on ChatSegment) require UI support in the chat renderer; without color support the banner falls back to plain text.