@aduptive/strapi-blockscene 2.0.0-alpha.6 → 2.0.0-alpha.8

package/README.md

@@ -1,8 +1,8 @@
 # Blockscene for Strapi
 
 A visual gallery for the components already allowed in a native Dynamic Zone,
-with configurable thumbnails, SVG wireframes, editor preferences and, on
-Strapi 5, a whole-page preview that edits the form through your own frontend.
+with configurable thumbnails, SVG wireframes, editor preferences and a
+whole-page preview that edits the form through your own frontend.
 No renderer, framework or content migration is required.
 
 **Alpha.** Published as pre-releases; APIs, settings and the preview bridge may
@@ -45,9 +45,43 @@ module.exports = {
 ```
 
 Rebuild/restart the admin. Open a content type with a Dynamic Zone. The
-editor panel provides one gallery button per editable, non-full zone. Zones
-that already have blocks get "Open all blocks" / "Close all blocks" icon
-buttons right beside the native zone label ("blocks (3)").
+native "Add a component to <zone>" button of each editable, non-full zone opens
+the gallery instead of Strapi's category picker; a full zone keeps its native
+button.
+
+### Zone bar
+
+Right beside the native zone label ("blocks (3)") each zone gets a short bar:
+
+- **Expand all / Collapse all**: one button with text. It reads the rows' own
+  state: "Expand all" while any block of the zone is collapsed, "Collapse all"
+  when every block is open (a header opened or closed by hand counts too), and
+  exposes it as `aria-expanded`. Blocks open or close a few at a time around the
+  viewport first (long pages stay responsive). Rows of a folded layout group
+  are left alone (see [Groups in the form](#groups-in-the-form)). Options `showOpenAll` /
+  `showCloseAll`: with both on (the default) the button toggles; with only one
+  on it offers that action alone, disabled while there is nothing to do; with
+  both off there is no button.
+- **Undo and Redo** (Strapi 5, first zone only): icon and text, the shortcut in
+  the tooltip. See [Undo and redo](#undo-and-redo).
+- **Editing mode** (first zone only, when a preview route exists): a
+  menu with Fields, Fields + page and Visual editor. Without a preview route the
+  menu is not shown; Settings, Blockscene says why.
+- **"…" (More actions)**: Select blocks, and "Paste N blocks" while the
+  clipboard holds blocks this zone allows (see [Row actions](#row-actions)).
+  No entries, no menu.
+
+"Select blocks" swaps the bar for a selection bar: a select-all box with the
+count ("2 selected"; indeterminate while only some are selected, a click then
+selects none), Copy (disabled until a block is selected) and Done; Esc leaves
+too. Each row gets a checkbox at the start of its header.
+
+An empty zone has no label row: its bar (Paste, and on the first zone Undo,
+Redo and the mode) sits right after its native add button.
+
+The plugin adds no side panel of its own for any of this. The Blockscene side
+panel appears only for what has no place in the form: version history (when
+enabled) and layout group problems. With neither, there is no panel.
 
 ## Gallery
 
@@ -70,8 +104,9 @@ The modal is a block browser (80vw wide):
   under `prefers-reduced-motion: reduce`. The panel shows a large live preview
   with Fit / Mobile / Tablet / Desktop widths (scaled to fit, as in the page
   preview) and a compact strip: label, uid, description, badges, fields (on
-  demand), star and Insert. Double click, "+" or Enter on a focused card
-  inserts without it.
+  demand), the variant choice (see [Insert variants](#insert-variants)), star
+  and Insert. Double click, "+" or Enter on a focused card inserts without it
+  (the first variant, when the block has variants).
 
 The magnified preview shows the card's thumbnail at once and fades the live
 page in over it once it has loaded. Live source, first match wins:
@@ -79,14 +114,16 @@ page in over it once it has loaded. Live source, first match wins:
 1. **Block preview URL** (`editor.blockPreviewUrl`, Settings, both versions):
    a plain page per block in a plain iframe, no bridge. Placeholders, URL
    encoded: `{uid}`, `{name}` (after the dot), `{category}` (before the dot),
-   `{variant}` (`default`) and `{locale}` (the entry's locale, empty when the
-   type is not localized). Example:
+   `{variant}` (the chosen [insert variant](#insert-variants)'s id, else
+   `default`) and `{locale}` (the entry's locale, empty when the type is not
+   localized). Example:
    `http://localhost:3026/{locale}/block-preview/{name}/{variant}`. Such a
    fixtures route is usually dev-only: leave the option empty on production.
-2. **Page preview route** (Strapi 5: the preview route base URL, else the
+2. **Page preview route** (the preview route base URL, else on Strapi 5 the
    native Preview origin + `/block-preview/page`): the same bridge as the
-   whole-page preview, sent one block made from the schema defaults, mode
-   `preview`. Read-only: every message except `ready` is ignored.
+   whole-page preview, sent one block made from the chosen variant over the
+   schema defaults, mode `preview`. Read-only: every message except `ready`
+   is ignored.
 3. Otherwise the image only.
 
 If the live page neither loads nor says `ready` within 8 s, the image stays
@@ -123,6 +160,59 @@ label ending with the raw zone name, which Strapi's message carries in every
 locale; a zone whose name ends another zone's name (`blocks` and `sub blocks`)
 is the documented limit.
 
+### Insert variants
+
+A block can offer named presets of its field values, so the editor inserts
+"Hero, dark" instead of the bare schema defaults. Variants come from the
+project's code, never from the Settings page: the plugin config
+`components[uid].variants`, a list of `{ id, label, values }`.
+
+```js
+// config/plugins.js
+components: {
+  'blocks.hero': {
+    variants: [
+      { id: 'default', label: 'Default', values: {} },
+      { id: 'dark', label: { en: 'Dark', 'pt-BR': 'Escuro' }, values: {
+        title: 'Big launch', theme: 'dark',
+        link: { text: 'Read more', url: '/news' },
+        items: [{ label: 'One' }, { label: 'Two' }],
+      } },
+      // A frontend fixture works as is: ids, __component, media and relations are dropped.
+      { id: 'cases', label: 'Cases', values: require('../fixtures/hero/cases.json').data },
+    ],
+  },
+},
+```
+
+- **Choosing**: with two or more variants the magnified block shows them as a
+  row of buttons; the live preview follows the choice (`{variant}` in the
+  block preview URL, or the variant's block sent through the bridge) and
+  Insert inserts it. Double click, "+" and Enter insert the first variant.
+  The picker opened from a page preview insertion seam offers the same
+  choice. A block without variants behaves as before; Settings, Blockscene
+  lists each block's variants read-only.
+- **Merge**: `values` is a partial field map over the schema defaults. A
+  nested component merges over its own defaults; a repeatable list replaces
+  the default list, each item over the item's defaults. The row goes through
+  the same form path as any gallery insert (Strapi 5 `addFieldRow`, Strapi 4
+  `addComponentToDynamicZone` then the fields' `onChange`), so nothing is
+  saved until Save and undo/redo covers it.
+- **Supported values**, checked against the schema once at boot: text-like
+  fields (strings, rich text, email, uid, dates as strings), numbers
+  (integers, big integers, floats, decimals), booleans, enumerations (one of
+  their values), JSON, blocks (an array) and `null`; nested components,
+  single or repeatable (up to the attribute's `max`, and 100), each validated
+  against its own schema. Media and relation values are dropped with a boot
+  warning: their ids belong to one install and are not checked here. `id` and
+  `__component` keys are ignored, so a content-API shaped block works.
+  Unknown attributes, passwords and Dynamic Zones reject the variant.
+- **Bounds**: `id` is 1 to 40 of `a-z 0-9 - _`, unique per block (it is the
+  `{variant}` URL segment); `label` a string of 1 to 60 characters or
+  `{ "<locale>": string }`; at most 12 variants per block, 16 KB of values
+  per variant and 256 KB for all of them. An invalid variant is left out with
+  a warning naming the problem; the block keeps its valid ones.
+
 ## Row thumbnails
 
 Each added block shows its thumbnail at the left of the native accordion
@@ -152,14 +242,14 @@ Each block header gets a few icons right before Strapi's own delete button
   nested components, new row key, media kept, relations kept (Strapi 5 reads
   the source row's relations from the server and adds its unsaved changes).
   A group OPEN duplicates with its whole range. Option `duplicate`.
-- **Copy / Paste** across pages. The copy icon copies one block; the select
-  icon in the zone label shows a checkbox per row, then "Copy selected". The
+- **Copy / Paste** across pages. The copy icon copies one block; "Select
+  blocks" in the zone bar's "…" menu shows a checkbox per row, then Copy. The
   blocks are stored in this browser's localStorage (`blockscene:clipboard:v1`,
-  with the source content type and locale). "Paste" appears in the zone label
-  (under the gallery button for an empty zone) and in the page preview seams.
-  Paste is all or nothing: every block must be allowed in the target zone, fit
-  its maximum, and groups must be whole; otherwise a notice explains why and the
-  form is not changed. Media and relations are kept by id/documentId, so paste
+  with the source content type and locale). "Paste N blocks" appears in the
+  zone bar's "…" menu of every zone that allows all the copied components, and
+  in the page preview seams. Paste is all or nothing: every block must be
+  allowed in the target zone, fit its maximum, and groups must be whole;
+  otherwise a notice explains why and the form is not changed. Media and relations are kept by id/documentId, so paste
   within the same install. Option `clipboard`.
 - **Confirm delete**. The native delete asks "Delete block …?" first;
   confirming runs Strapi's own removal. On a group marker the dialog says only
@@ -219,15 +309,16 @@ needed for the gallery to pick them up. Reading requires the
   and "Restore default colors". Colors must be `#RRGGBB`.
 - Component list with the effective source, choose/replace image from the
   Media Library, "Use automatic image", the wireframe template, the gallery
-  typology ("Automatic" shows the guess) and tags (comma separated).
+  typology ("Automatic" shows the guess) and tags (comma separated); a group
+  OPEN also has its layout grid fields (see [Layout grid](#layout-grid)).
 - Editor preferences: enhancements on/off, visibility of each collective
   button, initial accordion state and the initial block mode.
 - Version history (Strapi 5): module switch, covered content types, retention
   (see "Version history").
 - Content types: every project type with a Dynamic Zone, each with on/off
-  (off leaves its edit view fully native) and, on Strapi 5, the mode its edit
-  views open in ("Default" follows the global preview mode) and its visual
-  editor sidebar (see below).
+  (off leaves its edit view fully native), the mode its edit
+  views open in ("Default" follows the global preview mode), its visual
+  editor sidebar and optionally its own page preview toolbar (see below).
 - "Restore project defaults" (or "Reset to defaults" when the project has no
   code defaults), after a confirmation, deletes what was saved here
   (`DELETE /blockscene/settings`, same permission as saving).
@@ -259,7 +350,12 @@ module.exports = {
 The effective settings are the built-in defaults, then the code `settings`,
 then what was saved on the page:
 
-- `palette` and `editor`: a saved key wins over the code key by key.
+- `palette` and `editor`: a saved key wins over the code key by key, except
+  an empty `previewUrl` or `blockPreviewUrl`, which means "not set": the code
+  value applies. Clearing either field on the page therefore falls back to the
+  project default (there is no saved "off" for a URL the code provides; remove
+  it from the code settings, or set `previewMode` per content type, to keep a
+  type out of the page preview).
 - `components` and `contentTypes`: a saved entry replaces the code entry for
   that uid as a whole (a saved `api::page.page` entry replaces its code
   sidebar too); other uids keep their code values.
@@ -277,27 +373,31 @@ ignored (boot continues). `GET /blockscene/settings` returns them as
 | Option | Values | Default |
 | --- | --- | --- |
 | Editor enhancements enabled | on/off | on |
-| Show "Open all blocks" | yes/no | yes |
-| Show "Close all blocks" | yes/no | yes |
+| Show "Expand all" (`showOpenAll`) | yes/no | yes |
+| Show "Collapse all" (`showCloseAll`) | yes/no | yes |
 | Show block thumbnails in the rows (`showRowThumbnails`) | yes/no | yes |
 | Initial accordion state | all closed / all open / remember | all closed |
 | Load rich-text editors on demand (`lazyEditors`, Strapi 5) | yes/no | yes |
 | Custom fields loaded on demand (`lazyFields`, Strapi 5) | up to 20 uids `plugin::x.y` / `global::x` | `["plugin::ckeditor5.CKEditor"]` |
-| Preview route base URL (Strapi 5) | full URL or empty | empty: native Preview origin |
+| Preview route base URL | full URL or empty | empty: native Preview origin (Strapi 5; none on Strapi 4) |
 | Block preview URL | http(s) URL with placeholders, up to 500 characters, or empty | empty: page preview route, else image |
-| Initial preview mode (Strapi 5) | form / side by side / preview | form |
+| Initial preview mode | form / side by side / preview | form |
 | Confirm before deleting a block (`confirmDelete`) | yes/no | yes |
 | Duplicate on each block (`duplicate`) | yes/no | yes |
 | Copy and Paste (`clipboard`) | yes/no | yes |
 | Blocks hidden on the site (`hiddenBlocks`) | `strip` / `flag` / `off` | `strip` |
 | Friendly field labels (`friendlyLabels`, see [Field labels](#field-labels)) | yes/no | yes |
+| Page preview toolbar (`previewToolbar`, see [Pane toolbar](#pane-toolbar)) | ordered list of `modes`, `history`, `devices`, `status`, `actions` | all five |
+| Page widths (`previewDevices`) | 1 to 8 of `fit`, `mobile`, `tablet`, `desktop`, `{ label, width }` | the four built-in |
 
 Every edit view opens in its content type's mode, else the initial preview
 mode. Editors can switch while they edit; the switch is not remembered.
 
 The initial state is applied once per document/locale after the blocks
-render; edits, reorders and newly inserted blocks are not re-applied. Hiding a
-button only hides it; native accordion headers keep working.
+render; edits, reorders and newly inserted blocks are not re-applied.
+`showOpenAll` and `showCloseAll` shape the zone bar's single toggle (both: it
+toggles; one: only that action; none: no button). Hiding it only hides it;
+native accordion headers keep working.
 
 Lazy editors: a custom field listed in `lazyFields` first shows a read-only
 preview of its HTML (same label, hint and error; scripts, frames, styles, event
@@ -309,7 +409,7 @@ registered custom field at boot and passes the others straight through; until
 the catalog loads, and when the plugin or the content type is off, every field
 is native.
 
-"Remember" stores only the last explicit open all / close all click, as
+"Remember" stores only the last explicit Expand all / Collapse all click, as
 `open`/`closed` in the browser's localStorage, keyed by admin URL, user id,
 content type and zone. Another user in the same browser does not inherit it.
 Blocked storage or an invalid value falls back to all closed. No sync between
@@ -319,11 +419,12 @@ The accordion controls drive the native Dynamic Zone accordions through their
 `aria-expanded` headers, so no Strapi source is patched. They are validated on
 the two supported versions only.
 
-## Whole-page preview (Strapi 5)
+## Whole-page preview
 
-The Strapi 5 distribution adds a "Page preview" panel with three modes: form,
-side by side (resizable pane, native actions moved to a bar above the form) and
-preview. The panel posts the live values of the first Dynamic Zone to a page
+Both distributions add a page preview with three modes, chosen from the
+first zone's bar and from the pane toolbar: Fields (form), Fields + page (side
+by side: resizable pane, native actions moved to a bar above the form) and
+Visual editor. It posts the live values of the first Dynamic Zone to a page
 your frontend serves; the page renders them with its own components and styles
 and can ask the admin to open a block, edit a field or pick media. Nothing is
 saved or published by the preview.
@@ -393,7 +494,7 @@ Minimal configuration:
    Use the same host name the frontend dev server was started for
    (`localhost` vs `127.0.0.1`): Next 16 refuses its dev WebSocket for the
    other one and the page then never hydrates, so `ready` never arrives and
-   the panel reports the preview as unavailable with no error in either console.
+   the pane reports the preview as unavailable with no error in either console.
 
 The bridge only exposes what the schema allows: attributes marked `private`
 are never projected, focused or edited; media URLs are passed through for any
@@ -411,15 +512,115 @@ page updates while you type; Done, Esc or the backdrop put the block back. Side
 by side focuses the field in the form on the left instead. Media
 fields open the native Media Library. Everything is validated against the schema
 and the zone's edit permission; a published page never receives unsaved values
-by itself. Strapi 4 does not have this panel yet (see `docs/BACKLOG.md`).
+by itself.
+
+On Strapi 4 (run on 4.26.1; the edit view APIs it uses are the same in 4.11.0)
+the page preview is the same: the three modes, the same bridge
+(`blockscene:page-preview:v1`, so one frontend route serves both), widths,
+hover sync, the block dialog, the visual editor sidebar, custom panels,
+insertion, groups and paste from the page, and the per content type settings.
+It reads and writes the edit view's own data (`useCMEditViewDataManager`); new
+blocks use the native insertion at a position. Differences:
+
+- No undo and redo (no History buttons, no shortcuts). Strapi 4's form has no
+  way to set all values at once, and restoring each field would also undo the
+  relations it loads lazily, which Save would then disconnect.
+- No native Preview to fall back on: set the preview route base URL.
+- The toolbar's status shows Draft or Published (Strapi 4 has no Modified
+  state) and the unsaved hint; its Save and Publish (or Unpublish) click the
+  edit view header's own buttons, so their checks and dialogs are Strapi's.
+- The browser smoke covers split mode, select, inline and live edits, widths,
+  hover, the block dialog, a sidebar item, media, insertion and toolbar Save
+  on 4.26.1; group tools, paste and custom panels from the page share the
+  Strapi 5 code and are checked there only.
+- With Strapi 4's two navigation columns the content area is narrower: the
+  form keeps at least 520 px, so side by side the page gets less than half on
+  a 1440 px screen.
+
+### Pane toolbar
+
+Which controls the toolbar shows, and in which order, is `previewToolbar`:
+`modes` (Fields, Fields + page, Visual editor), `history` (Undo, Redo),
+`devices` (the width menu), `status` (Draft/Modified/Published and the unsaved
+hint) and `actions` (Save, Publish). A missing id is hidden; `status` and
+`actions` stay one group on the right, placed where the first of them is
+listed. The preview's loading or error notice always shows. Without `modes` the
+pane stays in the mode the edit view opened in (for example a visual editor
+only view with `previewMode: 'preview'`); the form's zone bar keeps its own
+Undo, Redo and mode menu.
+
+`previewDevices` lists the width menu's entries in order; the first is used
+until an editor picks another. Besides the four names, `{ label, width }` adds
+a custom width (label up to 24 characters, width a whole number from 240 to
+3840 px; no name or width twice; up to 8 entries). With a single entry the menu
+is hidden.
+
+```js
+// Settings, Blockscene (Editor preferences, or per content type), PUT /blockscene/settings, or the code `settings`:
+editor: {
+  previewToolbar: ['modes', 'devices', 'actions'],
+  previewDevices: ['fit', 'mobile', { label: 'Laptop', width: 1280 }, 'desktop'],
+},
+contentTypes: {
+  'api::landing.landing': { previewToolbar: ['actions'], previewDevices: ['desktop'] },
+}
+```
+
+A content type's value replaces the global one. The Settings page edits both as
+checklists (check to show, arrows to order, "Add a width" for custom widths);
+"Own page preview toolbar" under a content type starts as a copy of the global
+choice, and turning it off goes back to the global one.
+
+### Custom sidebar panels
+
+A project (in its `src/admin/app.tsx`) or another plugin can add its own panel
+to the visual editor sidebar. Registered panels come after the configured field
+items, in registration order; the rail shows in the Visual editor mode as soon
+as there is one item.
+
+```tsx
+// src/admin/app.tsx
+const Notes = ({ values, onChange, disabled, close }) => (
+  <textarea value={values.notes ?? ''} disabled={disabled}
+    onChange={(e) => onChange('notes', e.target.value)} />
+)
+export default {
+  bootstrap(app) {
+    app.getPlugin('blockscene')?.apis.registerPanel({
+      id: 'notes', // 1 to 40 letters, digits, _ or -; the same id again replaces the panel
+      label: 'Notes', // 1 to 40 characters
+      icon: 'info', // optional: an icon name (the sidebar icons above, for example) or a React element
+      open: 'drawer', // 'drawer' (default) or 'modal'
+      contentTypes: ['api::page.page'], // optional: only these types (default: every type)
+      Component: Notes,
+    })
+  },
+}
+```
+
+`Component` receives `model` (content type uid), `documentId` (undefined while
+creating), `locale`, `values` (the live form values), `onChange(name, value)`
+(the form's own setter: the change is unsaved, goes through undo and redo, and
+Save or Publish store it with the usual permission checks), `disabled` (the form
+is read-only) and `close()`. It renders inside the Content Manager edit view, so
+it can also use the admin's hooks (`useForm`, `useFetchClient`...). Strapi runs
+every plugin's `register` before any `bootstrap`, then the host's `bootstrap`:
+calling `registerPanel` from either bootstrap works. An invalid panel is logged
+(`[blockscene] registerPanel: ...`) and ignored; `registerPanel` returns `true`
+or `false`. A panel that throws while rendering shows the plugin's error notice
+in its drawer; the editor keeps working. On Strapi 4 the same call works (its
+`values` and `onChange` are the edit view data manager's); the lab smoke covers
+panels on Strapi 5 only.
 
 ### Undo and redo
 
-The Blockscene panel and the pane toolbar have Undo and Redo buttons (Strapi 5).
+The first zone's bar and the pane toolbar have Undo and Redo buttons (Strapi 5),
+on one shared history (the shortcuts use it too).
 They step through the whole edit view: blocks inserted, removed or moved from the
 gallery, the page, groups or the native actions, and any field edit. Changes
 within 400 ms of each other are one step, so a burst of typing undoes at once;
-up to 100 steps. Shortcuts: Cmd/Ctrl+Z, Cmd/Ctrl+Shift+Z and Ctrl+Y, only while
+a block dragged with the mouse is one step however long the drag lasts; up to
+100 steps. Shortcuts: Cmd/Ctrl+Z, Cmd/Ctrl+Shift+Z and Ctrl+Y, only while
 the focus is outside a text field, select or rich text editor (those keep their
 own undo).
 
@@ -467,7 +668,7 @@ With a valid map:
   groups may nest; a CLOSE right after its OPEN is a valid empty group. Errors
   are `closeBeforeOpen` (CLOSE with no open group), `mismatch` (CLOSE is not the
   one expected by the innermost open group) and `unclosed` (OPEN never closed).
-- Nothing is repaired on read: the panel lists the problems (row, marker) and
+- Nothing is repaired on read: the Blockscene side panel lists the problems (row, marker) and
   the stray rows stay visible so the editor can fix them. Drafts save normally.
 - Publishing is refused server-side while a configured pair is unbalanced.
   Strapi 5: a document-service middleware intercepts every facade path that
@@ -491,6 +692,81 @@ With a valid map:
 Configured groups are stored exactly as before: the flat list of components in
 the zone. Removing the config only removes the group tools and the guard.
 
+### Groups in the form
+
+The edit view draws the same structure over Strapi's native rows (Strapi 5 and
+4; data attributes on the rows, nothing of the Content Manager is patched):
+
+- The rows between an OPEN and its CLOSE are indented under it with a guide line
+  in the admin's primary colour, one level (and one line) per nested group.
+- The CLOSE row reads as the group's end: compact, dimmed, without a drag handle
+  (it cannot be dragged on its own; its delete stays, with the marker notice).
+- Each closed group's OPEN header gets a chevron before its title. It folds the
+  group: its rows and CLOSE are hidden and the header shows "N blocks" (every
+  row inside, nested ones too, CLOSE markers excluded). Folding is kept in memory
+  for the session, per document, zone and group; a reload shows every group open.
+  A validation error inside a folded group (on Save or Publish) unfolds it.
+  Expand all / Collapse all act on the visible block accordions only: they never
+  open the forms of a folded group's rows, and a group keeps its own chevron.
+- Moving an OPEN moves its group. Nothing intercepts Strapi's drag and drop:
+  after any change of the zone, if the only thing that changed is one OPEN
+  moving, its members as they were (children and CLOSE) are put back right after
+  it, in the same unsaved form change. This covers the mouse (settled on drop:
+  Strapi moves the row on every hover), the keyboard (Space, arrows, Space on the
+  drag handle) and the move arrows of small screens. An OPEN dropped among its
+  own rows (a single keyboard or arrow step down) moves the group one row down
+  instead. The whole drag and the correction are one undo step (Strapi 5).
+- Everything else keeps the flat-list meaning: a child dragged out of the range
+  is an ordinary block from then on, a block dropped inside becomes a child, and
+  an OPEN dropped inside another group is nested there with its rows. A CLOSE
+  moved by other means (the small-screen arrows) ends the group where it lands.
+  Unclosed groups and stray markers are indented as the page preview shows them
+  but have no chevron and are never moved (the diagnostics list them).
+
+### Layout grid
+
+An OPEN whose component lays its children out in columns (a "grid columns"
+wrapper) can show them that way in the form. Name the OPEN attribute that holds
+its desktop column count, per component, in Settings (the OPEN's card, "Layout
+grid") or in the code `settings`:
+
+```json
+{ "components": { "wrappers.grid-columns": { "layout": { "columnsField": "columnsMd", "mobileColumnsField": "columns", "maxColumns": 3 } } } }
+```
+
+- `columnsField` (required) and `mobileColumnsField` (optional) must be
+  attributes of that component that can hold a count: `integer`, `biginteger`,
+  `float`, `decimal`, `string`, or an `enumeration` whose every value is a whole
+  number (`["1", "2", "3"]`). `maxColumns` is 1 to 12 (default 12). Checked on
+  `PUT` and on the code settings at boot; a saved layout whose attribute was
+  removed is dropped on read. A layout on a component that is not a configured
+  OPEN does nothing.
+- The count is read live from the OPEN's form: its value, else the attribute's
+  default, else 1, capped at `maxColumns` (a value that is not a whole number
+  from 1 counts as missing). The grid shows the desktop count; the mobile one is
+  named in its caption.
+- Each child is a cell under the OPEN's header (its name and the first text of
+  its fields); a nested group is one cell ("N blocks"); the CLOSE stays a row
+  below. The children's own rows are hidden but stay mounted, so the form,
+  validation, Save and the row tools keep working on them; Expand all skips
+  them as it skips a folded group.
+- A cell opens its block's native form in the block dialog (the one of the
+  visual editor), in any mode, with every field type. A validation error inside
+  a child gives its cell a red border; the dialog shows the field.
+- Reorder by dragging a cell onto another, or with Alt+Arrow keys on a focused
+  cell (left/right one cell, up/down one row of the grid); nested groups move
+  whole. "Remove from group" in a cell's "…" menu moves the block right after
+  the CLOSE. "Add a block" opens the gallery (the zone's allowed components) and
+  inserts at the end of the group; an OPEN brings its CLOSE. Each of these is
+  one form change: one undo step on Strapi 5, nothing saved before Save.
+- The icon on the OPEN's header switches that group between grid and list (the
+  native rows) for the session, per document and group. A folded group shows no
+  grid.
+- Dragging a cell out of the grid onto the list is not supported (it would need
+  Strapi's own drag and drop): use "Remove from group", or the list view.
+
+Strapi 5 and 4 (the block dialog is shared by both since the page preview core).
+
 ## Field labels
 
 The Content Manager shows each field under its "Configure the view" label, which
@@ -519,13 +795,23 @@ blockscene: { config: { fields: {
     pageSeo: { label: { en: 'Search engine settings', 'pt-BR': 'Configurações de SEO' },
       description: { en: 'Title and description shown on Google', 'pt-BR': 'Título e descrição no Google' } },
   },
-  'shared.seo': { metaTitle: { placeholder: 'Up to 60 characters' } },
+  'shared.seo': { metaTitle: { placeholder: 'Up to 60 characters' },
+    metaDescription: { help: { en: 'Shown under the title in search results. Google cuts it around 155 characters; write for people, not keywords.' } } },
 } } },
 ```
 
 Keys are content type or component uids, then attribute names; each of
-`label` (up to 80 characters), `description` (300) and `placeholder` (120) is a
-string or `{ "<locale>": string }`. The map is validated at boot: an unknown
+`label` (up to 80 characters), `description` (300), `placeholder` (120) and
+`help` (500) is a string or `{ "<locale>": string }`.
+
+`description` stays the line under the input. `help` is for the longer
+explanation that would stretch the form: on Strapi 5 it becomes an "i" icon next
+to the label, in the Content Manager's own label action slot (where the i18n
+plugin puts its globe; both icons show on localized fields), with the text in a
+tooltip on hover and on keyboard focus (the button is reachable with Tab and
+named "More information"). A field can have both. On Strapi 4 the Content
+Manager gives component fields, where blocks live, no label action, so `help`
+is appended to the description under the input instead. The map is validated at boot: an unknown
 key, an empty or too long text, or a malformed locale code logs a warning
 naming it and the whole `fields` config is ignored (labels fall back to the two
 other steps). Entries for a uid or attribute the schema no longer has (a
@@ -613,7 +899,7 @@ harmless.
 ```js
 // config/plugins.js
 blockscene: { config: { settings: { history: { enabled: true, contentTypes: ['api::page.page', 'api::post.post'],
-  retentionDays: 90, maxSnapshots: 100, eventDays: 365 } } } }
+  retentionDays: 90, maxSnapshots: 100, eventDays: 365, trashDays: 90 } } } }
 ```
 
 Events live in the `blockscene_events` table (content type
@@ -622,6 +908,100 @@ Builder). Removing the plugin, or installing a Blockscene version older than
 the one that added history, lets Strapi drop that table and every recorded
 version on the next start: back up `blockscene_events` first if you need it.
 
+### Trash (Strapi 5)
+
+Part of the version history module: on with it, for the same content types.
+Strapi has no trash in any plan; here a delete made through the document service
+(the admin's Delete, bulk delete and "Delete locale", the APIs, plugins) also
+writes one trash entry per document, in the same transaction as the delete.
+
+**What an entry keeps.** Every deleted locale, draft and published rows (they
+can differ), as snapshots like the history's; the document's title (its Content
+Manager main field); who deleted it and when; and the links other documents and
+blocks had to it. Strapi removes those links with the document, and the
+document's own snapshot does not hold them when the relation is unidirectional
+(declared only on the other side, like a menu listing pages or a block linking
+to a page), so they are captured before the delete: owner, field, locale and the
+position in the owner's list. A delete without a locale removes the default
+locale only (Strapi's rule), `'*'` every locale; the entry has exactly what was
+deleted. If the capture fails, nothing is deleted.
+
+**Restore.** From the Trash page, which first shows what the restore would do
+and writes nothing if something blocks it:
+
+- Blocking: the content type is gone; a unique field (`unique: true` or a uid
+  field, such as a slug) is now used by another document in that locale; the
+  document has that locale again; a single type has a document again; none of
+  its locales is configured any more.
+- Reported, then restored anyway: a published version existed (see below);
+  required fields are empty under the current schema (drafts may be, Strapi
+  checks them on publish); fields the schema no longer has, blocks whose
+  component the zone no longer allows, media files and related documents that no
+  longer exist (left out); locales no longer configured (skipped); links whose
+  owner is gone or now points elsewhere.
+
+The document comes back as a **draft with its draft content**: the draft is the
+latest work, and publishing is the editor's decision (the site may have moved
+on). The published snapshot stays in the entry and in the preview. Every locale
+is restored under one documentId, the default locale first, through the
+document service (validation and the project's lifecycles run). A document that
+is gone gets a new documentId, since Strapi's create does not take one; a locale
+deleted from a document that still exists goes back into that document. The
+captured links are put back where they were (same position in the owner's
+list) when the owner still exists; links from published versions come back
+when those owners are published again after this document is. A restore is one
+transaction and is idempotent: the entry is claimed first, so a second restore
+(a double click, another editor, another instance) returns the first one's
+document. The history gets a `restore` event per locale.
+
+**Delete forever** removes one entry (recorded as a `purge` event in the
+activity). The nightly job deletes entries past their expiry, restored ones too,
+in batches; neither ever deletes media files.
+
+**Retention.** `trashDays` (90, 1 to 3650) in the same settings; each entry's
+expiry is fixed when the document is deleted, so a later change applies to later
+deletes.
+
+```js
+blockscene: { config: { settings: { history: { enabled: true, trashDays: 30 } } } }
+```
+
+Entries live in `blockscene_trash` (`plugin::blockscene.trash`, hidden from the
+Content Manager and the Content-Type Builder); the same backup note as for
+`blockscene_events` applies.
+
+### Activity and Trash pages (Strapi 5)
+
+A main menu link, "Activity and trash", opens one page with a tab each (the
+pages are tools for editors, not configuration, so they are not under
+Settings). **Activity** lists every recorded event, newest first, 25 per page,
+filtered by person, content type, action, date range and title (documents whose
+main field contains the text now, or whose trash entry's title does); each row
+links to the document's edit view while that locale exists and shows the
+summary. **Trash** lists the entries (title, type, locales, who, when, when it
+is deleted for good), filtered by content type, with restored entries on a
+switch; Preview shows the fields and blocks of each deleted locale, read-only;
+Restore shows the pre-check report and asks to confirm; Delete forever asks
+first.
+
+**Permissions.** `Read content activity` (`activity.read`), `Read the trash`
+(`trash.read`), `Restore from the trash` (`trash.restore`), `Delete from the
+trash forever` (`trash.purge`), none granted to non-super-admin roles by
+default. On top of them, every list shows only content types the user may read
+in the Content Manager (an entry of another type answers 404), restoring needs
+create there and deleting forever needs delete. Admin API: `GET /blockscene/activity`
+(`actor`, `contentType`, `action`, `from`, `to` as ISO dates, `q`, `page`,
+`pageSize` up to 100), `GET /blockscene/trash` (`contentType`, `status`
+trashed or restored, `page`, `pageSize`), `GET /blockscene/trash/:id` (the
+preview), `GET /blockscene/trash/:id/check` (the pre-check),
+`POST /blockscene/trash/:id/restore` (409 with the report when blocked) and
+`DELETE /blockscene/trash/:id`. Lists never load snapshots.
+
+**Coverage boundary**, the same as the history's: the document service only.
+A raw `strapi.db.query` delete, SQL or a database restore leaves no trash
+entry; deleting a content type (Content-Type Builder) drops its data without
+one. The trash is a safety net for editors, not a backup: keep database backups.
+
 ## Languages
 
 All plugin chrome (gallery, settings, page preview, editor dialogs, diagnostics)
@@ -635,15 +1015,15 @@ component display names are never translated by the plugin.
 
 ## Turning the editor enhancements off
 
-- **From the panel**: switch "Editor enhancements enabled" off. The gallery
-  button, controls and initial-state logic disappear and the native picker and
+- **From the settings page**: switch "Editor enhancements enabled" off. The
+  gallery, the zone bars and the initial-state logic disappear and the native picker and
   accordions remain. Content, config, media and unsaved edits are preserved; the
   form is not reloaded. The settings page stays available to turn it back on.
-- **Emergency, outside the panel**: start the server with
+- **Emergency, outside the admin**: start the server with
   `BLOCKSCENE_DISABLED=true` (or set `config.disabled: true`). It is read at
   boot and reported by the catalog, wins over the saved settings and cannot be
   undone from the client. Changing it requires a restart.
-- **If the catalog request fails**, the panel renders nothing and the native
+- **If the catalog request fails**, the plugin renders nothing and the native
   editor is used, so a plugin outage does not block editing.
 - **Completely**: set `'blockscene': { enabled: false }` in `config/plugins.js`
   and rebuild/restart. This is the only way out of an import/build failure; a
@@ -701,10 +1081,10 @@ installs without overrides, not a promise for every minor in between. Strapi
 - Authenticated admin catalog endpoint exposes only supported metadata, resolved
   override URLs, palette and editor preferences; never the whole config.
 - Top-level Dynamic Zones only. Conditional fields are omitted conservatively.
-- "Open all" / "Close all" drive the native accordions without touching the
-  whole list at once: open all opens the rows in and near the visible area, a
-  few per frame, and the others as they approach while scrolling (until Close
-  all or leaving the document); close all closes the visible rows at once and
+- "Expand all" / "Collapse all" drive the native accordions without touching the
+  whole list at once: expanding opens the rows in and near the visible area, a
+  few per frame, and the others as they approach while scrolling (until Collapse
+  all or leaving the document); collapsing closes the visible rows at once and
   the rest in idle time. With lazy editors, on a 34-block page with CKEditor
   fields (Strapi 5.31) the longest pause went from about 2.9 s to 0.14 s on
   open all and from 1.6 s to 0.14 s on close all.