@editora/plugins 1.0.20 โ†’ 1.0.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,706 +1,320 @@
1
- # @editora/plugins
2
-
3
- [![Version](https://img.shields.io/npm/v/@editora/plugins)](https://www.npmjs.com/package/@editora/plugins)
4
- [![License](https://img.shields.io/npm/l/@editora/plugins)](https://github.com/ajaykr089/Editora/blob/main/LICENSE)
5
- [![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
6
- [![Size](https://img.shields.io/bundlephobia/minzip/@editora/plugins)](https://bundlephobia.com/package/@editora/plugins)
7
-
8
- > [!IMPORTANT]
9
- > **Live Website:** https://editora-ecosystem.netlify.app/
10
- > **Storybook:** https://editora-ecosystem-storybook.netlify.app/
11
-
12
-
13
- <div align="center">
14
- <img src="../../images/editora_logo_blocks.svg" alt="Editora Logo" width="200" height="auto">
15
- </div>
16
-
17
- <div align="center">
18
- <img src="../../images/features-overview-7.png" alt="Editora Plugins - Plugin Architecture" width="600" style="border-radius: 8px; box-shadow: 0 4px 8px rgba(0,0,0,0.1);">
19
- <p><em>Comprehensive plugin collection with 40+ plugins for rich text editing</em></p>
20
- </div>
21
-
22
- Comprehensive plugin collection for Editora Rich Text Editor with 40+ plugins for text formatting, media management, accessibility, and more.
23
-
24
- ## ๐Ÿ“ฆ Installation
1
+ <h1 align="center">@editora/plugins</h1>
2
+
3
+ <p align="center">
4
+ Fifty-six plugins for the Editora editor: formatting, tables, math, comments, track changes, document import and
5
+ export, and more. Pick the ones you need and the toolbar is built from them.
6
+ </p>
7
+
8
+ <p align="center">
9
+ <a href="https://www.npmjs.com/package/@editora/plugins"><img src="https://img.shields.io/npm/v/@editora/plugins.svg" alt="npm version"></a>
10
+ <a href="https://www.npmjs.com/package/@editora/plugins"><img src="https://img.shields.io/npm/dm/@editora/plugins.svg" alt="npm downloads"></a>
11
+ <a href="https://github.com/ajaykr089/Editora/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@editora/plugins.svg" alt="license"></a>
12
+ <a href="https://www.npmjs.com/package/@editora/plugins"><img src="https://img.shields.io/npm/types/@editora/plugins.svg" alt="TypeScript types included"></a>
13
+ </p>
14
+
15
+ <p align="center">
16
+ <a href="https://editora-ecosystem.netlify.app/">Website</a> ยท
17
+ <a href="https://editora-ecosystem-storybook.netlify.app/">Storybook</a> ยท
18
+ <a href="https://github.com/ajaykr089/Editora">GitHub</a>
19
+ </p>
20
+
21
+ <p align="center">
22
+ <img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/plugins/docs/images/table.png" alt="An editor with a freshly inserted table and the floating table toolbar above it, for adding and removing rows and columns" width="900">
23
+ </p>
24
+
25
+ ## What you get
26
+
27
+ - **A plugin per feature.** Bold, headings, lists, links and tables; fonts and colours; code blocks and math; comments,
28
+ track changes and approval workflows; Word and PDF export. [The full catalog](#plugin-catalog) lists all 56.
29
+ - **The toolbar follows your plugins.** Each plugin adds its own buttons, dialogs and shortcuts.
30
+ - **Three ways to import**, from the whole catalog down to a single plugin, so you can keep your bundle small
31
+ ([measured below](#choose-an-entry-point)).
32
+ - **For React and for the web component.** The same plugins run in
33
+ [`@editora/react`](https://www.npmjs.com/package/@editora/react) and in the `<editora-editor>` element of
34
+ [`@editora/core`](https://www.npmjs.com/package/@editora/core).
35
+ - MIT licensed and typed; the typings ship with the package.
36
+
37
+ ## Install
25
38
 
26
39
  ```bash
27
- npm install @editora/plugins @editora/core @editora/themes
40
+ npm install @editora/plugins @editora/core @editora/react @editora/themes
28
41
  ```
29
42
 
30
- When using plugin UI features (table toolbar, pickers, dialogs), also import:
43
+ Import the plugin styles once, next to a theme. They style the dialogs, pickers and the table toolbar:
31
44
 
32
45
  ```ts
33
- import "@editora/plugins/styles.css";
46
+ import '@editora/themes/themes/default.css';
47
+ import '@editora/plugins/styles.css';
34
48
  ```
35
49
 
36
- ## ๐ŸŽฏ Overview
37
-
38
- This package provides a complete set of plugins for building feature-rich text editors. Each plugin is modular, tree-shakeable, and can be used independently.
39
-
40
- ## โœจ Plugin Categories
41
-
42
- ### Text Formatting (12 plugins)
43
- - Bold, Italic, Underline, Strikethrough
44
- - Font Family, Font Size, Text Color, Background Color
45
- - Subscript, Superscript, Code Inline
46
- - Clear Formatting
47
-
48
- ### Block Elements (8 plugins)
49
- - Headings (H1-H6)
50
- - Paragraphs
51
- - Blockquotes
52
- - Code Blocks with syntax highlighting
53
- - Horizontal Rules
54
- - Page Breaks
55
- - Preformatted Text
56
- - Footnotes
57
-
58
- ### Lists & Structure (5 plugins)
59
- - Bullet Lists
60
- - Numbered Lists
61
- - Checklists
62
- - Indent/Outdent
63
- - Text Alignment (Left, Center, Right, Justify)
64
-
65
- ### Media & Embeds (6 plugins)
66
- - Images with upload
67
- - Videos
68
- - Audio
69
- - Embed IFrames
70
- - Media Manager
71
- - Special Characters & Emojis
72
-
73
- ### Advanced Features (10 plugins)
74
- - Tables (full editing capabilities)
75
- - Math Equations (LaTeX support)
76
- - Merge Tags / Templates
77
- - Comments & Annotations
78
- - Document Manager (import/export)
79
- - Spell Checker
80
- - Accessibility Checker
81
- - Link Management
82
- - Anchor Links
83
- - Print Preview
84
-
85
- ### Utilities (4 plugins)
86
- - History (Undo/Redo)
87
- - Fullscreen Mode
88
- - Line Height
89
- - Text Direction (LTR/RTL)
90
- - Capitalization (uppercase, lowercase, title case)
91
-
92
- ## ๐Ÿš€ Quick Start
93
-
94
- ### Entry Paths (All Free + Customizable)
95
-
96
- Every plugin entry path is MIT-licensed, free to use, and customizable:
97
-
98
- - `@editora/plugins`: full plugin catalog
99
- - `@editora/plugins/lite`: common/core plugin subset for lean bundles
100
- - `@editora/plugins/enterprise`: advanced/specialized workflow plugins
101
- - `@editora/plugins/<plugin-name>`: targeted per-plugin imports
102
-
103
- ### Recommended Imports For Smaller Bundles
104
-
105
- For best bundle size, avoid importing everything from `@editora/plugins` in large apps.
106
-
107
- Use one of these patterns:
108
-
109
- ```ts
110
- // Lightweight preset entry
111
- import { BoldPlugin, ItalicPlugin, HistoryPlugin } from '@editora/plugins/lite';
112
-
113
- // Enterprise preset entry (advanced/specialized plugins)
114
- import { MentionPlugin, TrackChangesPlugin, SmartPastePlugin } from '@editora/plugins/enterprise';
50
+ ## Quick start
115
51
 
116
- // Per-plugin subpath entry (most explicit)
117
- import { BoldPlugin } from '@editora/plugins/bold';
118
- import { ItalicPlugin } from '@editora/plugins/italic';
119
- import { SpellCheckPlugin } from '@editora/plugins/spell-check';
120
- ```
52
+ A plugin is a function. Call it, put the result in the `plugins` array of the editor, and name the buttons you want in
53
+ `toolbar.items`:
121
54
 
122
- Lazy-load heavy plugins only when needed:
55
+ ```tsx
56
+ import { EditoraEditor } from '@editora/react';
123
57
 
124
- ```ts
125
- const { DocumentManagerPlugin } = await import('@editora/plugins/document-manager');
126
- const { MediaManagerPlugin } = await import('@editora/plugins/media-manager');
127
- const { SpellCheckPlugin } = await import('@editora/plugins/spell-check');
128
- ```
129
-
130
- ### Enterprise Preset Details
131
-
132
- `@editora/plugins/enterprise` includes advanced plugins for governance, compliance, workflow, and QA:
133
-
134
- - Collaboration/workflow: `TrackChangesPlugin`, `VersionDiffPlugin`, `CommentsPlugin`, `ApprovalWorkflowPlugin`
135
- - Validation/compliance: `ContentRulesPlugin`, `DocSchemaPlugin`, `A11yCheckerPlugin`, `SpellCheckPlugin`, `PIIRedactionPlugin`
136
- - Structured/dynamic authoring: `ConditionalContentPlugin`, `DataBindingPlugin`, `MergeTagPlugin`, `TemplatePlugin`, `CitationsPlugin`
137
- - Productivity/runtime intelligence: `SmartPastePlugin`, `SlashCommandsPlugin`, `MentionPlugin`, `BlocksLibraryPlugin`, `TranslationWorkflowPlugin`
138
- - Manager-backed advanced plugins: `MediaManagerPlugin`, `DocumentManagerPlugin`
139
-
140
- ### Basic Formatting
141
-
142
- ```typescript
143
- import {
144
- BoldPlugin,
145
- ItalicPlugin,
146
- UnderlinePlugin,
147
- StrikethroughPlugin
148
- } from '@editora/plugins';
149
-
150
- import "@editora/plugins/styles.css";
151
- import "@editora/themes/themes/default.css";
152
- const plugins = [
153
- BoldPlugin(),
154
- ItalicPlugin(),
155
- UnderlinePlugin(),
156
- StrikethroughPlugin()
157
- ];
158
- ```
58
+ // 1. The common plugins, in one small entry point.
59
+ import { BoldPlugin, HeadingPlugin, HistoryPlugin, LinkPlugin, TablePlugin } from '@editora/plugins/lite';
60
+ // 2. Advanced plugins: review, workflow and structured authoring.
61
+ import { TrackChangesPlugin } from '@editora/plugins/enterprise';
62
+ // 3. A single plugin, and nothing else.
63
+ import { MathPlugin } from '@editora/plugins/math';
159
64
 
160
- ### Complete Editor Setup
161
-
162
- ```typescript
163
- import {
164
- // Text formatting
165
- BoldPlugin,
166
- ItalicPlugin,
167
- UnderlinePlugin,
168
- FontFamilyPlugin,
169
- FontSizePlugin,
170
- TextColorPlugin,
171
- BackgroundColorPlugin,
172
-
173
- // Block elements
174
- HeadingPlugin,
175
- BlockquotePlugin,
176
- CodeSamplePlugin,
177
-
178
- // Lists
179
- ListPlugin,
180
- ChecklistPlugin,
181
- IndentPlugin,
182
- TextAlignmentPlugin,
183
-
184
- // Media
185
- LinkPlugin,
186
- TablePlugin,
187
- MediaManagerPlugin,
188
-
189
- // Advanced
190
- MathPlugin,
191
- CommentsPlugin,
192
- HistoryPlugin,
193
- FullscreenPlugin,
194
- DocumentManagerPlugin
195
- } from '@editora/plugins';
65
+ import '@editora/themes/themes/default.css';
66
+ import '@editora/plugins/styles.css';
196
67
 
197
68
  const plugins = [
198
- // Text formatting
199
- BoldPlugin(),
200
- ItalicPlugin(),
201
- UnderlinePlugin(),
202
- FontFamilyPlugin(),
203
- FontSizePlugin(),
204
- TextColorPlugin(),
205
- BackgroundColorPlugin(),
206
-
207
- // Block elements
208
69
  HeadingPlugin(),
209
- BlockquotePlugin(),
210
- CodeSamplePlugin(),
211
-
212
- // Lists
213
- ListPlugin(),
214
- ChecklistPlugin(),
215
- IndentPlugin(),
216
- TextAlignmentPlugin(),
217
-
218
- // Media
70
+ BoldPlugin(),
219
71
  LinkPlugin(),
220
72
  TablePlugin(),
221
- MediaManagerPlugin(),
222
-
223
- // Advanced
224
73
  MathPlugin(),
225
- CommentsPlugin(),
74
+ TrackChangesPlugin({ author: 'Ava Miller' }),
226
75
  HistoryPlugin(),
227
- FullscreenPlugin(),
228
- DocumentManagerPlugin()
229
76
  ];
230
- ```
231
77
 
232
- ## ๐Ÿ“– Plugin API Reference
78
+ export default function EntryPoints() {
79
+ return (
80
+ <EditoraEditor
81
+ defaultValue="<p>Import from the smallest entry point that has what you need.</p>"
82
+ plugins={plugins}
83
+ toolbar={{ items: 'undo redo | heading bold link | table math | trackchanges' }}
84
+ />
85
+ );
86
+ }
87
+ ```
233
88
 
234
- ### Text Formatting Plugins
89
+ Create the plugins once, outside the component or with `useMemo`, so the editor is not rebuilt on every render.
90
+
91
+ ## Choose an entry point
92
+
93
+ | Import from | You get | Cost of importing one plugin from it |
94
+ | --- | --- | --- |
95
+ | `@editora/plugins/<subpath>` | One plugin, such as `@editora/plugins/bold`. | `BoldPlugin`: 3 KB (1 KB gzipped)<br>`TrackChangesPlugin`: 20 KB (5 KB gzipped) |
96
+ | `@editora/plugins/lite` | The 27 common plugins: formatting, lists, links, tables, colours, fonts, history. | `BoldPlugin`: 83 KB (24 KB gzipped) |
97
+ | `@editora/plugins/enterprise` | The 22 advanced plugins: review, workflow, structured authoring, import and export. | `TrackChangesPlugin`: 256 KB (77 KB gzipped) |
98
+ | `@editora/plugins` | All 56 plugins. | `BoldPlugin`: 447 KB (125 KB gzipped)<br>`TrackChangesPlugin`: 467 KB (129 KB gzipped) |
99
+
100
+ The last column is measured with esbuild, as minified ES modules, importing that one plugin and nothing else; a
101
+ bundler of your own may differ a little. The point is that **the entry points do not tree-shake**: importing one plugin
102
+ from `@editora/plugins`, `lite` or `enterprise` bundles everything that entry exports. Six common plugins (bold, italic,
103
+ headings, lists, links, history) cost 127 KB gzipped from the root and 27 KB from `lite`. Import from `lite` for the
104
+ common ones, and from a subpath for anything else.
105
+
106
+ ## Plugin catalog
107
+
108
+ Every plugin is a function with the same name, available from the root entry and from its own subpath. **Entry** says
109
+ which entry point also has it. **Toolbar item** is the name to use in `toolbar.items` of the React editor. **Name** is
110
+ what you write in the `plugins` attribute of `<editora-editor>`.
111
+
112
+ | Plugin | What it adds | Toolbar item | Entry | Subpath | Name |
113
+ | --- | --- | --- | --- | --- | --- |
114
+ | `A11yCheckerPlugin` | Accessibility checker panel | `a11ychecker` | `enterprise` | `a11y-checker` | `a11yChecker` |
115
+ | `AnchorPlugin` | Named anchors to link to | `anchor` | `lite` | `anchor` | `anchor` |
116
+ | `ApprovalWorkflowPlugin` | Approval workflow: request a review and track it | `approvalworkflow` | `enterprise` | `approval-workflow` | `approvalWorkflow` |
117
+ | `BackgroundColorPlugin` | Background (highlight) colour | `backgroundcolor` | `lite` | `background-color` | `backgroundColor` |
118
+ | `BlockquotePlugin` | Block quotes | `blockquote` | `lite` | `blockquote` | `blockquote` |
119
+ | `BlocksLibraryPlugin` | A library of reusable content blocks | `blockslibrary` | `enterprise` | `blocks-library` | `blocksLibrary` |
120
+ | `BoldPlugin` | Bold | `bold` | `lite` | `bold` | `bold` |
121
+ | `CapitalizationPlugin` | Change the case of the selected text | `capitalization` | `lite` | `capitalization` | `capitalization` |
122
+ | `ChecklistPlugin` | Checklists (task lists) | `checklist` | `lite` | `checklist` | `checklist` |
123
+ | `CitationsPlugin` | Citations panel | `citations` | `enterprise` | `citations` | `citations` |
124
+ | `ClearFormattingPlugin` | Clear formatting | `clearformatting` | `lite` | `clear-formatting` | `clearFormatting` |
125
+ | `CodePlugin` | Source (HTML) view | `sourceview` | | `code` | `code` |
126
+ | `CodeSamplePlugin` | Code blocks | `codeblock` | | `code-sample` | `codeSample` |
127
+ | `CollaborationPlugin` | Real-time collaboration through a y-websocket server (Yjs); see [Collaboration](#collaboration) | | `enterprise` | `collaboration` | `collaboration` |
128
+ | `CommentsPlugin` | Comments on selected text | `comments` | `enterprise` | `comments` | `comments` |
129
+ | `ConditionalContentPlugin` | Content shown only for certain audiences or locales | `conditionalcontent` | `enterprise` | `conditional-content` | `conditionalContent` |
130
+ | `ContentRulesPlugin` | Content rules: banned words, required headings, readability | `contentrules` | `enterprise` | `content-rules` | `contentRules` |
131
+ | `DataBindingPlugin` | Fields bound to your data by key, such as `user.firstName` | `databinding` | `enterprise` | `data-binding` | `dataBinding` |
132
+ | `DirectionPlugin` | Left-to-right and right-to-left text | `direction` | `lite` | `direction` | `direction` |
133
+ | `DocSchemaPlugin` | Validate a document against a structure | `docschema` | `enterprise` | `doc-schema` | `docSchema` |
134
+ | `DocumentManagerPlugin` | Import Word documents; export Word and PDF | `importword` `exportword` `exportpdf` | `enterprise` | `document-manager` | `document-manager` |
135
+ | `EmbedIframePlugin` | Embed an iframe | `embediframe` | | `embed-iframe` | `embedIframe` |
136
+ | `EmojisPlugin` | Emoji picker | `openEmojiDialog` | | `emojis` | `emojis` |
137
+ | `FontFamilyPlugin` | Font family | `fontfamily` | `lite` | `font-family` | `fontFamily` |
138
+ | `FontSizePlugin` | Font size | `fontsize` | `lite` | `font-size` | `fontSize` |
139
+ | `FootnotePlugin` | Footnotes | `footnote` | `lite` | `footnote` | `footnote` |
140
+ | `FormatPainterPlugin` | Copy formatting from one place to another | `formatpainter` | | `format-painter` | `formatPainter` |
141
+ | `FullscreenPlugin` | Fullscreen | `fullscreen` | `lite` | `fullscreen` | `fullscreen` |
142
+ | `HeadingPlugin` | Paragraph and heading levels | `heading` | `lite` | `heading` | `heading` |
143
+ | `HistoryPlugin` | Undo and redo | `undo` `redo` | `lite` | `history` | `history` |
144
+ | `IndentPlugin` | Indent and outdent | `indent` `outdent` | `lite` | `indent` | `indent` |
145
+ | `ItalicPlugin` | Italic | `italic` | `lite` | `italic` | `italic` |
146
+ | `LineHeightPlugin` | Line spacing | `lineheight` | `lite` | `line-height` | `lineHeight` |
147
+ | `LinkPlugin` | Links | `link` | `lite` | `link` | `link` |
148
+ | `ListPlugin` | Bulleted and numbered lists | `bullist` `numlist` | `lite` | `list` | `list` |
149
+ | `MathPlugin` | Math formulas (LaTeX or MathML) | `math` | | `math` | `math` |
150
+ | `MediaManagerPlugin` | Insert images and video | `image` `video` | `enterprise` | `media-manager` | `image` |
151
+ | `MentionPlugin` | @mentions from a list you provide | `mention` | `enterprise` | `mentions` | `mentions` |
152
+ | `MergeTagPlugin` | Merge tags such as `{{ First name }}` | `mergetag` | `enterprise` | `merge-tag` | `mergeTag` |
153
+ | `PIIRedactionPlugin` | Scan for personal data | `piiredaction` | `enterprise` | `pii-redaction` | `piiRedaction` |
154
+ | `PageBreakPlugin` | Page breaks | `pagebreak` | `lite` | `page-break` | `pageBreak` |
155
+ | `PreviewPlugin` | Preview | `preview` | `lite` | `preview` | `preview` |
156
+ | `PrintPlugin` | Print | `print` | `lite` | `print` | `print` |
157
+ | `SlashCommandsPlugin` | A `/` command menu | `slashcommands` | `enterprise` | `slash-commands` | `slashCommands` |
158
+ | `SmartPastePlugin` | Smart paste profiles | `smartpaste` | `enterprise` | `smart-paste` | `smartPaste` |
159
+ | `SpecialCharactersPlugin` | Special characters | `specialcharacters` | | `special-characters` | `specialCharacters` |
160
+ | `SpellCheckPlugin` | Spell check | `spellcheck` | `enterprise` | `spell-check` | `spellCheck` |
161
+ | `StrikethroughPlugin` | Strikethrough | `strikethrough` | `lite` | `strikethrough` | `strikethrough` |
162
+ | `TablePlugin` | Tables, with a toolbar for editing rows and columns | `table` | `lite` | `table` | `table` |
163
+ | `TemplatePlugin` | Insert content templates | `template` | `enterprise` | `template` | `template` |
164
+ | `TextAlignmentPlugin` | Text alignment | `textalignment` | `lite` | `text-alignment` | `textAlignment` |
165
+ | `TextColorPlugin` | Text colour | `textcolor` | `lite` | `text-color` | `textColor` |
166
+ | `TrackChangesPlugin` | Suggested edits, attributed to an author, that can be accepted or rejected | `trackchanges` | `enterprise` | `track-changes` | `trackChanges` |
167
+ | `TranslationWorkflowPlugin` | Translation workflow: locale validation and segment locking | `translationworkflow` | `enterprise` | `translation-workflow` | `translationWorkflow` |
168
+ | `UnderlinePlugin` | Underline | `underline` | `lite` | `underline` | `underline` |
169
+ | `VersionDiffPlugin` | Compare the document with a baseline | `versiondiff` | `enterprise` | `version-diff` | `versionDiff` |
170
+
171
+ Plugins with no entry are imported from their subpath (or the root). A plugin's own command name also works as a
172
+ toolbar item in React, for example `openEmojiDialog`.
173
+
174
+ ## Configure a plugin
175
+
176
+ Most plugins work without options. Some take an options object:
177
+
178
+ ```tsx
179
+ import { EditoraEditor } from '@editora/react';
180
+ import { BoldPlugin, HeadingPlugin, HistoryPlugin } from '@editora/plugins/lite';
181
+ import { DataBindingPlugin, MergeTagPlugin, TrackChangesPlugin } from '@editora/plugins/enterprise';
182
+
183
+ import '@editora/themes/themes/default.css';
184
+ import '@editora/plugins/styles.css';
235
185
 
236
- #### Bold Plugin
237
- ```typescript
238
- BoldPlugin(options?: {
239
- keyboard?: string; // Default: 'Mod-b'
240
- icon?: ReactNode;
241
- className?: string;
242
- })
243
- ```
186
+ const plugins = [
187
+ HeadingPlugin(),
188
+ BoldPlugin(),
189
+ HistoryPlugin(),
244
190
 
245
- #### Font Family Plugin
246
- ```typescript
247
- FontFamilyPlugin(options?: {
248
- fonts?: Array<{
249
- name: string;
250
- value: string;
251
- fallback?: string;
252
- }>;
253
- defaultFont?: string;
254
- })
255
-
256
- // Example
257
- const fontFamilyPlugin = FontFamilyPlugin({
258
- fonts: [
259
- { name: 'Arial', value: 'Arial, sans-serif' },
260
- { name: 'Times New Roman', value: 'Times New Roman, serif' },
261
- { name: 'Courier New', value: 'Courier New, monospace' }
262
- ]
263
- });
264
- ```
191
+ // Tags the author can insert, grouped by category, with a preview value.
192
+ MergeTagPlugin({
193
+ tags: [
194
+ { key: 'first_name', label: 'First name', category: 'Contact', preview: 'Ava' },
195
+ { key: 'company', label: 'Company', category: 'Account', preview: 'Editora Labs' },
196
+ ],
197
+ }),
265
198
 
266
- #### Font Size Plugin
267
- ```typescript
268
- FontSizePlugin(options?: {
269
- sizes?: string[]; // Default: ['8pt', '10pt', '12pt', '14pt', '18pt', '24pt', '36pt']
270
- defaultSize?: string;
271
- })
272
- ```
199
+ // Record edits as suggestions that can be accepted or rejected, attributed to this author.
200
+ TrackChangesPlugin({ author: 'Ava Miller', enabledByDefault: false }),
273
201
 
274
- #### Text Color Plugin
275
- ```typescript
276
- TextColorPlugin(options?: {
277
- colors?: string[];
278
- customColors?: boolean;
279
- recentColors?: boolean;
280
- })
281
- ```
202
+ // Values that data-bound fields in the document are resolved against.
203
+ DataBindingPlugin({ data: { user: { firstName: 'Ava' }, account: { name: 'Editora Labs' } } }),
204
+ ];
282
205
 
283
- ### Block Element Plugins
284
-
285
- #### Heading Plugin
286
- ```typescript
287
- HeadingPlugin(options?: {
288
- levels?: number[]; // Default: [1, 2, 3, 4, 5, 6]
289
- defaultLevel?: number;
290
- keyboard?: Record<number, string>;
291
- })
292
-
293
- // Example
294
- const headingPlugin = HeadingPlugin({
295
- levels: [1, 2, 3],
296
- keyboard: {
297
- 1: 'Mod-Alt-1',
298
- 2: 'Mod-Alt-2',
299
- 3: 'Mod-Alt-3'
300
- }
301
- });
206
+ export default function PluginOptions() {
207
+ return (
208
+ <EditoraEditor
209
+ defaultValue="<h2>Welcome</h2><p>Insert a merge tag, or turn on track changes and edit this sentence.</p>"
210
+ plugins={plugins}
211
+ toolbar={{ items: 'undo redo | heading bold | mergetag | trackchanges databinding' }}
212
+ />
213
+ );
214
+ }
302
215
  ```
303
216
 
304
- #### Code Sample Plugin
305
- ```typescript
306
- CodeSamplePlugin(options?: {
307
- languages?: Array<{
308
- name: string;
309
- value: string;
310
- }>;
311
- theme?: 'light' | 'dark' | 'github' | 'monokai';
312
- lineNumbers?: boolean;
313
- highlightActiveLine?: boolean;
314
- })
315
-
316
- // Example
317
- const codeSamplePlugin = CodeSamplePlugin({
318
- languages: [
319
- { name: 'JavaScript', value: 'javascript' },
320
- { name: 'TypeScript', value: 'typescript' },
321
- { name: 'Python', value: 'python' },
322
- { name: 'HTML', value: 'html' },
323
- { name: 'CSS', value: 'css' }
324
- ],
325
- theme: 'github',
326
- lineNumbers: true
327
- });
328
- ```
217
+ <table>
218
+ <tr>
219
+ <td width="50%"><img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/plugins/docs/images/merge-tags.png" alt="The Insert Merge Tag dialog, with a search box, the Contact and Account categories and a preview of the tag"></td>
220
+ <td width="50%"><img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/plugins/docs/images/track-changes.png" alt="A sentence with a tracked insertion highlighted in green"></td>
221
+ </tr>
222
+ <tr>
223
+ <td align="center"><sub>Merge tags, from the <code>tags</code> option</sub></td>
224
+ <td align="center"><sub>Track changes, with the edit marked</sub></td>
225
+ </tr>
226
+ </table>
329
227
 
330
- ### List Plugins
331
-
332
- #### List Plugin
333
- ```typescript
334
- ListPlugin(options?: {
335
- bulletList?: boolean;
336
- orderedList?: boolean;
337
- keyboard?: {
338
- bullet?: string; // Default: 'Mod-Shift-8'
339
- ordered?: string; // Default: 'Mod-Shift-7'
340
- };
341
- })
342
- ```
228
+ The option types are in the typings of each plugin. Others that take options include `MentionPlugin`,
229
+ `SlashCommandsPlugin`, `VersionDiffPlugin`, `ContentRulesPlugin`, `CitationsPlugin` and `SmartPastePlugin`.
343
230
 
344
- #### Checklist Plugin
345
- ```typescript
346
- ChecklistPlugin(options?: {
347
- nested?: boolean;
348
- keyboard?: string;
349
- })
350
- ```
231
+ ## Math
351
232
 
352
- ### Media Plugins
353
-
354
- #### Image Plugin
355
- ```typescript
356
- MediaManagerPlugin(options: {
357
- upload: (file: File) => Promise<string>;
358
- validate?: (file: File) => boolean;
359
- maxSize?: number; // bytes
360
- allowedTypes?: string[];
361
- resize?: boolean;
362
- maxWidth?: number;
363
- maxHeight?: number;
364
- quality?: number; // 0-1
365
- })
366
-
367
- // Example
368
- const imagePlugin = MediaManagerPlugin({
369
- upload: async (file) => {
370
- const formData = new FormData();
371
- formData.append('image', file);
372
- const response = await fetch('/api/upload', {
373
- method: 'POST',
374
- body: formData
375
- });
376
- const data = await response.json();
377
- return data.url;
378
- },
379
- maxSize: 5 * 1024 * 1024, // 5MB
380
- allowedTypes: ['image/jpeg', 'image/png', 'image/gif', 'image/webp'],
381
- resize: true,
382
- maxWidth: 1200,
383
- quality: 0.9
384
- });
385
- ```
233
+ `MathPlugin` opens a dialog with quick templates and a LaTeX or MathML field:
386
234
 
387
- #### Link Plugin
388
- ```typescript
389
- LinkPlugin(options?: {
390
- openOnClick?: boolean;
391
- validate?: (url: string) => boolean;
392
- onLinkClick?: (url: string) => void;
393
- targetBlank?: boolean;
394
- nofollow?: boolean;
395
- })
396
-
397
- // Example
398
- const linkPlugin = LinkPlugin({
399
- openOnClick: false,
400
- validate: (url) => {
401
- return url.startsWith('http://') || url.startsWith('https://');
402
- },
403
- onLinkClick: (url) => {
404
- window.open(url, '_blank', 'noopener,noreferrer');
405
- },
406
- targetBlank: true
407
- });
408
- ```
235
+ <p align="center">
236
+ <img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/plugins/docs/images/math.png" alt="The Insert Math Formula dialog with LaTeX and MathML, quick templates such as fraction and square root, and a formula field" width="700">
237
+ </p>
409
238
 
410
- ### Advanced Plugins
411
-
412
- #### Table Plugin
413
- ```typescript
414
- TablePlugin(options?: {
415
- allowResize?: boolean;
416
- defaultRows?: number;
417
- defaultCols?: number;
418
- maxRows?: number;
419
- maxCols?: number;
420
- cellSelection?: boolean;
421
- headerRow?: boolean;
422
- })
423
-
424
- // Example
425
- const tablePlugin = TablePlugin({
426
- allowResize: true,
427
- defaultRows: 3,
428
- defaultCols: 3,
429
- maxRows: 20,
430
- maxCols: 10,
431
- cellSelection: true,
432
- headerRow: true
433
- });
434
- ```
239
+ ## Load a heavy plugin on demand
435
240
 
436
- #### Math Plugin
437
- ```typescript
438
- MathPlugin(options?: {
439
- engine?: 'katex' | 'mathjax';
440
- inline?: boolean;
441
- display?: boolean;
442
- macros?: Record<string, string>;
443
- })
444
-
445
- // Example
446
- const mathPlugin = MathPlugin({
447
- engine: 'katex',
448
- inline: true,
449
- display: true,
450
- macros: {
451
- '\\R': '\\mathbb{R}',
452
- '\\N': '\\mathbb{N}'
453
- }
454
- });
455
- ```
241
+ Plugins are ordinary modules, so you can load one when it is needed and keep it out of your main bundle:
456
242
 
457
- #### Comments Plugin
458
- ```typescript
459
- CommentsPlugin(options?: {
460
- onCommentAdd?: (comment: Comment) => void;
461
- onCommentEdit?: (comment: Comment) => void;
462
- onCommentDelete?: (commentId: string) => void;
463
- onCommentResolve?: (commentId: string) => void;
464
- showResolved?: boolean;
465
- })
466
- ```
243
+ ```tsx
244
+ import { useEffect, useState } from 'react';
245
+ import type { Plugin } from '@editora/core';
246
+ import { EditoraEditor } from '@editora/react';
247
+ import { BoldPlugin, HistoryPlugin, ItalicPlugin } from '@editora/plugins/lite';
467
248
 
468
- #### Document Manager Plugin
469
- ```typescript
470
- DocumentManagerPlugin(options?: {
471
- export?: {
472
- word?: boolean;
473
- pdf?: boolean;
474
- html?: boolean;
475
- markdown?: boolean;
476
- };
477
- import?: {
478
- word?: boolean;
479
- html?: boolean;
480
- markdown?: boolean;
481
- };
482
- fileName?: string;
483
- })
484
-
485
- // Example
486
- const documentManagerPlugin = DocumentManagerPlugin({
487
- export: {
488
- word: true,
489
- pdf: true,
490
- html: true
491
- },
492
- fileName: 'document'
493
- });
494
- ```
249
+ import '@editora/themes/themes/default.css';
250
+ import '@editora/plugins/styles.css';
495
251
 
496
- #### Spell Check Plugin
497
- ```typescript
498
- SpellCheckPlugin(options?: {
499
- language?: string; // Default: 'en-US'
500
- customDictionary?: string[];
501
- ignoreUppercase?: boolean;
502
- ignoreNumbers?: boolean;
503
- })
504
- ```
252
+ const basePlugins: Plugin[] = [BoldPlugin(), ItalicPlugin(), HistoryPlugin()];
505
253
 
506
- #### Accessibility Checker Plugin
507
- ```typescript
508
- A11yCheckerPlugin(options?: {
509
- rules?: string[];
510
- autoCheck?: boolean;
511
- severity?: 'error' | 'warning' | 'info';
512
- })
513
- ```
254
+ // Load a heavy plugin only when the editor is shown, so it stays out of your main bundle.
255
+ export default function LazyPlugins() {
256
+ const [plugins, setPlugins] = useState<Plugin[]>(basePlugins);
514
257
 
515
- ### Utility Plugins
516
-
517
- #### History Plugin
518
- ```typescript
519
- HistoryPlugin(options?: {
520
- depth?: number; // Default: 100
521
- keyboard?: {
522
- undo?: string; // Default: 'Mod-z'
523
- redo?: string; // Default: 'Mod-Shift-z'
524
- };
525
- })
526
- ```
258
+ useEffect(() => {
259
+ import('@editora/plugins/spell-check').then(({ SpellCheckPlugin }) => {
260
+ setPlugins([...basePlugins, SpellCheckPlugin()]);
261
+ });
262
+ }, []);
527
263
 
528
- #### Fullscreen Plugin
529
- ```typescript
530
- FullscreenPlugin(options?: {
531
- keyboard?: string; // Default: 'F11'
532
- onEnter?: () => void;
533
- onExit?: () => void;
534
- })
264
+ return <EditoraEditor defaultValue="<p>Spell check arrives after the first render.</p>" plugins={plugins} />;
265
+ }
535
266
  ```
536
267
 
537
- ## ๐Ÿ’ก Usage Examples
538
-
539
- ### Blog Editor
268
+ ## Collaboration
540
269
 
541
- ```typescript
542
- import {
543
- BoldPlugin,
544
- ItalicPlugin,
545
- HeadingPlugin,
546
- ParagraphPlugin,
547
- LinkPlugin,
548
- MediaManagerPlugin,
549
- ListPlugin,
550
- BlockquotePlugin,
551
- HistoryPlugin
552
- } from '@editora/plugins';
270
+ `CollaborationPlugin` edits one document together through a [y-websocket](https://github.com/yjs/y-websocket) server.
271
+ Give it your own server:
553
272
 
554
- const blogPlugins = [
555
- BoldPlugin(),
556
- ItalicPlugin(),
557
- HeadingPlugin({ levels: [1, 2, 3] }),
558
- LinkPlugin({ targetBlank: true }),
559
- MediaManagerPlugin({
560
- upload: uploadImage,
561
- maxSize: 2 * 1024 * 1024
562
- }),
563
- ListPlugin(),
564
- BlockquotePlugin(),
565
- HistoryPlugin()
566
- ];
273
+ ```ts
274
+ CollaborationPlugin({
275
+ websocketUrl: 'wss://collab.example.com', // your own y-websocket server
276
+ roomName: 'proposal-42',
277
+ userName: 'Ava Miller',
278
+ });
567
279
  ```
568
280
 
569
- ### Technical Documentation Editor
570
-
571
- ```typescript
572
- import {
573
- BoldPlugin,
574
- ItalicPlugin,
575
- CodePlugin,
576
- CodeSamplePlugin,
577
- HeadingPlugin,
578
- TablePlugin,
579
- LinkPlugin,
580
- AnchorPlugin,
581
- MathPlugin,
582
- HistoryPlugin
583
- } from '@editora/plugins';
584
-
585
- const docsPlugins = [
586
- BoldPlugin(),
587
- ItalicPlugin(),
588
- CodePlugin(),
589
- CodeSamplePlugin({
590
- languages: [
591
- { name: 'JavaScript', value: 'javascript' },
592
- { name: 'TypeScript', value: 'typescript' },
593
- { name: 'Python', value: 'python' }
594
- ],
595
- lineNumbers: true
596
- }),
597
- HeadingPlugin(),
598
- TablePlugin({ headerRow: true }),
599
- LinkPlugin(),
600
- AnchorPlugin(),
601
- MathPlugin({ engine: 'katex' }),
602
- HistoryPlugin()
603
- ];
604
- ```
281
+ > [!WARNING]
282
+ > **Without `websocketUrl` the plugin syncs through the public Yjs demo server** (`wss://demos.yjs.dev`). The room is
283
+ > named after `roomName`, then the editor's `id`, and otherwise `editora-default-room`, which every user of the
284
+ > default shares. Anyone who knows the room name can read and edit the document. The plugin logs a warning once when
285
+ > this happens. Always pass your own server. In `<editora-editor>`, also list your plugins: leaving the `plugins`
286
+ > attribute out loads every plugin, this one included.
605
287
 
606
- ### Collaborative Editor
288
+ The other options are `userColor`, and `doc` or `provider` if you already have a Yjs document or provider.
607
289
 
608
- ```typescript
609
- import {
610
- BoldPlugin,
611
- ItalicPlugin,
612
- CommentsPlugin,
613
- HistoryPlugin,
614
- MergeTagPlugin
615
- } from '@editora/plugins';
290
+ ## With the web component
616
291
 
617
- const collaborativePlugins = [
618
- BoldPlugin(),
619
- ItalicPlugin(),
620
- CommentsPlugin({
621
- onCommentAdd: async (comment) => {
622
- await saveComment(comment);
623
- },
624
- onCommentResolve: async (commentId) => {
625
- await resolveComment(commentId);
626
- }
627
- }),
628
- MergeTagPlugin({
629
- tags: [
630
- { label: 'First Name', value: '{{firstName}}', category: 'User' },
631
- { label: 'Last Name', value: '{{lastName}}', category: 'User' },
632
- { label: 'Email', value: '{{email}}', category: 'User' }
633
- ],
634
- defaultCategory: 'User',
635
- dialog: {
636
- title: 'Insert Variable',
637
- searchPlaceholder: 'Search variables...',
638
- showPreview: true
639
- },
640
- tokenTemplate: '{value}'
641
- }),
642
- HistoryPlugin()
643
- ];
644
- ```
292
+ The plugins also run in `<editora-editor>`. Name them in the `plugins` attribute, using the **Name** column above:
645
293
 
646
- `MergeTagPlugin` supports functional customization:
647
-
648
- - `tags`: flat list of tags (auto-grouped by `category`)
649
- - `categories`: explicit grouped categories with custom order
650
- - `defaultCategory`: initial tab
651
- - `dialog`: labels/placeholders/preview toggle
652
- - `tokenTemplate`: string template (`{key}`, `{label}`, `{category}`, `{value}`) or formatter function
653
-
654
- ### Custom Templates
655
-
656
- You can register your own templates before initializing the editor:
657
-
658
- ```typescript
659
- import { TemplatePlugin, addCustomTemplate } from '@editora/plugins';
660
-
661
- addCustomTemplate({
662
- id: 'invoice-basic',
663
- name: 'Invoice (Basic)',
664
- category: 'Billing',
665
- description: 'Simple invoice template',
666
- html: `
667
- <h1>Invoice</h1>
668
- <p><strong>Customer:</strong> {{customer.name}}</p>
669
- <p><strong>Date:</strong> {{today}}</p>
670
- <p><strong>Total:</strong> {{invoice.total}}</p>
671
- `,
672
- tags: ['invoice', 'billing']
673
- });
294
+ ```html
295
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@editora/core/dist/webcomponent.min.css" />
296
+ <script type="module" src="https://cdn.jsdelivr.net/npm/@editora/core/dist/webcomponent.js"></script>
674
297
 
675
- const plugins = [
676
- TemplatePlugin()
677
- ];
298
+ <editora-editor plugins="history heading bold table mergeTag" toolbar="undo redo | heading bold | table | mergeTags"></editora-editor>
678
299
  ```
679
300
 
680
- Notes:
681
- - `id` must be unique.
682
- - HTML is sanitized on insertion.
683
- - Use `validateTemplate(template)` if you want to pre-check templates before registering.
301
+ Toolbar names in the element are camelCase and case-sensitive (`textColor`, `trackChanges`, `mergeTags`), unlike the
302
+ lowercase names in the table. See [`@editora/core`](https://www.npmjs.com/package/@editora/core#toolbar-items) for the
303
+ list and for the element's other options. Plugin options such as `tags` are set through the factory functions, in React.
684
304
 
685
- ## ๐Ÿ”ง TypeScript Support
305
+ ## TypeScript
686
306
 
687
- All plugins include full TypeScript definitions:
307
+ The typings ship with the package, for the root entry and for every subpath. A plugin is typed as `Plugin` from
308
+ `@editora/core`.
688
309
 
689
- ```typescript
690
- import type { Plugin, PluginConfig } from '@editora/plugins';
310
+ ## The rest of the family
691
311
 
692
- const customConfig: PluginConfig = {
693
- // Full type safety
694
- };
695
- ```
312
+ | Package | |
313
+ | --- | --- |
314
+ | [`@editora/react`](https://www.npmjs.com/package/@editora/react) | The editor as a React component. |
315
+ | [`@editora/core`](https://www.npmjs.com/package/@editora/core) | The editor engine and the `<editora-editor>` web component. |
316
+ | [`@editora/themes`](https://www.npmjs.com/package/@editora/themes) | Light, dark and acme themes. |
696
317
 
697
- ## ๐Ÿ“„ License
318
+ ## License
698
319
 
699
320
  MIT ยฉ [Ajay Kumar](https://github.com/ajaykr089)
700
-
701
- ## ๐Ÿ”— Links
702
-
703
- - [Documentation](https://editora-ecosystem.netlify.app/)
704
- - [GitHub Repository](https://github.com/ajaykr089/Editora)
705
- - [Issue Tracker](https://github.com/ajaykr089/Editora/issues)
706
- - [npm Package](https://www.npmjs.com/package/@editora/plugins)