Add UML diagrams to documentation directory

2025-03-31 20:31:31 +02:00
parent 626b7aaa7a
commit e82df2f308
5 changed files with 529 additions and 1 deletions
@@ -0,0 +1,117 @@
+# PowerPoint Toolbox Data Flow UML
+
+This UML diagram represents the data flow and interaction patterns in the PowerPoint toolbox add-in.
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant UI as UI Components
+    participant Context as Status Context
+    participant Office as Office JS API
+    participant PowerPoint as PowerPoint Application
+
+    %% Initial Load
+    User->>UI: Open Add-in
+    UI->>Office: Initialize
+    Office->>PowerPoint: Connect
+    PowerPoint-->>Office: Connection Established
+    Office-->>UI: Ready
+
+    %% Feature Interaction (e.g., Match Sizes)
+    User->>UI: Click "Match Sizes"
+    UI->>Context: Set isProcessing(true)
+    UI->>Office: Get Selected Shapes
+    Office->>PowerPoint: getSelectedShapes()
+    PowerPoint-->>Office: Selected Shapes
+    Office-->>UI: Shape Collection
+
+    %% Processing Logic
+    Note over UI: Validate selection
+    Note over UI: Extract dimensions from first shape
+    Note over UI: Apply to other shapes
+
+    %% Apply Changes
+    UI->>Office: Update Shape Properties
+    Office->>PowerPoint: Apply Changes
+    PowerPoint-->>Office: Changes Applied
+    Office-->>UI: Success
+
+    %% Status Update
+    UI->>Context: Set statusMessage("Resized N shapes...")
+    UI->>Context: Set statusType("success")
+    UI->>Context: Set isProcessing(false)
+    Context-->>UI: Update UI with Status
+    UI-->>User: Show Success Message
+```
+
+## Data Flow Explanation
+
+This sequence diagram illustrates the typical data flow in the PowerPoint toolbox add-in:
+
+1. **Initialization Flow**:
+   - User opens the add-in in PowerPoint
+   - The UI initializes and connects to the Office JS API
+   - The Office JS API establishes a connection with PowerPoint
+
+2. **Feature Interaction** (using "Match Sizes" as an example):
+   - User clicks a feature button in the UI
+   - The UI sets the processing state via the Status Context
+   - The UI requests selected shapes from the Office JS API
+   - PowerPoint returns the selected shapes
+
+3. **Processing Logic**:
+   - The UI component validates the selection
+   - It extracts necessary information from the first shape
+   - It applies changes to the other shapes
+
+4. **Apply Changes**:
+   - The UI sends updated properties to the Office JS API
+   - The Office JS API applies the changes in PowerPoint
+   - PowerPoint confirms the changes
+
+5. **Status Update**:
+   - The UI updates the status message and type via the Status Context
+   - The Status Context updates the UI with the new status
+   - The user sees a success message
+
+## Error Handling Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant UI as UI Components
+    participant Context as Status Context
+    participant Office as Office JS API
+    participant PowerPoint as PowerPoint Application
+
+    %% Feature Interaction with Error
+    User->>UI: Click Feature Button
+    UI->>Context: Set isProcessing(true)
+    UI->>Office: Perform Operation
+    Office->>PowerPoint: Execute Command
+    PowerPoint-->>Office: Error Occurs
+    Office-->>UI: Error Response
+
+    %% Error Handling
+    UI->>Context: Set statusMessage("Error: ...")
+    UI->>Context: Set statusType("error")
+    UI->>Context: Set isProcessing(false)
+    Context-->>UI: Update UI with Error
+    UI-->>User: Show Error Message
+```
+
+## Component Communication Pattern
+
+```mermaid
+flowchart TD
+    User([User]) --> |Interacts with| UI[UI Components]
+    UI --> |Updates| Context[Status Context]
+    UI --> |Calls| Office[Office JS API]
+    Office --> |Communicates with| PowerPoint[PowerPoint]
+    PowerPoint --> |Returns data to| Office
+    Office --> |Returns results to| UI
+    Context --> |Provides state to| UI
+    UI --> |Displays results to| User
+```
+
+This diagram set illustrates how data flows through the application, from user interaction to PowerPoint manipulation and back to user feedback. The architecture follows a unidirectional data flow pattern with the Status Context serving as a central state management system.