@aduptive/strapi-blockscene 1.0.0-alpha.3 → 1.0.0-alpha.5

package/README.md

@@ -33,7 +33,8 @@ module.exports = {
         'blocks.hero': {
           label: 'Hero banner',
           description: 'Introduce a page with a prominent title and image.',
-          category: 'Editorial',
+          typology: 'hero', // optional; guessed from the name otherwise
+          tags: ['Editorial'],
           keywords: 'heading introduction',
           image: '/block-previews/hero.png',
         },
@@ -44,19 +45,75 @@ 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 plus
-"Open all blocks" / "Close all blocks" for zones that already have blocks.
+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)").
 
 ## Gallery
 
-The modal has one header row: block count (`34 blocks`, or `3 of 34` while
-filtering), search, a category filter (only when the zone spans more than one
-category, with counts), a "Fields" switch that shows each block's attribute
-list on its card, and a columns slider (1 to 5, remembered per browser). Blocks
-are grouped by category, system-like categories (`admin`) last; search and the
-category filter combine, and the empty state offers a reset. Categories come
-from `config.components[uid].category`, else the component's `category` in its
-schema. The modal is 80vw wide.
+The modal is a block browser (80vw wide):
+
+- **Sidebar** (collapsible to icons; remembered per browser): All, Recently
+  used and Starred with counts, then the typologies present in the zone.
+- **Top bar**: count (`34 blocks`, or `3 of 34` while filtering), search,
+  filter menus Tags, Media and Content (checkboxes; several values in one menu
+  match any of them, different menus combine), a "Fields" switch that shows
+  each block's attribute list on its card, and a columns slider (1 to 5,
+  remembered per browser). Active values show as removable chips with "Clear
+  all"; the empty state offers a reset.
+- **Cards**, grouped by typology: facet badges (IMAGE, VIDEO, GALLERY, RICH
+  TEXT, LIST, DYNAMIC, FORM), a star and a hover "+" that inserts at once.
+- A click **magnifies** the block: the card grows into a large panel over the
+  grid (sidebar and top bar stay usable, the grid dims underneath) and shrinks
+  back into its card on close (close button, Esc or a click on the dimmed
+  grid). The animation is transform/opacity only, about 250 ms, and is skipped
+  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.
+
+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:
+
+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:
+   `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
+   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.
+3. Otherwise the image only.
+
+If the live page neither loads nor says `ready` within 8 s, the image stays
+with a short note. The iframe uses the page preview's sandbox
+(`allow-scripts allow-same-origin`) and `referrerpolicy="no-referrer"`.
+
+Stars and recently used blocks are stored per admin user on the server
+(`GET`/`PUT /blockscene/me/prefs`, `{ starred, recent }`, at most 200 and 20
+existing component uids).
+
+### Taxonomy
+
+Facets are read from each component schema and the components it nests (one
+level): media fields (`image`, `video` by allowed types, `gallery` when
+multiple), `richtext` (rich text, blocks or a CKEditor custom field), `list`
+(repeatable component), `dynamic` (a relation, or a uid with query, archive or
+related) and `form` (uid or display name with form or contact).
+
+The typology is one of hero, text, media, listing, cards, cta, form and
+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
+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
 gallery as well (the click is intercepted in the capture phase; Strapi's
@@ -66,6 +123,64 @@ 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.
 
+## Row thumbnails
+
+Each added block shows its thumbnail at the left of the native accordion
+header, and clicking it opens the image full size in a modal instead of
+opening or closing the row. The sources are the same as the gallery cards,
+minus the wireframe: a block with no image shows nothing, so nothing new is
+invented for blocks that were never captured. The thumbnail is inserted into
+Strapi's own header through the DOM (no Content Manager patch) and is
+restored when Strapi re-renders the list. Turn it off with the editor option
+`showRowThumbnails: false`.
+
+## Row actions
+
+Each block header gets a few icons right before Strapi's own delete button
+(inserted through the DOM, like the thumbnails; read-only rows get none):
+
+- **Hide on the site** (eye). The block stays in the document and in the
+  admin, dimmed with a "Hidden" badge (also in the page preview, which receives
+  `hidden: true` for it). What the content API does is the editor option
+  `hiddenBlocks`: `strip` (default) removes hidden rows from Dynamic Zones in
+  content-API reads (REST and GraphQL, including zones of populated relations
+  and components; admin and Content Manager reads always return every row),
+  `flag` sends them with the attribute so the frontend decides, `off` removes
+  the eye and strips nothing. On a configured group OPEN the eye hides the
+  whole group.
+- **Duplicate**. A deep copy right below: ids removed from the row and its
+  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
+  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
+  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
+  the marker is removed. Option `confirmDelete`.
+
+Everything goes through the form: nothing is saved until Save, and undo/redo
+(Strapi 5) covers every action. Strapi 4 supports the same actions; relations
+are copied as the form holds them there (the loaded relations of an opened
+block).
+
+**The hidden attribute is a database column.** At register time the plugin adds
+a boolean attribute (like i18n adds `locale`) to every component used in a
+Dynamic Zone: `{ type: 'boolean', default: false, visible: false,
+configurable: false }`, so Strapi's schema sync creates a `bs_hidden` column in
+each of those component tables on the next start (existing rows read as not
+hidden). It is hidden from the edit view. 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
+`false`) leaves the column in place with its data; drop it yourself if you want.
+
 ## Thumbnail priority
 
 Each card tries these sources in order and moves on when one fails to load.
@@ -99,9 +214,57 @@ needed for the gallery to pick them up. Reading requires the
 - Wireframe palette (background, surfaces, text, accent) with a live preview
   and "Restore default colors". Colors must be `#RRGGBB`.
 - Component list with the effective source, choose/replace image from the
