# 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)