@themarioga/grid-editor 4.0.0 → 5.0.0

package/CHANGELOG.md

@@ -5,6 +5,101 @@ 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).
 
 
+## [5.0.0] - 2026-09-23
+### Changed
+- **The all view writes one class.** A size or an offset set in the all view
+  is written as the class with no breakpoint (`col-4`, `offset-2`), and the
+  breakpoints' own sizes or offsets are taken off, as the utilities have done
+  since 4.1. Up to 4.x it wrote all six breakpoints. The resize and indent
+  payloads carry `cleared`, with what was taken off.
+- Resize payloads' `from` and `to` can be `'equal'` or `'auto'`, `from` is
+  `null` for a column its row sizes, and `source` can be `panel`.
+- `valid_col_sizes` defaults to `[1, … 12, 'equal', 'auto']`.
+- `ge.viewTiers()` returns the one breakpoint a view writes: `xs` in the all
+  view.
+
+See [UPGRADING.md](UPGRADING.md) for what these mean for a host.
+
+### Added
+- Equal and auto column sizes: Bootstrap's `col` and `col-auto`, at every
+  breakpoint. The editor recognises them, previews them in each view, offers
+  them in the add column picker and in `new_row_layouts`, `createRow` and
+  `createColumn`, and the width tools turn them into a number starting from
+  the width the column has. A column with only `col` used to be no column at
+  all, and a `col-auto` one was given a `col-12` that overrode it.
+- A *Width* field in each column's Responsive section, with every size.
+- Columns per row: a *Columns per row* field in each row's panel writes
+  `row-cols-{bp}-{1–6,auto}`. Columns with no size of their own share the
+  line out and are left without a `col-12`; the preview, the budget and the
+  tools settle row-cols against each column's own size as Bootstrap's css
+  does, and the row says in a corner how many it puts per line. Layouts,
+  `createRow` and `createColumn` take rows with row-cols, and `row_cols: false`
+  takes the field away.
+- The `sections` plugin: Bootstrap's `.container`, `.container-fluid` and
+  `.container-{bp}` as sections on the canvas, grouping rows. Each gets a
+  drawer with a width field, the toolbar a *Section* button, and the API
+  `createSection`. Rows drag in and out of sections, sections drag along the
+  canvas, and a breakpoint view gives each the max-width its container has
+  there.
+- Feature plugins can add blocks, regions and toolbar buttons (`blocks`,
+  `regions`, `accepts`, `toolbar`), and the handle gains `rowFromLayout`.
+- The `textalign` utility plugin: `text-{bp}-start`, `-center` and `-end` on
+  rows, columns, elements and containers. With no class applying in a view, the
+  preview shows what the node inherits from its parent or the host's css.
+- The `float` utility plugin: `float-{bp}-start`, `-end` and `-none` on
+  elements, with the text of the content area flowing round them.
+- `ge.bareStyle(node, family, property)` on the plugin handle: a property's
+  value with the family's classes out of the way, for previews whose "no
+  class" is not a constant.
+- `example/autocols.html`.
+
+### Fixed
+- The toolbar's layout icons nested each column inside the one before, since
+  jQuery 4 stopped expanding `<div/>`: the icon of `[6, 6]` drew one block.
+- A column's drawer no longer counts towards an auto column's width.
+
+## [4.1.0] - 2026-09-22
+### Added
+- Utility plugins, a third kind beside containers and features:
+  `$.fn.gridEditor.utilities`. A plugin declares families of Bootstrap's
+  responsive utility classes and the editor reads them through the cascade,
+  writes them per breakpoint (the all view writes the class with no infix and
+  clears the rest), shows them in a folded *Responsive* section of the settings
+  panel, and previews them in each breakpoint view. See docs/plugins.md.
+- `getUtility` and `setUtility` methods, and the `utilities` setting for the
+  plugins' options.
+- `before-utility`, `after-utility` and `view-change` events. `view-change` is
+  new for every host, not only for utility plugins.
+- The plugin handle gains `kindOf`, `view`, `viewTiers`, `breakpoints`,
+  `getUtility` and `setUtility`, and a utility plugin may add tools beside any
+  drawer's gear and mark the canvas in `onRefresh`.
+- The `visibility` utility plugin: hide a row, column, element or container at
+  some breakpoints with `d-{bp}-none` and show it at others. An eye in each
+  drawer toggles the view being edited with as few classes as that takes. A
+  hidden node stays on the canvas, faded, and in the all view a badge says at
+  which breakpoints it is hidden.
+- The `order` utility plugin: a column's place in its row per breakpoint,
+  with `order-{bp}-*`. Two arrows in each column drawer move it one place
+  earlier or later in the view being edited without moving the markup, and
+  take the classes off again once the row is back in the markup's order. A
+  column ordered by class says so in a corner of the canvas.
+- The `alignment` utility plugin: `justify-content-{bp}-*` and
+  `align-items-{bp}-*` on rows, `align-self-{bp}-*` on columns, as fields in
+  the settings panel.
+- The `gutters` utility plugin: `g-{bp}-*`, `gx-{bp}-*` and `gy-{bp}-*` on
+  rows. A row with gutter classes is drawn with its real gutters instead of the
+  editor's frame, the preview settles `g` against `gx`/`gy` the way Bootstrap's
+  css does, and choosing `g` takes that breakpoint's `gx` and `gy` off.
+  `utilities.gutters.scale` follows a page that changed `$spacers`.
+- The `spacing` utility plugin: padding and margin on rows, columns, elements
+  and containers, `{p,m}{,x,y,t,b,s,e}-{bp}-*`. The panel has a padding and a
+  margin group, each a side and a value, and the preview settles the fourteen
+  families the way Bootstrap's css does. `utilities.spacing.values` and
+  `.scale` narrow the steps and follow a changed `$spacers`.
+- A utility plugin can build its own panel (`panel`, `ge.utilityField`,
+  families with `panel: false`) and preview a node as a whole (`preview`).
+- `example/utilities.html`.
+
 ## [4.0.0] - 2026-09-22
 ### Added
 - Editing from a touchscreen. Sorting, resizing a column and carrying a toolbar

