@themarioga/grid-editor 6.0.0 → 7.1.0

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

@@ -13,23 +13,31 @@
  * back, and making the host's plain content a text through the core's
  * `textTypes` hook.
  *
- * Each editor registers under $.fn.gridEditor.texts, which is this file's own
+ * Each editor registers under GridEditor.texts, which is this file's own
  * registry and not a contract: an editor of a host's own is a feature plugin
  * of its own, as example/custom_editor.html shows.
  */
-(function($) {
+import { GridEditor } from '../grideditor.js';
+import * as dom from '../dom.js';
 
-    if ($.fn.gridEditor.features.text) { return; }
+// However many editors a page loads, each with a copy of this file in its
+// classic script: the first one installs it
+if (!GridEditor.features.text) {
 
-    $.extend($.fn.gridEditor.locales.en, {
+    Object.assign(GridEditor.locales.en, {
         'text.add': 'Text',
         'text.add_type': 'Text ({editor})',
         'panel.editor': 'Editor',
         'panel.kind_text': 'Text',
     });
 
-    /** The text editors, by the content type each edits. */
-    $.fn.gridEditor.texts = $.fn.gridEditor.texts || {};
+    /**
+     * What a content area's attributes were before its editor opened, and
+     * once it had: the two readings closeText plays the host's changes
+     * back from. Shared by every editor on the page, like the nodes.
+     */
+    var readBefore = new WeakMap();
+    var readReady = new WeakMap();
 
     /** What a text editor puts on a content area while it is open, whenever it likes. */
     var EDITOR_CLASS = /^(mce-|cke|note-)|^(active|ge-rte-active)$/;
@@ -37,7 +45,7 @@
 
     function attributesOf(element) {
         var found = {};
-        $.each($.makeArray(element.attributes), function(i, attribute) {
+        Array.prototype.slice.call(element.attributes).forEach(function(attribute) {
             found[attribute.name] = attribute.value;
         });
         return found;
@@ -51,9 +59,9 @@
 
     /** The host's markup, with what changed from `ready` to `open` played back onto it. */
     function restoreAttributes(block, before, ready, open) {
-        var result = $.extend({}, before);
+        var result = Object.assign({}, before);
 
-        $.each($.extend({}, ready, open), function(name) {
+        Object.keys(Object.assign({}, ready, open)).forEach(function(name) {
             if (name === 'class' || EDITOR_ATTRIBUTE.test(name) || ready[name] === open[name]) { return; }
 
             if (open[name] === undefined) {
@@ -76,8 +84,8 @@
         // shuffle a node's attributes because it was edited
         if (classes.length) { result['class'] = classes.join(' '); } else { delete result['class']; }
 
-        $.each(attributesOf(block[0]), function(name) { block.removeAttr(name); });
-        $.each(result, function(name, value) { block.attr(name, value); });
+        Object.keys(attributesOf(block)).forEach(function(name) { block.removeAttribute(name); });
+        Object.keys(result).forEach(function(name) { block.setAttribute(name, result[name]); });
     }
 
     function textFeature(ge) {
@@ -86,8 +94,8 @@
         var TEXTS = {};
         var warned = {};
 
-        $.each($.fn.gridEditor.texts, function(type, factory) {
-            TEXTS[type] = factory(ge);
+        Object.keys(GridEditor.texts).forEach(function(type) {
+            TEXTS[type] = GridEditor.texts[type](ge);
         });
 
         // Every editor loaded, in the order the page loaded them, unless the
@@ -110,11 +118,17 @@
         /** A detached content area of `type`, holding `content` or the editor's initial content. */
         function makeText(type, content) {
             var text = TEXTS[type];
+            var block = dom.element('div', {
+                'class': 'ge-content ge-content-type-' + type,
+                'data-ge-content-type': type,
+            });
 
-            return $('<div class="ge-content" />')
-                .addClass('ge-content-type-' + type)
-                .attr('data-ge-content-type', type)
-                .html(content !== undefined ? content : (text && text.initialContent) || '');
+            if (content && content.nodeType) {
+                block.appendChild(content);
+            } else {
+                dom.setHtml(block, content !== undefined ? content : (text && text.initialContent) || '');
+            }
+            return block;
         }
 
         /**
@@ -144,21 +158,20 @@
 
         /** Whether a content area is a text of one of the editors loaded here. */
         function isOurs(block) {
-            return !!TEXTS[block.attr('data-ge-content-type')];
+            return !!TEXTS[block.getAttribute('data-ge-content-type')];
         }
 
         /** Open the editor on a text, once: until it is closed again. */
         function startText(block) {
-            if (block.hasClass('ge-rte-active')) { return; }
+            if (dom.hasClass(block, 'ge-rte-active')) { return; }
 
             // A content area nobody can see - a tab that is not the open one,
             // a closed accordion item - has no geometry for an editor to lay
             // its toolbar out against, and nothing anyone can type into
-            if (!block.is(':visible')) { return; }
+            if (!dom.visible(block)) { return; }
 
-            // The attribute, not jQuery's cached copy of it: it is markup, and
-            // the drawer reads it the same way
-            var text = TEXTS[block.attr('data-ge-content-type')];
+            // The attribute: it is markup, and the drawer reads it the same way
+            var text = TEXTS[block.getAttribute('data-ge-content-type')];
             if (!text) { return; }
 
             // Not marked active, so the next click tries again: the library
@@ -168,13 +181,14 @@
                 return;
             }
 
-            block.data('ge-text-before', attributesOf(block[0])).removeData('ge-text-ready');
-            block.addClass('ge-rte-active');
-            text.start(block);
+            readBefore.set(block, attributesOf(block));
+            readReady.delete(block);
+            dom.addClass(block, 'ge-rte-active');
+            text.start([block]);
         }
 
         function onClick() {
-            startText($(this));
+            startText(this);
         }
 
         /**
@@ -192,28 +206,30 @@
          * is left out either way.
          */
         function closeText(block) {
-            var text = TEXTS[block.attr('data-ge-content-type')];
-            var before = block.data('ge-text-before');
-            var open = before ? attributesOf(block[0]) : null;
+            var text = TEXTS[block.getAttribute('data-ge-content-type')];
+            var before = readBefore.get(block);
+            var open = before ? attributesOf(block) : null;
 
             // Every content area is told, as in 5.x: one whose editor never
             // started is the plugin's to ignore
-            if (text) { text.stop(block); }
+            if (text) { text.stop([block]); }
 
             // After stop, not before: an editor that restores the class
             // attribute it snapshotted would put ge-rte-active back
-            block.removeClass('ge-rte-active');
+            dom.removeClass(block, 'ge-rte-active');
 
             if (before) {
-                restoreAttributes(block, before, block.data('ge-text-ready') || before, open);
-                block.removeData('ge-text-before').removeData('ge-text-ready');
+                restoreAttributes(block, before, readReady.get(block) || before, open);
+                readBefore.delete(block);
+                readReady.delete(block);
             }
         }
 
         function createTextControls(textBlock) {
-            var block = textBlock.children('.ge-content');
-            var type = block.attr('data-ge-content-type');
-            var drawer = $('<div class="ge-tools-drawer ge-text-drawer" />').prependTo(textBlock);
+            var block = dom.child(textBlock, '.ge-content');
+            var type = block.getAttribute('data-ge-content-type');
+            var drawer = dom.element('div', { 'class': 'ge-tools-drawer ge-text-drawer' });
+            textBlock.insertBefore(drawer, textBlock.firstChild);
 
             ge.createMoveTool(drawer);
 
@@ -221,10 +237,11 @@
 
             // Which editor edits it, first in its settings: something to
             // know about it, not something to do with it
-            $('<div class="ge-field ge-text-editor" />')
-                .append($('<span class="ge-field-label" />').text(ge.t('panel.editor')))
-                .append($('<span class="ge-field-value" />').text(textLabel(type)))
-                .prependTo(details.children('.ge-details-general'));
+            var general = dom.child(details, '.ge-details-general');
+            var editor = dom.element('div', { 'class': 'ge-field ge-text-editor' });
+            editor.appendChild(dom.element('span', { 'class': 'ge-field-label' }, ge.t('panel.editor')));
+            editor.appendChild(dom.element('span', { 'class': 'ge-field-value' }, textLabel(type)));
+            general.insertBefore(editor, general.firstChild);
 
             settings.text_tools.forEach(function(hostTool) {
                 ge.createTool(drawer, hostTool.title || '', hostTool.className || '',
@@ -236,7 +253,7 @@
                     // Its editor lets go first: removed while open, it would
                     // be left behind, attached to nothing
                     closeText(block);
-                    textBlock.slideUp(function() {
+                    dom.slideUp(textBlock, function() {
                         textBlock.remove();
                         removed();
                     });
@@ -246,16 +263,18 @@
 
         /** A drawer for each text of ours in a text block that has none yet. */
         function markTexts() {
-            ge.canvas.find('.ge-text-block').each(function() {
-                var textBlock = $(this);
-                if (textBlock.children('.ge-tools-drawer').length) { return; }
-                if (!isOurs(textBlock.children('.ge-content'))) { return; }
+            dom.all(ge.canvas, '.ge-text-block').forEach(function(textBlock) {
+                if (dom.child(textBlock, '.ge-tools-drawer')) { return; }
+
+                var block = dom.child(textBlock, '.ge-content');
+                if (!block || !isOurs(block)) { return; }
 
                 createTextControls(textBlock);
             });
         }
 
         var texts = offeredTexts();
+        var clicks = null; // The delegated click listener, while editing
 
         return {
             methods: {
@@ -281,8 +300,8 @@
                         available: text.available ? function() { return text.available(); } : null,
                         missingKey: text.missingKey,
                         edit: function(block) {
-                            var textBlock = block.parent('.ge-text-block');
-                            if (textBlock.length && !textBlock.children('.ge-tools-drawer').length) {
+                            var textBlock = block.parentElement;
+                            if (dom.hasClass(textBlock, 'ge-text-block') && !dom.child(textBlock, '.ge-tools-drawer')) {
                                 createTextControls(textBlock);
                             }
 
@@ -310,26 +329,28 @@
             onInit: function() {
                 markTexts();
 
-                ge.canvas.off('click.ge-text').on('click.ge-text', '.ge-content', onClick);
+                if (clicks) { ge.canvas.removeEventListener('click', clicks); }
+                clicks = dom.delegate(ge.canvas, 'click', '.ge-content', onClick);
             },
 
             // While the drawers and the text blocks are still there, as the
             // editors left them
             onBeforeDeinit: function() {
-                ge.canvas.find('.ge-content').each(function() {
-                    if (isOurs($(this))) { closeText($(this)); }
+                dom.all(ge.canvas, '.ge-content').forEach(function(block) {
+                    if (isOurs(block)) { closeText(block); }
                 });
             },
 
             onDeinit: function() {
-                ge.canvas.off('click.ge-text');
+                if (clicks) { ge.canvas.removeEventListener('click', clicks); }
+                clicks = null;
             },
 
             // The first time only: an undo says ready again, and by then the
             // host may have changed the content area itself
             onContentReady: function(area) {
-                if (area.data('ge-text-before') && !area.data('ge-text-ready')) {
-                    area.data('ge-text-ready', attributesOf(area[0]));
+                if (readBefore.has(area) && !readReady.has(area)) {
+                    readReady.set(area, attributesOf(area));
                 }
             },
         };
@@ -338,6 +359,6 @@
     // Whatever the plugins setting says: content_types chooses the editors
     textFeature.always = true;
 
-    $.fn.gridEditor.features.text = textFeature;
+    GridEditor.features.text = textFeature;
 
-})(jQuery);
+}

package/types/grideditor.d.ts

@@ -0,0 +1,335 @@
+/**
+ * Types for grid-editor's public API: the GridEditor class, its methods, its
+ * settings, and its events and their payloads.
+ *
+ * The plugin contract - the handle a plugin's factory gets - is not typed
+ * here; docs/plugins.md describes it. A plugin's factory is typed loosely as
+ * a function of that handle.
+ */
+
+/** A breakpoint key. */
+export type Breakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
+
+/** A view: a breakpoint, or every one at once. */
+export type View = Breakpoint | 'all';
+
+/** A column's size: units, Bootstrap's `col` (`'equal'`) or `col-auto` (`'auto'`). */
+export type ColumnSize = number | 'equal' | 'auto';
+
+/** A row's columns-per-row layout: row-cols per breakpoint, and how many columns. */
+export interface RowColsLayout {
+    row_cols: Partial<Record<Breakpoint, number | 'auto'>>;
+    columns?: number;
+}
+
+/** What a row is made of: sizes, or a columns-per-row layout. */
+export type RowLayout = ColumnSize[] | RowColsLayout;
+
+/** An element, or a selector for the first element it matches. */
+export type Target = Element | string;
+
+/** Where a created node goes. The first one given wins; none leaves it detached. */
+export interface Placement {
+    appendTo?: Target;
+    prependTo?: Target;
+    insertAfter?: Target;
+    insertBefore?: Target;
+}
+
+/** A host tool in a drawer: row_tools, col_tools and the rest. */
+export interface HostTool {
+    title?: string;
+    className?: string;
+    iconClass?: string;
+    /** A click handler, or handlers by event name. `this` is the tool. */
+    on?: ((this: HTMLElement, event: Event) => void) | Record<string, (this: HTMLElement, event: Event) => void>;
+}
+
+/** A preset class toggle on a settings panel. */
+export interface PresetClass {
+    label: string;
+    cssClass: string;
+    title?: string;
+}
+
+/** A content filter: run on init and deinit with the canvas. A string names a function on window. */
+export type CustomFilter = ((canvas: HTMLElement, isInit: boolean) => void) | string;
+
+/** The settings. Every one is optional. */
+export interface GridEditorOptions {
+    new_row_layouts?: RowLayout[];
+    row_classes?: PresetClass[];
+    col_classes?: PresetClass[];
+    element_classes?: PresetClass[];
+    container_classes?: PresetClass[];
+    pane_classes?: PresetClass[];
+    text_classes?: PresetClass[];
+    row_tools?: HostTool[];
+    col_tools?: HostTool[];
+    element_tools?: HostTool[];
+    container_tools?: HostTool[];
+    tab_tools?: HostTool[];
+    accordion_tools?: HostTool[];
+    text_tools?: HostTool[];
+    drag_handle?: 'tool' | 'drawer';
+    toolbar_drag?: 'auto' | boolean;
+    /** The plugins to use, of any kind; null is every one loaded. */
+    plugins?: string[] | null;
+    /** The text editors offered, in order. */
+    content_types?: string[];
+    row_cols?: boolean;
+    utilities?: Record<string, unknown>;
+    elements?: { enabled?: boolean | 'auto'; selector?: string; auto?: boolean };
+    custom_filter?: CustomFilter | CustomFilter[] | '';
+    valid_col_sizes?: ColumnSize[];
+    valid_col_offsets?: number[];
+    add_column?: { size?: ColumnSize | null; picker?: boolean; delay?: number };
+    layout_modes?: View[];
+    default_view?: View;
+    resize?: { enabled?: boolean; handles?: string; balance?: 'next' | false };
+    /** A textarea whose html the canvas starts with. */
+    source_textarea?: Target | '';
+    edit_source?: boolean;
+    locale?: string;
+    locale_strings?: Record<string, string>;
+    callbacks?: Partial<GridEditorCallbacks>;
+    confirm_delete?: boolean;
+    settings_panel?: 'offcanvas' | 'popover' | 'modal' | 'inline';
+    drag?: { delay?: number; touch_delay?: number; threshold?: number; animation?: number; scroll?: boolean };
+    tinymce?: { config?: Record<string, unknown> };
+    ckeditor?: { config?: Record<string, unknown> };
+    summernote?: { config?: Record<string, unknown> };
+    [plugin: string]: unknown;
+}
+
+/** Where a node was, or went: its parent and its index among the blocks there. */
+export interface Position {
+    parent: HTMLElement;
+    index: number;
+}
+
+/** What a breakpoint said before the all view's write took it off. */
+export interface Cleared {
+    breakpoint: Breakpoint;
+    value: string | number;
+}
+
+/** What every notification carries. */
+export interface Payload {
+    /** What the node is: row, column, text, plain, element, tab, accordion-item, a container's type… */
+    kind: string;
+    node: HTMLElement;
+    /** Where the node is going, or coming from on a delete; null while it is detached. */
+    parent: HTMLElement | null;
+    canvas: HTMLElement;
+    breakpoint: View;
+    source: 'api' | 'tool' | 'dragdrop' | 'paste' | 'panel' | string;
+    /** A pane inside a container. */
+    container?: HTMLElement;
+}
+
+export interface MovePayload extends Payload {
+    from: Position;
+    to?: Position;
+}
+
+export interface ResizePayload extends Payload {
+    from: ColumnSize | null;
+    to: ColumnSize | null;
+    cleared?: Cleared[];
+}
+
+export interface IndentPayload extends Payload {
+    from: number;
+    to: number;
+    cleared?: Cleared[];
+}
+
+export interface UtilityPayload extends Payload {
+    family: string;
+    from: string | null;
+    to: string | null;
+    tiers: Breakpoint[];
+    cleared: Cleared[];
+}
+
+export interface ConvertPayload extends Payload {
+    from: 'plain';
+    to: string;
+}
+
+export interface EditHtmlPayload extends Omit<Payload, 'node'> {
+    node: HTMLElement | null;
+    /** Every element written, which may be several. */
+    nodes?: HTMLElement[];
+    from: string;
+    to: string;
+}
+
+export interface PopupOrphanPayload extends Payload {
+    missing: string;
+}
+
+export interface ViewChangePayload {
+    canvas: HTMLElement;
+    breakpoint: View;
+    from: View;
+    to: View;
+}
+
+/** The events, by name, with their payloads. Adding fires a specific name and the generic one. */
+export interface GridEditorEventMap {
+    'grideditor:before-add': Payload;
+    'grideditor:after-add': Payload;
+    'grideditor:before-add-row': Payload;
+    'grideditor:after-add-row': Payload;
+    'grideditor:before-add-column': Payload;
+    'grideditor:after-add-column': Payload;
+    'grideditor:before-add-text': Payload;
+    'grideditor:after-add-text': Payload;
+    'grideditor:before-add-element': Payload;
+    'grideditor:after-add-element': Payload;
+    'grideditor:before-add-container': Payload;
+    'grideditor:after-add-container': Payload;
+    'grideditor:before-add-tab': Payload;
+    'grideditor:after-add-tab': Payload;
+    'grideditor:before-add-accordion-item': Payload;
+    'grideditor:after-add-accordion-item': Payload;
+    'grideditor:before-add-section': Payload;
+    'grideditor:after-add-section': Payload;
+    'grideditor:before-delete': Payload;
+    'grideditor:after-delete': Payload;
+    'grideditor:before-move': MovePayload;
+    'grideditor:after-move': MovePayload;
+    'grideditor:before-resize': ResizePayload;
+    'grideditor:after-resize': ResizePayload;
+    'grideditor:before-indent': IndentPayload;
+    'grideditor:after-indent': IndentPayload;
+    'grideditor:before-utility': UtilityPayload;
+    'grideditor:after-utility': UtilityPayload;
+    'grideditor:before-convert': ConvertPayload;
+    'grideditor:after-convert': ConvertPayload;
+    'grideditor:before-edit-html': EditHtmlPayload;
+    'grideditor:after-edit-html': EditHtmlPayload;
+    'grideditor:after-copy': Payload;
+    'grideditor:popup-orphan': PopupOrphanPayload;
+    'grideditor:view-change': ViewChangePayload;
+}
+
+/** An event the editor dispatches on its canvas: a CustomEvent whose detail is the payload. */
+export type GridEditorEvent<K extends keyof GridEditorEventMap> = CustomEvent<GridEditorEventMap[K]>;
+
+/** 'grideditor:before-add-row' is the callback before_add_row. */
+type CallbackName<K> = K extends `grideditor:${infer Name}` ? Snake<Name> : never;
+type Snake<S extends string> = S extends `${infer Head}-${infer Tail}` ? `${Head}_${Snake<Tail>}` : S;
+
+/** The callbacks setting: the events by another route. Returning false cancels a before-*. */
+export type GridEditorCallbacks = {
+    [K in keyof GridEditorEventMap as CallbackName<K>]: (payload: GridEditorEventMap[K]) => boolean | void;
+};
+
+/** A plugin's factory: called once per editor with the handle in docs/plugins.md. */
+export type PluginFactory = ((ge: any) => Record<string, unknown>) & { always?: boolean };
+
+export interface CreateColumnOptions extends Placement {
+    offset?: number;
+    /** Html, or a node: a text of the first editor offered, or plain content with none. */
+    content?: string | Node;
+}
+
+export interface CreateTextOptions extends Placement {
+    content?: string | Node;
+}
+
+export interface CreateElementOptions extends Placement {
+    type?: string;
+    label?: string;
+}
+
+export interface CreateSectionOptions extends Placement {
+    width?: 'fixed' | 'fluid' | Breakpoint;
+    rows?: RowLayout[];
+}
+
+export interface PaneOptions {
+    label?: string;
+    [option: string]: unknown;
+}
+
+/** An editor on a canvas element. */
+export declare class GridEditor {
+    /**
+     * An editor on `target`. An element carries one at most: asked for a
+     * second, this gives back the first, with its options, and warns once.
+     * Throws a TypeError when `target` is neither an element nor a selector
+     * that matches one.
+     */
+    constructor(target: Target, options?: GridEditorOptions);
+
+    /** The same as `new GridEditor(target, options)`. */
+    static create(target: Target, options?: GridEditorOptions): GridEditor;
+    /** The editor on `target`, or null. */
+    static get(target: Target | null | undefined): GridEditor | null;
+
+    static containers: Record<string, PluginFactory>;
+    static features: Record<string, PluginFactory>;
+    static utilities: Record<string, PluginFactory>;
+    static texts: Record<string, PluginFactory>;
+    static locales: Record<string, Record<string, string>>;
+    /** A string from the locale `settings.locale` names, English when it has none. */
+    static t(settings: { locale?: string; locale_strings?: Record<string, string> }, key: string, params?: Record<string, string | number>): string;
+    /** SortableJS, for a page that imports it rather than loading it as window.Sortable. */
+    static Sortable: unknown;
+    /** Bootstrap's javascript (only its Modal is used), for a page with no window.bootstrap. */
+    static bootstrap: { Modal?: unknown } | null;
+    static version: string;
+
+    /** The canvas element. */
+    readonly canvas: HTMLElement;
+    /** A read-only copy of the settings the editor runs with. */
+    readonly settings: Readonly<GridEditorOptions>;
+
+    /** The html to save: no drawers, no editor classes, no inline styles. */
+    getHtml(): string;
+    /** getHtml without grid-editor's marking, for publishing. It cannot be edited again as it was. */
+    getPlainHtml(): string;
+    /** Run the editing pass over the canvas again, after markup was put in. */
+    init(): this;
+    /** Take the editing furniture off, leaving the markup. */
+    deinit(): this;
+    /** deinit(), then init(). */
+    reset(): this;
+    /** Take the editor off: the markup stays, everything else goes. */
+    destroy(): this;
+    changeView(view: View): this;
+    getView(): View;
+    setLocale(code: string): this;
+    createRow(layout?: RowLayout, options?: Placement): HTMLElement | null;
+    createColumn(size?: ColumnSize | null, options?: CreateColumnOptions): HTMLElement | null;
+    createText(type?: string, options?: CreateTextOptions): HTMLElement | null;
+    createText(options: CreateTextOptions): HTMLElement | null;
+    createElement(content: string | Node | ArrayLike<Node>, options?: CreateElementOptions): HTMLElement | null;
+    createSection(options?: CreateSectionOptions): HTMLElement | null;
+    createContainer(type: string, options?: Placement & Record<string, unknown>): HTMLElement | null;
+    addTab(container: Target, options?: PaneOptions): HTMLElement | null;
+    addAccordionItem(container: Target, options?: PaneOptions): HTMLElement | null;
+    /** A utility's value on a node in a view (the current one by default), or null. */
+    getUtility(node: Target, family: string, view?: View): string | null;
+    /** Write one through the events; null is inherit. False when canceled or nothing changed. */
+    setUtility(node: Target, family: string, value: string | number | null, view?: View): boolean;
+}
+
+export default GridEditor;
+
+declare global {
+    interface Window {
+        GridEditor: typeof GridEditor;
+    }
+
+    interface HTMLElementEventMap extends GridEditorEventMap_ {}
+}
+
+/** The events on any element, so canvas.addEventListener('grideditor:...') is typed. */
+type GridEditorEventMap_ = {
+    [K in keyof GridEditorEventMap]: CustomEvent<GridEditorEventMap[K]>;
+};