-  Media Library, "Use automatic image" and the wireframe template.
+  Media Library, "Use automatic image", the wireframe template, the gallery
+  typology ("Automatic" shows the guess) and tags (comma separated).
 - Editor preferences: enhancements on/off, visibility of each collective
   button, initial accordion state and the initial block mode.
+- 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).
+- "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).
+
+### Project defaults from code
+
+A project can ship its baseline in the plugin config, with the same shape as
+the stored settings (every key optional):
+
+```js
+// config/plugins.js
+module.exports = {
+  blockscene: { config: { settings: require('./blockscene.json') } },
+}
+// config/blockscene.json
+{
+  "palette": { "accent": "#AA3300" },
+  "editor": { "previewMode": "split", "initialState": "open" },
+  "components": { "blocks.faq": { "template": "faq", "typology": "text" } },
+  "contentTypes": {
+    "api::page.page": {
+      "sidebarPosition": "right",
+      "sidebar": [{ "label": "SEO", "icon": "seo", "open": "drawer", "fields": ["seo"] }]
+    }
+  }
+}
+```
+
+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.
+- `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.
+
+Saving stores only what differs from the code defaults, so later changes to the
+code reach every key nobody overrode. A document saved before the project had
+code defaults holds every palette and editor key, and those keep winning until
+"Restore project defaults". The code settings are checked at boot with the same
+rules as `PUT`; if they are invalid a warning names the problem and they are
+ignored (boot continues). `GET /blockscene/settings` returns them as
+`projectDefaults` (null when absent or invalid).
 
 ### Editor preferences
 
@@ -110,14 +273,35 @@ needed for the gallery to pick them up. Reading requires the
 | Editor enhancements enabled | on/off | on |
 | Show "Open all blocks" | yes/no | yes |
 | Show "Close all blocks" | 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 |
+| 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 |
+| 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` |
+
+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.
 
