0
# Core Plugin System
1

2
The core plugin system provides the foundation for caption functionality in Plate editors through `BaseCaptionPlugin` and the `withCaption` editor enhancement.
3

4
## Imports
5

6
```typescript
7
import { 
8
  BaseCaptionPlugin, 
9
  withCaption, 
10
  type CaptionConfig 
11
} from "@udecode/plate-caption";
12
import type { 
13
  OverrideEditor, 
14
  PluginConfig, 
15
  SlateEditor, 
16
  Path 
17
} from "@udecode/plate";
18
```
19

20
## Capabilities
21

22
### BaseCaptionPlugin
23

24
Core plugin that integrates caption functionality with Plate's plugin system, managing state for focus paths, visibility, and element queries.
25

26
```typescript { .api }
27
/**
28
 * Core caption plugin with configuration options
29
 */
30
const BaseCaptionPlugin = createTSlatePlugin<CaptionConfig>({
31
  key: KEYS.caption,
32
  options: {
33
    focusEndPath: null,
34
    focusStartPath: null,
35
    query: { allow: [] },
36
    visibleId: null,
37
  },
38
});
39

40
type CaptionConfig = PluginConfig<
41
  'caption',
42
  {
43
    /** When defined, focus end of caption textarea with the same path. */
44
    focusEndPath: Path | null;
45
    /** When defined, focus start of caption textarea with the same path. */
46
    focusStartPath: Path | null;
47
    query: {
48
      /** Plugin keys to enable caption. */
49
      allow: string[];
50
    };
51
    /** ID of currently visible caption element */
52
    visibleId: string | null;
53
  },
54
  {},
55
  {},
56
  {
57
    /** Check if caption is visible for given element ID */
58
    isVisible?: (elementId: string) => boolean;
59
  }
60
>;
61
```
62

63
**Usage Examples:**
64

65
```typescript
66
import { createPlateEditor } from "@udecode/plate";
67
import { BaseCaptionPlugin } from "@udecode/plate-caption";
68

69
// Basic configuration
70
const editor = createPlateEditor({
71
  plugins: [
72
    BaseCaptionPlugin.configure({
73
      options: {
74
        query: { allow: ['img', 'media', 'video'] } // Enable captions for these element types
75
      }
76
    })
77
  ]
78
});
79

80
// Access plugin options
81
const captionOptions = editor.getOptions(BaseCaptionPlugin);
82
console.log(captionOptions.query.allow); // ['img', 'media', 'video']
83

84
// Set visibility for specific element
85
editor.setOption(BaseCaptionPlugin, 'visibleId', 'element-123');
86

87
// Check if element caption is visible
88
const isVisible = editor.getSelector(BaseCaptionPlugin).isVisible('element-123');
89
```
90

91
### withCaption Editor Enhancement
92

93
Editor override function that adds caption-specific behavior including selection handling and keyboard navigation.
94

95
```typescript { .api }
96
/**
97
 * Editor override that adds caption-specific behavior including selection handling and keyboard navigation.
98
 * This is an OverrideEditor function that's automatically applied by BaseCaptionPlugin.
99
 */
100
const withCaption: OverrideEditor<CaptionConfig>;
101

102
type OverrideEditor<T extends PluginConfig> = (config: {
103
  editor: SlateEditor;
104
  getOptions: () => T['options'];
105
  tf: any;
106
}) => any;
107
```
108

109
**Key Behaviors:**
110

111
- **Selection Handling**: Automatically focuses caption textarea when navigating up from elements with captions
112
- **Keyboard Navigation**: Handles up/down arrow keys to move between editor content and caption fields
113
- **Focus Management**: Sets appropriate focus paths when caption interaction is detected
114

115
**Usage Examples:**
116

117
```typescript
118
import { createPlateEditor } from "@udecode/plate";
119
import { BaseCaptionPlugin } from "@udecode/plate-caption";
120

121
// The plugin automatically applies withCaption when configured
122
const editor = createPlateEditor({
123
  plugins: [BaseCaptionPlugin]
124
});
125

126
// withCaption is automatically applied by the plugin system - no manual application needed
127
// The editor enhancement handles selection and keyboard navigation behavior internally
128
```
129

130
## Configuration Options
131

132
### Query Configuration
133

134
Controls which element types can have captions:
135

136
```typescript
137
// Enable captions for specific element types
138
BaseCaptionPlugin.configure({
139
  options: {
140
    query: { 
141
      allow: ['img', 'media', 'video', 'embed'] 
142
    }
143
  }
144
})
145

146
// Disable captions entirely
147
BaseCaptionPlugin.configure({
148
  options: {
149
    query: { allow: [] }
150
  }
151
})
152
```
153

154
### Focus Path Management
155

156
Control focus behavior for caption interaction:
157

158
```typescript
159
// Programmatically set focus to caption
160
editor.setOption(BaseCaptionPlugin, 'focusEndPath', [0, 1]); // Focus end of caption at path [0, 1]
161
editor.setOption(BaseCaptionPlugin, 'focusStartPath', [0, 1]); // Focus start of caption at path [0, 1]
162

163
// Clear focus paths
164
editor.setOption(BaseCaptionPlugin, 'focusEndPath', null);
165
editor.setOption(BaseCaptionPlugin, 'focusStartPath', null);
166
```
167

168
### Visibility Management
169

170
Control which caption is currently visible:
171

172
```typescript
173
// Show caption for specific element
174
editor.setOption(BaseCaptionPlugin, 'visibleId', 'img-element-123');
175

176
// Hide all captions
177
editor.setOption(BaseCaptionPlugin, 'visibleId', null);
178

179
// Check visibility
180
const isVisible = editor.getSelector(BaseCaptionPlugin).isVisible('img-element-123');
181
```
182

183
## Integration with Plate Elements
184

185
Caption functionality integrates with existing Plate elements by extending them with caption data:
186

187
```typescript
188
// Element with caption
189
interface TCaptionElement extends TElement {
190
  id: string; // Required for caption identification
191
  caption?: TElement[]; // Optional caption content
192
}
193

194
// Example element structure
195
const imageWithCaption: TCaptionElement = {
196
  id: 'img-123',
197
  type: 'img',
198
  url: 'example.jpg',
199
  children: [{ text: '' }],
200
  caption: [{ text: 'This is the image caption' }]
201
};
202
```
203

204
## Error Handling
205

206
The plugin handles various edge cases and errors:
207

208
- **Invalid Paths**: Gracefully handles invalid or non-existent element paths
209
- **Missing Elements**: Safely handles cases where caption elements are not found
210
- **Focus Management**: Prevents focus conflicts between editor and caption fields
211
- **Selection Edge Cases**: Handles complex selection scenarios during caption interaction