@themarioga/grid-editor 8.4.0 → 8.6.0

package/src/js/plugins/grideditor.autosave.js

@@ -0,0 +1,349 @@
+/**
+ * Autosave for grid-editor.
+ *
+ * A feature plugin: load this file after the editor and what is being edited
+ * is kept in the browser's storage as it changes, and offered back the next
+ * time an editor starts from the same html. What it can ask the editor for is
+ * the handle its factory is called with, described in docs/plugins.md.
+ *
+ *   <script src="dist/grideditor.min.js"></script>
+ *   <script src="dist/plugins/grideditor.autosave.min.js"></script>
+ *
+ * It reads the canvas with ge.snapshotHtml(), which leaves the canvas
+ * editing: the text being typed into stays open, with its cursor. A save
+ * comes `delay` ms after the last change, and when the page is left.
+ *
+ * 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 is not offered one document's draft over another.
+ * Such a page gives each document a key of its own, and each keeps its draft.
+ *
+ *   new GridEditor('#myGrid', { autosave: { key: 'page-42', storage: 'session' } });
+ */
+import { GridEditor } from '../grideditor.js';
+
+Object.assign(GridEditor.locales.en, {
+    'autosave.restore_title': 'Restore the draft?',
+    'autosave.restore_message': 'There is a draft of this page saved on {date}, with changes that were not published. Restore it?',
+    'autosave.restore': 'Restore',
+    'autosave.discard': 'Discard',
+});
+
+var VERSION = 1;
+var STORAGES = { local: 'localStorage', session: 'sessionStorage' };
+var DEFAULT_DELAY = 1000;
+
+/** The keys the editors on this page save to: one editor to a key. */
+var liveKeys = new Set();
+
+/** FNV-1a, 32 bits, as hex: enough to tell one document's html from another's. */
+function fingerprint(text) {
+    var hash = 0x811c9dc5;
+
+    for (var i = 0; i < text.length; i++) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+
+    return (hash >>> 0).toString(16).padStart(8, '0');
+}
+
+/** A stored value that is a draft this file wrote, or null. */
+function validDraft(value) {
+    return !!value && typeof value === 'object' && value.version === VERSION &&
+        typeof value.html === 'string' && typeof value.base === 'string' &&
+        typeof value.savedAt === 'string' && !isNaN(Date.parse(value.savedAt));
+}
+
+GridEditor.features.autosave = function(ge) {
+
+    var options = optionsFrom(ge.settings.autosave || {});
+    var key = options.key || 'grideditor.autosave:' + window.location.pathname + '#' + ge.canvas.id;
+    var storage = storageFor(options.storage);
+
+    // unavailable | disabled | asking | enabled | destroyed
+    var state = 'disabled';
+    var enabledAfterAsking = true; // What asking ends in: a method may have changed it meanwhile
+    var started = false; // Whether the first init has been looked at
+    var draft = null; // The draft found when the editor was made, while it may be offered
+    var base = null; // The fingerprint of the html the editor started from
+    var last = null; // The html saved last, or the one there was to start from
+    var timer = null;
+    var observer = null;
+    var sourceOpen = false;
+    var warnedWrite = false;
+
+    if (!storage) {
+        ge.warn('autosave: the browser will not give this page its ' + STORAGES[options.storage] +
+            ', so nothing is saved');
+        state = 'unavailable';
+    } else if (liveKeys.has(key)) {
+        ge.warn('autosave: another editor on this page already saves to "' + key + '", so this one does not; ' +
+            'give each its own autosave.key');
+        state = 'unavailable';
+    } else {
+        liveKeys.add(key);
+        if (options.enabled) {
+            state = 'enabled';
+            draft = readDraft(true);
+        }
+    }
+
+    function optionsFrom(given) {
+        var result = {
+            enabled: given.enabled === undefined ? true : !!given.enabled,
+            storage: given.storage === undefined ? 'local' : given.storage,
+            key: given.key === undefined ? null : given.key,
+            delay: given.delay === undefined ? DEFAULT_DELAY : given.delay,
+            maxAge: given.maxAge === undefined ? null : given.maxAge,
+        };
+
+        if (!STORAGES[result.storage]) {
+            ge.warn('autosave.storage "' + result.storage + '" is not local or session: local is used');
+            result.storage = 'local';
+        }
+        if (result.key !== null && (typeof result.key !== 'string' || result.key === '')) {
+            ge.warn('autosave.key must be a string: the page\'s own key is used');
+            result.key = null;
+        }
+        if (typeof result.delay !== 'number' || !Number.isInteger(result.delay) || result.delay < 0) {
+            ge.warn('autosave.delay must be a whole number of milliseconds, 0 or more: ' + DEFAULT_DELAY + ' is used');
+            result.delay = DEFAULT_DELAY;
+        }
+        if (result.maxAge !== null && !(typeof result.maxAge === 'number' && isFinite(result.maxAge) && result.maxAge > 0)) {
+            ge.warn('autosave.maxAge must be a number of milliseconds over 0, or null: drafts do not expire');
+            result.maxAge = null;
+        }
+
+        return result;
+    }
+
+    /** The storage, if the browser lets the page have it. */
+    function storageFor(name) {
+        try {
+            var found = window[STORAGES[name]];
+            found.getItem(key);
+            return found;
+        } catch (error) {
+            return null;
+        }
+    }
+
+    /**
+     * The draft saved under the key, or null. Starting, one that cannot be
+     * read or has expired is taken away: nothing will ever offer it.
+     */
+    function readDraft(starting) {
+        var raw;
+
+        try {
+            raw = storage.getItem(key);
+        } catch (error) {
+            return null;
+        }
+        if (raw === null) { return null; }
+
+        var value = null;
+        try { value = JSON.parse(raw); } catch (error) { /* not ours, or mangled */ }
+
+        if (!validDraft(value)) {
+            if (starting) {
+                ge.warn('autosave: what is saved under "' + key + '" is not a draft this version can read: it is discarded');
+                remove();
+            }
+            return null;
+        }
+
+        if (starting && options.maxAge !== null && Date.now() - Date.parse(value.savedAt) > options.maxAge) {
+            remove();
+            return null;
+        }
+
+        return value;
+    }
+
+    function remove() {
+        try { storage.removeItem(key); } catch (error) { /* nothing to take away */ }
+    }
+
+    /** Write the canvas as it is, if it changed. True when it was written. */
+    function save(source) {
+        window.clearTimeout(timer);
+        timer = null;
+
+        if (sourceOpen || base === null) { return false; }
+
+        // The read itself may change the canvas - getHtml, when a plugin
+        // cannot be read on a copy - and that is not a change to save
+        var watching = !!observer;
+        if (watching) { observer.disconnect(); }
+        var html = ge.snapshotHtml();
+        if (watching) { watch(); }
+
+        if (html === last) { return false; }
+
+        var value = { version: VERSION, html: html, savedAt: new Date().toISOString(), base: base };
+
+        try {
+            storage.setItem(key, JSON.stringify(value));
+        } catch (error) {
+            if (!warnedWrite) {
+                warnedWrite = true;
+                ge.warn('autosave: the draft could not be saved (' + (error && error.message || error) + ')');
+            }
+            ge.emit('autosave-error', { canvas: ge.canvas, error: error });
+            return false;
+        }
+
+        last = html;
+        ge.emit('after-autosave', { canvas: ge.canvas, html: html, savedAt: value.savedAt, source: source });
+        return true;
+    }
+
+    function schedule() {
+        window.clearTimeout(timer);
+        timer = window.setTimeout(function() { save('change'); }, options.delay);
+    }
+
+    function watch() {
+        if (!observer) { observer = new MutationObserver(schedule); }
+        observer.observe(ge.canvas, { subtree: true, childList: true, attributes: true, characterData: true });
+    }
+
+    function unwatch() {
+        window.clearTimeout(timer);
+        timer = null;
+        if (observer) { observer.disconnect(); }
+    }
+
+    function onPageHide() {
+        if (state === 'enabled') { save('pagehide'); }
+    }
+
+    /** After the first init has finished: what there is to start from, and the draft offered. */
+    function start() {
+        if (state === 'destroyed' || state === 'unavailable') { return; }
+
+        last = ge.snapshotHtml();
+        base = fingerprint(last);
+        window.addEventListener('pagehide', onPageHide);
+
+        // One of another document, or the same as what is there, is not offered
+        if (state === 'enabled' && draft && draft.base === base && draft.html !== last) {
+            ask(draft);
+            return;
+        }
+
+        draft = null;
+        if (state === 'enabled') { watch(); }
+    }
+
+    function dateOf(savedAt) {
+        try {
+            return new Date(savedAt).toLocaleString(ge.settings.locale || undefined);
+        } catch (error) {
+            return new Date(savedAt).toLocaleString();
+        }
+    }
+
+    function ask(found) {
+        state = 'asking';
+
+        ge.confirm(ge.t('autosave.restore_message', { date: dateOf(found.savedAt) }), {
+            title: ge.t('autosave.restore_title'),
+            ok: ge.t('autosave.restore'),
+            cancel: ge.t('autosave.discard'),
+        }, function(restore) {
+            if (state === 'destroyed') { return; }
+
+            // Taken away unanswered - setLocale - so asked again, in the new
+            // language, once the old modal is out of the way
+            if (restore === null) {
+                window.setTimeout(function() {
+                    if (state === 'asking') { ask(found); }
+                }, 0);
+                return;
+            }
+
+            draft = null;
+
+            if (restore) {
+                last = found.html;
+                ge.setHtml(found.html);
+                ge.emit('after-restore-draft', { canvas: ge.canvas, html: found.html, savedAt: found.savedAt });
+            } else {
+                remove();
+            }
+
+            state = enabledAfterAsking ? 'enabled' : 'disabled';
+            if (state === 'enabled') { watch(); }
+        });
+    }
+
+    return {
+        // The first init, once it has finished: the canvas is ready to be read
+        onInit: function() {
+            if (started) { return; }
+            started = true;
+            Promise.resolve().then(start);
+        },
+
+        onSourceOpen: function() { sourceOpen = true; },
+        onSourceClose: function() { sourceOpen = false; },
+
+        onDestroy: function() {
+            if (state === 'enabled' && timer) { save('destroy'); }
+
+            unwatch();
+            observer = null;
+            window.removeEventListener('pagehide', onPageHide);
+            if (state !== 'unavailable') { liveKeys.delete(key); }
+            state = 'destroyed';
+        },
+
+        methods: {
+            enableAutosave: function() {
+                if (state === 'unavailable') { return false; }
+                if (state === 'asking') {
+                    enabledAfterAsking = true;
+                    return true;
+                }
+                if (state !== 'enabled') {
+                    state = 'enabled';
+                    if (base !== null) { watch(); }
+                }
+                return true;
+            },
+
+            disableAutosave: function() {
+                if (state === 'unavailable') { return false; }
+                if (state === 'asking') {
+                    enabledAfterAsking = false;
+                    return true;
+                }
+                unwatch();
+                state = 'disabled';
+                return true;
+            },
+
+            saveDraft: function() {
+                if (state === 'unavailable' || state === 'asking') { return false; }
+                return save('api');
+            },
+
+            getDraft: function() {
+                if (state === 'unavailable') { return null; }
+
+                var found = readDraft(false);
+                return found ? { html: found.html, savedAt: found.savedAt } : null;
+            },
+
+            clearDraft: function() {
+                if (state === 'unavailable') { return false; }
+
+                remove();
+                return true;
+            },
+        },
+    };
+};