package/README.md

@@ -1,7 +1,7 @@
 Grid Editor
 ===========
 
-Grid Editor is a visual javascript editor for the [bootstrap 5 grid system](https://getbootstrap.com/docs/5.3/layout/grid/), written as a [jQuery](http://jquery.com/) plugin. You can create, drag, resize and delete rows and columns, indent them, and give each of bootstrap's six breakpoints its own layout — or edit them all at once, with a mouse or with a finger. It also edits tabs, accordions, popups and cards, and any markup you mark as an element, and it tells your application about every change it makes.
+Grid Editor is a visual javascript editor for the [bootstrap 5 grid system](https://getbootstrap.com/docs/5.3/layout/grid/), written as a [jQuery](http://jquery.com/) plugin. You can create, drag, resize and delete rows and columns — sized in units, equal (`col`) or to their content (`col-auto`), or shared out by their row (`row-cols-*`) — indent them, group them in sections (`.container`), and give each of bootstrap's six breakpoints its own layout — or edit them all at once, with a mouse or with a finger. Bootstrap's responsive utilities — visibility, order, alignment, gutters, spacing, text alignment and float — are edited per breakpoint too. It also edits tabs, accordions, popups and cards, and any markup you mark as an element, and it tells your application about every change it makes.
 
 This is a fork of [Friendly-Pixel/grid-editor](https://github.com/Friendly-Pixel/grid-editor)
 by Simon Epskamp, carrying it on from 2.x. It is published as
@@ -30,6 +30,8 @@ from any web server, or from GitHub Pages, with no build step.
 | [example/plugins.html](example/plugins.html) | The plugin model, with one written in the page itself | [live](https://themarioga.github.io/grid-editor/example/plugins.html) |
 | [example/containers.html](example/containers.html) | Tabs, accordions, popups and cards, two levels deep | [live](https://themarioga.github.io/grid-editor/example/containers.html) |
 | [example/elements.html](example/elements.html) | Element level controls, including an element with no visual output | [live](https://themarioga.github.io/grid-editor/example/elements.html) |
+| [example/autocols.html](example/autocols.html) | Equal and auto columns, columns per row, and sections | [live](https://themarioga.github.io/grid-editor/example/autocols.html) |
+| [example/utilities.html](example/utilities.html) | Bootstrap's responsive utilities, edited per breakpoint | [live](https://themarioga.github.io/grid-editor/example/utilities.html) |
 | [example/locale.html](example/locale.html) | The interface in Spanish, with a language switcher | [live](https://themarioga.github.io/grid-editor/example/locale.html) |
 | [example/ckeditor.html](example/ckeditor.html) | CKEditor instead of tinyMCE | [live](https://themarioga.github.io/grid-editor/example/ckeditor.html) |
 | [example/summernote.html](example/summernote.html) | Summernote instead of tinyMCE | [live](https://themarioga.github.io/grid-editor/example/summernote.html) |
@@ -91,15 +93,18 @@ $('#myGrid').gridEditor('method', argument);
 | `reset` | — | `this` | `deinit()` then `init()` |
 | `destroy` | — | `this` | Deinit, drop the controls, unbind, forget the instance |
 | `remove` | — | `this` | Deprecated alias of `destroy` |
-| `changeView` | `breakpoint` | `this` | `'xs'`…`'xxl'`, or `'all'` to edit every breakpoint at once |
+| `changeView` | `breakpoint` | `this` | `'xs'`…`'xxl'`, or `'all'` to edit every breakpoint at once, with one class |
 | `getView` | — | `String` | The view the editor is in |
 | `setLocale` | `code` | `this` | Switch language and re-render the controls |
-| `createRow` | `layout?`, `options?` | `jQuery` | A row, optionally with columns: `createRow([8, 4])` |
-| `createColumn` | `size`, `options?` | `jQuery` | A column. `options`: `offset`, `content` |
+| `createRow` | `layout?`, `options?` | `jQuery` | A row, optionally with columns: `createRow([8, 4])`, `createRow(['auto', 'equal'])`, `createRow({ row_cols: { xs: 1, md: 3 }, columns: 6 })` |
+| `createColumn` | `size`, `options?` | `jQuery` | A column: units, `'equal'` or `'auto'`; no size into a row with row-cols takes the row's share. `options`: `offset`, `content` |
+| `createSection` | `options?` | `jQuery` | A section, with the sections plugin. `options`: `width` (`'fixed'`, `'fluid'` or a breakpoint), `rows` (layouts), and a placement |
 | `createElement` | `content`, `options?` | `jQuery` | Host markup wrapped as an element. `options`: `type`, `label` |
 | `createContainer` | `type`, `options?` | `jQuery` | `'tabs'`, `'accordion'` or `'popup'` |
 | `addTab` | `container`, `options?` | `jQuery` | Appends a tab, returns its pane |
 | `addAccordionItem` | `container`, `options?` | `jQuery` | Appends an item, returns its body |
+| `getUtility` | `node`, `family`, `view?` | `String` | A utility plugin's value on a node in a view (the current one by default), or `null` |
+| `setUtility` | `node`, `family`, `value`, `view?` | `Boolean` | Write it through the events; `null` is inherit. `false` if canceled or nothing changed |
 
 A method called on an element with no editor on it is a no-op that returns the
 set, so host code does not have to check first. `getHtml` is the exception: it
@@ -181,14 +186,44 @@ Options
 
 ### General options
 
-__`new_row_layouts`:__ Set the column layouts that appear in the "new row" buttons at the top of the editor.
+__`new_row_layouts`:__ Set the column layouts that appear in the "new row" buttons at the top of the editor. A size is a number of units, `'equal'` (Bootstrap's `col`, sharing what the row has left) or `'auto'` (`col-auto`, as wide as its content).
 
 ```javascript
 $('#myGrid').gridEditor({
-    new_row_layouts: [[12], [6,6], [9,3]],
+    new_row_layouts: [[12], [6,6], [9,3], ['auto', 'equal'], { row_cols: { xs: 1, md: 3 }, columns: 6 }],
 });
 ```
 
+A layout can also be a row with columns per row: `{ row_cols: { xs: 1, md: 3 }, columns: 6 }` makes a `row-cols-1 row-cols-md-3` row of six columns with no size of their own.
+
+### Column sizes
+
+A column's size at each breakpoint is a number of units, equal or auto:
+
+| Size | Class | On the page |
+| --- | --- | --- |
+| `1`–`12` | `col-4`, `col-md-4` | That many twelfths of the row |
+| `'equal'` | `col`, `col-md` | An equal share of what the row has left |
+| `'auto'` | `col-auto`, `col-md-auto` | As wide as its content |
+
+The width tools and dragging a column's edge work in units, so they turn an
+equal or auto column into a number, starting from the width it has on the
+canvas. Every size is in the *Width* field of a column's settings panel, in its
+Responsive section, and a change made there is a resize like any other.
+
+**Columns per row.** A row's *Columns per row* field writes Bootstrap's
+`row-cols-{bp}-{1–6,auto}`, which gives each column with no size of its own an
+equal share of a line. A column added to such a row takes its share, and the
+width tools take a column out of the share with a size of its own. Which one
+sizes a column at a breakpoint is settled as in Bootstrap's css: the class from
+the wider breakpoint wins, and at one breakpoint `col` loses to `row-cols`,
+which loses to `col-auto` and `col-N`. `row_cols: false` takes the field away.
+
+In a breakpoint view a size or an offset is written for that breakpoint. In the
+all view it is written once, as the class with no breakpoint (`col-4`,
+`offset-2`), and the breakpoints' own sizes or offsets are taken off: one value
+for every size. Up to 4.x the all view wrote all six breakpoints instead.
+
 The settings button on a row, a column, a container, a tab, an accordion item
 or an element opens a panel with two fields: the node's `id`, and its css
 classes. The classes field shows what your markup put
@@ -269,7 +304,7 @@ $('#myGrid').gridEditor({
 });
 ```
 
-__`valid_col_sizes`:__ Specify the column widths that can be selected using the +/- buttons
+__`valid_col_sizes`:__ The column sizes the +/- buttons step through, and that the add column picker and the width field offer. Default `[1, 2, … 12, 'equal', 'auto']`; leave `'equal'` and `'auto'` out and they are not offered, though a column that has one still shows it.
 
 ```javascript
 $('#myGrid').gridEditor({
@@ -328,7 +363,7 @@ $('#myGrid').gridEditor({
 });
 ```
 
-__`default_view`:__ The view the editor starts in. Default `'all'`, which writes every breakpoint at once — what a layout that needs no per-device tuning wants.
+__`default_view`:__ The view the editor starts in. Default `'all'`, which writes one class for every breakpoint at once — what a layout that needs no per-device tuning wants.
 
 __`resize`:__ Resizing a column by dragging its edge. Defaults:
 
@@ -378,6 +413,83 @@ __`element_tools`:__ Extra tools on every element drawer, same shape as `row_too
 See [example/elements.html](example/elements.html), which also shows the
 pattern for an element with no visual output of its own.
 
+### Responsive utilities
+
+Bootstrap's responsive utility classes, edited per breakpoint. Each family is
+a plugin in a file of its own:
+
+```html
+<script src="grid-editor/dist/plugins/grideditor.visibility.min.js"></script>
+<script src="grid-editor/dist/plugins/grideditor.order.min.js"></script>
+<script src="grid-editor/dist/plugins/grideditor.alignment.min.js"></script>
+<script src="grid-editor/dist/plugins/grideditor.gutters.min.js"></script>
+<script src="grid-editor/dist/plugins/grideditor.spacing.min.js"></script>
+<script src="grid-editor/dist/plugins/grideditor.textalign.min.js"></script>
+<script src="grid-editor/dist/plugins/grideditor.float.min.js"></script>   <!-- after grideditor.elements -->
+```
+
+| Plugin | Classes | On |
+| --- | --- | --- |
+| `visibility` | `d-{bp}-none`, `d-{bp}-block`, `d-{bp}-flex` | rows, columns, elements, containers |
+| `order` | `order-{bp}-{first,0–5,last}` | columns |
+| `alignment` | `justify-content-{bp}-*`, `align-items-{bp}-*`; `align-self-{bp}-*` | rows; columns |
+| `gutters` | `g-{bp}-{0–5}`, `gx-{bp}-*`, `gy-{bp}-*` | rows |
+| `spacing` | `{p,m}{,x,y,t,b,s,e}-{bp}-{0–5}`, and `auto` for margin | rows, columns, elements, containers |
+| `textalign` | `text-{bp}-start`, `-center`, `-end` | rows, columns, elements, containers |
+| `float` | `float-{bp}-start`, `-end`, `-none` | elements |
+
+A plugin puts a field in the *Responsive* section of each drawer's settings
+panel, and some add a tool to the drawer. In a breakpoint view a change is
+written for that breakpoint alone, and the field says what it inherits and from
+where. In the all view it is written once, as the class with no breakpoint, and
+replaces what the breakpoints said. While you edit, the canvas shows what the
+classes mean in the view you are in; `getHtml` returns only the classes.
+
+```javascript
+$('#myGrid').gridEditor('setUtility', column, 'visibility', 'none', 'md');   // d-md-none
+$('#myGrid').gridEditor('getUtility', column, 'visibility', 'lg');           // 'none', inherited
+```
+
+__`utilities`:__ Options for each plugin, under its name.
+
+```javascript
+$('#myGrid').gridEditor({
+    utilities: {
+        visibility: { drawer: false },   // no eye in the drawers, the field only
+        order: { drawer: false },        // no arrows in the column drawers
+        gutters: { scale: ['0', '.25rem', '.5rem', '1rem', '1.5rem', '3rem'] },  // if you changed $spacers
+        spacing: { values: ['0', '2', '4'], scale: [/* the same */] },          // offer fewer steps
+    },
+});
+```
+
+See [example/utilities.html](example/utilities.html), and
+[docs/plugins.md](docs/plugins.md#utility-plugins) for writing one.
+
+### Sections
+
+Bootstrap's `.container`, `.container-fluid` and `.container-{bp}` on the
+canvas, each grouping rows at a width of its own. A plugin, since many pages
+put the whole canvas in a `.container` already:
+
+```html
+<script src="grid-editor/dist/plugins/grideditor.sections.min.js"></script>
+```
+
+A container that is a child of the canvas is a section, and gets a drawer:
+move, settings - with a *Width* field for the seven kinds of container - add
+row and delete. The toolbar gets a *Section* button. Rows drag in and out of
+sections, and sections drag along the canvas but not into a column. In a
+breakpoint view each section is as wide as its container would be at that
+breakpoint. They are called sections, not containers, because a container is
+what the tabs, accordion, popup and card plugins make.
+
+```javascript
+$('#myGrid').gridEditor('createSection', { width: 'md', rows: [[6, 6]], appendTo: '#myGrid' });
+```
+
+__`sections`:__ `{ widths: ['fixed', 'sm', 'md', 'lg', 'xl', 'xxl', 'fluid'] }`, the widths the field offers.
+
 ### Containers
 
 Tabs, accordions, popups and cards. A tabs, accordion or popup container holds
@@ -399,7 +511,7 @@ it available:
 The toolbar offers a button per loaded plugin. See [docs/plugins.md](docs/plugins.md)
 for the contract, and for writing one of your own.
 
-__`plugins`:__ Which of the loaded plugins to use, containers and features alike. Every one by default; name them to use fewer than the page loaded.
+__`plugins`:__ Which of the loaded plugins to use, containers, features and utilities alike. Every one by default; name them to use fewer than the page loaded.
 
 ```javascript
 $('#myGrid').gridEditor({ plugins: ['tabs', 'elements'] });

package/UPGRADING.md

@@ -1,3 +1,58 @@
+Upgrading from grid-editor `4.*` to `5.*`
+=========================================
+
+One change makes it a major: **the all view writes one class.** Everything
+else in 5.0 is new, and a page that uses none of it edits as it did.
+
+* __A size or an offset set in the all view is the class with no breakpoint.__
+  Up to 4.x the all view wrote all six breakpoints; 5.0 writes the base class
+  and takes the breakpoints' own sizes or offsets off, as the utilities have
+  done since 4.1. The markup means the same on the page and is shorter:
+
+  ```html
+  <!-- 4.x, after "narrower" on a col-lg-6 column in the all view -->
+  <div class="col-5 col-sm-5 col-md-5 col-lg-5 col-xl-5 col-xxl-5">
+
+  <!-- 5.0, the same click -->
+  <div class="col-5">
+  ```
+
+  Reading has not changed: markup with the six classes written out is read as
+  before, and the first change made in the all view simplifies it. What to do:
+  nothing, unless you compare or post-process the html the editor saves and
+  expect six classes. A breakpoint view still writes its own breakpoint alone.
+
+* __Resize and indent payloads carry `cleared` in the all view__, with what the
+  write took off each breakpoint: `[{ breakpoint: 'lg', value: 6 }]`. A
+  listener that checks the payload's keys exactly will see one more.
+
+* __A resize's `from` and `to` can be `'equal'` or `'auto'`__ - Bootstrap's
+  `col` and `col-auto` - and `from` is `null` for a column its row sizes with
+  `row-cols`. `source` can be `panel`, for a width chosen in a column's
+  settings panel. A listener that does arithmetic on them should check
+  `typeof size === 'number'` first. These only happen on columns that use the
+  new sizes.
+
+* __`valid_col_sizes` has two more values by default__, `'equal'` and `'auto'`,
+  which the add column picker and the width field offer. A host that sets its
+  own list keeps it; one that wants the 4.x picker sets
+  `valid_col_sizes: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]`.
+
+* __Every column's settings panel has a Width field, and every row's a Columns
+  per row field__, in the Responsive section, which is folded until the user
+  opens it. `row_cols: false` takes the row field away.
+
+* __Columns with `col`, `col-auto`, or in a row with `row-cols-*` are no longer
+  given a `col-12`.__ In 4.x a column with only `col` was not a column at all,
+  and one with `col-auto` got a `col-12` that overrode it; both now edit as
+  Bootstrap renders them. A page that relied on the `col-12` gets the layout
+  its classes describe instead.
+
+New and opt-in, so nothing to do: the `sections` plugin for Bootstrap's
+containers, and the feature hooks it is built on (`blocks`, `regions`,
+`accepts`, `toolbar`). See the [CHANGELOG](CHANGELOG.md) for the full list.
+
+
 Upgrading from grid-editor `3.*` to `4.*`
 =========================================