@endora-commerce/mod-cms 0.102.0 → 0.103.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -10,17 +10,19 @@ The CMS module ships built-in components — `Row`, `Columns`, `Text`,
10
10
  backend module can contribute its own components. (`InsertTemplate` remains
11
11
  registered for legacy content trees but is no longer listed in the drawer
12
12
  palette.) The `cms`, `catalog`, `orders`, `invoices` and `transactional_emails`
13
- modules already contribute blocks this way. A contributing module participates in two
14
- places:
13
+ modules already declare their blocks this way. Their renderers are still the
14
+ built-in ones in `@endora-commerce/cms-components` and
15
+ `@endora-commerce/email-components`; a module package outside the platform
16
+ ships its own, as section 2 describes. A contributing module participates in
17
+ two places:
15
18
 
16
19
  1. **Manifest declaration**: declare the block's metadata — name, labels,
17
20
  palette category, contexts and editable fields — in the module's own
18
21
  `manifest.ts`. The CMS module builds its Page Builder registry from the
19
22
  manifests of the composed modules, so there is no registration call to
20
23
  write.
21
- 2. **Shared renderer**: ship a React component to a workspace package both
22
- admin and storefront depend on (typically `@endora-commerce/cms-components` itself
23
- or a per-module package re-exporting from it).
24
+ 2. **Renderers**: ship, in the module's own package, the code that draws the
25
+ block on the storefront, in e-mail and in the admin editors.
24
26
 
25
27
  ## 1. Declare the block in the manifest
26
28
 
