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
@@ -12,6 +12,17 @@ Edison is a PowerPoint add-in built with:

 The application follows a component-based architecture where each tool is encapsulated in its own React component.

+## UML Diagrams
+
+To better understand the architecture and structure of the Edison PowerPoint Add-in, refer to the following UML diagrams:
+
+- [UML Diagrams Index](powerpoint-toolbox-uml-index.md) - Overview and index of all UML diagrams
+- [Component Relationships](powerpoint-toolbox-uml.md) - Shows the relationships between React components
+- [Project Structure](powerpoint-toolbox-structure-uml.md) - Illustrates the file and directory organization
+- [Data Flow](powerpoint-toolbox-dataflow-uml.md) - Demonstrates the flow of data and interactions
+
+These diagrams provide visual representations of the application's architecture, component relationships, and data flow patterns, which can help new developers understand the codebase more quickly.
+
 ## Project Structure

 ```
@@ -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.
@@ -0,0 +1,148 @@
+# PowerPoint Toolbox Project Structure UML
+
+This UML diagram represents the file and directory structure of the PowerPoint toolbox add-in.
+
+```mermaid
+classDiagram
+    %% Project Structure
+    class Repository {
+        <<Root>>
+        Configuration Files
+        Source Code
+        Assets
+        Documentation
+    }
+
+    %% Configuration Files
+    class ConfigFiles {
+        <<Config>>
+        .eslintrc.json
+        .gitignore
+        .hintrc
+        babel.config.json
+        manifest.xml
+        package.json
+        tsconfig.json
+        webpack.config.js
+    }
+
+    %% Source Code Structure
+    class SourceCode {
+        <<Source>>
+        /src
+    }
+
+    class Commands {
+        <<Module>>
+        /src/commands
+        commands.html
+        commands.ts
+    }
+
+    class Taskpane {
+        <<Module>>
+        /src/taskpane
+        index.tsx
+        taskpane.html
+    }
+
+    class Components {
+        <<Module>>
+        /src/taskpane/components
+        ActionButton.tsx
+        AlignmentButtons.tsx
+        App.tsx
+        commonStyles.tsx
+        ConfidentialButtons.tsx
+        DraftButtons.tsx
+        GridGuidelineManager.tsx
+        Header.tsx
+        InsertTitles.tsx
+        MatchProperties.tsx
+        MatchSizes.tsx
+        ProgressBarButtons.tsx
+        RoundImage.tsx
+        Section.tsx
+        SwapPositions.tsx
+    }
+
+    class Types {
+        <<Module>>
+        /src/taskpane/types
+        office-types.ts
+    }
+
+    %% Assets
+    class Assets {
+        <<Resources>>
+        /assets
+        edison-16.png
+        edison-32.png
+        edison-64.png
+        edison-80.png
+        edison-128.png
+        edison-filled.png
+    }
+
+    %% Documentation
+    class Documentation {
+        <<Docs>>
+        /docs
+        DEVELOPERS.md
+        USER_GUIDE.md
+    }
+
+    %% Relationships
+    Repository *-- ConfigFiles : contains
+    Repository *-- SourceCode : contains
+    Repository *-- Assets : contains
+    Repository *-- Documentation : contains
+    
+    SourceCode *-- Commands : contains
+    SourceCode *-- Taskpane : contains
+    
+    Taskpane *-- Components : contains
+    Taskpane *-- Types : contains
+    
+    %% Dependency Relationships
+    Components --> Types : imports
+    Commands --> Components : may use
+```
+
+## Project Structure Explanation
+
+This UML diagram illustrates the file and directory organization of the PowerPoint toolbox add-in:
+
+1. **Repository Root**: Contains configuration files, source code, assets, and documentation.
+
+2. **Configuration Files**: Various configuration files for the development environment, including:
+   - manifest.xml: Office add-in manifest
+   - package.json: NPM package configuration
+   - webpack.config.js: Webpack bundler configuration
+   - tsconfig.json: TypeScript configuration
+   - babel.config.json: Babel configuration
+   - .eslintrc.json: ESLint configuration
+   - .gitignore: Git ignore rules
+   - .hintrc: Hint configuration
+
+3. **Source Code Structure**:
+   - **/src/commands**: Command-related files for Office ribbon integration
+   - **/src/taskpane**: Main taskpane UI implementation
+     - **/components**: React components for the UI
+     - **/types**: TypeScript type definitions
+
+4. **Assets**: Icon files in various sizes for the add-in
+
+5. **Documentation**: Developer and user documentation
+
+## Build and Execution Flow
+
+The PowerPoint toolbox add-in follows this general build and execution flow:
+
+1. Source code is written in TypeScript and React
+2. Webpack bundles the code according to webpack.config.js
+3. The Office add-in manifest (manifest.xml) defines how the add-in appears in PowerPoint
+4. When loaded in PowerPoint, the add-in renders the taskpane UI
+5. The taskpane components interact with PowerPoint through the Office JS API
+
+This structure follows Microsoft's recommended patterns for Office add-in development using React and TypeScript.
@@ -0,0 +1,57 @@
+# PowerPoint Toolbox UML Diagrams
+
+This document serves as an index for the UML diagrams created for the PowerPoint toolbox add-in repository.
+
+## Available Diagrams
+
+1. [Component Relationships](powerpoint-toolbox-uml.md) - Shows the relationships between React components and their interactions.
+
+2. [Project Structure](powerpoint-toolbox-structure-uml.md) - Illustrates the file and directory organization of the repository.
+
+3. [Data Flow](powerpoint-toolbox-dataflow-uml.md) - Demonstrates the flow of data and interactions between components and the PowerPoint API.
+
+## Repository Overview
+
+The PowerPoint toolbox add-in is a Microsoft Office add-in built with React and TypeScript that provides various tools for enhancing PowerPoint presentations. The add-in is structured as follows:
+
+### Key Technologies
+
+- **React**: For building the user interface
+- **TypeScript**: For type-safe JavaScript development
+- **Office JS API**: For interacting with PowerPoint
+- **Fluent UI**: For consistent Microsoft-style UI components
+- **Webpack**: For bundling and building the application
+
+### Architecture Highlights
+
+- **Component-Based Structure**: The application is organized into reusable UI components
+- **Context API for State Management**: Uses React's Context API for sharing state across components
+- **Unidirectional Data Flow**: Data flows from user interaction through the application to PowerPoint and back
+- **Centralized Error Handling**: Error handling is managed through the Status Context
+
+### Main Features
+
+The add-in provides tools for:
+
+- Matching sizes and properties between shapes
+- Rounding image corners
+- Swapping positions of shapes
+- Inserting title slides
+- Adding confidential markings and draft watermarks
+- Managing progress bars
+- Aligning shapes
+- Managing grid guidelines
+
+## How to View the Diagrams
+
+Each diagram is contained in a separate Markdown file with embedded Mermaid syntax. To view the diagrams:
+
+1. Open the desired diagram file in a Markdown viewer that supports Mermaid diagrams (such as GitHub, VS Code with the Mermaid extension, or any Mermaid-compatible viewer).
+
+2. The diagrams will render automatically in compatible viewers.
+
+## Diagram Types
+
+- **Class Diagrams**: Used for component relationships and project structure
+- **Sequence Diagrams**: Used for data flow and interaction patterns
+- **Flowcharts**: Used for component communication patterns
@@ -0,0 +1,195 @@
+# PowerPoint Toolbox UML Diagram
+
+This UML diagram represents the structure and relationships of the PowerPoint toolbox add-in.
+
+```mermaid
+classDiagram
+    %% Main Application Component
+    class App {
+        +title: string
+        +statusMessage: string
+        +statusType: StatusType
+        +isProcessing: boolean
+        +setStatusMessage(message: string)
+        +setStatusType(type: StatusType)
+        +setIsProcessing(processing: boolean)
+        +getStatusIcon()
+    }
+
+    %% Context Provider
+    class StatusContext {
+        <<Context>>
+        +statusMessage: string
+        +setStatusMessage: function
+        +statusType: StatusType
+        +setStatusType: function
+        +isProcessing: boolean
+        +setIsProcessing: function
+    }
+
+    %% Common UI Components
+    class Section {
+        +title: string
+        +children: ReactNode
+    }
+
+    class ActionButton {
+        +icon: ReactNode
+        +onClick: function
+        +disabled: boolean
+        +title: string
+        +appearance: string
+        +className: string
+        +handleClick()
+    }
+
+    %% Feature Components
+    class MatchSizes {
+        -validateShapeSelection(shapes): boolean
+        -loadSourceShape(sourceShape, context, matchType): Promise
+        -applySizeChanges(sourceShape, shapes, matchType): number
+        -generateStatusMessage(resizedCount, matchType): string
+        -matchSizeToFirstSelected(matchType): Promise
+    }
+
+    class MatchProperties {
+        <<Component>>
+    }
+
+    class RoundImage {
+        <<Component>>
+    }
+
+    class SwapPositions {
+        <<Component>>
+    }
+
+    class InsertTitles {
+        <<Component>>
+    }
+
+    class ConfidentialButtons {
+        <<Component>>
+    }
+
+    class DraftButtons {
+        <<Component>>
+    }
+
+    class ProgressBarButtons {
+        <<Component>>
+    }
+
+    class AlignmentButtons {
+        <<Component>>
+    }
+
+    class GridGuidelineManager {
+        <<Component>>
+    }
+
+    %% Utility Types
+    class OfficeTypes {
+        <<Utility>>
+        +getErrorMessage(error): string
+        +isPictureShape(shape): boolean
+        +getFirstSelectedSlide(context): PowerPoint.Slide
+        +selectShapesById(slide, shapeIds): void
+    }
+
+    class CommonStyles {
+        <<Styles>>
+        +container: style
+        +buttonGroup: style
+        +actionButton: style
+        +statusContainer: style
+        +successStatus: style
+        +warningStatus: style
+        +errorStatus: style
+        +statusIcon: style
+        +statusText: style
+    }
+
+    %% Relationships
+    App *-- StatusContext : provides
+    App *-- Section : contains
+    Section *-- MatchSizes : contains
+    Section *-- MatchProperties : contains
+    Section *-- RoundImage : contains
+    Section *-- SwapPositions : contains
+    Section *-- InsertTitles : contains
+    Section *-- ConfidentialButtons : contains
+    Section *-- DraftButtons : contains
+    Section *-- ProgressBarButtons : contains
+    Section *-- AlignmentButtons : contains
+    Section *-- GridGuidelineManager : contains
+    
+    MatchSizes --> ActionButton : uses
+    MatchSizes --> OfficeTypes : uses
+    MatchSizes --> StatusContext : consumes
+    MatchSizes --> CommonStyles : uses
+    
+    ActionButton --> StatusContext : consumes
+    ActionButton --> CommonStyles : uses
+    ActionButton --> OfficeTypes : uses
+    
+    %% Other components follow similar patterns
+    MatchProperties --> ActionButton : uses
+    MatchProperties --> StatusContext : consumes
+    RoundImage --> ActionButton : uses
+    RoundImage --> StatusContext : consumes
+    SwapPositions --> ActionButton : uses
+    SwapPositions --> StatusContext : consumes
+    InsertTitles --> ActionButton : uses
+    InsertTitles --> StatusContext : consumes
+    ConfidentialButtons --> ActionButton : uses
+    ConfidentialButtons --> StatusContext : consumes
+    DraftButtons --> ActionButton : uses
+    DraftButtons --> StatusContext : consumes
+    ProgressBarButtons --> ActionButton : uses
+    ProgressBarButtons --> StatusContext : consumes
+    AlignmentButtons --> ActionButton : uses
+    AlignmentButtons --> StatusContext : consumes
+    GridGuidelineManager --> ActionButton : uses
+    GridGuidelineManager --> StatusContext : consumes
+```
+
+## Diagram Explanation
+
+This UML diagram shows:
+
+1. **App Component**: The main container component that provides the StatusContext to all child components.
+
+2. **StatusContext**: A React context that manages status messages and processing state across the application.
+
+3. **UI Components**:
+   - **Section**: A reusable component for grouping related functionality
+   - **ActionButton**: A reusable button component with built-in error handling and status updates
+
+4. **Feature Components**: Various tools for PowerPoint manipulation:
+   - MatchSizes: For matching dimensions between shapes
+   - MatchProperties: For matching properties between shapes
+   - RoundImage: For rounding image corners
+   - SwapPositions: For swapping positions of shapes
+   - InsertTitles: For inserting title slides
+   - ConfidentialButtons: For adding confidential markings
+   - DraftButtons: For adding draft watermarks
+   - ProgressBarButtons: For managing progress bars
+   - AlignmentButtons: For aligning shapes
+   - GridGuidelineManager: For managing grid guidelines
+
+5. **Utility Types**: Helper functions and types for Office JS API integration
+
+6. **Relationships**: Shows how components are composed and how they consume the StatusContext
+
+## Project Architecture
+
+The PowerPoint toolbox add-in follows a React-based architecture with the following characteristics:
+
+- **Component-Based Structure**: The application is organized into reusable UI components
+- **Context API for State Management**: Uses React's Context API for sharing state across components
+- **Office JS API Integration**: Interacts with PowerPoint through the Office JS API
+- **Fluent UI Components**: Uses Microsoft's Fluent UI for consistent styling
+- **Error Handling**: Centralized error handling through the StatusContext
+
+The add-in is designed to provide various tools for PowerPoint presentations, including shape manipulation, slide formatting, and layout management.