@themarioga/grid-editor 8.4.0 → 8.6.0

package/CHANGELOG.md

@@ -5,6 +5,57 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [8.6.0] - 2026-10-02
+
+### Added
+- The autosave plugin, `grideditor.autosave.js`: what is edited is kept in
+  `localStorage` or `sessionStorage` a second after each change and when the
+  page is left, without closing the text being typed into. An editor that
+  starts from the html a draft was made from asks, in its confirm modal,
+  whether to restore it. Options `enabled`, `storage`, `key`, `delay` and
+  `maxAge`; methods `enableAutosave`, `disableAutosave`, `saveDraft`,
+  `getDraft` and `clearDraft`; events `after-autosave`, `after-restore-draft`
+  and `autosave-error`.
+- `getHtml({ keepEditing: true })` and `getPlainHtml({ keepEditing: true })`:
+  the same markup, read on a copy of the canvas, so the canvas never leaves
+  editing - open texts, settings panels and the focus stay where they are.
+  `custom_filter` is run on the copy too.
+- For plugins: `cleanMarkup(root, liveOf)`, what `unmark`, `onDeinit` and
+  `onBeforeDeinit` take off, taken off the copy - a plugin that has one of
+  those and no `cleanMarkup` makes `keepEditing` fall back on `getHtml`, with
+  a warning; `onDestroy`; and on the handle `ge.snapshotHtml()`,
+  `ge.setHtml(html)` and `ge.confirm(message, options, answer)`. A text editor
+  of `GridEditor.texts` has `read(contentArea)` and `cleanCopy(copy, area)`.
+  Every shipped plugin and text editor has them.
+- A feature plugin's `methods` are the instance's, whatever their names: up
+  to now only the editor's own documented ones were.
+
+### Changed
+- `example/autosave.html` is built on the plugin, with an on/off switch and
+  a key per imported file; `AUTO_SAVE.md` is gone, its content in the README.
+- The toolbar's add buttons on the left - rows, containers, the feature
+  plugins' and the overflow menu's button - are grey (`btn-light`), and the
+  `toolbar_groups` tabs `btn-outline-secondary`. Blue is left to the buttons
+  on the right: source, preview, layout and the `align: 'end'` ones.
+
+## [8.5.0] - 2026-10-01
+
+### Added
+- `elements.types`: the elements the toolbar offers, a button each. A type
+  has its `type`, its `html` - a string, or a function called for each one
+  made - a `label` or `labelKey`, an `iconClass` and a `group`. A button
+  makes the html's root, marked with `data-ge-element` and `data-ge-label`
+  the way a host marks its own elements, or a `div` around html with no
+  single root. Declaring a type turns `enabled: 'auto'` on.
+- `toolbar_groups`: a third core category, *Elements*, after *Content*. The
+  element buttons go there unless they name another `group`.
+- A feature plugin's `toolbar` item whose `create()` returns `null` adds
+  nothing, rather than failing.
+
+### Changed
+- `toolbar_groups`: the *Text* buttons are in *Elements* now, not in
+  *Content*, which keeps the containers and the sections.
+
 ## [8.4.0] - 2026-10-01
 
 ### Added

package/README.md