+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
+handlers and `javascript:` URLs removed) and mounts the real editor on click,
+Enter/Space or keyboard focus, then puts the caret in it. Once mounted it stays
+for that view; closing and reopening the block shows the preview again.
+Disabled fields only show the preview. The wrapper is installed on every
+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
 `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.
@@ -137,11 +321,62 @@ 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.
 
+Side by side, hovering a zone row in the form (open or closed) outlines its
+block in the page, and hovering a block in the page outlines its form row in the
+theme's primary color; hovering never scrolls. When that row is outside the
+visible form, an arrow at the top or bottom edge of the form scrolls to it. The
+divider between form and page drags to resize, takes the arrow keys, Home and
+End, and a double click resets it to half.
+
+### Visual editor sidebar
+
+Per content type, a bar of buttons on the left, right or bottom edge of the
+visual editor. Each button (label, optional icon) opens some of the document's
+own fields in a modal or a drawer: the native form itself, with every other
+field hidden, so components, repeatable components, media, relations and custom
+fields all keep working. Done, Esc or the backdrop put the form back.
+
+```js
+// Settings, Blockscene, Content types (or PUT /blockscene/settings, or the code `settings`):
+contentTypes: {
+  'api::page.page': {
+    sidebarPosition: 'left', // left | right | bottom
+    sidebar: [
+      { label: 'Title', icon: 'text', open: 'modal', fields: ['title'] },
+      { label: 'SEO', icon: 'seo', open: 'drawer', fields: ['pageSeo'] },
+    ],
+  },
+}
+```
+
+Icons: text, tag, seo, settings, image, link, palette, list, globe, info (or
+none). Fields are the type's own top-level attributes; an item naming a field
+removed from the schema is dropped on read. Up to 12 items.
+
+The Settings page edits it under each enabled content type: position, then per
+item the label, icon, drawer or modal, the fields (checkboxes), move up/down and
+remove. An item without a label or without fields is flagged and blocks Save.
+Removing every item removes the override.
+
+The pane toolbar sets the page width: Fit (the pane), Mobile (390 px), Tablet
+(834 px) or Desktop (1440 px). A device renders at its own width and scales down
+when the pane is narrower, so the desktop layout fits side by side; switching
+never reloads the page. The choice is remembered per browser.
+
 Minimal configuration:
 
 1. Serve a page that implements the bridge. `examples/page-preview/index.html`
    is a framework-free reference: it answers `ready`/`ping`, renders
    `update-page`, and sends `select`, `focus`, `edit`, `media`, `media-remove`.
+   Hover sync is optional: the page sends `{ type: 'hover', key }` (a block
+   key, or `null` off blocks) when it changes, and marks the block of the
+   admin's `{ type: 'hover', key }` without scrolling. A page that ignores it
+   keeps working.
+   Row actions: a block hidden on the site arrives with `hidden: true` (the
+   example dims it), and `update-page` carries `clipboard` (the number of copied
+   blocks, 0 when none or not editable); while it is positive the page may show
+   a Paste button in its seams that sends `{ type: 'paste', after }` (a block
+   key, or `null` for the start). Both are optional.
    Keep the origin check (`admin` query parameter or your own constant).
 2. Allow the admin origin to embed it (`Content-Security-Policy: frame-ancestors`)
    and allow the page origin in the Strapi admin CSP (`frame-src`).
@@ -161,14 +396,34 @@ update permission on it. Pending dialogs are dropped when the document or
 locale changes.
 
 Editing from the page: plain-text areas the page explicitly maps
-(`data-block-field` + `contenteditable="plaintext-only"`) send `edit`; any other
-editable field opens an admin modal with the field's own native input (custom
-fields such as CKEditor keep their options; string/text use the admin input).
-Apply updates the form and the preview; Cancel discards only the modal. Media
+(`data-block-field` + `contenteditable="plaintext-only"`) send `edit`. In the
+visual editor, a click on any other field or on the block opens the whole block
+over the page: its own native form (every field type, CKEditor, media, nested
+and repeatable components), with the clicked field focused and outlined. The
+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`).
 
+### Undo and redo
+
+The Blockscene panel and the pane toolbar have Undo and Redo buttons (Strapi 5).
+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
+the focus is outside a text field, select or rich text editor (those keep their
+own undo).
+
+Limits: the history lives in the open edit view and starts over when the
+document, the locale or its loaded values change, so a Save clears it. Shortcuts
+pressed inside the preview page are not seen (it is another origin); use the
+buttons there. A custom field that reads its value only once on mount keeps
+showing the old text after an undo until the view reloads; the CKEditor 5
+custom field (@_sh/strapi-plugin-ckeditor) follows the restored value (checked
+on Strapi 5.31).
+
 ## Layout groups (optional)
 
 Some sites keep "wrappers" in the flat Dynamic Zone: an OPEN component, the
@@ -192,7 +447,8 @@ pairs naming unknown components are dropped. Several OPENs may share one CLOSE.
 With a valid map:
 
 - The gallery (form mode) and the page preview insert OPEN and its CLOSE in the
-  same unsaved change: an empty group, never a lone marker. When the CLOSE is
+  same unsaved change: an empty group, never a lone marker. A CLOSE is not
+  offered on its own in the gallery or the preview picker. When the CLOSE is
   not allowed in that zone, or the zone has no room for two rows, nothing is
   inserted and a notice explains why (two form dispatches in one React batch;
   no partial state is rendered or saved). Children are added
@@ -307,14 +563,17 @@ 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: opening is batched into
-  one render; closing yields a frame per block so the admin stays responsive.
-  On a page with about 34 blocks whose fields include CKEditor, closing still
-  takes a few seconds with pauses up to about 1.7 s: that is the editors being
-  torn down by the host, not the plugin's loop.
+- "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
+  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.
 - No screenshot server, no hourly job, no in-editor rendered preview.
 - Removing the plugin leaves native content intact; remove its config entry and
-  rebuild. No plugin data migration is needed.
+  rebuild. No plugin data migration is needed. The "hide on the site" column
+  (see Row actions) stays in the component tables until you drop it.
 
 Configuration edits require a server restart. Backend URL/prefix deployments
 should set `previewBaseUrl` explicitly. HTTP(S) image hosts must also be allowed