@editora/core 1.0.32 → 1.1.0

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
@@ -52,6 +52,10 @@ Or from npm, for a bundler such as Vite, webpack or esbuild:
52
52
  npm install @editora/core
53
53
  ```
54
54
 
55
+ A bundler (Vite, webpack, esbuild, Next.js) handles the packages on any Node version. Importing them in plain
56
+ Node, with no bundler in between (a script, a test runner, a server render that keeps dependencies external), needs
57
+ Node 20.19 or later, or 22.12 or later: older releases, Node 18 included, cannot load them.
58
+
55
59
  ## Quick start
56
60
 
57
61
  ```html
@@ -95,7 +99,7 @@ Set options as attributes:
95
99
 
96
100
  | Attribute | |
97
101
  | --- | --- |
98
- | `plugins` | The plugins to load, separated by spaces (see [the plugin list](https://www.npmjs.com/package/@editora/plugins#plugin-catalog), column *Name*). |
102
+ | `plugins` | The plugins to load, separated by spaces (see [the plugin list](https://www.npmjs.com/package/@editora/plugins#plugin-catalog), column *Name*). `all` loads every plugin in the bundle. Leave it out for [the default set](#default-plugins). |
99
103
  | `toolbar` | The toolbar items, with `\|` between groups: `"undo redo \| bold italic"`. `"false"` hides the toolbar. |
100
104
  | `height` | The height in pixels. Default `400`. |
101
105
  | `width` | The width in pixels. By default the editor fills its parent. |
@@ -164,12 +168,17 @@ The editor in the picture at the top of this page is configured like this:
164
168
  ```
165
169
 
166
170
  You can also configure an editor from JavaScript with `editor.setConfig({ toolbar: 'bold italic', height: 300 })`.
171
+ `setConfig` rebuilds the editor and keeps what the user has typed; pass `content` to replace it instead.
167
172
  To switch the theme at run time, set the attribute: `editor.setAttribute('theme', 'dark')`.
168
173
 
174
+ `readonly` shows content that cannot be edited. `disabled` goes further, like a disabled form field: it also
175
+ disables the toolbar buttons and takes the editor out of the tab order. Both work as attributes and in `setConfig`.
176
+
169
177
  ### Toolbar items
170
178
 
171
179
  `toolbar` takes names separated by spaces, with `|` between groups. The names are camelCase and case-sensitive
172
- (`textColor`, not `textcolor`), and each one needs its plugin in `plugins`:
180
+ (`textColor`, not `textcolor`). Each one needs its plugin: if you set `plugins`, list it there; if you don't, the
181
+ editor loads it for you (see [Default plugins](#default-plugins)).
173
182
 
174
183
  | Name | Plugin |
175
184
  | --- | --- |
@@ -229,13 +238,13 @@ loaded by, is in [`@editora/plugins`](https://www.npmjs.com/package/@editora/plu
229
238
  | `setContent(html)` | Replaces the content. The HTML is sanitised first. |
230
239
  | `execCommand(name)` | Runs a command, as the toolbar does: `toggleBold`, `toggleItalic`, `toggleBulletList`, `insertTable`, `undo`, and so on. Returns `true` if the command ran. |
231
240
  | `focus()` / `blur()` | Moves the focus into or out of the editor. |
232
- | `setConfig(options)` | Changes options at run time, such as `toolbar` or `height`. |
241
+ | `setConfig(options)` | Rebuilds the editor with new options, such as `toolbar`, `height`, `theme` or `disabled`. What the user typed is kept; `content` replaces it. |
233
242
  | `getAPI()` | The same methods as an object, plus `on(event, handler)`, `getConfig()` and `setReadonly(boolean)`. |
234
243
 
235
244
  | Event | `event.detail` | |
236
245
  | --- | --- | --- |
237
- | `editor-ready` | | The editor has been built. It fires again if the editor is rebuilt, for example after you change `plugins` or `toolbar`. |
238
- | `content-change` | `{ html }` | The content changed. It can fire more than once for the same HTML, so compare before you save. |
246
+ | `editor-ready` | | The editor has been built. It fires again if the editor is rebuilt, for example after you change `plugins` or `toolbar` (once, however many attributes you change together). |
247
+ | `content-change` | `{ html }` | The content changed. It fires once after the user pauses typing, and when the editor loses the focus with a change that has not been reported yet, so it does not repeat the same HTML. |
239
248
  | `editor-focus` / `editor-blur` | | The editor gained or lost the focus. |
240
249
  | `editor-destroy` | | The editor was torn down. |
241
250
 
@@ -243,7 +252,7 @@ loaded by, is in [`@editora/plugins`](https://www.npmjs.com/package/@editora/plu
243
252
 
244
253
  | File | Contains |
245
254
  | --- | --- |
246
- | `dist/webcomponent.js` | Every plugin. List the ones you want in `plugins`; leave it out and all load except `collaboration`, which needs a server. |
255
+ | `dist/webcomponent.js` | Every plugin, each fetched only when an editor uses it. Without `plugins`, an editor loads [the default set](#default-plugins). |
247
256
  | `dist/webcomponent-core.js` | Ten essentials: `bold`, `italic`, `underline`, `strikethrough`, `clearFormatting`, `heading`, `blockquote`, `code`, `list` and `history`. |
248
257
 
249
258
  Each has its own stylesheet (`webcomponent.min.css`, `webcomponent-core.min.css`).
@@ -257,12 +266,31 @@ Each has its own stylesheet (`webcomponent.min.css`, `webcomponent-core.min.css`
257
266
  </editora-editor>
258
267
  ```
259
268
 
260
- > [!NOTE]
261
- > List the plugins you want. If you leave `plugins` out, every plugin in the bundle is loaded **except `collaboration`**,
262
- > because it sends the document to a server. It loads only when you name it in `plugins` (or configure it under
263
- > `pluginConfig`), and then stays off until you give it your own `websocketUrl` or a `provider`. Earlier versions loaded
264
- > it by default and synced through a public Yjs demo server, in a room shared by every default editor. See
265
- > [`@editora/plugins`](https://www.npmjs.com/package/@editora/plugins#collaboration).
269
+ ## Default plugins
270
+
271
+ Without a `plugins` attribute, `<editora-editor>` loads a small default set: `bold`, `italic`, `underline`,
272
+ `strikethrough`, `clearFormatting`, `heading`, `blockquote`, `list`, `link`, `table` and `history`. That is about
273
+ 68 KB gzipped of JavaScript for a page with nothing but the tag, against about 437 KB when it loaded every plugin.
274
+
275
+ The editor also loads any other plugin the page asks for:
276
+
277
+ - a toolbar item: `toolbar="undo redo | bold italic | fontSize textColor | insertImage"` loads `fontSize`,
278
+ `textColor` and `image` as well;
279
+ - an entry under `pluginConfig`, such as `pluginConfig: { mentions: { ... } }`;
280
+ - `accessibility: { checker: true }`, which loads `a11yChecker`;
281
+ - a plugin you registered yourself, or loaded with `EditoraPlugins.loadPlugins()`.
282
+
283
+ To get every plugin, as a bare tag did before 1.1.0, ask for all of them:
284
+
285
+ ```html
286
+ <editora-editor plugins="all"></editora-editor>
287
+ ```
288
+
289
+ `all` can be combined with other names (`plugins="all collaboration"`). It never includes `collaboration` on its own,
290
+ because that plugin sends the document to a server: it loads only when you name it in `plugins` or configure it under
291
+ `pluginConfig`, and then stays off until you give it your own `websocketUrl` or a `provider`. Earlier versions loaded
292
+ it by default and synced through a public Yjs demo server, in a room shared by every default editor. See
293
+ [`@editora/plugins`](https://www.npmjs.com/package/@editora/plugins#collaboration).
266
294
 
267
295
  ## Security
268
296