@@ -36,7 +36,7 @@ from any web server, or from GitHub Pages, with no build step.
 | [example/summernote.html](example/summernote.html) | Summernote instead of tinyMCE | [live](https://themarioga.github.io/grid-editor/example/summernote.html) |
 | [example/clipboard.html](example/clipboard.html) | Copy and paste, within an editor, between two, and between tabs | [live](https://themarioga.github.io/grid-editor/example/clipboard.html) |
 | [example/wrap_content.html](example/wrap_content.html) | Non-bootstrap markup wrapped into the grid | [live](https://themarioga.github.io/grid-editor/example/wrap_content.html) |
-| [example/autosave.html](example/autosave.html) | Saving the html as the user edits | [live](https://themarioga.github.io/grid-editor/example/autosave.html) |
+| [example/autosave.html](example/autosave.html) | The autosave plugin: drafts kept as the user edits, offered back after a reload; import and export | [live](https://themarioga.github.io/grid-editor/example/autosave.html) |
 | [example/adapter.html](example/adapter.html) | A page written for 6.x, with jQuery, running unchanged through the adapter | [live](https://themarioga.github.io/grid-editor/example/adapter.html) |
 
 [example/angular](example/angular) is the editor in an Angular app, from the npm
@@ -142,6 +142,14 @@ which parts are elements, tabs, accordions or popups. That marking is how the
 editor reads its markup back, so **save `getHtml`** for anything that will be
 edited again.
 
+`getHtml` takes the canvas out of editing to read it and puts it back, which
+closes a text being typed into and a settings panel that is open.
+`getHtml({ keepEditing: true })` gives the same markup without the canvas
+leaving editing - it is read on a copy - which is what something that reads
+it as the user works, an autosave, wants. A plugin that cannot be read on a
+copy (see [docs/plugins.md](docs/plugins.md#reading-on-a-copy)) makes it fall
+back on `getHtml`, with a warning in the console.
+
 `getPlainHtml` is the same markup with that marking taken off, and each
 `div.ge-content` replaced by what it holds. Bootstrap's own classes and
 attributes stay, so tabs, accordions and popups still work in a page that
@@ -166,8 +174,8 @@ has, with the options it was made with, and warns once.
 
 | Method | Arguments | Returns | What it does |
 | --- | --- | --- | --- |
-| `getHtml` | — | `String` | The clean html: no drawers, no editor classes, no inline styles |
-| `getPlainHtml` | — | `String` | `getHtml` without grid-editor's marking (`ge-*`, `column`, `data-ge-*`), for publishing. It cannot be edited again as it was |
+| `getHtml` | `options?` | `String` | The clean html: no drawers, no editor classes, no inline styles. `{ keepEditing: true }` reads it without the canvas leaving editing |
+| `getPlainHtml` | `options?` | `String` | `getHtml` without grid-editor's marking (`ge-*`, `column`, `data-ge-*`), for publishing. It cannot be edited again as it was. Takes the same `options` |
 | `init` | — | `this` | Run the editing pass over the canvas again. Safe to call after you inject markup |
 | `deinit` | — | `this` | Strip the editing furniture, leave the markup |
 | `reset` | — | `this` | `deinit()` then `init()` |
@@ -379,7 +387,7 @@ new GridEditor('#myGrid', {
 });
 ```
 
-__`toolbar_groups`:__ Whether the toolbar's add buttons are sorted into categories, with tabs at the start of the toolbar choosing which one shows. Default `false`. With `true` the core's categories are *Rows*, the add row buttons, and *Content*, the texts, the containers and the sections; a plugin's buttons go in the category they name with `group` (see [docs/plugins.md](docs/plugins.md)), or in one of their own. The tab chosen is kept while the editor lives, through `setLocale` too. With a single category there is nothing to choose and no tabs. The buttons on the right - the view, source and preview, paste - are never grouped. The more button of `toolbar_overflow` holds what doesn't fit of the category shown; the tabs themselves never go behind it, so with a great many categories they can run out of room.
+__`toolbar_groups`:__ Whether the toolbar's add buttons are sorted into categories, with tabs at the start of the toolbar choosing which one shows. Default `false`. With `true` the core's categories are *Rows*, the add row buttons, *Content*, the containers and the sections, and *Elements*, the texts and the elements of `elements.types`; a plugin's buttons go in the category they name with `group` (see [docs/plugins.md](docs/plugins.md)), or in one of their own. The tab chosen is kept while the editor lives, through `setLocale` too. With a single category there is nothing to choose and no tabs. The buttons on the right - the view, source and preview, paste - are never grouped. The more button of `toolbar_overflow` holds what doesn't fit of the category shown; the tabs themselves never go behind it, so with a great many categories they can run out of room.
 
 ```javascript
 new GridEditor('#myGrid', {
@@ -397,7 +405,7 @@ ge.canvas.addEventListener('grideditor:target-change', function(e) {
 ```
 
 __`custom_filter`:__ Allows the execution of a custom function before initialization and after de-initialization. Accepts a functions or a function name as string.
-Gives the `canvas` element and `isInit` (true/false) as parameter.
+Gives the `canvas` element and `isInit` (true/false) as parameter. `getHtml({ keepEditing: true })` runs it too, with `isInit` false, on a copy of the canvas rather than the canvas: work on the element it is given, not on one you kept.
 
 ```javascript
 new GridEditor('#myGrid', {
@@ -592,6 +600,32 @@ new GridEditor('#myGrid', {
         enabled: 'auto',                 // on when the page has any; true or false to decide yourself
         selector: '[data-ge-element]',   // what counts as an element
         auto: false,                     // true treats every loose node of a column as one
+        types: [],                       // the elements the toolbar offers, see below
+    },
+});
+```
+
+__`elements.types`:__ The elements the toolbar offers, a button each, in this order. A click makes one in a row and column of its own at the end of the canvas - or at the end of the active target, with `active_target` - and a drag drops it in the column it lands in, as a text or a container. Declaring a type turns `enabled: 'auto'` on, so the buttons are there on a page with no elements yet; `enabled: false` takes them away too.
+
+| Field | | |
+| --- | --- | --- |
+| `type` | required | what it is: its `data-ge-element` |
+| `html` | required | its markup: html, or a function called for each one made, which returns html or a node |
+| `label` / `labelKey` | | the button's label, as it is or as a locale key, which wins and follows `setLocale`. Without either, the `type` |
+| `iconClass` | | the button shows the icon alone, with the label as its title |
+| `group` | | its `toolbar_groups` category. Default `elements` |
+
+What a button makes is the html's root, marked the way you mark your own elements - `data-ge-element`, and `data-ge-label` with the label unless the html has one - so `getHtml` gives it back as you would have written it. Html with more than one root, or none, is wrapped in a `div`. A `<script>` in html given as a string does not run. A type with no `type` or no `html` is left off the toolbar, and one whose function throws or gives nothing adds nothing; both with a warning in the console, as is a type whose markup does not match your `elements.selector`.
+
+```javascript
+new GridEditor('#myGrid', {
+    elements: {
+        types: [
+            { type: 'quote', label: 'Pull quote', iconClass: 'bi bi-quote',
+              html: '<blockquote class="my-quote"><p>Quote</p></blockquote>' },
+            { type: 'figure', labelKey: 'element.figure', group: 'media',
+              html: function() { return '<figure id="fig-' + Date.now() + '"><img src="…"></figure>'; } },
+        ],
     },
 });
 ```
@@ -791,6 +825,72 @@ A paste is an add like any other: `before-add-*` and `after-add-*` with
 `source: 'paste'`, and canceling the first turns it away. A copy fires
 `grideditor:after-copy`.
 
+### Autosave
+
+A plugin:
+
+```html
+<script src="grid-editor/dist/plugins/grideditor.autosave.min.js"></script>
+```
+
+What is being edited is kept in the browser's storage as it changes: a second
+after the last change, and when the page is left or reloaded. It is read with
+`getHtml({ keepEditing: true })`, so a text being typed into stays open, with
+its cursor. When an editor starts and a draft of the same html is saved, the
+editor's confirm modal asks whether to restore it; *Discard*, or closing the
+modal, takes the draft away.
+
+```javascript
+new GridEditor('#myGrid', {
+    autosave: {
+        enabled: true,        // saving from the start; the methods turn it on and off
+        storage: 'local',     // or 'session'
+        key: null,            // where the draft is kept: one per document, see below
+        delay: 1000,          // milliseconds after the last change
+        maxAge: null,         // milliseconds a draft is offered for; null for ever
+    },
+});
+```
+
+A draft remembers the html its editor started from, and is only offered to an
+editor that starts from the same html. A page that loads one document after
+another into the editor is not offered one document's draft over another, but
+with one key, editing the second overwrites the first's draft. Give each
+document a key of its own - its file name, its id - and each keeps its draft:
+
+```javascript
+new GridEditor('#myGrid', { autosave: { key: 'page-' + pageId } });
+```
+
+The default key is `grideditor.autosave:` with the page's path and the canvas's
+id. Two editors on a page with the same key would overwrite each other's
+drafts, so the second saves nothing and says so in the console.
+
+| Method | Returns | What it does |
+| --- | --- | --- |
+| `enableAutosave()` | `Boolean` | Starts saving, from what there is now |
+| `disableAutosave()` | `Boolean` | Stops saving; the draft is kept |
+| `saveDraft()` | `Boolean` | Saves now, if the html changed, even when disabled; `true` when it wrote |
+| `getDraft()` | `Object` | `{ html, savedAt }`, or `null` |
+| `clearDraft()` | `Boolean` | Takes the draft away, as a page does once it has saved to its server |
+
+The methods are there only when the plugin is loaded, and answer `false` or
+`null` when the browser gives the page no storage - a private window may not -
+in which case nothing is saved and the console says so.
+
+| Event | Payload | Fires |
+| --- | --- | --- |
+| `grideditor:after-autosave` | `canvas`, `html`, `savedAt`, `source` (`change`, `pagehide`, `api` or `destroy`) | after a draft is written |
+| `grideditor:after-restore-draft` | `canvas`, `html`, `savedAt` | after the user chose to restore one |
+| `grideditor:autosave-error` | `canvas`, `error` | when the storage refused a draft - it is full; the next change tries again |
+
+A draft in `localStorage` outlives the browser being closed, on a computer
+someone else may use next: `storage: 'session'` keeps it for the tab only. A
+draft is offered only to an editor that starts from the same html *as this
+version of grid-editor reads it*, so one saved before an upgrade that changes
+what `getHtml` gives is not offered after it. Drafts are a safety net, not a
+place to keep work.
+
 ### Containers
 
 Tabs, accordions, popups and cards. A tabs, accordion or popup container holds