# OpenPolotno

[![npm version](https://img.shields.io/npm/v/openpolotno.svg)](https://www.npmjs.com/package/openpolotno)
[![npm downloads](https://img.shields.io/npm/dm/openpolotno.svg)](https://www.npmjs.com/package/openpolotno)
[![license](https://img.shields.io/npm/l/openpolotno.svg)](./LICENSE)

Open-source alternative to Polotno with full template and API support.

https://github.com/therutvikp/OpenPolotno/assets/200716703/48e012c4-4d7b-4e8b-b718-2a277f2aae2a

A powerful, extensible React-based design editor framework for building browser-based design tools. Supports multi-page layouts, rich media elements, animations, AI features, and multiple export formats.

---

## Features

- Multi-page design canvas with undo/redo history and history timeline panel
- Rich set of supported elements: text, image, SVG, video, GIF, figure, line, HTML, audio, and groups
- Context-sensitive toolbar with element-specific controls
- Side panel with templates, photos, videos, uploads, layers, backgrounds, and more
- Rulers and guides with element snapping
- Advanced selection by element type, color, or font
- Paste image from clipboard (Ctrl+V)
- Copy Style / Paste Style (paint format) across elements
- Gradient fill for shapes — linear and radial
- Pattern and texture fill for shapes with built-in patterns and custom image upload
- Image adjustments: brightness, contrast, saturation, highlights, shadows, temperature
- Duotone / color overlay effect on images
- Blend modes for elements
- Animation system with enter, exit, and loop effects
- Video and animation timeline with export to MP4
- Presentation mode (fullscreen slideshow)
- Keyboard shortcuts help panel
- Interactive onboarding tour
- AI image generation and AI-powered text writing
- Export to PNG, JPEG, SVG, HTML, PDF, GIF, and PowerPoint (PPTX)
- Google Fonts integration with custom font upload support
- Image filters, effects, cropping, masking, and background removal
- Element alignment, distribution, grouping, locking, and clipboard operations
- Fully extensible: register custom shapes, toolbars, and components
- Localization support via `setTranslations()`

---

## Installation

```bash
npm install openpolotno
```

---

## Quick Start

### React component approach

```tsx
import { createStore } from 'openpolotno/model';
import { RaeditorContainer, SidePanelWrap, WorkspaceWrap } from 'openpolotno';
import { SidePanel } from 'openpolotno/side-panel';
import { Toolbar } from 'openpolotno/toolbar';
import { Workspace } from 'openpolotno/canvas';

const store = createStore({ key: 'YOUR_API_KEY' });
store.addPage();

export default function App() {
  return (
    <RaeditorContainer>
      <SidePanelWrap>
        <SidePanel store={store} />
      </SidePanelWrap>
      <WorkspaceWrap>
        <Toolbar store={store} />
        <Workspace store={store} />
      </WorkspaceWrap>
    </RaeditorContainer>
  );
}
```

### Vanilla JS / programmatic approach

```ts
import { createRaeditorApp } from 'openpolotno';

const { store } = createRaeditorApp({
  container: document.getElementById('app'),
  key: 'YOUR_API_KEY',
  showCredit: true,
  sections: undefined, // pass string[] to show only specific side panel sections
});

// Add elements programmatically
const page = store.pages[0];
page.addElement({
  type: 'text',
  text: 'Hello OpenPolotno',
  x: 100,
  y: 100,
  fontSize: 40,
});
```

---

## Supported Elements

| Element | Description |
|---------|-------------|
| `text` | Rich text with full typography controls |
| `image` | Raster images with crop, mask, clip, adjustments, and duotone |
| `svg` | Vector graphics with color replacement |
| `video` | Video playback with seeking and animation timeline |
| `gif` | Animated GIF playback |
| `figure` | Pre-built SVG shapes with gradient and pattern fill |
| `line` | Customizable lines with arrow heads and dash patterns |
| `html` | Rich HTML content using a Quill editor |
| `audio` | Audio track metadata |
| `group` | Nested grouping and ungrouping of elements |

All elements share common properties: position, dimensions, rotation, opacity, visibility, blend mode, filters, shadow, animations, and lock/edit states.

---

## Side Panel Sections

- **Templates** — Pre-designed layout templates
- **Text** — Text insertion and font management with custom font upload
- **Photos** — Stock photo search and insertion
- **Elements** — Pre-built shapes, lines, and figures
- **Upload** — Custom image and media uploads
- **Background** — Page background colors and images
- **Layers** — Hierarchical layer management with visibility toggles
- **Size** — Page and element dimension controls
- **Videos** — Video library integration
- **AI Images** — Stable Diffusion text-to-image generation (requires API key)
- **Animations** — Element entry, exit, and loop animations
- **Effects** — Image filtering, color grading, duotone, and blend modes
- **Image Clip** — Masking and clipping tools
- **Pattern Fill** — Built-in patterns and custom texture upload for shapes

---

## Toolbar

Universal controls available for all elements:

- Undo / Redo
- Position (X, Y) and alignment (left, right, top, bottom, center)
- Opacity and blend mode
- Lock / Unlock
- Duplicate
- Delete
- Group / Ungroup
- Copy Style / Paste Style (paint format)
- Export / Download
- Presentation mode
- Keyboard shortcuts reference

Type-specific toolbars:

- **Text** — Font, size, weight, style, letter spacing, alignment, line height, AI writing
- **Image** — Crop, flip, background removal, adjustments (brightness/contrast/saturation), duotone
- **SVG / Figure** — Per-color replacement, gradient fill, pattern fill
- **Video** — Video-specific controls, playback speed
- **Line** — Style, width, dash pattern, arrow heads
- **GIF** — Playback controls
- **HTML** — Bold, italic, and rich text formatting
- **Multi-select** — Bulk operations on multiple elements

---

## Rulers & Guides

Rulers appear along the top and left edges of the canvas. Drag from a ruler to create a guide line. Elements snap to guides during drag. Toggle rulers via the ruler button in the toolbar.

---

## Advanced Selection

The **Advanced Select** toolbar button opens a dialog to select all elements on the current page matching a given:

- **Element type** (text, image, figure, etc.)
- **Fill / stroke color**
- **Font family**

---

## Copy Style / Paste Style

Click the paint-format button in the toolbar to copy the style of the selected element (fill, stroke, opacity, font, effects). Then click another element to paste those styles onto it.

---

## Gradient & Pattern Fill

Shapes and figures support three fill modes accessible from the color picker:

- **Solid** — flat color fill
- **Gradient** — linear or radial gradient with configurable stops
- **Pattern** — built-in repeating textures or a custom uploaded image tile

---

## Image Adjustments & Duotone

Select an image element and open the **Adjustments** panel to tune:

- Brightness, Contrast, Saturation
- Highlights, Shadows, Temperature, Hue

Enable **Duotone** to map the image to two colors (shadows color → highlights color) for a stylized overlay effect.

---

## Blend Modes

Every element supports a CSS-compatible blend mode (Multiply, Screen, Overlay, Darken, Lighten, etc.) set via the toolbar opacity/blend picker.

---

## Animations

The animation system supports three types:

- `enter` — Element appears at page start
- `exit` — Element disappears at page end
- `loop` — Continuous animation during page display

Available effects: **Fade**, **Rotate**, **Blink**, **Bounce**, **Move** (8 directions), **Camera** (zoom/pan), **Morph**, **Wave**

Each animation supports delay, duration, direction, strength, and enable/disable toggle.

---

## Presentation Mode

Click the **Present** button to enter fullscreen slideshow mode. Pages are shown one at a time with animations playing. Press `Escape` to exit.

---

## Export Options

| Format | Method |
|--------|--------|
| PNG / JPEG | `store.saveAsImage()` |
| SVG | `store.saveAsSVG()` |
| HTML | `store.saveAsHTML()` |
| PDF | `store.saveAsPDF()` |
| Animated GIF | `store.saveAsGIF()` |
| MP4 Video | `store.exportVideo()` |
| PowerPoint | via `to-pptx` utility |
| JSON | `store.toJSON()` / `store.loadJSON()` |

---

## AI Features

### AI Image Generation
The `AiImagesPanel` integrates with Stable Diffusion for text-to-image generation. Requires an external API key. Generated images can be added to the canvas or used to replace a selected image element.

### AI Text Writing
The `TextAiWrite` toolbar component provides GPT-powered text manipulation:
- Rewrite, shorten, continue, proofread
- Tone adjustment: friendly, professional, humorous, formal
- Custom prompt support

---

## Filters & Effects

- Sepia, Grayscale, Natural, Warm, Cold, Temperature
- Contrast, Shadows, Highlights, White point, Black point
- Saturation, Vibrance
- Blur, Brightness
- Shadow (offset, blur, color, opacity)

---

## Customization & Extension

```ts
import {
  registerShapeModel,
  registerShapeComponent,
  registerToolbarComponent,
  setGoogleFonts,
  addGlobalFont,
  setTranslations,
  setUploadFunc,
  setRemoveBackground,
  setHighlighterStyle,
  setTransformerStyle,
} from 'openpolotno/config';
```

- **Custom shapes** — Register new element types with `registerShapeModel` + `registerShapeComponent`
- **Custom toolbar** — Add toolbar sections with `registerToolbarComponent`
- **Fonts** — Set Google Fonts list or add custom fonts
- **Localization** — Override any UI string with `setTranslations()`
- **Upload** — Provide your own upload handler with `setUploadFunc()`
- **Background removal** — Plug in your own removal service with `setRemoveBackground()`

---

## Store API

```ts
// Pages
store.addPage()
store.deletePages(ids)
store.selectPage(id)

// Elements
store.selectElements(ids)
store.deleteElements(ids)
store.groupElements(ids)
store.ungroupElements(id)

// Playback (for animations and video)
store.play()
store.stop()
store.seek(timeMs)

// History
store.history.undo()
store.history.redo()
store.history.clear()

// State
store.toJSON()
store.loadJSON(json)
store.clear()
```

---

## Tech Stack

- [React](https://react.dev/) — UI framework
- [Konva.js](https://konvajs.org/) — 2D canvas rendering
- [MobX-State-Tree](https://mobx-state-tree.js.org/) — Reactive state management
- [Blueprint.js](https://blueprintjs.com/) — UI component library
- [MobX](https://mobx.js.org/) — Reactivity

---

## License

See [LICENSE](./LICENSE) for details.