init

enriched-qwen3-coder-next/Common/DTS.Common/Interface/ISO/ExtraProperties.md

@@ -0,0 +1,103 @@
+---
+source_files:
+  - Common/DTS.Common/Interface/ISO/ExtraProperties/IExtraPropertiesListView.cs
+  - Common/DTS.Common/Interface/ISO/ExtraProperties/IExtraPropertiesListViewModel.cs
+  - Common/DTS.Common/Interface/ISO/ExtraProperties/IExtraProperty.cs
+generated_at: "2026-04-16T03:06:05.680006+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "fa52f93f74894066"
+---
+
+# ExtraProperties
+
+## Documentation: Extra Properties List Module
+
+---
+
+### 1. Purpose  
+This module defines the interface contracts for managing a list of *extra properties*—custom key-value metadata associated with data objects in the ISO data processing pipeline. It provides a standardized view-model and view layer abstraction for displaying, editing, filtering, sorting, and manipulating these properties in a UI (likely WPF, given `ICommand` and `ObservableCollection`). The module exists to decouple UI logic for extra properties from domain-specific implementations, enabling reuse across different ISO data entry or review workflows.
+
+---
+
+### 2. Public Interface  
+
+#### `IExtraPropertiesListView`  
+- **Inherits**: `IBaseView`  
+- **Description**: A marker interface for the view (e.g., XAML user control) that renders the extra properties list. No additional members are defined here; behavior is driven entirely by the view model.
+
+#### `IExtraPropertiesListViewModel`  
+- **Inherits**: `IBaseViewModel`  
+- **Methods & Properties**:  
+  - `void SetPage(IDataPROPage page)`  
+    Sets the data context page (likely representing a step or section in a data entry workflow) for the list.  
+  - `void SetParent(object parent)`  
+    Assigns a parent object (e.g., a container or parent view model) for navigation or coordination.  
+  - `IExtraPropertiesListView View { get; set; }`  
+    Gets or sets the associated view instance (MVVM pattern binding).  
+  - `void CopySelected()`  
+    Copies currently selected extra properties to the clipboard (likely in a structured format like CSV or tab-delimited).  
+  - `void DeleteSelected()`  
+    Removes the selected extra properties from the list.  
+  - `ObservableCollection<IExtraProperty> ExtraProperties { get; set; }`  
+    The collection of extra properties displayed in the list; supports change notification.  
+  - `void SetExtraProperties(IList<IExtraProperty> properties)`  
+    Replaces the current `ExtraProperties` collection with a new list of properties.  
+  - `void Filter(object tag, string term)`  
+    Filters the list based on `term` (search string), optionally scoped by `tag` (e.g., column or category identifier).  
+  - `void Sort(object o, bool columnClick)`  
+    Sorts the list, where `o` likely identifies the sort key (e.g., column header), and `columnClick` indicates if triggered by UI interaction.  
+  - `bool Validate(ref List<string> errors)`  
+    Validates all extra properties in the list; returns `false` and populates `errors` if any validation failures occur.  
+  - `bool IsReadOnly { get; set; }`  
+    Controls whether the list is editable (`true` = read-only, `false` = editable).  
+  - `IExtraProperty[] SelectedProperties { get; }`  
+    Returns an array of currently selected extra properties (read-only; no setter).  
+
+#### `IExtraProperty`  
+- **Inherits**: `INotifyPropertyChanged`  
+- **Properties & Commands**:  
+  - `string Key { get; set; }`  
+    The property’s name/key (e.g., `"Manufacturer"`, `"BatchID"`).  
+  - `string Value { get; set; }`  
+    The property’s value (e.g., `"Acme Corp"`, `"B-2024-001"`).  
+  - `ICommand PasteCommand { get; set; }`  
+    A command invoked when pasting data (e.g., multi-row CSV) into a single field. Handles parsing and splitting into multiple properties.  
+  - `UIItemStatus ItemStatus { get; set; }`  
+    Indicates UI validation status (e.g., `Success`, `Failed`, `Warning`)—values defined in `DTS.Common.Enums.UIItemStatus`.  
+
+---
+
+### 3. Invariants  
+- `ExtraProperties` must be an `ObservableCollection<IExtraProperty>`; direct replacement via `SetExtraProperties` must trigger collection change notifications.  
+- `SelectedProperties` is read-only and reflects the *current* selection state at the time of access (no guarantee of immutability beyond the array copy).  
+- `IsReadOnly` applies globally to all properties in the list; when `true`, edits to `Key`/`Value` should be blocked.  
+- `Validate` must inspect *all* properties in `ExtraProperties` and return `false` if any property fails validation (e.g., empty `Key`, invalid `ItemStatus`).  
+- `PasteCommand` is expected to handle multi-row input (e.g., newline- or comma-separated values) and may create/modify multiple `IExtraProperty` instances.  
+- `Filter` and `Sort` operations must operate on the *current* `ExtraProperties` collection without mutating the underlying data source (unless explicitly intended).  
+
+---
+
+### 4. Dependencies  
+
+#### This module depends on:  
+- `DTS.Common.Base` (for `IBaseView`, `IBaseViewModel`)  
+- `DTS.Common.Enums` (for `UIItemStatus`)  
+- Standard .NET types: `System.Collections.ObjectModel.ObservableCollection<T>`, `System.ComponentModel.INotifyPropertyChanged`, `System.Windows.Input.ICommand`  
+
+#### This module is depended upon by:  
+- UI components implementing `IExtraPropertiesListView` (e.g., WPF user controls).  
+- View models or services that manage ISO data pages (e.g., `IDataPROPage` implementations) requiring extra property editing.  
+- Concrete implementations of `IExtraProperty` (e.g., `ExtraProperty` class in a derived project).  
+
+---
+
+### 5. Gotchas  
+- **No explicit thread-safety guarantees**: `ObservableCollection` is not thread-safe; UI updates must occur on the UI thread.  
+- **`SetExtraProperties` vs. `ExtraProperties`**: Replacing the collection via `SetExtraProperties` may reset selection state (not specified). Consumers should re-select items if needed.  
+- **`Filter` and `Sort` signatures are ambiguous**: `object tag` and `object o` are not typed—likely `string` or `DataGridColumn` in practice, but the interface does not enforce this.  
+- **`PasteCommand` behavior is implementation-defined**: While documented as handling multi-row pastes, the exact parsing logic (e.g., delimiters, row/column mapping) is not standardized here.  
+- **`SelectedProperties` returns an array**: Calling code must not assume the array is a live view; it is a snapshot.  
+- **No error handling contract**: `Validate` populates `errors`, but the interface does not specify whether partial failures are allowed or if validation stops on the first error.  
+
+None identified beyond the above.