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

---
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-16T02:31:01.486440+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "785426dcfee2c243"
---

# ExtraProperties

## 1. Purpose  
This module defines the core interfaces for managing a list of *extra properties*—custom key-value metadata associated with ISO-compliant data objects—in a WPF-based UI layer. It establishes a clean separation between view (`IExtraPropertiesListView`), view model (`IExtraPropertiesListViewModel`), and individual property data (`IExtraProperty`) to support data binding, editing, validation, and user interactions (copy, delete, sort, filter, paste) in a structured, testable manner. The module exists to abstract the UI logic for handling dynamic, user-defined properties while enforcing consistency with the broader `DTS.Common` architecture.

## 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—behavior is entirely driven by the view model.

### `IExtraPropertiesListViewModel`  
- **Inherits**: `IBaseViewModel`  
- **Properties**:  
  - `IExtraPropertiesListView View { get; set; }` — Binds to the associated view instance.  
  - `ObservableCollection<IExtraProperty> ExtraProperties { get; set; }` — The mutable collection of properties displayed/managed.  
  - `bool IsReadOnly { get; set; }` — Controls whether edits are permitted.  
  - `IExtraProperty[] SelectedProperties { get; }` — Returns currently selected items in the UI (read-only snapshot).  
- **Methods**:  
  - `void SetPage(IDataPROPage page)` — Associates the view model with a specific data page context (likely for persistence or scoping).  
  - `void SetParent(object parent)` — Sets a parent object (e.g., containing entity), though its exact use is not specified in the interface.  
  - `void SetExtraProperties(IList<IExtraProperty> properties)` — Replaces the current `ExtraProperties` collection with a new list.  
  - `void CopySelected()` — Copies selected properties (likely to clipboard or internal buffer).  
  - `void DeleteSelected()` — Removes selected properties from `ExtraProperties`.  
  - `void Filter(object tag, string term)` — Filters the displayed properties based on a search term (`term`) and optional `tag` (e.g., column or field identifier).  
  - `void Sort(object o, bool columnClick)` — Sorts the properties, where `o` likely identifies the sort key/column and `columnClick` indicates whether the sort was triggered by UI interaction.  
  - `bool Validate(ref List<string> errors)` — Validates all properties in `ExtraProperties`; returns `false` and populates `errors` if any property fails validation.  

### `IExtraProperty`  
- **Inherits**: `INotifyPropertyChanged`  
- **Properties**:  
  - `string Key { get; set; }` — The property’s name/identifier.  
  - `string Value { get; set; }` — The property’s value.  
  - `UIItemStatus ItemStatus { get; set; }` — Current UI validation/status state (e.g., `Success`, `Failed`, `Warning`—values defined in `DTS.Common.Enums`).  
- **Commands**:  
  - `ICommand PasteCommand { get; set; }` — Handles paste operations, supporting multi-row pastes (e.g., CSV) into a single field.  

## 3. Invariants  
- `ExtraProperties` must be an `ObservableCollection<IExtraProperty>` to support UI data binding and change notifications.  
- `IsReadOnly` controls mutability: when `true`, operations like `DeleteSelected()` and edits to `Key`/`Value` should be disabled (enforced by the view or view model implementation).  
- `SelectedProperties` is a *snapshot* of the current selection at the time of access—its contents may change independently of the view model’s internal state.  
- `Validate(ref List<string> errors)` must populate `errors` with human-readable messages for *all* invalid properties, not just the first failure.  
- `PasteCommand` is expected to handle multi-line or multi-property pastes (e.g., pasting multiple rows into one cell), though the exact behavior is implementation-defined.  

## 4. Dependencies  
- **Depends on**:  
  - `DTS.Common.Base` (for `IBaseView`, `IBaseViewModel`)  
  - `DTS.Common.Enums` (for `UIItemStatus`)  
  - `System.Collections.ObjectModel` (for `ObservableCollection<T>`)  
  - `System.Windows.Input` (for `ICommand`)  
- **Depended on by**:  
  - Likely consumed by UI components (e.g., `UserControl` implementing `IExtraPropertiesListView`) and higher-level view models managing ISO data pages (e.g., `IDataPROPage` implementations).  
  - `IDataPROPage` (referenced in `SetPage`) is assumed to be defined elsewhere in `DTS.Common.Base`.  

## 5. Gotchas  
- **Ambiguous `SetParent` usage**: The `object parent` parameter lacks type safety or documentation—implementers must infer its role (e.g., parent entity, container, or context object).  
- **`Filter`/`Sort` signature ambiguity**: The `object tag` and `object o` parameters in `Filter` and `Sort` are untyped; their expected types (e.g., `string`, `int`, or custom enum) are not specified.  
- **`SelectedProperties` is read-only**: The array is not live-updated; consumers must re-query after selection changes.  
- **No explicit thread-safety guarantees**: `ObservableCollection` is not thread-safe; modifications must occur on the UI thread (standard WPF constraint).  
- **`PasteCommand` behavior is underspecified**: While documented as handling multi-row pastes, the interface does not define how pasted data is parsed or distributed (e.g., row/column splitting).  
- **No event for selection changes**: The interface lacks a `SelectedPropertiesChanged` event—consumers must rely on external mechanisms (e.g., binding to `ICollectionView.SelectionChanged`).  

*None identified beyond the above.*
-												init

											
										
										
											2026-04-17 14:55:32 -04:00
