powerpoint-toolbox/docs/DEVELOPERS.md

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
│       │   ├── ActionButton.tsx  # Reusable button with error handling
│       │   ├── AlignmentButtons.tsx
│       │   ├── App.tsx           # Main application component
│       │   ├── ConfidentialButtons.tsx
│       │   ├── DraftButtons.tsx
│       │   ├── GridGuidelineManager.tsx
│       │   ├── Header.tsx
│       │   ├── InsertTitles.tsx
│       │   ├── MatchProperties.tsx
│       │   ├── MatchSizes.tsx
│       │   ├── ProgressBarButtons.tsx
│       │   ├── RoundImage.tsx
│       │   ├── Section.tsx       # Reusable section component
│       │   ├── SmartTextFormatter.tsx
│       │   ├── SwapPositions.tsx
│       │   └── commonStyles.tsx
│       ├── types/            # TypeScript type definitions
│       │   └── office-types.ts # Office API type utilities
│       ├── 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:

   git clone https://github.com/your-org/edison-powerpoint-addin.git
   cd edison-powerpoint-addin
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build:dev
   

4. Start the development server:

   npm run dev-server
   

5. Start the add-in in PowerPoint:

   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:

npx office-addin-dev-certs install

Component Development Guidelines

Reusable Components

ActionButton

A reusable button component that handles error states, loading states, and consistent styling:

import ActionButton from "./ActionButton";

// In your component:
<ActionButton
  title="Match Sizes"
  icon={<ArrowFitInRegular />}
  onClick={myAsyncFunction}
/>

Section

A consistent container for organizing the UI:

import Section from "./Section";

// In your component:
<Section title="My Feature Group">
  <MyFeatureComponent />
</Section>

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:

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

Type-Safe Utilities

The application provides type-safe utility functions in src/taskpane/types/office-types.ts:

// Get error message safely from any error type
const errorMsg = getErrorMessage(error);

// Check if a shape is an image
if (isPictureShape(shape)) {
  // It's a picture shape
}

// Get the first selected slide
const slide = getFirstSelectedSlide(context);

// Select shapes by ID
selectShapesById(slide, [shape1.id, shape2.id]);

Selecting Shapes

const shapes = context.presentation.getSelectedShapes();
shapes.load("items");
await context.sync();

Working with Slide Masters

const slideMasters = context.presentation.slideMasters;
slideMasters.load("items");
await context.sync();

Creating Shapes

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:

const { 
  statusMessage, 
  setStatusMessage, 
  statusType, 
  setStatusType, 
  isProcessing, 
  setIsProcessing 
} = useStatusContext();

Build and Deployment

Development Build

npm run build:dev

Production Build

npm run build

Manifest Validation

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

Optimizing context.sync() calls

A key performance optimization is to batch context.sync() calls:

// BAD: Calling context.sync() in a loop
for (let i = 0; i < shapes.items.length; i++) {
  shapes.items[i].load("name");
  await context.sync(); // Slow! One network roundtrip per shape
  if (shapes.items[i].name === "Target") {
    // Do something
  }
}

// GOOD: Batching context.sync() calls
// Load all properties at once
for (let i = 0; i < shapes.items.length; i++) {
  shapes.items[i].load("name");
}
await context.sync(); // Single network roundtrip for all shapes

// Process the data locally
for (let i = 0; i < shapes.items.length; i++) {
  if (shapes.items[i].name === "Target") {
    // Do something
  }
}

Additional performance tips:

• Use memoization for expensive calculations
• Ensure proper cleanup of event listeners
• Use the ActionButton component for consistent loading states
• Consider using Web Workers for heavy computations

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 and use proper types (see office-types.ts)
2. User Feedback: Provide clear status messages for all operations using the StatusContext
3. Accessibility: Ensure all UI elements have proper ARIA attributes and support keyboard navigation
4. Theme Support: Use Fluent UI theme tokens for consistent theming
5. Code Organization: Keep component files focused on a single responsibility
6. Performance: Batch context.sync() calls and avoid calling them inside loops
7. Reusability: Use custom hooks for common operations and shared components like ActionButton and Section
8. Type Safety: Avoid using "any" type and leverage TypeScript's static typing

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
• Office.js API Reference
• Fluent UI Documentation
• React Documentation