@themarioga/grid-editor 8.4.0 → 8.5.0

package/package.json

@@ -33,7 +33,7 @@
     "comment": "A scoped package publishes restricted unless it is told otherwise.",
     "access": "public"
   },
-  "version": "8.4.0",
+  "version": "8.5.0",
   "main": "dist/grideditor.js",
   "module": "dist/grideditor.esm.js",
   "types": "dist/grideditor.d.ts",

package/src/js/grideditor.js

@@ -142,6 +142,7 @@ var NESTED_SETTINGS = {
         enabled: 'auto', // 'auto' turns them on when the page has any
         selector: '[data-ge-element]', // What the host marks an element with
         auto: false, // Treat every child of a content area as an element
+        types: [], // The elements the toolbar offers: { type, html, label | labelKey, iconClass, group }
     },
     resize: {
         enabled: true, // The handle on the column's edge
@@ -1239,6 +1240,7 @@ function build(instance, baseElem, optionsOrMethod) {
         var CORE_GROUPS = [
             { name: 'rows', labelKey: 'group.rows' },
             { name: 'content', labelKey: 'group.content' },
+            { name: 'elements', labelKey: 'group.elements' },
         ];
 
         /** A plugin's category, when it names one. */
@@ -1452,6 +1454,8 @@ function build(instance, baseElem, optionsOrMethod) {
                 if (activeTarget) { addToTarget(button, item.source || 'tool'); return; }
 
                 var made = item.create();
+                // A plugin that could not make one says so with null
+                if (!made) { return; }
 
                 // One that belongs in a column brings a row and a column
                 // of its own, the way a container does
@@ -1611,6 +1615,7 @@ function build(instance, baseElem, optionsOrMethod) {
         function insertFeatureFromToolbar(button, where, source) {
             var item = FEATURES[button.getAttribute('data-ge-feature')].toolbar[parseInt(button.getAttribute('data-ge-item'), 10)];
             var made = item.create();
+            if (!made) { return null; }
             var placed = made;
 
             if (item.inColumn) {
@@ -5770,6 +5775,7 @@ GridEditor.locales = {
         'tool.more': 'More',
         'group.rows': 'Rows',
         'group.content': 'Content',
+        'group.elements': 'Elements',
         'group.select': 'Add',
         'panel.title': '{kind} settings',
         'panel.close': 'Close',

package/src/js/locales/grideditor.es.js

@@ -54,6 +54,7 @@ GridEditor.locales.es = {
     'tool.more': 'Más',
     'group.rows': 'Filas',
     'group.content': 'Contenido',
+    'group.elements': 'Elementos',
     'group.select': 'Añadir',
     'panel.title': 'Ajustes: {kind}',
     'panel.close': 'Cerrar',

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. */
@@ -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;

package/src/js/text/grideditor.text.js

@@ -321,7 +321,7 @@ if (!GridEditor.features.text) {
                     iconClass: TEXTS[type].iconClass,
                     className: 'ge-add-text-button',
                     kind: 'text',
-                    group: 'content',
+                    group: 'elements',
                     inColumn: true,
                     create: function() { return makeText(type); },
                 };

package/types/grideditor.d.ts

@@ -125,7 +125,7 @@ export interface GridEditorOptions {
     inline_style?: InlineStyleOptions;
     /** The tabs plugin: the variant of the tabs containers made new. */
     tabs?: TabsOptions;
-    elements?: { enabled?: boolean | 'auto'; selector?: string; auto?: boolean };
+    elements?: { enabled?: boolean | 'auto'; selector?: string; auto?: boolean; types?: ElementType[] };
     custom_filter?: CustomFilter | CustomFilter[] | '';
     valid_col_sizes?: ColumnSize[];
     valid_col_offsets?: number[];
@@ -286,6 +286,22 @@ export type GridEditorCallbacks = {
 };
 
 /** A plugin's factory: called once per editor with the handle in docs/plugins.md. */
+/** An element the toolbar offers, from elements.types. */
+export interface ElementType {
+    /** What it is: its data-ge-element. */
+    type: string;
+    /** Its markup: html, or a function called for each one made that returns html or a node. */
+    html: string | (() => string | Node);
+    /** Its button's label, as it is. */
+    label?: string;
+    /** Its button's label, a locale key: wins over label, and follows setLocale. */
+    labelKey?: string;
+    /** The button shows this icon alone, with the label as its title. */
+    iconClass?: string;
+    /** Its toolbar_groups category. Default 'elements'. */
+    group?: string;
+}
+
 export type PluginFactory = ((ge: any) => Record<string, unknown>) & { always?: boolean };
 
 export interface CreateColumnOptions extends Placement {