@aduptive/strapi-blockscene 1.0.0-alpha.7 → 1.0.0-alpha.9

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
@@ -64,7 +64,7 @@ Right beside the native zone label ("blocks (3)") each zone gets a short bar:
   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** (Strapi 5, first zone only, when a preview route exists): a
+- **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
@@ -104,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:
@@ -113,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
@@ -144,9 +147,10 @@ layout, guessed from the component name and display name (hero, banner,
 cover; text, rich, quote, title; image, media, video, gallery, carousel; list,
 query, archive, related, posts, projects; card; cta, button, link; form,
 contact; wrapper, column, grid, divider, spacer, section; else text). Override
-it, and add up to 10 tags (1 to 24 characters), in Settings, Blockscene, or in
-the plugin config: `components[uid].typology` and `components[uid].tags`. A
-Settings value wins over the config. The former `category` config key still
+it, and add up to 10 tags (1 to 24 characters), in Settings, Blockscene, in
+the plugin config (`components[uid].typology` and `components[uid].tags`) or in
+the component schema ([`pluginOptions.blockscene`](#describing-blocks-and-fields-in-the-schema)).
+A Settings value wins over the config, the config over the schema. The former `category` config key still
 works: it becomes the block's tag when no tags are set.
 
 The native "Add a component to <zone>" button of an editable zone opens this
@@ -157,6 +161,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
@@ -213,7 +270,16 @@ as an input: the plugin removes it from the components' edit layouts through
 the Content Manager's layout hook (it may be listed in "Configure the view" of
 a component; leave it out of the layout). It is not marked `visible: false`,
 because before Strapi 5.45 the edit view crashes on a value whose attribute the
-admin does not know. Rename it with the plugin config
+admin does not know. It is kept out of the Content-Type Builder instead (the
+plugin wraps the builder's component reads), so saving a component there in
+`strapi develop` never writes it to the component's JSON file. With earlier
+versions (up to 2.0.0-alpha.8, and 1.0.0-alpha.8 on Strapi 4) the builder did
+write it (`"bsHidden": { "type": "boolean", "configurable": false, "default": false }`);
+a file that has it keeps working, and the builder keeps it there on later saves.
+To clean it up, delete that entry from the component JSON by hand (the plugin
+still adds the attribute at startup, so the column and its data stay). To check,
+edit a Dynamic Zone component in the builder (for example its display name),
+save, and diff its JSON file: only your change is there. Rename it with the plugin config
 `hiddenAttribute: 'myName'`, or set `hiddenAttribute: false` to add nothing (no
 eye, nothing stripped). A component that already has an attribute of that name
 with another type is skipped with a warning. Removing the plugin (or setting
@@ -253,13 +319,14 @@ 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
+  (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
@@ -322,16 +389,16 @@ ignored (boot continues). `GET /blockscene/settings` returns them as
 | 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`, Strapi 5, see [Pane toolbar](#pane-toolbar)) | ordered list of `modes`, `history`, `devices`, `status`, `actions` | all five |
-| Page widths (`previewDevices`, Strapi 5) | 1 to 8 of `fit`, `mobile`, `tablet`, `desktop`, `{ label, width }` | the four built-in |
+| 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.
@@ -362,9 +429,9 @@ 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 with three modes, chosen from the
+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
@@ -455,7 +522,30 @@ 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 the page preview 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
 
@@ -528,8 +618,9 @@ 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. Strapi 5 only (the Strapi 4 package has
-no visual editor).
+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
 
@@ -642,6 +733,50 @@ The edit view draws the same structure over Strapi's native rows (Strapi 5 and
   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
@@ -652,8 +787,10 @@ same hook the i18n plugin uses), so nothing in the DOM is patched and the
 saved view configuration is never changed. Per field, the first that applies:
 
 1. **Project texts** from the plugin config `fields` (below);
-2. **a label set in "Configure the view"** (anything other than the attribute name);
-3. **the humanized name** when "Friendly field labels" is on: `mobileColumnsCount`
+2. **schema metadata**: `pluginOptions.blockscene` on the attribute, with its
+   translations (see [Describing blocks and fields in the schema](#describing-blocks-and-fields-in-the-schema));
+3. **a label set in "Configure the view"** (anything other than the attribute name);
+4. **the humanized name** when "Friendly field labels" is on: `mobileColumnsCount`
    reads "Mobile columns count", `page_seo` "Page seo", acronym runs stay
    (`pageSEO` "Page SEO", `ctaURL` "Cta URL").
 
@@ -713,6 +850,85 @@ content type turned off all leave the native labels; any error leaves the
 layout untouched. Changing the interface language applies from the next edit
 view.
 
+## Describing blocks and fields in the schema
+
+The same texts can live in the component and content type JSON files, next to
+what they describe, instead of the long `components` and `fields` config maps:
+
+```jsonc
+// src/components/sections/rich-text.json
+{
+  "collectionName": "components_sections_rich_texts",
+  "info": { "displayName": "Rich text", "description": "Formatted text with an optional title and anchor." },
+  "pluginOptions": { "blockscene": { "tags": ["Editorial"] } },
+  "attributes": {
+    "anchor": { "type": "string", "pluginOptions": { "blockscene": { "help": "Id for links to this block (#id), without the \"#\"." } } },
+    "text": { "type": "richtext" }
+  }
+}
+// src/components/shared/tag.json, attribute "label"
+"label": { "type": "string", "pluginOptions": { "blockscene": { "label": "Tag text", "help": "One or two words." } } }
+```
+
+- **Block**: the native `info.description` is the gallery description;
+  `pluginOptions.blockscene` takes `label`, `typology`, `tags`, `keywords` and
+  `image`, with the same rules as the `components` config entries.
+- **Field** (any content type or component attribute): `pluginOptions.blockscene`
+  takes `label` (up to 80 characters), `description` (300), `placeholder` (120)
+  and `help` (500), each a plain string in the source language, English.
+
+Other languages go in one flat file per locale, given to the plugin config:
+
+```js
+// config/plugins.js
+blockscene: { config: { translations: { 'pt-BR': require('./blockscene/pt-BR.json') } } },
+```
+
+```json
+{
+  "sections.rich-text": "Texto formatado",
+  "sections.rich-text.description": "Texto formatado com título e âncora opcionais.",
+  "sections.rich-text.anchor": "Âncora",
+  "sections.rich-text.anchor.help": "Id para links a este bloco (#id), sem o \"#\".",
+  "shared.tag.label": "Texto da tag"
+}
+```
+
+Keys are `<uid>` (block label, else the `displayName`), `<uid>.description`
+(block description), `<uid>.<attribute>` (field label) and
+`<uid>.<attribute>.<description|placeholder|help>`. A component attribute named
+`description` takes its label as `<uid>.description.label`. The admin picks the
+language as for the field labels above; a missing key shows the schema's
+English text, and a translated field label with no English one in the schema
+shows Strapi's own label in English.
+
+Precedence, per text: the plugin config (`components`, `fields`, and Settings
+for typology and tags) > schema metadata > native Strapi ("Configure the view"
+labels, `displayName`) > automatic (humanized names, guessed typology). The
+existing config keeps working unchanged. Everything is read once at boot:
+invalid values (a typology outside the list, a label over 80 characters, an
+unknown key) and translation keys naming no known block or field are left out,
+with one warning listing them by uid.
+
+**Content-Type Builder.** Tested on Strapi 5.52.1 and 4.26.1 in development
+mode: editing and saving a component in the Content-Type Builder keeps
+`pluginOptions.blockscene` (block and attributes) and `info.description`. It
+has no field for them, so add and change them in the JSON files.
+
+To move an existing config, from a clone of this repository (idempotent; each
+schema file keeps its indentation and key order; labels equal to what the
+plugin would show anyway, the humanized name or the `displayName`, are dropped):
+
+```bash
+node scripts/schema-metadata.mjs ../my-project/backend --fields fields.json --components components.json [--out dir] [--source en] [--dry-run]
+```
+
+`fields.json` and `components.json` hold the two config maps as JSON. The
+translation files go to `config/blockscene/<locale>.json`; the script lists
+what it could not place and the `components` keys that stay in the config
+(`variants`, `template`). Remove the migrated entries from the config
+afterwards: the config wins.
+
 ## Version history (Strapi 5)
 
 Off by default. Turn it on in Settings, Blockscene, "Version history" (or from