0
# Plate Juice Plugin
1

2
Plate Juice Plugin provides HTML processing functionality for the Plate rich text editor framework. It integrates the `juice` library to automatically inline CSS properties into HTML style attributes during HTML parsing, making it ideal for contexts that don't support external stylesheets like email templates or embedded content.
3

4
## Package Information
5

6
- **Package Name**: @udecode/plate-juice
7
- **Package Type**: npm  
8
- **Language**: TypeScript
9
- **Installation**: `npm install @udecode/plate-juice`
10

11
## Core Imports
12

13
```typescript
14
import { JuicePlugin } from "@udecode/plate-juice";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { JuicePlugin } = require("@udecode/plate-juice");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { createPlateEditor } from "@udecode/plate";
27
import { JuicePlugin } from "@udecode/plate-juice";
28

29
// Create editor with juice plugin
30
const editor = createPlateEditor({
31
  plugins: [
32
    // ... other plugins
33
    JuicePlugin,
34
  ],
35
});
36

37
// The plugin automatically processes HTML content during parsing
38
// CSS in <style> tags gets inlined into style attributes
39
```
40

41
## Architecture
42

43
The Plate Juice Plugin integrates with Plate's plugin architecture through these key components:
44

45
- **Plugin Integration**: Uses `createSlatePlugin` to create a standard Plate plugin
46
- **HTML Parser Injection**: Hooks into the HTML plugin's parser to process HTML content  
47
- **CSS Inlining**: Uses the `juice` library to convert CSS rules to inline styles
48
- **Edit-Only Mode**: Only active during editing, not during rendering
49

50
## Capabilities
51

52
### JuicePlugin
53

54
Main plugin that provides CSS inlining functionality for HTML content in Plate editors.
55

56
```typescript { .api }
57
/**
58
 * Plate plugin that inlines CSS properties into HTML style attributes
59
 * Uses the juice library to process HTML content during parsing
60
 * Created via createSlatePlugin with configuration for HTML parsing integration
61
 */
62
export const JuicePlugin: PlatePlugin<'juice'>;
63
```
64

65
The plugin configuration includes:
66

67
```typescript { .api }
68
interface JuicePluginConfig {
69
  /** Plugin identifier key */
70
  key: 'juice';
71
  /** Only active in edit mode, not render mode */
72
  editOnly: true;
73
  /** Plugin injection configuration */
74
  inject: {
75
    plugins: {
76
      /** HTML plugin integration */
77
      [KEYS.html]: {
78
        parser: {
79
          /** HTML transformation function */
80
          transformData: ({ data }: { data: string }) => string;
81
        };
82
      };
83
    };
84
  };
85
}
86
```
87

88
### HTML Transformation Process
89

90
The plugin processes HTML content through the following steps:
91

92
1. **Comment Cleanup**: Removes `<!-- ` markers that appear after `<style>` tags using the regex pattern `/<style>\s*<!--/g` (workaround for juice library limitation)
93
2. **CSS Inlining**: Applies the `juice()` function to convert CSS rules in `<style>` tags to inline `style` attributes
94
3. **Content Return**: Returns the processed HTML with inlined styles
95

96
**Input Example:**
97
```html
98
<style>
99
  .highlight { background-color: yellow; }
100
</style>
101
<p class="highlight">This text will be highlighted</p>
102
```
103

104
**Output Example:**
105
```html
106
<p class="highlight" style="background-color: yellow;">This text will be highlighted</p>
107
```
108

109
## Plugin Integration
110

111
### Dependencies
112

113
The plugin integrates with these Plate framework components:
114

115
```typescript { .api }
116
/** Plate plugin creation utility from @udecode/plate */
117
function createSlatePlugin<K extends string>(
118
  config: PlatePluginConfig & { key: K }
119
): PlatePlugin<K>;
120

121
/** Plate plugin keys constants from @udecode/plate */
122
const KEYS: PlateKeys;
123

124
/** CSS inlining library from juice package */
125
function juice(html: string): string;
126
```
127

128
### Usage in Plugin Array
129

130
```typescript
131
import { createPlateEditor } from "@udecode/plate";
132
import { HtmlPlugin } from "@udecode/plate-html";
133
import { JuicePlugin } from "@udecode/plate-juice";
134

135
const editor = createPlateEditor({
136
  plugins: [
137
    // HTML plugin must be included for juice plugin to work
138
    HtmlPlugin,
139
    JuicePlugin,
140
    // ... other plugins
141
  ],
142
});
143
```
144

145
## Error Handling
146

147
The plugin handles common CSS processing issues:
148

149
- **Comment markers**: Automatically removes `<!-- ` patterns that interfere with CSS parsing
150
- **Invalid CSS**: Relies on the `juice` library's error handling for malformed CSS
151
- **Missing HTML plugin**: Requires the HTML plugin to be present in the plugin array
152

153
## Types
154

155
```typescript { .api }
156
/** Main plugin export type */
157
type JuicePlugin = PlatePlugin<'juice'>;
158

159
/** HTML transformation function signature */
160
type TransformDataFunction = ({ data }: { data: string }) => string;
161

162
/** Plugin configuration structure */
163
interface PlatePluginConfig {
164
  key: string;
165
  editOnly?: boolean;
166
  inject?: {
167
    plugins?: Record<string, any>;
168
  };
169
}
170

171
/** Plate plugin base type */
172
interface PlatePlugin<K extends string = string> {
173
  key: K;
174
  editOnly?: boolean;
175
  inject?: {
176
    plugins?: Record<string, any>;
177
  };
178
}
179

180
/** Plate KEYS constants type */
181
interface PlateKeys {
182
  juice: 'juice';
183
  html: 'html';
184
  [key: string]: string | string[];
185
}
186
```