package/src/js/plugins/grideditor.card.js

@@ -64,5 +64,11 @@ GridEditor.containers.card = function(ge) {
         unmark: function(container) {
             ge.unwrapLabels(container);
         },
+
+        // The same, on a copy of the canvas: unmark only touches markup
+        cleanMarkup: function(root) {
+            var definition = this;
+            dom.all(root, '[data-ge-container="card"]').forEach(function(container) { definition.unmark(container); });
+        },
     };
 };

package/src/js/plugins/grideditor.ckeditor.js

@@ -157,6 +157,12 @@ GridEditor.texts.ckeditor = function(ge) {
             });
         },
 
+        // What destroy() puts back. Null while it is still starting
+        read: function(contentArea) {
+            var editor = editors.get(contentArea);
+            return editor ? editor.getData() : null;
+        },
+
         stop: function(contentAreas) {
             contentAreas.filter(function(contentArea) {
                 return dom.hasClass(contentArea, 'active');

package/src/js/plugins/grideditor.clipboard.js

@@ -276,5 +276,8 @@ GridEditor.features.clipboard = function(ge) {
             document.removeEventListener(CHANGE, refresh);
             listening = false;
         },
+
+        // Nothing of its own on the canvas: the tools are in the drawers
+        cleanMarkup: function() {},
     };
 };

package/src/js/plugins/grideditor.codemirror-inline.js

@@ -187,6 +187,13 @@ GridEditor.features['codemirror-inline'] = function(ge) {
             open.forEach(hide);
         },
 
+        // On a copy of the canvas: the editors are drawers, which the core
+        // takes off, and what they hid shows again. What is typed in one and
+        // not applied is not the block's yet
+        cleanMarkup: function(root) {
+            dom.all(root, '.ge-code-hidden').forEach(function(node) { dom.removeClass(node, 'ge-code-hidden'); });
+        },
+
         onInit: function() {
             open.slice().forEach(function(entry) {
                 if (!dom.attached(entry.node)) {

package/src/js/plugins/grideditor.elements.js

@@ -28,11 +28,95 @@ var NOT_ELEMENTS = '.row, .ge-content, .ge-text-block, [data-ge-container], .ge-
 GridEditor.features.elements = function(ge) {
 
     var warnedIntoText = false;
+    var types = validTypes();
 
     function elementsEnabled() {
         if (ge.settings.elements.enabled !== 'auto') { return !!ge.settings.elements.enabled; }
 
-        return ge.settings.elements.auto || !!ge.canvas.querySelector(ge.settings.elements.selector);
+        // A host that offers elements on the toolbar uses them, even on a
+        // page that has none yet
+        return ge.settings.elements.auto || types.length > 0 ||
+            !!ge.canvas.querySelector(ge.settings.elements.selector);
+    }
+
+    /** The elements.types the toolbar can offer. One that can't be made is left out, with a word to the host. */
+    function validTypes() {
+        return (ge.settings.elements.types || []).filter(function(type, index) {
+            var named = type && typeof type.type === 'string' && type.type.trim() !== '';
+            var html = type && (typeof type.html === 'function' || (typeof type.html === 'string' && type.html.trim() !== ''));
+
+            if (!named || !html) {
+                ge.warn('elements.types[' + index + ']: a type needs a type name and its html, as a string or a ' +
+                    'function; it is left off the toolbar.');
+            }
+
+            return named && html;
+        });
+    }
+
+    /** A type's toolbar button. */
+    function typeItem(type) {
+        var mismatched = false;
+
+        return {
+            // Asked again whenever the toolbar is built, so setLocale
+            // translates a labelKey
+            label: function() { return labelOf(type); },
+            iconClass: type.iconClass,
+            group: type.group || 'elements',
+            kind: 'element',
+            inColumn: true,
+            create: function() {
+                var element = makeElement(type);
+
+                if (element && !mismatched && !ge.settings.elements.auto && !element.matches(ge.settings.elements.selector)) {
+                    mismatched = true;
+                    ge.warn('elements.types "' + type.type + '": what it makes does not match elements.selector "' +
+                        ge.settings.elements.selector + '", so it will not be an element once the editor looks again.');
+                }
+
+                return element;
+            },
+        };
+    }
+
+    function labelOf(type) {
+        if (type.labelKey) { return ge.t(type.labelKey); }
+
+        return type.label || type.type;
+    }
+
+    /**
+     * What a type's button makes: the root of its html, marked as the host
+     * marks its own, or a div around it when it has no single root. Null,
+     * with a word to the host, when there is nothing to make.
+     */
+    function makeElement(type) {
+        var made;
+
+        try {
+            made = typeof type.html === 'function' ? type.html() : type.html;
+        } catch (error) {
+            ge.warn('elements.types "' + type.type + '": its html function threw (' + error.message + '); nothing was added.');
+            return null;
+        }
+
+        var nodes = typeof made === 'string' ? dom.parse(made) : (made && made.nodeType ? [made] : []);
+        // Whitespace between tags is not content
+        nodes = nodes.filter(function(node) { return node.nodeType !== 3 || node.textContent.trim() !== ''; });
+
+        if (!nodes.length) {
+            ge.warn('elements.types "' + type.type + '": its html came out empty; nothing was added.');
+            return null;
+        }
+
+        var element = nodes.length === 1 && nodes[0].nodeType === 1 ? nodes[0] : dom.element('div');
+        if (element !== nodes[0] || nodes.length > 1) { fill(element, nodes); }
+
+        element.setAttribute('data-ge-element', type.type);
+        if (!element.hasAttribute('data-ge-label')) { element.setAttribute('data-ge-label', labelOf(type)); }
+
+        return element;
     }
 
     /** Whether a child of a column is an element. */
@@ -55,8 +139,8 @@ GridEditor.features.elements = function(ge) {
         });
     }
 
-    function unmarkElements() {
-        dom.all(ge.canvas, '.ge-element').forEach(function(element) {
+    function unmarkElements(root) {
+        dom.all(root || ge.canvas, '.ge-element').forEach(function(element) {
             dom.removeClass(element, 'ge-element');
 
             // A host element that had no class of its own should not come
@@ -121,6 +205,11 @@ GridEditor.features.elements = function(ge) {
         return placed;
     }
 
+    /** enabled: false takes the toolbar's element buttons away too. */
+    function elementsOff() {
+        return ge.settings.elements.enabled === false;
+    }
+
     /** A place a caller named: an element, or the first one a selector matches. */
     function nodeFrom(node) {
         if (typeof node === 'string') { return document.querySelector(node); }
@@ -163,6 +252,10 @@ GridEditor.features.elements = function(ge) {
             createElement: apiCreateElement,
         },
 
+        // A button for each type the host offers, in the elements category
+        // unless the type names another
+        toolbar: elementsOff() ? [] : types.map(typeItem),
+
         /** A node this plugin marked is an element, whatever else it is. */
         kindOf: function(node) {
             return dom.hasClass(node, 'ge-element') ? 'element' : null;
@@ -188,6 +281,7 @@ GridEditor.features.elements = function(ge) {
         },
 
         onInit: markElements,
-        onDeinit: unmarkElements,
+        onDeinit: function() { unmarkElements(); },
+        cleanMarkup: unmarkElements,
     };
 };

package/src/js/plugins/grideditor.gutters.js

@@ -146,5 +146,9 @@ GridEditor.utilities.gutters = function(ge) {
             listening = null;
             dom.all(ge.canvas, '.ge-gutters').forEach(function(row) { dom.removeClass(row, 'ge-gutters'); });
         },
+
+        cleanMarkup: function(root) {
+            dom.all(root, '.ge-gutters').forEach(function(row) { dom.removeClass(row, 'ge-gutters'); });
+        },
     };
 };

package/src/js/plugins/grideditor.inline-style.js

@@ -182,5 +182,7 @@ GridEditor.utilities['inline-style'] = function(ge) {
             each('onDeinit')();
             accordions = [];
         },
+
+        cleanMarkup: each('cleanMarkup'),
     };
 };

package/src/js/plugins/grideditor.order.js

@@ -205,5 +205,9 @@ GridEditor.utilities.order = function(ge) {
             listening = null;
             dom.all(ge.canvas, '[data-ge-order]').forEach(function(col) { col.removeAttribute('data-ge-order'); });
         },
+
+        cleanMarkup: function(root) {
+            dom.all(root, '[data-ge-order]').forEach(function(col) { col.removeAttribute('data-ge-order'); });
+        },
     };
 };

package/src/js/plugins/grideditor.popup.js

@@ -25,8 +25,8 @@ GridEditor.containers.popup = function(ge) {
     }
 
     /** Whether a popup with this id is on the canvas. */
-    function popupExists(id) {
-        return dom.all(ge.canvas, '[data-ge-popup-id]').some(function(popup) {
+    function popupExists(id, root) {
+        return dom.all(root || ge.canvas, '[data-ge-popup-id]').some(function(popup) {
             return popupIdOf(popup) === id;
         });
     }
@@ -67,8 +67,10 @@ GridEditor.containers.popup = function(ge) {
         });
     }
 
-    function writePopupTriggerAttributes() {
-        dom.all(ge.canvas, '[data-ge-popup-target]').forEach(function(trigger) {
+    function writePopupTriggerAttributes(root) {
+        root = root || ge.canvas;
+
+        dom.all(root, '[data-ge-popup-target]').forEach(function(trigger) {
             var wanted = trigger.getAttribute('data-ge-popup-target');
 
             // The warning marking is editing furniture, whether or not
@@ -76,7 +78,7 @@ GridEditor.containers.popup = function(ge) {
             dom.removeClass(trigger, 'ge-popup-orphan');
             dom.dropEmptyClass(trigger);
 
-            if (!popupExists(wanted)) { return; }
+            if (!popupExists(wanted, root)) { return; }
 
             trigger.setAttribute('data-bs-toggle', 'modal');
             trigger.setAttribute('data-bs-target', '#' + wanted);
@@ -91,7 +93,14 @@ GridEditor.containers.popup = function(ge) {
         // are looked at whenever the canvas is initialized rather than only
         // when a popup is touched
         onInit: wirePopupTriggers,
-        onDeinit: writePopupTriggerAttributes,
+        onDeinit: function() { writePopupTriggerAttributes(); },
+
+        // What onDeinit and unmark do, on a copy of the canvas
+        cleanMarkup: function(root) {
+            var definition = this;
+            writePopupTriggerAttributes(root);
+            dom.all(root, '[data-ge-container="popup"]').forEach(function(container) { definition.unmark(container); });
+        },
 
         create: function(options) {
             var id = ge.containerId('popup');

package/src/js/plugins/grideditor.sections.js

@@ -149,8 +149,8 @@ GridEditor.features.sections = function(ge) {
         });
     }
 
-    function unmark() {
-        dom.children(ge.canvas, '.ge-section').forEach(function(section) {
+    function unmark(root) {
+        dom.children(root || ge.canvas, '.ge-section').forEach(function(section) {
             dom.removeClass(section, 'ge-section');
         });
     }
@@ -197,7 +197,8 @@ GridEditor.features.sections = function(ge) {
         }],
 
         onInit: mark,
-        onDeinit: unmark,
+        onDeinit: function() { unmark(); },
+        cleanMarkup: unmark,
     };
 
     /** A section the toolbar just made, before init has marked it. */

package/src/js/plugins/grideditor.summernote.js

@@ -120,6 +120,20 @@ GridEditor.texts.summernote = function(ge) {
             });
         },
 
+        // What destroy leaves in the content area: the editor's code
+        read: function(contentArea) {
+            var $ = window.jQuery;
+            if (!$ || !$.fn.summernote || !$(contentArea).data('summernote')) { return null; }
+
+            return $(contentArea).summernote('code');
+        },
+
+        // Its frame, which air mode puts right after the content area
+        cleanCopy: function(copy) {
+            var frame = copy.nextElementSibling;
+            if (frame && dom.hasClass(frame, 'note-editor')) { frame.remove(); }
+        },
+
         stop: function(contentAreas) {
             var $ = window.jQuery;
 

package/src/js/plugins/grideditor.tabs.js

@@ -428,6 +428,12 @@ GridEditor.containers.tabs = function(ge) {
             ge.unwrapLabels(container);
         },
 
+        // The same, on a copy of the canvas: unmark only touches markup
+        cleanMarkup: function(root) {
+            var definition = this;
+            dom.all(root, '[data-ge-container="tabs"]').forEach(function(container) { definition.unmark(container); });
+        },
+
         panelSection: function(node, kind) {
             if (kind !== 'tabs' || !stripOf(node)) { return null; }