Initial commit of documentation files.

2025-03-12 20:10:39 +01:00
parent 28b245f1fb
commit f0773d93d8
3 changed files with 595 additions and 0 deletions
@@ -0,0 +1,257 @@
+# Edison PowerPoint Add-in Developer Documentation
+
+This document provides detailed technical information for developers working on the Edison PowerPoint Add-in.
+
+## Architecture Overview
+
+Edison is a PowerPoint add-in built with:
+- **TypeScript** for type-safe code
+- **React** for UI components
+- **Office.js API** for PowerPoint integration
+- **Fluent UI** for Microsoft-style interface components
+
+The application follows a component-based architecture where each tool is encapsulated in its own React component.
+
+## Project Structure
+
+```
+/
+├── assets/                  # Images and icons
+├── dist/                    # Build output (generated)
+├── src/
+│   ├── commands/            # Command handlers
+│   │   ├── commands.html    # HTML for command UI
+│   │   └── commands.ts      # Command implementations
+│   └── taskpane/            # Main add-in UI
+│       ├── components/      # React components
+│       │   ├── AlignmentButtons.tsx
+│       │   ├── App.tsx      # Main application component
+│       │   ├── ConfidentialButtons.tsx
+│       │   ├── DraftButtons.tsx
+│       │   ├── Header.tsx
+│       │   ├── InsertTitles.tsx
+│       │   ├── MatchProperties.tsx
+│       │   ├── MatchSizes.tsx
+│       │   ├── ProgressBarButtons.tsx
+│       │   ├── RoundImage.tsx
+│       │   ├── SwapPositions.tsx
+│       │   └── commonStyles.tsx
+│       ├── index.tsx        # Entry point
+│       └── taskpane.html    # Main HTML container
+├── babel.config.json        # Babel configuration
+├── manifest.xml             # Add-in manifest
+├── package.json             # Dependencies and scripts
+├── tsconfig.json            # TypeScript configuration
+└── webpack.config.js        # Webpack configuration
+```
+
+## Development Environment Setup
+
+### Prerequisites
+
+- Node.js (LTS version recommended)
+- npm 
+- Microsoft PowerPoint (desktop version)
+
+### Setup Steps
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/your-org/edison-powerpoint-addin.git
+   cd edison-powerpoint-addin
+   ```
+
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+3. Build the project:
+   ```bash
+   npm run build:dev
+   ```
+
+4. Start the development server:
+   ```bash
+   npm run dev-server
+   ```
+
+5. Start the add-in in PowerPoint:
+   ```bash
+   npm run start
+   ```
+
+### Local Development Certificates
+
+Office Add-ins require HTTPS even for local development. The `office-addin-dev-certs` package is used to create and install self-signed certificates for development.
+
+If you encounter certificate issues, run:
+```bash
+npx office-addin-dev-certs install
+```
+
+## Component Development Guidelines
+
+### Creating a New Tool
+
+1. Create a new component file in `src/taskpane/components/`
+2. Import the necessary Office.js APIs and React hooks
+3. Use the StatusContext for user feedback
+4. Follow the pattern of existing components:
+   - Use the `PowerPoint.run()` method for PowerPoint operations
+   - Provide clear success/error messaging
+   - Handle selection states appropriately
+
+Example component structure:
+```tsx
+import * as React from "react";
+import { useState } from "react";
+import { Button } from "@fluentui/react-components";
+import { useStatusContext } from "./App";
+
+const MyNewTool: React.FC = () => {
+  const { setStatusMessage, setStatusType, isProcessing, setIsProcessing } = useStatusContext();
+
+  const performAction = async () => {
+    setIsProcessing(true);
+    try {
+      await PowerPoint.run(async (context) => {
+        // Implement your PowerPoint operations here
+        await context.sync();
+      });
+      setStatusMessage("Operation completed successfully!");
+      setStatusType("success");
+    } catch (error) {
+      setStatusMessage(`Error: ${error.message}`);
+      setStatusType("error");
+      console.error("Operation error:", error);
+    } finally {
+      setIsProcessing(false);
+    }
+  };
+
+  return (
+    <Button onClick={performAction} disabled={isProcessing}>
+      My New Tool
+    </Button>
+  );
+};
+
+export default MyNewTool;
+```
+
+### Common PowerPoint.js Operations
+
+#### Selecting Shapes
+```typescript
+const shapes = context.presentation.getSelectedShapes();
+shapes.load("items");
+await context.sync();
+```
+
+#### Working with Slide Masters
+```typescript
+const slideMasters = context.presentation.slideMasters;
+slideMasters.load("items");
+await context.sync();
+```
+
+#### Creating Shapes
+```typescript
+const shape = slide.shapes.addGeometricShape("Rectangle");
+shape.left = 100;
+shape.top = 100;
+shape.height = 50;
+shape.width = 50;
+await context.sync();
+```
+
+## Status System
+
+The application includes a status system that provides feedback to users:
+
+- **Success**: Operation completed successfully
+- **Warning**: Operation completed with concerns
+- **Error**: Operation failed
+- **Processing**: Shows a spinner while operations are in progress
+
+Use the status context in your components:
+```typescript
+const { 
+  statusMessage, 
+  setStatusMessage, 
+  statusType, 
+  setStatusType, 
+  isProcessing, 
+  setIsProcessing 
+} = useStatusContext();
+```
+
+## Build and Deployment
+
+### Development Build
+```bash
+npm run build:dev
+```
+
+### Production Build
+```bash
+npm run build
+```
+
+### Manifest Validation
+```bash
+npm run validate
+```
+
+This validates the manifest.xml file against the Office Add-in schema.
+
+## Testing
+
+Currently, the project doesn't have automated tests. This is an area for future improvement.
+
+Recommended testing approach:
+1. Manual testing in PowerPoint
+2. Implementation of unit tests for individual utilities
+3. Integration tests for PowerPoint API interactions
+
+## Performance Considerations
+
+- Minimize `context.sync()` calls, especially in loops
+- Batch operations when possible
+- Use memoization for expensive calculations
+- Ensure proper cleanup of event listeners
+
+## Common Issues and Solutions
+
+### Add-in not loading in PowerPoint
+- Verify the development server is running
+- Check for certificate errors in the browser console
+- Validate the manifest.xml file
+
+### PowerPoint API errors
+- Ensure correct API version is being used
+- Check the sequence of operations (some operations require specific order)
+- Verify selections exist before operating on them
+
+## Best Practices
+
+1. **Error Handling**: Always use try/catch blocks with PowerPoint API calls
+2. **User Feedback**: Provide clear status messages for all operations
+3. **Accessibility**: Ensure all UI elements have proper labels and keyboard access
+4. **Theme Support**: Use Fluent UI theme tokens for consistent theming
+5. **Code Organization**: Keep component files focused on a single responsibility
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request with a clear description of the changes
+
+## Resources
+
+- [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)