Add UML diagrams to documentation directory
This commit is contained in:
+12
-1
@@ -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)
|
||||
- [React Documentation](https://reactjs.org/docs/getting-started.html)
|
||||
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user