init

enriched-qwen3-coder-next/Common/DTS.Common/Interface/Menu/HamburgerMenu.md

@@ -0,0 +1,82 @@
+---
+source_files:
+  - Common/DTS.Common/Interface/Menu/HamburgerMenu/IHamburgerMenuView.cs
+  - Common/DTS.Common/Interface/Menu/HamburgerMenu/IHamburgerMenuViewModel.cs
+generated_at: "2026-04-16T03:09:52.260112+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "9a1e8d073f3885f4"
+---
+
+# HamburgerMenu
+
+## Documentation: Hamburger Menu Module Interfaces
+
+### 1. Purpose  
+This module defines the contract interfaces (`IHamburgerMenuView` and `IHamburgerMenuViewModel`) for the hamburger menu UI component in the application. It serves as the presentation-layer abstraction for a navigation menu (likely the primary sidebar or top-level menu), separating view concerns (via `IHamburgerMenuView`) from business logic and state management (via `IHamburgerMenuViewModel`). The module enables dynamic population and interaction with menu items, supports activation/deactivation lifecycle events, and provides a mechanism for enabling/disabling the menu—likely to prevent user interaction during sensitive operations (e.g., admin viewing another user’s context, as referenced in the code comment).
+
+---
+
+### 2. Public Interface  
+
+#### `IHamburgerMenuView`  
+- **Inherits**: `IBaseView`  
+- **Description**: A marker interface representing the view layer for the hamburger menu. No additional members beyond base view contract. Used for dependency injection or view-model binding to ensure type safety and separation of concerns.
+
+#### `IHamburgerMenuViewModel`  
+- **Inherits**: `IBaseViewModel`  
+- **Properties**:  
+  - `IHamburgerMenuView View { get; set; }`  
+    Gets or sets the associated view instance. Used for view-model/view coordination (e.g., updating UI state).  
+  - `bool IsEnabled { get; }`  
+    Read-only property indicating whether the hamburger menu is currently enabled (i.e., interactive).  
+  - `MenuItemPressedDelegate MenuItemPressed { get; set; }`  
+    Gets or sets a delegate handler invoked when a menu item is selected.  
+
+- **Methods**:  
+  - `void OnSetActive()`  
+    Invoked when the view becomes active (e.g., tab selected or view loaded). Intended for initialization logic (e.g., populating menu items, registering event handlers).  
+  - `void Unset()`  
+    Invoked when the view is unloaded or deactivated. Intended for cleanup (e.g., unregistering handlers, releasing resources).  
+  - `ContextMenu GetContextMenu()`  
+    Returns the `ContextMenu` instance used for the hamburger menu. Likely used to attach the menu to a UI element (e.g., a button or icon).  
+  - `void SetMenuItems(string[] items)`  
+    Populates the menu with items derived from the provided string array. Each string likely represents a menu item label or command name.  
+  - `void ClearMenuItems()`  
+    Removes all menu items from the current menu.  
+  - `void EnableMenu(bool enable)`  
+    Enables or disables the hamburger menu based on the `enable` parameter. Affects `IsEnabled` state (though `IsEnabled` itself is read-only, its value is controlled via this method).  
+
+#### `MenuItemPressedDelegate`  
+- **Signature**: `delegate void MenuItemPressedDelegate(string command)`  
+- **Description**: Delegate for handling menu item selection events. The `command` parameter identifies the selected menu item (e.g., by label, key, or command name).  
+
+---
+
+### 3. Invariants  
+- `IHamburgerMenuViewModel.View` must be set before `OnSetActive()` is called (implied by typical MVVM patterns and lifecycle semantics).  
+- `IsEnabled` reflects the current enabled state of the menu and is updated only via `EnableMenu(bool)`.  
+- `SetMenuItems(string[])` and `ClearMenuItems()` must be called in a mutually exclusive manner relative to `GetContextMenu()`—i.e., the returned `ContextMenu` must reflect the latest state after these operations.  
+- `OnSetActive()` and `Unset()` are expected to be called in balanced pairs (e.g., `OnSetActive()` on activation, `Unset()` on deactivation).  
+- `MenuItemPressed` must be non-null before menu items are interacted with (though not enforced by interface—consumers must handle null delegates).  
+
+---
+
+### 4. Dependencies  
+- **Depends on**:  
+  - `DTS.Common.Base` (for `IBaseView`, `IBaseViewModel` base interfaces).  
+  - `System.Windows.Controls` (for `ContextMenu`, `MenuItem` types—indicating WPF UI framework usage).  
+- **Used by**:  
+  - Likely consumed by a WPF view (e.g., `UserControl`) implementing `IHamburgerMenuView`.  
+  - View models or services that manage application navigation or global commands (e.g., a main window view model or menu controller).  
+- **Inferred consumers**: Any module requiring dynamic hamburger menu population (e.g., group/channel management, user switching, admin tools).  
+
+---
+
+### 5. Gotchas  
+- **Critical**: The comment `//15324 Warning dialog displayed on every tab change once admin user tries to view another users view` indicates a known bug where enabling/disabling the menu (`EnableMenu`) may be tied to user context changes, potentially causing excessive warnings. This suggests `EnableMenu(false)` might be used to suppress interactions during sensitive operations, but the implementation may not correctly manage state transitions or dialog suppression.  
+- `IsEnabled` is read-only; external code cannot directly set it—must use `EnableMenu(bool)`. Misuse (e.g., bypassing `EnableMenu`) could lead to inconsistent state.  
+- `SetMenuItems(string[])` does not specify how items map to commands or UI behavior (e.g., are items labels, keys, or full command strings?). Implementation details are hidden.  
+- `GetContextMenu()` returns a `ContextMenu` instance, but the interface does not clarify whether this is a new instance per call or a cached reference. Repeated calls may or may not return the same object.  
+- No explicit thread-safety guarantees are provided for methods like `SetMenuItems`, `ClearMenuItems`, or `EnableMenu`. If called from non-UI threads, marshaling to the UI thread may be required.  
+- **None identified from source alone** for lifecycle management (e.g., `OnSetActive`/`Unset` ordering), but real-world usage may require additional constraints (e.g., `Unset()` must be idempotent).