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

package/README.md

@@ -172,10 +172,14 @@ 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
+Dynamic Zone: `{ type: 'boolean', default: 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 never shown
+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
 `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
@@ -218,6 +222,8 @@ needed for the gallery to pick them up. Reading requires the
   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.
+- 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
@@ -284,6 +290,7 @@ ignored (boot continues). `GET /blockscene/settings` returns them as
 | 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 |
 
 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.
@@ -484,6 +491,137 @@ 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.
 
+## Field labels
+
+The Content Manager shows each field under its "Configure the view" label, which
+defaults to the raw attribute name (`mobileColumnsCount`). Blockscene rewrites
+the edit view labels, hints and placeholders through the Content Manager's own
+`Admin/CM/pages/EditView/mutate-edit-view-layout` hook (Strapi 5 and 4, the
+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`
+   reads "Mobile columns count", `page_seo` "Page seo", acronym runs stay
+   (`pageSEO` "Page SEO", `ctaURL` "Cta URL").
+
+Description (the hint under the field) and placeholder change only when the
+project texts have them. Texts follow the admin user's interface language
+(`strapi-admin-language`, else English), resolved as: exact locale, then its
+language (`pt-BR` → `pt`), then any variant of that language, then `en`, then
+the first value.
+
+```js
+// config/plugins.js
+blockscene: { config: { fields: {
+  'api::page.page': {
+    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' } },
+} } },
+```
+
+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
+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
+renamed or removed field) are skipped with one warning listing them; the rest
+keep working. It is code only, versioned with the
+project; the Settings page has the on/off switch but does not edit texts.
+
+To start the file, generate every field of a project with its humanized English
+label from a clone of this repository, then keep what you want to change:
+
+```bash
+node scripts/fields-skeleton.mjs ../my-project/backend > ../my-project/backend/config/blockscene-fields.json
+# config/plugins.js: fields: require('./blockscene-fields.json')
+```
+
+Limits: the hook runs synchronously and reads the last catalog the admin
+loaded. The first edit or list view of a session starts that request and shows
+native labels; the next layout computed (another document, list → edit, a
+locale switch) has them. Strapi 5 gives the hook no content type uid, so the
+layout is matched by display name and field names; two content types that
+share both are left untouched (component fields always work: they are keyed by
+uid). The switch "Editor enhancements enabled", `BLOCKSCENE_DISABLED` and a
+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.
+
+## Version history (Strapi 5)
+
+Off by default. Turn it on in Settings, Blockscene, "Version history" (or from
+code, `settings.history`, see below). Strapi Community has no content history
+(it is a Growth feature); this module records one event per content change and
+keeps a snapshot of the content, so an editor can see what changed and load an
+earlier version back into the form.
+
+**What it captures.** Every create, save, publish, unpublish, discard draft and
+delete of the covered content types (all `api::` types by default, or a list)
+made through Strapi's document service: the admin (single and bulk actions),
+the REST and GraphQL APIs, and any plugin or custom code that uses
+`strapi.documents`. One event per affected locale, with who (admin user, API
+token, Users & Permissions user, or `system`), when, the action and a summary
+(blocks added, removed and changed per Dynamic Zone, top-level fields changed)
+against the previous snapshot of the same locale. The snapshot is the stored
+entry with components and Dynamic Zones in full, relations as documentIds and
+media as file ids (a 34-block page is a few KB; the capture adds a few
+milliseconds to a save). A snapshot identical to the previous one is not stored
+again (the event is, with the same hash).
+
+**What it does not see.** Writes that bypass the document service: raw
+`strapi.db.query`, knex or SQL, imports that write the database directly. This
+is content activity for editors, not a security audit log.
+
+**Failure policy.** A failed capture never blocks a save or a publish: the
+change goes through, the error is logged and the event is marked "Not
+recorded". A failed capture fails a delete: the delete runs in one transaction
+with its events, so nothing is deleted without its last version (a bulk delete
+is rolled back whole). `BLOCKSCENE_DISABLED=true` or the module switch off stop
+all capture. The plugin never records its own content types.
+
+**In the edit view.** The Blockscene side panel gets a History section (saved
+documents of covered types, also on types without a Dynamic Zone): the
+versions of the document in the current locale, newest first. Selecting one
+shows a block-level diff against the form (relations are not compared) and
+"Load this version", which puts the version into the form the way undo does:
+nothing is written until the editor saves, so validation, permissions and
+lifecycles apply as for any edit, and undo reverts the load. Components and
+blocks come back as new rows; relations become the connect/disconnect change
+from what the document has now; fields the editor may not update, fields the
+schema no longer has, blocks whose component is no longer allowed, and media or
+related entries that no longer exist are left out and listed.
+
+**Permission.** `Blockscene: Read version history` (`history.read`), plus read
+access to the content type in the Content Manager. Snapshots hold removed and
+unpublished text, so the section is hidden without it. Admin API:
+`GET /blockscene/history/:uid/:documentId?locale=` (the latest 100 events, no
+snapshots) and `GET /blockscene/history-events/:id` (one event, its snapshot and
+the media and relation targets that still exist).
+
+**Retention.** Snapshots are kept `retentionDays` (90) and at most
+`maxSnapshots` (100) per document, newest first; events without a snapshot are
+kept `eventDays` (365, at least `retentionDays`). A cron job added by the plugin
+runs nightly at 03:00 server time, in batches of 500; it only empties snapshots
+and deletes events, never media files, and running it on several instances is
+harmless.
+
+```js
+// config/plugins.js
+blockscene: { config: { settings: { history: { enabled: true, contentTypes: ['api::page.page', 'api::post.post'],
+  retentionDays: 90, maxSnapshots: 100, eventDays: 365 } } } }
+```
+
+Events live in the `blockscene_events` table (content type
+`plugin::blockscene.event`, hidden from the Content Manager and the Content-Type
+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.
+
 ## Languages
 
 All plugin chrome (gallery, settings, page preview, editor dialogs, diagnostics)
@@ -584,7 +722,7 @@ uploads share an origin.
 ## Development
 
 - `admin/`: shared gallery, settings page, wireframes and version-specific adapters.
-- `server/`: settings store, validation, permissions, the catalog endpoint and the layout-group publish guard (`groups.js` is shared with the admin).
+- `server/`: settings store, validation, permissions, the catalog endpoint and the layout-group publish guard (`groups.js` is shared with the admin); `history.js` and `diff.js` for version history (`diff.js` is shared with the admin).
 - `admin/translations/`: one flat catalogue per admin locale (English is the source of truth).
 - `scripts/capture-previews.mjs`: local thumbnail capture.
 - `packages/strapi4`, `packages/strapi5`: independently installable distributions.