@@ -64,7 +66,8 @@ export const manifest = defineModuleManifest({
64
66
  ```
65
67
 
66
68
  The schema is `BlockDefinitionSchema` and `BlockCategorySchema` in
67
- `packages/contracts/src/cms.ts`. `defineModuleManifest` refuses a manifest
69
+ `packages/contracts/src/cms.ts` (both exported from
70
+ `@endora-commerce/contracts`). `defineModuleManifest` refuses a manifest
68
71
  that breaks either of two rules:
69
72
 
70
73
  - A block `name` is `<module id>.<PascalCaseName>`, and the part before the
@@ -89,71 +92,515 @@ declarations by module presence when it answers
89
92
  `GET /api/v1/admin/cms/page-builder/config`, so a module that is switched off
90
93
  takes its blocks out of the palette with it.
91
94
 
92
- ## 2. Ship the renderer
95
+ ## 2. Ship the renderers
96
+
97
+ A module package draws its own blocks. It does so through up to three
98
+ **layers**, one per process that renders a block, plus an optional stylesheet.
99
+ Each is a subpath of the package's `exports` map, and each is optional: a
100
+ module whose blocks are e-mail-only ships the e-mail layer and nothing else.
101
+
102
+ | Subpath | What it exports | Who renders with it |
103
+ | --- | --- | --- |
104
+ | `./storefront` | `contributions` — React renderers for the module's `cms` blocks | the storefront, in the server-rendered HTML |
105
+ | `./email` | `emailBlocks` — pure functions that render the module's `email` blocks to HTML and text | the backend when it sends, and the admin's e-mail editor |
106
+ | `./admin` | `contributions.blocks` — editor renderers, beside the module's routes and zones | the admin's CMS and e-mail editors |
107
+ | `./blocks.css` | one finished stylesheet | the storefront and the admin editor |
108
+
109
+ This is for a module **package** — one a storefront and an instance install
110
+ from a registry. The platform's own modules do not ship these layers yet: their
111
+ `package.json` is generated, and the generator does not render the three
112
+ subpaths. An overlay module has no package; its blocks are covered under
113
+ [A block no package renders](#a-block-no-package-renders).
114
+
115
+ The examples below quote the platform's own acceptance fixture: a module
116
+ outside every platform package that ships all three layers and a stylesheet
117
+ for one block, `acceptance_blocks.Badge`.
118
+
119
+ ### The package
120
+
121
+ A surface finds the package by its own `package.json`:
122
+
123
+ <!-- verbatim-from: backend/acceptance/block-renderers-fixture/package.json -->
124
+ ```json
125
+ "files": [
126
+ "dist",
127
+ "i18n",
128
+ "blocks.css",
129
+ "tailwind.css"
130
+ ],
131
+ "endora": {
132
+ "type": "module",
133
+ "id": "acceptance_blocks"
134
+ },
135
+ "exports": {
136
+ ".": {
137
+ "types": "./dist/manifest.d.ts",
138
+ "default": "./dist/manifest.js"
139
+ },
140
+ "./backend": {
141
+ "types": "./dist/backend/index.d.ts",
142
+ "default": "./dist/backend/index.js"
143
+ },
144
+ "./admin": {
145
+ "types": "./dist/admin/index.d.ts",
146
+ "default": "./dist/admin/index.js"
147
+ },
148
+ "./storefront": {
149
+ "types": "./dist/storefront/index.d.ts",
150
+ "default": "./dist/storefront/index.js"
151
+ },
152
+ "./email": {
153
+ "types": "./dist/email/index.d.ts",
154
+ "default": "./dist/email/index.js"
155
+ },
156
+ "./blocks.css": "./blocks.css",
157
+ "./tailwind.css": "./tailwind.css",
158
+ "./i18n/*": "./i18n/*",
159
+ "./package.json": "./package.json"
160
+ ```
161
+
162
+ - **`endora.type` must be `module`, and `endora.id` the module id** that
163
+ prefixes its block names. A package without that block is not a module
164
+ package: `blocks:generate` says so in a note and registers nothing from it,
165
+ and its blocks render as placeholders.
166
+ - **`files` lists everything an `exports` entry points at** — `blocks.css` and
167
+ `tailwind.css` beside `dist`. An entry whose file is not in the tarball is
168
+ refused by the generator that would import it.
169
+ - **Each layer publishes type declarations** beside its JavaScript (the `types`
170
+ condition above). A storefront written in TypeScript imports `./storefront`
171
+ from its generated registry, and `blocks:generate` refuses a storefront layer
172
+ that ships none as `untyped-layer`.
173
+ - **A package with `./admin` also publishes `./tailwind.css`**, which tells the
174
+ admin's Tailwind build where the layer is. `endora generate` refuses an admin
175
+ layer without it. The fixture's is one line, quoted below the list.
176
+ - **The layers' imports are peer dependencies**: `@endora-commerce/contracts`,
177
+ `@endora-commerce/page-builder-core`, `@endora-commerce/email-components`,
178
+ `@puckeditor/core` and `react`, with `@endora-commerce/platform` for the
179
+ backend.
180
+ - **The build is plain `tsc`**, which keeps a leading `'use client'` and emits
181
+ the declarations. Relative imports are written with the `.js` extension.
182
+
183
+ <!-- verbatim-from: backend/acceptance/block-renderers-fixture/tailwind.css -->
184
+ ```css
185
+ @source "./dist/admin";
186
+ ```
187
+
188
+ Where the names in the examples come from:
189
+
190
+ | Name | Import it from |
191
+ | --- | --- |
192
+ | `StorefrontContributions`, `PageBuilderBlockEditorConfig`, `useBlockRenderEnvironment` | `@endora-commerce/page-builder-core/contributions` |
193
+ | `sanitizeRichHtml` | `@endora-commerce/cms-components` |
194
+ | `EmailBlockRenderers` | `@endora-commerce/email-components/render/block-renderers` |
195
+ | `escapeHtml`, `escapeAttr` | `@endora-commerce/email-components/render/escape-html` |
196
+ | `AdminContributions`, `EmailBlockRendererRegistryPort` | `@endora-commerce/contracts` |
197
+ | `ModuleContext`, `lazyPort` | `@endora-commerce/platform/kernel` |
198
+
199
+ ### The declaration the layers draw
200
+
201
+ The block is declared in the module's manifest, for both contexts it is drawn
202
+ in, in a palette section the same manifest declares for both:
203
+
204
+ <!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/manifest.ts -->
205
+ ```ts
206
+ blockCategories: [
207
+ { key: 'acceptance', titleKey: 'blocks.section', contexts: ['cms', 'email'], weight: 900 },
208
+ ],
209
+ blocks: [
210
+ {
211
+ // The persisted name — `<endora.id>.<Name>`, and permanent. Written as a
212
+ // literal: `endora check` reads a block's name and contexts off the
213
+ // manifest's text, and a name it cannot read is one it cannot hold a
214
+ // renderer to.
215
+ name: 'acceptance_blocks.Badge',
216
+ labelKey: 'blocks.badge.label',
217
+ descriptionKey: 'blocks.badge.description',
218
+ category: 'acceptance',
219
+ contexts: ['cms', 'email'],
220
+ fields: {
221
+ text: { type: 'text', label: 'Text' },
222
+ // Forces every renderer of this block to throw. It exists for the
223
+ // failure-isolation assertion and for nothing an operator would use.
224
+ explode: {
225
+ type: 'radio',
226
+ label: 'Fail on render',
227
+ options: [
228
+ { label: 'No', value: 'no' },
229
+ { label: 'Yes', value: 'yes' },
230
+ ],
231
+ },
232
+ },
233
+ defaultProps: { text: 'New badge', explode: 'no' },
234
+ weight: 10,
235
+ },
236
+ ],
237
+ ```
238
+
239
+ Every renderer is keyed by the block's full name, and a package renders only
240
+ the blocks **its own manifest declares**, for a context that block declares:
241
+ `cms` for the storefront and the CMS editor, `email` for e-mail. Write the name
242
+ and the contexts as literals, in the manifest and in each layer:
243
+ `check:block-renderers` reads them off the source text, and a name it cannot
244
+ read is one it cannot hold a renderer to. A computed renderer key escapes the
245
+ check and is refused when the surface composes it.
246
+
247
+ ### The storefront layer
248
+
249
+ `src/storefront/index.ts` exports `contributions`, a map from block name to a
250
+ Puck component config:
251
+
252
+ <!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/storefront/index.ts -->
253
+ ```ts
254
+ import type { StorefrontContributions } from '@endora-commerce/page-builder-core/contributions';
93
255
 
94
- Add a React `ComponentConfig` in `packages/cms-components/src/components/`
95
- (or in your module's own admin/storefront package) and export it from the
96
- package's entry point:
256
+ import { Badge } from './Badge.js';
97
257
 
258
+ export const contributions: StorefrontContributions = {
259
+ blocks: {
260
+ 'acceptance_blocks.Badge': {
261
+ defaultProps: { text: 'New badge', explode: 'no' },
262
+ render: Badge,
263
+ },
264
+ },
265
+ };
266
+ ```
267
+
268
+ The renderer is an ordinary React component. Its props are the block's stored
269
+ props, with the `defaultProps` above filled in underneath them — so a prop the
270
+ module added after a page was saved still has a value:
271
+
272
+ <!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/storefront/Badge.tsx -->
98
273
  ```tsx
99
- // packages/cms-components/src/components/PromoBanner.tsx
100
- import type { ComponentConfig } from '@puckeditor/core';
274
+ 'use client';
275
+
276
+ import { useBlockRenderEnvironment } from '@endora-commerce/page-builder-core/contributions';
277
+ import type { ReactNode } from 'react';
278
+
279
+ export interface BadgeProps {
280
+ readonly text?: string;
281
+ readonly explode?: string | boolean;
282
+ }
283
+
284
+ /**
285
+ * The renderer's one built-in string — a label that is not operator content —
286
+ * shipped in both languages inside the layer and chosen by the request's
287
+ * content language, with English as the fallback. The storefront's own
288
+ * catalogue belongs to the storefront's owner.
289
+ */
290
+ const LABEL: Readonly<Record<string, string>> = { en: 'Badge', pl: 'Odznaka' };
291
+
292
+ /**
293
+ * Synchronous, reads no browser global, and draws the same output on the
294
+ * server and on hydration for the same props: it is part of the
295
+ * server-rendered HTML.
296
+ */
297
+ export function Badge({ text, explode }: BadgeProps): ReactNode {
298
+ const { language } = useBlockRenderEnvironment();
299
+ if (explode === true || explode === 'yes') {
300
+ throw new Error('acceptance_blocks.Badge was asked to fail on render');
301
+ }
302
+ const label = LABEL[language.slice(0, 2).toLowerCase()] ?? LABEL['en'];
303
+ return (
304
+ <span className="acceptance_blocks-badge" title={label}>
305
+ {`acceptance-badge:${String(text ?? '')}`}
306
+ </span>
307
+ );
308
+ }
309
+ ```
310
+
311
+ A storefront renderer runs once on the server and once in the browser, so:
312
+
313
+ - it is **synchronous** — no `async` component — and reads no browser global
314
+ (`window`, `document`, `localStorage`) while rendering, only in an effect;
315
+ - it draws the same output on the server and in the browser for the same
316
+ props: no `Date.now()`, no `Math.random()`, no locale-dependent formatting
317
+ without the language from `useBlockRenderEnvironment()`;
318
+ - every file of the layer starts with `'use client'`. `check:block-renderers`
319
+ does not hold this one; a layer without it fails the storefront's build;
320
+ - it imports only `react`, `react-dom`, `@puckeditor/core`,
321
+ `@endora-commerce/page-builder-core`, `@endora-commerce/cms-components`,
322
+ `@endora-commerce/contracts` and its own files. Nothing server-only, no
323
+ admin kit, no platform, no other module. Data it needs comes from its props,
324
+ from the CMS render context, or from a fetch in an effect;
325
+ - block props are **untrusted input**: HTML is injected only as
326
+ `dangerouslySetInnerHTML={{ __html: sanitizeRichHtml(value) }}`;
327
+ - a label the renderer prints itself — one that is not the operator's content —
328
+ ships in English and Polish inside the layer and is chosen by
329
+ `useBlockRenderEnvironment().language`, with English as the fallback.
330
+
331
+ **Installing it in a storefront.** A storefront owner adds the package to
332
+ their storefront (`pnpm add`) and builds. `blocks:generate`, which the
333
+ storefront's `dev` and `build` scripts run, finds every installed module
334
+ package that declares `./storefront` or `./blocks.css` and writes the registry
335
+ and the stylesheet import — there is no line to add to any file.
336
+
337
+ When `endora install` writes an instance and a storefront in one run, it adds
338
+ the instance's modules that publish a storefront layer to the storefront's
339
+ dependencies, once. No platform module publishes one yet, so a default install
340
+ adds nothing; a package added to the instance afterwards is added to the
341
+ storefront by its owner.
342
+
343
+ What `blocks:generate` refuses, writing nothing and exiting 1:
344
+
345
+ | Refusal | Meaning |
346
+ | --- | --- |
347
+ | `untyped-layer` | the package publishes `./storefront` with no type declarations |
348
+ | `missing-layer-file` | an `exports` entry points at a file the package does not hold |
349
+ | `layer-without-subpath` | the package ships `src/storefront/index.ts` and declares no `./storefront` |
350
+ | `duplicate-module` | two installed packages declare the same module id |
351
+
352
+ #### A block no package renders
353
+
354
+ A storefront can also render a block itself — typically one an overlay module
355
+ of its own instance declares — by adding it to
356
+ `lib/page-builder/local-blocks.tsx`, the one file of the block registry that is
357
+ the storefront owner's. A local block never replaces a block a package or the
358
+ platform already renders.
359
+
360
+ ### The e-mail layer
361
+
362
+ `src/email/index.ts` exports `emailBlocks`. Each renderer is a pure function —
363
+ no React, no I/O — that returns rows of the e-mail's table layout and escapes
364
+ every prop:
365
+
366
+ <!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/email/index.ts -->
367
+ ```ts
368
+ import type { EmailBlockRenderers } from '@endora-commerce/email-components/render/block-renderers';
369
+ import { escapeHtml } from '@endora-commerce/email-components/render/escape-html';
101
370
 
102
- interface Props {
103
- headline: string;
104
- codeInput?: string;
105
- tone: 'info' | 'urgent';
371
+ interface BadgeProps {
372
+ readonly text?: string;
373
+ readonly explode?: string | boolean;
106
374
  }
107
375
 
108
- export const PromoBanner: ComponentConfig<Props> = {
109
- fields: {
110
- headline: { type: 'text' },
111
- codeInput: { type: 'text' },
112
- tone: { type: 'select', options: [
113
- { label: 'Info', value: 'info' },
114
- { label: 'Urgent', value: 'urgent' },
115
- ] },
376
+ function assertRenderable(props: BadgeProps): void {
377
+ if (props.explode === true || props.explode === 'yes') {
378
+ throw new Error('acceptance_blocks.Badge was asked to fail on render');
379
+ }
380
+ }
381
+
382
+ export const emailBlocks: EmailBlockRenderers = {
383
+ 'acceptance_blocks.Badge': {
384
+ defaultProps: { text: 'New badge' },
385
+ html: (props: BadgeProps, ctx) => {
386
+ assertRenderable(props);
387
+ return (
388
+ '<tr><td style="padding:8px 24px;font-family:Arial,Helvetica,sans-serif;">' +
389
+ `<span style="display:inline-block;padding:4px 10px;border-radius:6px;background-color:${ctx.accentColor};color:#ffffff;font-size:14px;font-weight:bold;">` +
390
+ `acceptance-badge:${escapeHtml(String(props.text ?? ''))}` +
391
+ '</span></td></tr>'
392
+ );
393
+ },
394
+ text: (props: BadgeProps) => {
395
+ assertRenderable(props);
396
+ return `acceptance-badge:${String(props.text ?? '')}\n`;
397
+ },
116
398
  },
117
- defaultProps: { headline: 'Spring sale', tone: 'info' },
118
- contexts: ['cms'],
119
- render: ({ headline, codeInput, tone }) => (
120
- <div className={`promo-banner promo-${tone}`}>
121
- <strong>{headline}</strong>
122
- {codeInput ? <code>{codeInput}</code> : null}
123
- </div>
124
- ),
125
399
  };
126
400
  ```
127
401
 
128
- Wire it into the `defaultPageBuilderConfig` under the block's full name, so
129
- both the admin editor and the storefront `<Render>` call sites pick it up:
402
+ `text` is optional; without it the plain-text part is derived from the HTML.
403
+ The second argument carries `accentColor`, the message's `language` — a label
404
+ the renderer prints itself follows it, as on the storefront — and
405
+ `renderSlot(nodes)`, which renders nested content with the platform's own
406
+ renderer. `{{var …}}` directives in the output are resolved afterwards,
407
+ exactly as in a built-in block. The layer imports only
408
+ `@endora-commerce/email-components/render/*`, `@endora-commerce/contracts` and
409
+ its own files, because the same function runs in the backend and in the
410
+ admin's browser.
411
+
412
+ The module's backend registers the renderers when the platform boots, and its
413
+ manifest names `email` in `dependencies`:
130
414
 
415
+ <!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/manifest.ts -->
131
416
  ```ts
132
- // packages/cms-components/src/index.ts
133
- import { PromoBanner } from './components/PromoBanner.js';
134
-
135
- export const defaultPageBuilderConfig: Config = {
136
- components: {
137
- // ...the existing 'cms.*' and 'catalog.*' entries
138
- 'promotions.PromoBanner': definePageBuilderComponent({
139
- ...(PromoBanner as unknown as ComponentConfig),
140
- contexts: ['cms'],
141
- }),
142
- },
417
+ // `email` owns the registry this module registers its e-mail renderer into.
418
+ // It is non-deactivatable, so the edge never fails closed.
419
+ dependencies: ['email'],
420
+ ```
421
+
422
+ <!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/backend/index.ts -->
423
+ ```ts
424
+ import type { EmailBlockRendererRegistryPort } from '@endora-commerce/contracts';
425
+ import { lazyPort, type ModuleContext } from '@endora-commerce/platform/kernel';
426
+
427
+ import { emailBlocks } from '../email/index.js';
428
+
429
+ /** This module persists nothing. */
430
+ export const entities = [] as const;
431
+
432
+ export function registerModule(ctx: ModuleContext): void {
433
+ // From a boot hook, unprobed: the registry is ungated and decides presence
434
+ // itself, per render, on the contributor recorded here — so switching this
435
+ // module off, or back on, needs no restart and no re-registration.
436
+ ctx.onBoot(() => {
437
+ lazyPort<EmailBlockRendererRegistryPort>(ctx, 'emailBlockRendererRegistry').register(
438
+ 'acceptance_blocks',
439
+ emailBlocks,
440
+ );
441
+ });
442
+ }
443
+ ```
444
+
445
+ `register` never throws. A name the module does not own, or an entry without an
446
+ `html` function, is refused with a warning in the backend log and listed in the
447
+ `refused` array the call returns — assert on that array in a test.
448
+
449
+ Transactional e-mail and newsletter campaigns both render through that
450
+ registry, and content holding the block can be saved in either. A built-in
451
+ e-mail block cannot be overridden: a contributed renderer is consulted only for
452
+ a name the platform does not draw itself.
453
+
454
+ ### The admin layer
455
+
456
+ The module's `./admin` layer — the one that already declares its routes and
457
+ zone contributions — lists an editor renderer per block and editor:
458
+
459
+ <!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/admin/index.ts -->
460
+ ```ts
461
+ import type { AdminContributions } from '@endora-commerce/contracts';
462
+
463
+ export const contributions: AdminContributions = {
464
+ blocks: [
465
+ {
466
+ name: 'acceptance_blocks.Badge',
467
+ context: 'cms',
468
+ component: () => import('./badge-editor.js'),
469
+ },
470
+ {
471
+ name: 'acceptance_blocks.Badge',
472
+ context: 'email',
473
+ component: () => import('./badge-email.js'),
474
+ },
475
+ ],
143
476
  };
144
477
  ```
145
478
 
146
- The CMS renderers are this one bundle (e-mail blocks render from
147
- `@endora-commerce/email-components` the same way). A module published
148
- outside this repository cannot add a renderer to either bundle without a
149
- change to that package.
479
+ For the CMS editor the default export is the block's renderer — usually the
480
+ storefront's own component, so the canvas shows what the storefront draws:
481
+
482
+ <!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/admin/badge-editor.tsx -->
483
+ ```tsx
484
+ import type { PageBuilderBlockEditorConfig } from '@endora-commerce/page-builder-core/contributions';
485
+
486
+ import { Badge } from '../storefront/Badge.js';
487
+
488
+ const editor: PageBuilderBlockEditorConfig = { render: Badge };
489
+
490
+ export default editor;
491
+ ```
492
+
493
+ For the e-mail editor it is the e-mail layer's renderer, the function the send
494
+ path runs, so the canvas and the preview cannot differ from the message:
495
+
496
+ <!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/admin/badge-email.ts -->
497
+ ```ts
498
+ import { emailBlocks } from '../email/index.js';
499
+
500
+ export default emailBlocks['acceptance_blocks.Badge'];
501
+ ```
502
+
503
+ The block's label, palette section, default props and field set come from the
504
+ manifest declaration, not from the contribution. A CMS editor config may carry
505
+ `fields` to replace the editor of a field the manifest declares — a picker in
506
+ place of a text input — and cannot add a field the manifest does not declare.
507
+
508
+ A declared block with **no** editor renderer is still insertable and editable:
509
+ the editor builds its fields from the manifest declaration and shows a neutral
510
+ preview that names the block. That is what an overlay module's block gets,
511
+ since an overlay module has no admin layer. In the e-mail editor such a block
512
+ is also absent from the HTML preview, although the backend renders it in the
513
+ message that is sent.
514
+
515
+ **Installing it in an instance.** The instance's owner adds the package to the
516
+ instance's dependencies and installs. Then:
517
+
518
+ 1. `pnpm run build:admin` — it runs `endora generate`, which names the
519
+ package's `./admin` in the admin's contribution registry and its
520
+ `./blocks.css` in the admin's stylesheet, and then builds the admin.
521
+ 2. `pnpm run module:install <module id>` — the module's lifecycle install,
522
+ which creates the Setting an operator switches it on and off with.
523
+ 3. Restart the backend. Its e-mail renderers are registered at boot.
524
+
525
+ There is no line to add to any file of the instance.
526
+
527
+ ### The block stylesheet
528
+
529
+ `./blocks.css` is one finished stylesheet. Every selector is under a class
530
+ prefixed with the module id, and colours and fonts come from the storefront's
531
+ theme custom properties with literal fallbacks, so the block follows the
532
+ channel's theme and still renders on the admin canvas:
533
+
534
+ <!-- verbatim-from: backend/acceptance/block-renderers-fixture/blocks.css -->
535
+ ```css
536
+ .acceptance_blocks-badge {
537
+ display: inline-block;
538
+ padding: 0.25rem 0.625rem;
539
+ border-radius: var(--r-md, 6px);
540
+ background: var(--brand-600, #2563eb);
541
+ color: #ffffff;
542
+ font-family: var(--font-sans, system-ui, sans-serif);
543
+ font-size: 0.875rem;
544
+ font-weight: 600;
545
+ line-height: 1.4;
546
+ }
547
+ ```
548
+
549
+ No `@import`, no `@tailwind`, no `@source`, no element selectors. The
550
+ storefront imports it through `blocks:generate` and the admin through
551
+ `endora generate`.
552
+
553
+ ### When the module is switched off
554
+
555
+ A block whose module an operator switched off is absent on every surface, and
556
+ nothing is written to the stored content:
557
+
558
+ | Surface | What happens |
559
+ | --- | --- |
560
+ | Storefront | the block renders nothing to a customer; with `?cms_admin=1` it renders a note naming the block |
561
+ | E-mail | the block contributes nothing to the HTML or the text; the message is still sent, and content holding the block can still be saved |
562
+ | Admin editors | a stored block is a visible placeholder that keeps its props; the block is not offered in the palette |
563
+
564
+ Switching the module back on restores all three, with no document changed in
565
+ between. The storefront decides from the modules the backend **reports** as not
566
+ present, so a block whose owner the backend does not know — an overlay
567
+ module's — still renders. The same holds for a package the storefront has
568
+ installed and the backend does not compose, and when the backend cannot be
569
+ reached nobody is reported absent.
570
+
571
+ ### When a renderer fails
572
+
573
+ A renderer that throws costs the page that one block. On the storefront and in
574
+ the editors it becomes the same placeholder a missing renderer gets, and the
575
+ blocks around it are untouched; in an e-mail it contributes nothing, the
576
+ message is still sent, and the failure is logged with the block and its
577
+ module.
578
+
579
+ ### Check the package
580
+
581
+ Run the check in the module package:
582
+
583
+ ```bash
584
+ pnpm exec endora check --rule check:block-renderers
585
+ ```
586
+
587
+ | Finding | Meaning |
588
+ | --- | --- |
589
+ | `foreign-block-name` | a renderer keyed by a block another module owns |
590
+ | `undeclared-block` | a renderer for a block the manifest does not declare, or not for that surface's context |
591
+ | `storefront-import` | the storefront layer imports outside its allowed set |
592
+ | `raw-html` | `dangerouslySetInnerHTML` whose value is not `sanitizeRichHtml(…)` |
593
+ | `email-layer-import` | the e-mail layer imports React, a Node built-in or anything outside the e-mail renderer |
594
+ | `unscoped-stylesheet` | `./blocks.css` has a selector outside the module's prefix, or pulls in another stylesheet |
595
+ | `layer-without-subpath` | a layer's sources exist and the `exports` map does not publish them |
596
+
597
+ ### Keep old content rendering
150
598
 
151
- A renderer omitted from the bundle does not break the admin: the
152
- `PageBuilderEditor` merges the descriptor with the local config and
153
- substitutes a `MissingComponentPlaceholder` for any component the
154
- descriptor names but the bundle does not export. The placeholder renders
155
- nothing on the storefront unless the page is loaded with the
156
- `?cms_admin=1` query parameter (preview mode).
599
+ A block's name is permanent, and its stored props outlive the version of the
600
+ module that wrote them. A renderer must draw every shape of props the module
601
+ ever published: ignore a prop it does not know, and fall back to a default for
602
+ one that is missing. A change that cannot be made that way is a new block
603
+ under a new name, with the old renderer kept.
157
604
 
158
605
  ## Component name namespacing
159
606
 
@@ -183,10 +630,10 @@ name at least one surface:
183
630
  contexts: ['cms'], // CMS-only
184
631
  ```
185
632
 
186
- In `@endora-commerce/cms-components`, wrap the Puck config with
187
- `definePageBuilderComponent` from `@endora-commerce/page-builder-core` so the admin
188
- palette filter stays in sync. Components without `email` / `invoice` in
189
- `contexts` never appear in those editors (e.g. a product carousel).
633
+ A block without `email` / `invoice` in `contexts` never appears in those
634
+ editors (e.g. a product carousel). A module ships renderers for the `cms` and
635
+ `email` contexts; `newsletter` shows the `email` blocks, and invoice blocks are
636
+ drawn by the invoices module.
190
637
 
191
638
  ## Responsive props and visibility (CMS only)
192
639
 
@@ -254,7 +701,7 @@ Use `createSpacingField`, `createBorderField`, and `createColorField` from
254
701
 
255
702
  | Priority | Idea | Why |
256
703
  | -------- | ---- | --- |
257
- | Medium | Newsletter ↔ module 048 | Auto-wire channel subscribe endpoint |
704
+ | Medium | Newsletter signup ↔ the `newsletter` module | Auto-wire channel subscribe endpoint |
258
705
  | Low | Contact ↔ forms module | Pick an existing form instead of iframe URL |
259
706
 
260
707
  `Accordion` / `Tabs` already cover FAQ-style sections; prefer those before a
@@ -262,7 +709,7 @@ dedicated FAQ component.
262
709
 
263
710
  ## Testing
264
711
 
265
- The platform ships a TDD scaffold for the SPI in
266
- `backend/test/integration/cms/page-builder-extension.test.ts`. Use the
267
- fixture in `backend/test/fixtures/cms/test-extension-module.ts` as a
268
- template when adding tests for your own contributions.
712
+ Use `backend/acceptance/block-renderers-fixture/` as the template for a package
713
+ that ships renderers, and `endora check` as its first test.
714
+ `backend/test/integration/cms/page-builder-extension.test.ts` covers the
715
+ declaration half: a manifest's blocks reaching the descriptor.
package/docs/cms/index.md CHANGED
@@ -216,11 +216,10 @@ mirrors; the asset-ref scan covers `body` for backward compatibility.
216
216
 
217
217
  ## Extending the Page Builder
218
218
 
219
- Other backend modules contribute components via the SPI in
220
- `packages/modules/cms/src/backend/services/page-builder-registry.ts`. See the
221
- [Extending the Page Builder](./extending-page-builder) guide for the
222
- end-to-end workflow: descriptor declaration, renderer shipping, and
223
- composition wiring.
219
+ Other modules declare their blocks in their own manifest and ship the renderers
220
+ in their own package. See the
221
+ [Extending the Page Builder](./extending-page-builder) guide: the manifest
222
+ declaration, the three renderer layers and the block stylesheet.
224
223
 
225
224
  ## Error codes
226
225
 
package/i18n/en.json CHANGED
@@ -39,6 +39,7 @@
39
39
  "status.draft": "Draft",
40
40
  "status.published": "Published",
41
41
  "pageBuilder.extensions": "Extensions",
42
+ "pageBuilder.blockPreview.unavailable": "This block has no preview in the editor. Its fields can be edited in the side panel.",
42
43
  "pageBuilder.loadingConfig": "Loading Page Builder config...",
43
44
  "pageBuilder.drawer.searchPlaceholder": "Search components…",
44
45
  "pageBuilder.drawer.searchEmpty": "No components match your search.",
package/i18n/pl.json CHANGED
@@ -39,6 +39,7 @@
39
39
  "status.draft": "Szkic",
40
40
  "status.published": "Opublikowana",
41
41
  "pageBuilder.extensions": "Rozszerzenia",
42
+ "pageBuilder.blockPreview.unavailable": "Ten blok nie ma podglądu w edytorze. Jego pola można edytować w panelu bocznym.",
42
43
  "pageBuilder.loadingConfig": "Ładowanie konfiguracji Page Builder...",
43
44
  "pageBuilder.drawer.searchPlaceholder": "Szukaj komponentów…",
44
45
  "pageBuilder.drawer.searchEmpty": "Brak komponentów pasujących do wyszukiwania.",