init

enriched-qwen3-coder-next/DataPRO/Modules/Groups/GroupChannelList/Converters.md

@@ -0,0 +1,120 @@
+---
+source_files:
+  - DataPRO/Modules/Groups/GroupChannelList/Converters/BooleanToWidthConverter.cs
+  - DataPRO/Modules/Groups/GroupChannelList/Converters/SensorIdBackgroundConverter.cs
+generated_at: "2026-04-16T04:46:41.293810+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "b2bc34d167251ea0"
+---
+
+# Converters
+
+## Documentation: `GroupChannelList.Converters` Module
+
+### 1. Purpose  
+This module provides WPF value converters used for UI data binding in the `GroupChannelList` module. Specifically, it enables conditional presentation logic—converting boolean values to UI properties such as width (for collapsing/expanding UI elements) and background color (for highlighting sensor-related items). These converters facilitate declarative UI behavior in XAML without requiring additional view-model logic.
+
+---
+
+### 2. Public Interface  
+
+#### `BooleanToWidthConverter`  
+- **Namespace**: `GroupChannelList.Converters`  
+- **Type**: `class` implementing `IValueConverter`  
+- **Method**:  
+  ```csharp
+  public object Convert(object value, Type targetType, object parameter, CultureInfo culture)
+  ```  
+  - **Behavior**: Converts a `bool` input to a `double` width.  
+    - If `value` is `null`, returns `0`.  
+    - If `parameter` is provided and parses successfully as a `double`, uses that value for `true`; otherwise defaults to `double.NaN`.  
+    - Returns the parsed width for `true`, and `0` for `false`.  
+  - **Example usage in XAML**:  
+    ```xaml
+    Width="{Binding IsSensorActive, Converter={StaticResource BooleanToWidthConverter}, ConverterParameter=100}"
+    ```  
+
+- **Method**:  
+  ```csharp
+  public object ConvertBack(object value, Type targetType, object parameter, CultureInfo culture)
+  ```  
+  - **Behavior**: Always throws `NotImplementedException`. One-way conversion only.  
+
+#### `SensorIdBackgroundConverter`  
+- **Namespace**: `GroupChannelList.Converters`  
+- **Type**: `class` implementing `IValueConverter`  
+- **Field**:  
+  ```csharp
+  private static SolidColorBrush SensorIdBrush = new SolidColorBrush(Color.FromArgb(0xFF, 0xE3, 0xFB, 0xE1));
+  ```  
+  - A frozen `SolidColorBrush` with ARGB color `(0xFF, 0xE3, 0xFB, 0xE1)` (light green, #E3FBE1).  
+
+- **Method**:  
+  ```csharp
+  public object Convert(object value, Type targetType, object parameter, CultureInfo culture)
+  ```  
+  - **Behavior**: Converts a `bool` input to a `Brush`.  
+    - If `value` is `null`, returns `Brushes.Transparent`.  
+    - If `value` is `true`, returns `SensorIdBrush` (frozen for performance).  
+    - If `value` is `false`, returns `Brushes.Transparent`.  
+    - Any exception during conversion logs the message via `Trace.WriteLine` and returns `Brushes.Transparent`.  
+  - **Example usage in XAML**:  
+    ```xaml
+    Background="{Binding HasSensorId, Converter={StaticResource SensorIdBackgroundConverter}}"
+    ```  
+
+- **Method**:  
+  ```csharp
+  public object ConvertBack(object value, Type targetType, object parameter, CultureInfo culture)
+  ```  
+  - **Behavior**: Always throws `NotImplementedException`. One-way conversion only.  
+
+---
+
+### 3. Invariants  
+- **`BooleanToWidthConverter`**:  
+  - Output is always `0` or a `double` (including `double.NaN` if `parameter` parsing fails).  
+  - `parameter` is optional; if missing or invalid, `double.NaN` is used for `true`.  
+  - No validation on `value` beyond null-checking; non-`bool` values will cause a runtime `InvalidCastException` (not caught).  
+
+- **`SensorIdBackgroundConverter`**:  
+  - `SensorIdBrush` is frozen after first use (via `.Freeze()`) to ensure thread-safety and performance.  
+  - Output is always a `Brush`; specifically `Brushes.Transparent` or `SensorIdBrush`.  
+  - Null or non-`bool` inputs are handled gracefully (return `Brushes.Transparent`), but exceptions during conversion are silently logged.  
+
+---
+
+### 4. Dependencies  
+- **Dependencies on external frameworks**:  
+  - `System.Windows.Data` (WPF `IValueConverter` interface)  
+  - `System.Windows.Media` (`SolidColorBrush`, `Brushes`)  
+  - `System.Diagnostics` (`Trace`)  
+  - `System.Globalization` (`CultureInfo`)  
+
+- **Dependencies on other modules**:  
+  - None inferred from source (no internal project references in imports).  
+  - Used by XAML views in the `GroupChannelList` module (inferred from namespace path).  
+
+- **Depended upon by**:  
+  - XAML UI elements in `DataPRO.Modules.Groups.GroupChannelList` (e.g., `GroupChannelListView.xaml`), where these converters are referenced as static resources.  
+
+---
+
+### 5. Gotchas  
+- **`BooleanToWidthConverter`**:  
+  - `ConvertBack` is unimplemented—cannot be used in two-way bindings.  
+  - `parameter` parsing is silent: invalid values (e.g., `"abc"`) result in `double.NaN` without error.  
+  - Non-`bool` inputs (e.g., `null`, `int`, `string`) will throw `InvalidCastException` at runtime (not caught).  
+
+- **`SensorIdBackgroundConverter`**:  
+  - `SensorIdBrush` is shared and frozen *after first use*; if frozen prematurely (e.g., before first conversion), subsequent calls are safe but the freeze is redundant.  
+  - Exception handling is minimal: only logs to `Trace`, no user-facing error.  
+  - Assumes `value` is `bool`; non-`bool` inputs (e.g., `null`, `int`) will throw `InvalidCastException` (not caught).  
+
+- **Both converters**:  
+  - One-way only (`ConvertBack` throws `NotImplementedException`).  
+  - No support for culture-specific formatting (uses default `CultureInfo` behavior).  
+  - No documentation of expected `targetType` constraints (assumes WPF expects `double`/`Brush` outputs).  
+
+None identified beyond the above.