@themarioga/grid-editor 4.0.0 → 4.1.0

package/docs/plugins.md

@@ -14,11 +14,13 @@ the one to read first if you are about to write your own.
 <script src="dist/plugins/grideditor.elements.min.js"></script>
 ```
 
-There are two kinds. A **container plugin** builds a type of container — it
+There are three kinds. A **container plugin** builds a type of container — it
 registers under `$.fn.gridEditor.containers`, and the toolbar offers a button
-for it. A **feature plugin** is anything else the editor can do —
+for it. A **utility plugin** declares families of Bootstrap's responsive
+utility classes — `$.fn.gridEditor.utilities` — and the editor edits them per
+breakpoint. A **feature plugin** is anything else the editor can do —
 `$.fn.gridEditor.features`, hooks into the canvas, and may contribute methods.
-Both are factories called once per editor with the same handle.
+All three are factories called once per editor with the same handle.
 
 The `plugins` setting names which of the loaded ones to use:
 
@@ -114,6 +116,13 @@ not change without a major version.
 | `ge.emit(name, payload)` | Fire an event and its callbacks; false means a handler canceled |
 | `ge.payloadFor(kind, node, extra)` | Build a payload the documented way |
 | `ge.operate(body)` | Run `body` as one operation, so a handler calling back in is queued |
+| `ge.kindOf(node)` | What an event calls a node: `row`, `column`, `element`, a container's type… |
+| `ge.view()` | The view being edited: a breakpoint key, or `'all'` |
+| `ge.viewTiers()` | The breakpoint keys that view writes: one, or all six |
+| `ge.breakpoints` | Every breakpoint key, smallest first |
+| `ge.getUtility(node, family, view?)` | A utility's value, as in the public method |
+| `ge.setUtility(node, family, value, options?)` | Write one through the events. `options` is a view key or `{ view, source }` |
+| `ge.utilityField(node, family)` | A panel field for one family, for a plugin that builds its own panel |
 
 The add, delete and move events for a container and its panes are fired by the
 editor, not by the plugin: `createPaneControls` handles a pane's delete, and
@@ -177,3 +186,99 @@ the plugin.
 Sorting is the one thing a plugin sets up itself, in `mark`, because only the
 plugin knows which of its parts move: the tabs plugin makes its strip sortable
 and puts the panes back in strip order in `afterPaneMove`.
+
+
+Utility plugins
+---------------
+
+A utility plugin edits one of Bootstrap's responsive utility classes — the
+ones spelled `{property}-{breakpoint}-{value}`, like `order-md-2` or
+`d-lg-none` — and hardly has to do anything to do it. It declares **families**,
+and the editor reads, writes, previews and announces them:
+
+```javascript
+$.fn.gridEditor.utilities.order = function(ge) {
+    return {
+        families: [{
+            name: 'order',                 // what events and setUtility call it
+            prefix: 'order',               // order-2, order-md-2, order-xxl-2
+            values: ['first', 0, 1, 2, 3, 4, 5, 'last'],
+            appliesTo: ['column'],         // row | column | element | container | a container type
+            labelKey: 'utility.order',     // the field's label, optional
+            label: function(value) { … },  // an option's text, optional: the value itself otherwise
+            choices: function(node, kind) { … },   // what to offer this node, optional: every value otherwise
+            panel: false,                          // optional: no field of its own, see "A panel of your own"
+            preview: function(value, node, kind) { // what the value looks like, see below
+                return { order: value === null ? 0 : value };
+            },
+        }],
+        drawerTools: function(drawer, node, kind) { … },  // optional, tools beside the gear
+        onRefresh: function(scope) { … },                 // optional, see below
+        panel: function(node, kind) { … },                // optional, see "A panel of your own"
+        preview: function(node, kind, breakpoint) { … },  // optional, the same
+        onViewChange: function(view) { … },               // optional
+    };
+};
+```
+
+What the editor does with a family:
+
+- **Reading follows the cascade.** A breakpoint's value is its own class or the
+  nearest smaller breakpoint's. The all view reads the class with no infix.
+- **Writing depends on the view.** A breakpoint view writes its own tier and
+  nothing else. The all view writes the class with no infix and takes the
+  family off every other breakpoint, because choosing one value for every size
+  is choosing it over what the sizes said; the event says what it took off.
+  `null` is inherit: the tier's class comes off.
+- **The panel.** Every node with a gear gets a folded *Responsive* section in
+  its settings panel, with a field per family that applies to it. A field shows
+  the view being edited, says what it inherits and from which breakpoint, and
+  follows the classes field when the user types there.
+- **The preview.** A breakpoint view narrows the canvas, not the window, and
+  Bootstrap's utilities answer to the window with `!important`. So in a
+  breakpoint view each node that carries a family's class gets
+  `preview(value)` — the value that applies there, or `null` — as inline
+  `!important` styles. Return what `null` looks like too: a wider breakpoint's
+  class is still live in a wide window and has to be overruled. The all view
+  previews nothing, since every breakpoint there is live and what Bootstrap
+  shows is the truth. The styles come off on `deinit`, leaving the host's own
+  `style` as it was, so `getHtml` never sees them.
+- **The events.** Every write goes through `before-utility`, which can cancel
+  it, and `after-utility`. See [events.md](events.md).
+
+`drawerTools` runs for every drawer that has a gear — rows, columns, elements,
+containers and panes — so a plugin checks `kind` and adds nothing where its
+tool does not belong. A tool writes with `ge.setUtility(node, family, value,
+{ source: 'tool' })`, and the panel, the classes field and the preview follow.
+
+`onRefresh(scope)` runs whenever the preview is redrawn — on `init`, on a view
+change, after a write, after the user types in a classes field — with the node
+whose utilities changed, or the canvas. It is for what a plugin marks the canvas
+with beyond inline styles: the visibility plugin keeps hidden nodes on the
+canvas and fades them there. Whatever it adds, `onDeinit` takes away.
+
+### A panel of your own
+
+A field per family is the right panel for most plugins and the wrong one for
+some: spacing has fourteen families, and fourteen fields. Such a plugin marks
+its families `panel: false` and returns its own element from
+`panel(node, kind)` — or null where it does not apply — and the editor puts it
+in the Responsive section. Inside it, `ge.utilityField(node, family)` makes the
+same field the editor would, and the editor keeps every such field up to date
+with the view and the classes; swapping one field for another is the plugin's
+business. The spacing plugin's panel is a side and one field, and choosing a
+side swaps the field for that side's family.
+
+The same plugins tend to need the node as a whole for the preview, because
+their families settle one property between them — `p-3` and `pt-md-1` both
+set the top padding. A plugin-level `preview(node, kind, breakpoint)` is called
+for every node in a breakpoint view, after the families' own, and returns the
+styles for the node or an empty object.
+
+Two plugins cannot declare the same family name: the second one is ignored,
+with a warning.
+
+Plugin options live in the `utilities` setting, under the plugin's name:
+`utilities: { spacing: { values: ['0', '2', '4'] } }`. The editor passes the
+setting through as it is; each plugin fills in its own defaults.
+

package/example/autosave.html

@@ -20,6 +20,11 @@
     <script src="../dist/jquery.grideditor.min.js"></script>
 </head>
 <body>
+    <!-- Back to the demo index -->
+    <div class="container pt-3">
+        <a class="link-secondary" href="index.html"><i class="bi bi-arrow-left"></i> All demos</a>
+    </div>
+
 <div class="container py-3">
     <h2>Grid Editor example - auto save and import/export</h2>
     <div class="mb-3">

package/example/basic.html

@@ -37,6 +37,11 @@
     <title>Grid Editor example</title>
 </head>
 <body>
+    <!-- Back to the demo index -->
+    <div class="container pt-3">
+        <a class="link-secondary" href="index.html"><i class="bi bi-arrow-left"></i> All demos</a>
+    </div>
+
 
     <div class="container">
         <div id="myGrid">

package/example/breakpoints.html

@@ -41,6 +41,11 @@
     <title>Grid Editor breakpoints example</title>
 </head>
 <body>
+    <!-- Back to the demo index -->
+    <div class="container pt-3">
+        <a class="link-secondary" href="index.html"><i class="bi bi-arrow-left"></i> All demos</a>
+    </div>
+
 
     <div class="container">
 

package/example/ckeditor.html

@@ -47,6 +47,11 @@
     <title>Grid Editor example</title>
 </head>
 <body>
+    <!-- Back to the demo index -->
+    <div class="container pt-3">
+        <a class="link-secondary" href="index.html"><i class="bi bi-arrow-left"></i> All demos</a>
+    </div>
+
 
     <div class="container">
         <div id="myGrid">

package/example/containers.html

@@ -70,6 +70,10 @@
     <title>Grid Editor containers example</title>
 </head>
 <body>
+    <!-- Back to the demo index -->
+    <div class="container pt-3">
+        <a class="link-secondary" href="index.html"><i class="bi bi-arrow-left"></i> All demos</a>
+    </div>
 
     <div class="container">
 

package/example/elements.html

@@ -89,6 +89,11 @@
     <title>Grid Editor elements example</title>
 </head>
 <body>
+    <!-- Back to the demo index -->
+    <div class="container pt-3">
+        <a class="link-secondary" href="index.html"><i class="bi bi-arrow-left"></i> All demos</a>
+    </div>
+
 
     <div class="container">
 

package/example/index.html

@@ -21,6 +21,21 @@
             <code>npm run build</code> after changing anything under
             <code>src/</code>.
         </p>
+        <p class="text-body-secondary">
+            Since 4.0 every gesture works with a finger as well as with a
+            mouse &mdash; sorting, resizing a column, dragging a button off the
+            toolbar &mdash; so these are worth opening on a phone. The editor
+            needs jQuery, <a href="https://sortablejs.github.io/Sortable/">SortableJS</a>
+            and Bootstrap 5; the first demo loads
+            <code>jquery.grideditor.bundle.min.js</code> instead, which is the
+            editor and SortableJS in one file.
+        </p>
+        <p class="text-body-secondary">
+            New in 4.1: utility plugins, which edit Bootstrap's responsive
+            utility classes &mdash; visibility, column order, alignment,
+            gutters and spacing &mdash; per breakpoint. See
+            <a href="utilities.html">Responsive utilities</a>.
+        </p>
 
         <div class="list-group my-4">
 
@@ -29,7 +44,7 @@
                     <strong>The editor</strong>
                     <code class="text-body-secondary">basic.html</code>
                 </div>
-                <span class="text-body-secondary">tinyMCE in the content areas, and the drawer as the drag handle</span>
+                <span class="text-body-secondary">tinyMCE in the content areas, the drawer as the drag handle, and the bundled build</span>
             </a>
 
             <a class="list-group-item list-group-item-action" href="plugins.html">
@@ -64,6 +79,14 @@
                 <span class="text-body-secondary">The six breakpoints, the &ldquo;all sizes&rdquo; view, and resizing by dragging</span>
             </a>
 
+            <a class="list-group-item list-group-item-action" href="utilities.html">
+                <div class="d-flex justify-content-between">
+                    <strong>Responsive utilities</strong>
+                    <code class="text-body-secondary">utilities.html</code>
+                </div>
+                <span class="text-body-secondary">Bootstrap's utility classes edited per breakpoint: visibility, column order, alignment, gutters and spacing</span>
+            </a>
+
             <a class="list-group-item list-group-item-action" href="locale.html">
                 <div class="d-flex justify-content-between">
                     <strong>Languages</strong>

package/example/locale.html

@@ -41,6 +41,11 @@
     <title>Grid Editor locale example</title>
 </head>
 <body>
+    <!-- Back to the demo index -->
+    <div class="container pt-3">
+        <a class="link-secondary" href="index.html"><i class="bi bi-arrow-left"></i> All demos</a>
+    </div>
+
 
     <div class="container">
 

package/example/plugins.html

@@ -111,6 +111,11 @@
     <title>Grid Editor plugins example</title>
 </head>
 <body>
+    <!-- Back to the demo index -->
+    <div class="container pt-3">
+        <a class="link-secondary" href="index.html"><i class="bi bi-arrow-left"></i> All demos</a>
+    </div>
+
 
     <div class="container">
 

package/example/summernote.html

@@ -49,6 +49,11 @@
     <title>Grid Editor example</title>
 </head>
 <body>
+    <!-- Back to the demo index -->
+    <div class="container pt-3">
+        <a class="link-secondary" href="index.html"><i class="bi bi-arrow-left"></i> All demos</a>
+    </div>
+
 
     <div class="container">
         <div id="myGrid">

package/example/utilities.html

@@ -0,0 +1,145 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+
+    <!-- CSS dependencies -->
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-sRIl4kxILFvY47J16cr9ZwB07vP4J8+LH7qKQnuqkuIAvNWLzeN8tE5YBujZqJLB" crossorigin="anonymous">
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.13.1/font/bootstrap-icons.css">
+
+    <!-- Javascript dependencies -->
+    <script src="https://code.jquery.com/jquery-4.0.0.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/js/bootstrap.bundle.min.js" integrity="sha384-FKyoEForCGlyvwx9Hj09JcYn3nv7wiPVlz7YYwJrWVcXK/BmnVDxM+D2scQbITxI" crossorigin="anonymous"></script>
+
+    <!-- Grid editor CSS -->
+    <link rel="stylesheet" type="text/css" href="../dist/grideditor.css" />
+
+    <!-- The editor, and the utility plugins. Each is a file of its own, and
+         loading it is what puts its field in the settings panels. -->
+    <script src="https://cdn.jsdelivr.net/npm/sortablejs@1.15.6/Sortable.min.js"></script>
+    <script src="../dist/jquery.grideditor.min.js"></script>
+    <script src="../dist/plugins/grideditor.visibility.min.js"></script>
+    <script src="../dist/plugins/grideditor.order.min.js"></script>
+    <script src="../dist/plugins/grideditor.alignment.min.js"></script>
+    <script src="../dist/plugins/grideditor.gutters.min.js"></script>
+    <script src="../dist/plugins/grideditor.spacing.min.js"></script>
+
+    <script>
+        $(function() {
+            $('#myGrid').gridEditor({
+                new_row_layouts: [[12], [6,6], [4,4,4], [8,4]],
+                content_types: [],
+
+                // Utilities are edited per breakpoint, so this page starts in
+                // one. Switch to "All sizes" to see the page as it will render.
+                default_view: 'xs',
+            });
+
+            // Every change to a utility is announced, like any other operation
+            $('#myGrid').on('grideditor:after-utility', function(e, payload) {
+                $('#last').text(payload.family + ' at ' + payload.breakpoint + ': ' +
+                    (payload.from === null ? 'default' : payload.from) + ' → ' +
+                    (payload.to === null ? 'inherit' : payload.to));
+            });
+
+            $('#output').on('click', function() {
+                $('#html').text($('#myGrid').gridEditor('getHtml'));
+            });
+        });
+    </script>
+
+    <title>Grid Editor utilities example</title>
+</head>
+<body>
+    <!-- Back to the demo index -->
+    <div class="container pt-3">
+        <a class="link-secondary" href="index.html"><i class="bi bi-arrow-left"></i> All demos</a>
+    </div>
+
+
+    <div class="container">
+
+        <div class="row my-3">
+            <div class="col-lg-8">
+                <h1 class="h4">Responsive utilities</h1>
+                <p class="form-text">
+                    Bootstrap's responsive utility classes, edited per
+                    breakpoint. Pick a breakpoint in the dropdown and every
+                    change is written for that breakpoint alone; in
+                    <strong>All sizes</strong> it is written once, for every
+                    size. Each drawer's gear has a <strong>Responsive</strong>
+                    section with a field per utility, which says what the
+                    breakpoint inherits and from where.
+                </p>
+                <p class="form-text">
+                    <strong>Visibility:</strong> the eye in a drawer hides the
+                    node in the view being edited. It stays on the canvas,
+                    faded, so you can show it again; in All sizes a badge says
+                    at which breakpoints it is hidden. The sidebar below is
+                    hidden on phones and tablets.
+                </p>
+                <p class="form-text">
+                    <strong>Order:</strong> the arrows in a column's drawer
+                    move it earlier or later in the view being edited,
+                    without moving the markup. In the second row, "Second"
+                    comes first on phones only.
+                </p>
+                <p class="form-text">
+                    <strong>Alignment:</strong> fields in the panel of a row
+                    (justify and align its columns) and of a column (align
+                    itself). The third row centres its narrow column from
+                    small desktop up.
+                </p>
+                <p class="form-text">
+                    <strong>Gutters:</strong> fields in a row's panel. A row
+                    with gutter classes is drawn with its real gutters; the
+                    second row has none on phones and wide ones from small
+                    desktop up.
+                </p>
+                <p class="form-text">
+                    <strong>Spacing:</strong> a padding and a margin group in
+                    every panel, each a side and a value. The centred column
+                    below gets more padding from small desktop up.
+                </p>
+                <p class="form-text">Last change: <span id="last">none yet</span></p>
+                <button class="btn btn-sm btn-secondary" id="output" type="button">Show the html this produces</button>
+                <pre id="html" class="form-text"></pre>
+            </div>
+        </div>
+
+        <div id="myGrid">
+
+            <div class="row">
+                <div class="col-12 col-md-8">
+                    <h2 class="h5">Main content</h2>
+                    <p>Full width on phones and tablets, two thirds from small desktop up.</p>
+                </div>
+                <div class="col-12 col-md-4 d-none d-md-block">
+                    <h2 class="h5">Sidebar</h2>
+                    <p>Only from small desktop up: <code>d-none d-md-block</code>.</p>
+                </div>
+            </div>
+
+            <div class="row g-0 g-md-5">
+                <div class="col-6">
+                    <h2 class="h5">First</h2>
+                    <p>Change the views and the utilities of these two.</p>
+                </div>
+                <div class="col-6 order-first order-sm-0">
+                    <h2 class="h5">Second</h2>
+                    <p>First on phones, with <code>order-first order-sm-0</code>.</p>
+                </div>
+            </div>
+
+            <div class="row justify-content-md-center">
+                <div class="col-12 col-md-6 py-2 py-md-4">
+                    <h2 class="h5">Centred</h2>
+                    <p>Its row has <code>justify-content-md-center</code>, and it has <code>py-2 py-md-4</code>.</p>
+                </div>
+            </div>
+
+        </div> <!-- /#myGrid -->
+    </div> <!-- /.container -->
+
+</body>
+</html>

package/example/wrap_content.html

@@ -35,6 +35,11 @@
     <title>Grid Editor example</title>
 </head>
 <body>
+    <!-- Back to the demo index -->
+    <div class="container pt-3">
+        <a class="link-secondary" href="index.html"><i class="bi bi-arrow-left"></i> All demos</a>
+    </div>
+
     <div id="myGrid">
         <h1>Hello!</h1>
         <p>Test</p>

package/package.json

@@ -34,7 +34,7 @@
     "comment": "A scoped package publishes restricted unless it is told otherwise.",
     "access": "public"
   },
-  "version": "4.0.0",
+  "version": "4.1.0",
   "main": "dist/jquery.grideditor.js",
   "files": [
     "dist",