+								---
 								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-16T02:31:01.486440+00:00"
 								model: "Qwen/Qwen3-Coder-Next-FP8"
 								schema_version: 1
 								sha256: "785426dcfee2c243"
 								---
 								# ExtraProperties
 								## 1. Purpose
 								This module defines the core interfaces for managing a list of *extra properties*—custom key-value metadata associated with ISO-compliant data objects—in a WPF-based UI layer. It establishes a clean separation between view (`IExtraPropertiesListView`), view model (`IExtraPropertiesListViewModel`), and individual property data (`IExtraProperty`) to support data binding, editing, validation, and user interactions (copy, delete, sort, filter, paste) in a structured, testable manner. The module exists to abstract the UI logic for handling dynamic, user-defined properties while enforcing consistency with the broader `DTS.Common` architecture.
 								## 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—behavior is entirely driven by the view model.
 								### `IExtraPropertiesListViewModel`
 								- **Inherits**: `IBaseViewModel`
 								- **Properties**:
 								  - `IExtraPropertiesListView View { get; set; }` — Binds to the associated view instance.
 								  - `ObservableCollection<IExtraProperty> ExtraProperties { get; set; }` — The mutable collection of properties displayed/managed.
 								  - `bool IsReadOnly { get; set; }` — Controls whether edits are permitted.
 								  - `IExtraProperty[] SelectedProperties { get; }` — Returns currently selected items in the UI (read-only snapshot).
 								- **Methods**:
 								  - `void SetPage(IDataPROPage page)` — Associates the view model with a specific data page context (likely for persistence or scoping).
 								  - `void SetParent(object parent)` — Sets a parent object (e.g., containing entity), though its exact use is not specified in the interface.
 								  - `void SetExtraProperties(IList<IExtraProperty> properties)` — Replaces the current `ExtraProperties` collection with a new list.
 								  - `void CopySelected()` — Copies selected properties (likely to clipboard or internal buffer).
 								  - `void DeleteSelected()` — Removes selected properties from `ExtraProperties`.
 								  - `void Filter(object tag, string term)` — Filters the displayed properties based on a search term (`term`) and optional `tag` (e.g., column or field identifier).
 								  - `void Sort(object o, bool columnClick)` — Sorts the properties, where `o` likely identifies the sort key/column and `columnClick` indicates whether the sort was triggered by UI interaction.
 								  - `bool Validate(ref List<string> errors)` — Validates all properties in `ExtraProperties`; returns `false` and populates `errors` if any property fails validation.
 								### `IExtraProperty`
 								- **Inherits**: `INotifyPropertyChanged`
 								- **Properties**:
 								  - `string Key { get; set; }` — The property’s name/identifier.
 								  - `string Value { get; set; }` — The property’s value.
 								  - `UIItemStatus ItemStatus { get; set; }` — Current UI validation/status state (e.g., `Success`, `Failed`, `Warning`—values defined in `DTS.Common.Enums`).
 								- **Commands**:
 								  - `ICommand PasteCommand { get; set; }` — Handles paste operations, supporting multi-row pastes (e.g., CSV) into a single field.
 								## 3. Invariants
 								- `ExtraProperties` must be an `ObservableCollection<IExtraProperty>` to support UI data binding and change notifications.
 								- `IsReadOnly` controls mutability: when `true`, operations like `DeleteSelected()` and edits to `Key`/`Value` should be disabled (enforced by the view or view model implementation).
 								- `SelectedProperties` is a *snapshot* of the current selection at the time of access—its contents may change independently of the view model’s internal state.
 								- `Validate(ref List<string> errors)` must populate `errors` with human-readable messages for *all* invalid properties, not just the first failure.
 								- `PasteCommand` is expected to handle multi-line or multi-property pastes (e.g., pasting multiple rows into one cell), though the exact behavior is implementation-defined.
 								## 4. Dependencies
 								- **Depends on**:
 								  - `DTS.Common.Base` (for `IBaseView`, `IBaseViewModel`)
 								  - `DTS.Common.Enums` (for `UIItemStatus`)
 								  - `System.Collections.ObjectModel` (for `ObservableCollection<T>`)
 								  - `System.Windows.Input` (for `ICommand`)
 								- **Depended on by**:
 								  - Likely consumed by UI components (e.g., `UserControl` implementing `IExtraPropertiesListView`) and higher-level view models managing ISO data pages (e.g., `IDataPROPage` implementations).
 								  - `IDataPROPage` (referenced in `SetPage`) is assumed to be defined elsewhere in `DTS.Common.Base`.
 								## 5. Gotchas
 								- **Ambiguous `SetParent` usage**: The `object parent` parameter lacks type safety or documentation—implementers must infer its role (e.g., parent entity, container, or context object).
 								- **`Filter`/`Sort` signature ambiguity**: The `object tag` and `object o` parameters in `Filter` and `Sort` are untyped; their expected types (e.g., `string`, `int`, or custom enum) are not specified.
 								- **`SelectedProperties` is read-only**: The array is not live-updated; consumers must re-query after selection changes.
 								- **No explicit thread-safety guarantees**: `ObservableCollection` is not thread-safe; modifications must occur on the UI thread (standard WPF constraint).
 								- **`PasteCommand` behavior is underspecified**: While documented as handling multi-row pastes, the interface does not define how pasted data is parsed or distributed (e.g., row/column splitting).
 								- **No event for selection changes**: The interface lacks a `SelectedPropertiesChanged` event—consumers must rely on external mechanisms (e.g., binding to `ICollectionView.SelectionChanged`).
 								*None identified beyond the above.*