From e82df2f308fcc2c8cf8fefc0f061f1ba32feb541 Mon Sep 17 00:00:00 2001 From: Heiko Joerg Schick Date: Mon, 31 Mar 2025 20:31:31 +0200 Subject: [PATCH] Add UML diagrams to documentation directory --- docs/DEVELOPERS.md | 13 +- docs/powerpoint-toolbox-dataflow-uml.md | 117 ++++++++++++++ docs/powerpoint-toolbox-structure-uml.md | 148 +++++++++++++++++ docs/powerpoint-toolbox-uml-index.md | 57 +++++++ docs/powerpoint-toolbox-uml.md | 195 +++++++++++++++++++++++ 5 files changed, 529 insertions(+), 1 deletion(-) create mode 100644 docs/powerpoint-toolbox-dataflow-uml.md create mode 100644 docs/powerpoint-toolbox-structure-uml.md create mode 100644 docs/powerpoint-toolbox-uml-index.md create mode 100644 docs/powerpoint-toolbox-uml.md diff --git a/docs/DEVELOPERS.md b/docs/DEVELOPERS.md index baa2f8fc..5b46a842 100644 --- a/docs/DEVELOPERS.md +++ b/docs/DEVELOPERS.md @@ -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 ``` @@ -340,4 +351,4 @@ Additional performance tips: - [Office Add-ins Documentation](https://docs.microsoft.com/en-us/office/dev/add-ins/) - [Office.js API Reference](https://docs.microsoft.com/en-us/javascript/api/overview/office) - [Fluent UI Documentation](https://developer.microsoft.com/en-us/fluentui) -- [React Documentation](https://reactjs.org/docs/getting-started.html) \ No newline at end of file +- [React Documentation](https://reactjs.org/docs/getting-started.html) diff --git a/docs/powerpoint-toolbox-dataflow-uml.md b/docs/powerpoint-toolbox-dataflow-uml.md new file mode 100644 index 00000000..798188f0 --- /dev/null +++ b/docs/powerpoint-toolbox-dataflow-uml.md @@ -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. diff --git a/docs/powerpoint-toolbox-structure-uml.md b/docs/powerpoint-toolbox-structure-uml.md new file mode 100644 index 00000000..af722762 --- /dev/null +++ b/docs/powerpoint-toolbox-structure-uml.md @@ -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 { + <> + Configuration Files + Source Code + Assets + Documentation + } + + %% Configuration Files + class ConfigFiles { + <> + .eslintrc.json + .gitignore + .hintrc + babel.config.json + manifest.xml + package.json + tsconfig.json + webpack.config.js + } + + %% Source Code Structure + class SourceCode { + <> + /src + } + + class Commands { + <> + /src/commands + commands.html + commands.ts + } + + class Taskpane { + <> + /src/taskpane + index.tsx + taskpane.html + } + + class Components { + <> + /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 { + <> + /src/taskpane/types + office-types.ts + } + + %% Assets + class Assets { + <> + /assets + edison-16.png + edison-32.png + edison-64.png + edison-80.png + edison-128.png + edison-filled.png + } + + %% Documentation + class Documentation { + <> + /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. diff --git a/docs/powerpoint-toolbox-uml-index.md b/docs/powerpoint-toolbox-uml-index.md new file mode 100644 index 00000000..4d64b5d3 --- /dev/null +++ b/docs/powerpoint-toolbox-uml-index.md @@ -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 diff --git a/docs/powerpoint-toolbox-uml.md b/docs/powerpoint-toolbox-uml.md new file mode 100644 index 00000000..484b1cec --- /dev/null +++ b/docs/powerpoint-toolbox-uml.md @@ -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 { + <> + +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 { + <> + } + + class RoundImage { + <> + } + + class SwapPositions { + <> + } + + class InsertTitles { + <> + } + + class ConfidentialButtons { + <> + } + + class DraftButtons { + <> + } + + class ProgressBarButtons { + <> + } + + class AlignmentButtons { + <> + } + + class GridGuidelineManager { + <> + } + + %% Utility Types + class OfficeTypes { + <> + +getErrorMessage(error): string + +isPictureShape(shape): boolean + +getFirstSelectedSlide(context): PowerPoint.Slide + +selectShapesById(slide, shapeIds): void + } + + class CommonStyles { + <> + +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.