init

enriched-qwen3-coder-next/Common/DTS.Common/Interface/DTS.Viewer/CalculatedChannel.md

@@ -0,0 +1,87 @@
+---
+source_files:
+  - Common/DTS.Common/Interface/DTS.Viewer/CalculatedChannel/IAddCalculatedChannelView.cs
+  - Common/DTS.Common/Interface/DTS.Viewer/CalculatedChannel/IAddCalculatedChannelViewModel.cs
+generated_at: "2026-04-16T03:08:03.543997+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "d4749d84d62ef814"
+---
+
+# CalculatedChannel
+
+## Documentation: `IAddCalculatedChannelView` and `IAddCalculatedChannelViewModel`
+
+---
+
+### 1. **Purpose**
+
+This module defines the MVVM (Model-View-ViewModel) interface contract for a UI component used to add a *calculated channel*—a derived data channel computed from one or more existing channels—within the DTS Viewer application. The `IAddCalculatedChannelView` interface represents the view layer (UI), while `IAddCalculatedChannelViewModel` represents the corresponding ViewModel responsible for managing state, user input, and coordination with the rest of the system (e.g., publishing changes, handling search context). Together, they enable users to configure and submit a new calculated channel definition, including options like ISO export behavior and encoding.
+
+---
+
+### 2. **Public Interface**
+
+#### `IAddCalculatedChannelView`
+- **Definition**:  
+  ```csharp
+  public interface IAddCalculatedChannelView : IBaseView
+  ```
+- **Behavior**:  
+  A marker interface extending `IBaseView`, indicating this interface represents the *view* (e.g., XAML page or control) in the MVVM pattern. No additional members are declared—implementation details are assumed to reside in concrete classes.
+
+#### `IAddCalculatedChannelViewModel`
+- **Definition**:  
+  ```csharp
+  public interface IAddCalculatedChannelViewModel : IBaseViewModel
+  ```
+- **Members**:
+  - `IBaseView View { get; set; }`  
+    Gets or sets the associated view instance (e.g., the `IAddCalculatedChannelView` implementation). Enables the ViewModel to interact with or update the view.
+  - `IBaseViewModel Parent { get; set; }`  
+    Gets or sets the parent ViewModel in the hierarchy, supporting navigation or command relay.
+  - `void PublishChanges();`  
+    Commits or broadcasts the current configuration (e.g., channel definition, settings) to the system—likely triggering validation, channel creation, or persistence.
+  - `bool IncludeGroupNameInISOExport { get; set; }`  
+    Gets or sets a flag indicating whether the group name should be included when exporting channel data to ISO format.
+  - `int DefaultDTSEncoding { get; set; }`  
+    Gets or sets the default encoding (e.g., numeric ID for encoding type like UTF-8, ASCII) used for the calculated channel.
+  - `ICommand AddCalculatedChannelCommand { get; }`  
+    Exposes a command (e.g., bound to a UI button) that, when executed, initiates the process of adding the calculated channel—likely invoking `PublishChanges()` internally.
+  - `object ContextSearchRegion { get; set; }`  
+    Gets or sets an object representing the context or scope for channel search operations (e.g., a region ID, selection context, or search filter). Type is `object`, suggesting flexibility but requiring runtime type knowledge.
+
+---
+
+### 3. **Invariants**
+
+- `IAddCalculatedChannelView` must be implemented by a concrete UI class that satisfies `IBaseView` contract (e.g., implements view lifecycle or binding infrastructure).
+- `IAddCalculatedChannelViewModel` must maintain a valid reference to its associated `View` (via the `View` property) for proper MVVM binding and communication.
+- `AddCalculatedChannelCommand` must be non-null and executable; its execution must result in a call to `PublishChanges()` (or equivalent logic) to finalize the operation.
+- `DefaultDTSEncoding` and `IncludeGroupNameInISOExport` are mutable properties—changes must be persisted or reflected in the final channel definition upon `PublishChanges()`.
+- `ContextSearchRegion` is expected to be set before `AddCalculatedChannelCommand` is executed, as it likely influences channel search/selection behavior.
+
+---
+
+### 4. **Dependencies**
+
+#### *This module depends on*:
+- `DTS.Common.Base.IBaseView` (via `IAddCalculatedChannelView`)
+- `DTS.Common.Base.IBaseViewModel` (via `IAddCalculatedChannelViewModel`)
+- `System.Windows.Input.ICommand` (for `AddCalculatedChannelCommand`)
+
+#### *This module is depended on by*:
+- Concrete implementations of `IAddCalculatedChannelView` (e.g., WPF/XAML view classes).
+- Concrete implementations of `IAddCalculatedChannelViewModel` (e.g., view model classes handling calculated channel creation logic).
+- Likely consumed by a parent ViewModel (e.g., `CalculatedChannelManagerViewModel`) that instantiates and coordinates this component.
+
+---
+
+### 5. **Gotchas**
+
+- **`ContextSearchRegion` is typed as `object`**: Its expected runtime type (e.g., `string`, `Guid`, custom context object) is not specified in the interface. Consumers must infer or document the expected type externally.
+- **No explicit validation or error handling exposed**: The interface does not define properties/methods for validation state (e.g., `IsValid`, `ErrorMessage`), suggesting validation may be internal to the ViewModel implementation or handled via external mechanisms.
+- **`PublishChanges()` behavior is unspecified**: The interface does not define side effects, error conditions, or return values—implementation may throw, silently fail, or require specific preconditions (e.g., non-empty channel definition).
+- **No documentation on `IncludeGroupNameInISOExport` semantics**: It is unclear whether this flag affects *all* channels in a group or only the newly added one, or how it interacts with global export settings.
+
+> *None of the above are explicitly stated in the source; they are inferred from design patterns and naming.*