init

enriched-partialglm/Common/DTS.CommonCore/Interface/ISO/ExtraProperties.md

@@ -0,0 +1,109 @@
+---
+source_files:
+  - Common/DTS.CommonCore/Interface/ISO/ExtraProperties/IExtraPropertiesListView.cs
+  - Common/DTS.CommonCore/Interface/ISO/ExtraProperties/IExtraPropertiesListViewModel.cs
+  - Common/DTS.CommonCore/Interface/ISO/ExtraProperties/IExtraProperty.cs
+generated_at: "2026-04-16T12:25:39.988114+00:00"
+model: "zai-org/GLM-5-FP8"
+schema_version: 1
+sha256: "785426dcfee2c243"
+---
+
+# Documentation: DTS.Common.Interface.ISO.ExtraProperties
+
+## 1. Purpose
+
+This module defines the contract for a Model-View-ViewModel (MVVM) pattern implementation for managing a collection of "extra properties" — key-value pairs with UI status tracking. It provides interfaces for the view (`IExtraPropertiesListView`), view model (`IExtraPropertiesListViewModel`), and the individual property model (`IExtraProperty`). This abstraction layer allows for testable, decoupled management of dynamic property data within the broader DTS system, likely used for ISO-related metadata handling.
+
+---
+
+## 2. Public Interface
+
+### IExtraPropertiesListView
+A marker interface extending `IBaseView` with no additional members.
+
+```csharp
+public interface IExtraPropertiesListView : IBaseView { }
+```
+
+---
+
+### IExtraPropertiesListViewModel
+Defines the view model contract for managing a collection of extra properties.
+
+```csharp
+public interface IExtraPropertiesListViewModel : IBaseViewModel
+```
+
+**Properties:**
+
+| Signature | Description |
+|-----------|-------------|
+| `IExtraPropertiesListView View { get; set; }` | Gets or sets the associated view instance. |
+| `ObservableCollection<IExtraProperty> ExtraProperties { get; set; }` | The bindable collection of extra properties. |
+| `bool IsReadOnly { get; set; }` | Controls whether the collection is in read-only mode. |
+| `IExtraProperty[] SelectedProperties { get; }` | Returns an array of currently selected property items. |
+
+**Methods:**
+
+| Signature | Description |
+|-----------|-------------|
+| `void SetPage(IDataPROPage page)` | Injects a reference to the hosting page context. |
+| `void SetParent(object parent)` | Sets a parent object reference (purpose unclear from source). |
+| `void CopySelected()` | Copies the currently selected properties. |
+| `void DeleteSelected()` | Deletes the currently selected properties. |
+| `void SetExtraProperties(IList<IExtraProperty> properties)` | Replaces the collection with the provided list of properties. |
+| `void Filter(object tag, string term)` | Filters the displayed properties based on a tag and search term. |
+| `void Sort(object o, bool columnClick)` | Sorts the properties; parameters' specific meanings unclear from source. |
+| `bool Validate(ref List<string> errors)` | Validates the collection; returns `true` if valid, populates `errors` with validation messages otherwise. |
+
+---
+
+### IExtraProperty
+Defines the contract for an individual key-value property with UI state.
+
+```csharp
+public interface IExtraProperty : INotifyPropertyChanged
+```
+
+**Properties:**
+
+| Signature | Description |
+|-----------|-------------|
+| `string Key { get; set; }` | The name/identifier of the property. |
+| `string Value { get; set; }` | The value associated with the property. |
+| `ICommand PasteCommand { get; set; }` | Command handler for paste operations; supports pasting multi-row data (e.g., CSV) into a single field. |
+| `UIItemStatus ItemStatus { get; set; }` | The UI status of the item (e.g., failed, success). |
+
+---
+
+## 3. Invariants
+
+- **INotifyPropertyChanged contract:** `IExtraProperty` extends `INotifyPropertyChanged`, so implementations must raise `PropertyChanged` events when `Key`, `Value`, or `ItemStatus` change.
+- **Observable collection binding:** `ExtraProperties` uses `ObservableCollection<IExtraProperty>`, implying UI binding expectations where collection changes (add/remove) must notify observers.
+- **Validation contract:** The `Validate` method must populate the `errors` list (passed by reference) with human-readable error messages when returning `false`.
+- **Selection state:** `SelectedProperties` returns an array (not a collection), suggesting a snapshot of selection state at call time.
+
+---
+
+## 4. Dependencies
+
+**This module depends on:**
+- `DTS.Common.Base` — Provides `IBaseView`, `IBaseViewModel`, and `IDataPROPage`.
+- `DTS.Common.Enums` — Provides `UIItemStatus` enum.
+- `System.Collections.ObjectModel` — For `ObservableCollection<T>`.
+- `System.ComponentModel` — For `INotifyPropertyChanged`.
+- `System.Windows.Input` — For `ICommand`.
+
+**Consumers:**
+- Unknown from source alone. Concrete implementations of these interfaces would exist elsewhere in the codebase.
+
+---
+
+## 5. Gotchas
+
+- **`PasteCommand` handles multi-row paste:** The XML comment explicitly states this command is designed to handle pasting multiple rows (e.g., CSV data) into a single field. Implementations must parse and handle this case.
+- **`Sort` parameters are ambiguous:** The `Sort(object o, bool columnClick)` method signature does not clearly indicate what `object o` represents or how `columnClick` affects behavior. Purpose unclear from source alone.
+- **`Filter` tag parameter is ambiguous:** The `object tag` parameter in `Filter(object tag, string term)` lacks documentation; its purpose is unclear from source alone.
+- **`SetParent` purpose is unclear:** The method accepts a generic `object parent` without type constraints or documentation; its usage pattern cannot be determined from source alone.
+- **`Validate` uses ref parameter:** The `ref List<string> errors` pattern requires callers to instantiate the list before calling; the method will populate it rather than replace it.