powerpoint-toolbox/docs/powerpoint-toolbox-dataflow-uml.md

PowerPoint Toolbox Data Flow UML

This UML diagram represents the data flow and interaction patterns in the PowerPoint toolbox add-in.

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

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

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.