@endora-commerce/mod-cms 0.101.1 → 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.
Files changed (53) hide show
  1. package/README.md +1 -1
  2. package/dist/admin/components/AdminCmsAssetProvider.d.ts +1 -1
  3. package/dist/admin/components/AdminCmsAssetProvider.d.ts.map +1 -1
  4. package/dist/admin/components/BackgroundFields.d.ts +1 -1
  5. package/dist/admin/components/BackgroundFields.d.ts.map +1 -1
  6. package/dist/admin/components/BackgroundFields.js +1 -1
  7. package/dist/admin/components/BackgroundFields.js.map +1 -1
  8. package/dist/admin/components/ButtonLinkFields.d.ts +1 -1
  9. package/dist/admin/components/ButtonLinkFields.d.ts.map +1 -1
  10. package/dist/admin/components/CarouselPreviewNav.js +1 -1
  11. package/dist/admin/components/CarouselPreviewNav.js.map +1 -1
  12. package/dist/admin/components/ComponentDragHandle.js +1 -1
  13. package/dist/admin/components/ComponentDragHandle.js.map +1 -1
  14. package/dist/admin/components/ContentSliderActionBarExtras.js +1 -1
  15. package/dist/admin/components/ContentSliderActionBarExtras.js.map +1 -1
  16. package/dist/admin/components/PageBuilderActionBar.js +1 -1
  17. package/dist/admin/components/PageBuilderActionBar.js.map +1 -1
  18. package/dist/admin/components/PageBuilderEditor.d.ts +2 -2
  19. package/dist/admin/components/PageBuilderEditor.d.ts.map +1 -1
  20. package/dist/admin/components/PageBuilderEditor.js +91 -44
  21. package/dist/admin/components/PageBuilderEditor.js.map +1 -1
  22. package/dist/admin/components/PuckActionGuard.d.ts +1 -1
  23. package/dist/admin/components/PuckActionGuard.d.ts.map +1 -1
  24. package/dist/admin/components/block-contributions.d.ts +74 -0
  25. package/dist/admin/components/block-contributions.d.ts.map +1 -0
  26. package/dist/admin/components/block-contributions.js +94 -0
  27. package/dist/admin/components/block-contributions.js.map +1 -0
  28. package/dist/admin/components/cms-template-layout.d.ts +1 -1
  29. package/dist/admin/components/cms-template-layout.d.ts.map +1 -1
  30. package/dist/admin/components/page-builder-i18n.d.ts +1 -1
  31. package/dist/admin/components/page-builder-i18n.d.ts.map +1 -1
  32. package/dist/admin/components/puck-safe.d.ts +1 -1
  33. package/dist/admin/components/puck-safe.d.ts.map +1 -1
  34. package/dist/admin-ui/index.d.ts +1 -1
  35. package/dist/admin-ui/index.js +1 -1
  36. package/dist/backend/index.d.ts +3 -0
  37. package/dist/backend/index.d.ts.map +1 -1
  38. package/dist/backend/index.js +2 -1
  39. package/dist/backend/index.js.map +1 -1
  40. package/dist/backend/plugin.d.ts +7 -0
  41. package/dist/backend/plugin.d.ts.map +1 -1
  42. package/dist/backend/plugin.js +1 -1
  43. package/dist/backend/plugin.js.map +1 -1
  44. package/dist/backend/services/cms-page-service.d.ts +36 -1
  45. package/dist/backend/services/cms-page-service.d.ts.map +1 -1
  46. package/dist/backend/services/cms-page-service.js +231 -114
  47. package/dist/backend/services/cms-page-service.js.map +1 -1
  48. package/dist/manifest.d.ts +2 -2
  49. package/docs/cms/extending-page-builder.md +579 -120
  50. package/docs/cms/index.md +6 -7
  51. package/i18n/en.json +1 -0
  52. package/i18n/pl.json +1 -0
  53. package/package.json +16 -16
@@ -7,151 +7,609 @@ sidebar_position: 2
7
7
 
8
8
  The CMS module ships built-in components — `Row`, `Columns`, `Text`,
9
9
  `Heading`, `Button`, `InsertBlock`, and others — but every other
10
- backend module can contribute its own components through an in-process
11
- service-provider interface (SPI). (`InsertTemplate` remains registered for
12
- legacy content trees but is no longer listed in the drawer palette.)
13
- A contributing module participates in three places:
14
-
15
- 1. **Backend descriptor**: register field metadata at composition time so
16
- the admin's component palette can render the editor controls.
17
- 2. **Shared renderer**: ship a React component to a workspace package both
18
- admin and storefront depend on (typically `@endora-commerce/cms-components` itself
19
- or a per-module package re-exporting from it).
20
- 3. **Composition wiring**: pass the contributing module's registration
21
- helper to the platform's composition root before the CMS plugin is
22
- instantiated.
23
-
24
- ## 1. Declare the descriptor
25
-
26
- In your module's `plugin.ts` (or a dedicated `register-page-builder.ts`),
27
- declare a function that takes the registry and registers your components:
10
+ backend module can contribute its own components. (`InsertTemplate` remains
11
+ registered for legacy content trees but is no longer listed in the drawer
12
+ palette.) The `cms`, `catalog`, `orders`, `invoices` and `transactional_emails`
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:
18
+
19
+ 1. **Manifest declaration**: declare the block's metadata — name, labels,
20
+ palette category, contexts and editable fields — in the module's own
21
+ `manifest.ts`. The CMS module builds its Page Builder registry from the
22
+ manifests of the composed modules, so there is no registration call to
23
+ write.
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.
26
+
27
+ ## 1. Declare the block in the manifest
28
+
29
+ Add `blocks` and `blockCategories` to your module manifest:
28
30
 
29
31
  ```ts
30
- // the promotions module: src/backend/services/register-page-builder.ts
31
- import type { PageBuilderRegistry } from '../../cms/services/page-builder-registry.js';
32
-
33
- export function registerPromotionsPageBuilderComponents(
34
- registry: PageBuilderRegistry,
35
- ): void {
36
- registry.register('promotions', {
37
- components: {
38
- PromoBanner: {
39
- fields: {
40
- headline: { type: 'text', label: 'Headline', required: true },
41
- codeInput: { type: 'text', label: 'Promo code' },
42
- tone: {
43
- type: 'select',
44
- label: 'Tone',
45
- options: [
46
- { label: 'Info', value: 'info' },
47
- { label: 'Urgent', value: 'urgent' },
48
- ],
49
- },
32
+ // the promotions module: src/manifest.ts
33
+ import { defineModuleManifest } from '@endora-commerce/contracts';
34
+
35
+ export const manifest = defineModuleManifest({
36
+ id: 'promotions',
37
+ // ...name, version, dependencies...
38
+ blocks: [
39
+ {
40
+ name: 'promotions.PromoBanner',
41
+ labelKey: 'blocks.promoBanner.label',
42
+ descriptionKey: 'blocks.promoBanner.description',
43
+ category: 'promotions',
44
+ /** Omit email/invoice — this component is storefront-only. */
45
+ contexts: ['cms'],
46
+ fields: {
47
+ headline: { type: 'text', label: 'Headline', required: true },
48
+ codeInput: { type: 'text', label: 'Promo code' },
49
+ tone: {
50
+ type: 'select',
51
+ label: 'Tone',
52
+ options: [
53
+ { label: 'Info', value: 'info' },
54
+ { label: 'Urgent', value: 'urgent' },
55
+ ],
50
56
  },
51
- previewIcon: 'ticket',
52
- /** Omit email/invoice — this component is storefront-only. */
53
- contexts: ['cms'],
54
57
  },
58
+ previewIcon: 'ticket',
59
+ weight: 10,
55
60
  },
56
- });
57
- }
61
+ ],
62
+ blockCategories: [
63
+ { key: 'promotions', titleKey: 'blocks.category.promotions', contexts: ['cms'] },
64
+ ],
65
+ });
58
66
  ```
59
67
 
68
+ The schema is `BlockDefinitionSchema` and `BlockCategorySchema` in
69
+ `packages/contracts/src/cms.ts` (both exported from
70
+ `@endora-commerce/contracts`). `defineModuleManifest` refuses a manifest
71
+ that breaks either of two rules:
72
+
73
+ - A block `name` is `<module id>.<PascalCaseName>`, and the part before the
74
+ dot must be the declaring module's own `id`. The name is written into the
75
+ stored page content and never rewritten, so choose it once.
76
+ - A block's `category` must be declared in the same manifest's
77
+ `blockCategories` for every context the block lists. Several modules may
78
+ declare the same category key; the palette merges them.
79
+
80
+ `labelKey`, `descriptionKey` and `titleKey` are relative to the declaring
81
+ module's own i18n bundle (`blocks.promoBanner.label`, not
82
+ `promotions.blocks.promoBanner.label`). Nothing can check that when the
83
+ manifest is defined, so get it right by hand.
84
+
60
85
  Field types are taken from the closed enum declared in
61
86
  `packages/contracts/src/cms.ts`: `text | textarea | number | select |
62
87
  radio | array | object | external | uuid | richtext`. This metadata is
63
88
  React-free; the backend never imports a renderer.
64
89
 
65
- ## 2. Ship the renderer
90
+ A block is offered only while its module is present: the registry filters
91
+ declarations by module presence when it answers
92
+ `GET /api/v1/admin/cms/page-builder/config`, so a module that is switched off
93
+ takes its blocks out of the palette with it.
94
+
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';
255
+
256
+ import { Badge } from './Badge.js';
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
+ ```
66
267
 
67
- Add a React `ComponentConfig` in `packages/cms-components/src/components/`
68
- (or in your module's own admin/storefront package) and export it from the
69
- package's entry point:
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:
70
271
 
272
+ <!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/storefront/Badge.tsx -->
71
273
  ```tsx
72
- // packages/cms-components/src/components/PromoBanner.tsx
73
- import type { ComponentConfig } from '@measured/puck';
274
+ 'use client';
275
+
276
+ import { useBlockRenderEnvironment } from '@endora-commerce/page-builder-core/contributions';
277
+ import type { ReactNode } from 'react';
74
278
 
75
- interface Props {
76
- headline: string;
77
- codeInput?: string;
78
- tone: 'info' | 'urgent';
279
+ export interface BadgeProps {
280
+ readonly text?: string;
281
+ readonly explode?: string | boolean;
79
282
  }
80
283
 
81
- export const PromoBanner: ComponentConfig<Props> = {
82
- fields: {
83
- headline: { type: 'text' },
84
- codeInput: { type: 'text' },
85
- tone: { type: 'select', options: [
86
- { label: 'Info', value: 'info' },
87
- { label: 'Urgent', value: 'urgent' },
88
- ] },
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';
370
+
371
+ interface BadgeProps {
372
+ readonly text?: string;
373
+ readonly explode?: string | boolean;
374
+ }
375
+
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
+ },
89
398
  },
90
- defaultProps: { headline: 'Spring sale', tone: 'info' },
91
- contexts: ['cms'],
92
- render: ({ headline, codeInput, tone }) => (
93
- <div className={`promo-banner promo-${tone}`}>
94
- <strong>{headline}</strong>
95
- {codeInput ? <code>{codeInput}</code> : null}
96
- </div>
97
- ),
98
399
  };
99
400
  ```
100
401
 
101
- Wire it into the `defaultPageBuilderConfig` so both the admin editor and
102
- 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`:
103
414
 
415
+ <!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/manifest.ts -->
104
416
  ```ts
105
- // packages/cms-components/src/index.ts
106
- import { PromoBanner } from './components/PromoBanner.js';
107
-
108
- export * from './components/PromoBanner.js';
109
-
110
- export const defaultPageBuilderConfig = {
111
- // ...existing categories
112
- components: {
113
- Row,
114
- Columns,
115
- Text,
116
- Heading,
117
- Button,
118
- InsertBlock,
119
- InsertTemplate,
120
- PromoBanner,
121
- },
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
+ ],
122
476
  };
123
477
  ```
124
478
 
125
- A renderer omitted from the bundle does not break the admin: the
126
- `PageBuilderEditor` merges the descriptor with the local config and
127
- substitutes a `MissingComponentPlaceholder` for any component the
128
- descriptor names but the bundle does not export. The placeholder renders
129
- nothing on the storefront unless the page is loaded with the
130
- `?cms_admin=1` query parameter (preview mode).
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:
131
481
 
132
- ## 3. Wire composition
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';
133
485
 
134
- Call your registration helper from `composition.ts` before the CMS module
135
- is instantiated:
486
+ import { Badge } from '../storefront/Badge.js';
136
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 -->
137
497
  ```ts
138
- // backend/src/composition.ts
139
- const cms = cmsModule({ emFactory, requireAdmin });
140
- registerPromotionsPageBuilderComponents(cms.handle.pageBuilderRegistry);
498
+ import { emailBlocks } from '../email/index.js';
499
+
500
+ export default emailBlocks['acceptance_blocks.Badge'];
141
501
  ```
142
502
 
143
- The CMS module's plugin reads the registry on every
144
- `GET /api/v1/admin/cms/page-builder/config` call, so registering after the
145
- module instance is constructed is fine — the editor picks the new
146
- component up on the next admin reload.
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
598
+
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.
147
604
 
148
605
  ## Component name namespacing
149
606
 
150
- Component names are unique platform-wide. The registry warns and
151
- overwrites on collisions; reviewers should reject changes that produce a
152
- warning. By convention, prefix names with the contributing module's
153
- domain when ambiguity is likely (`PromoBanner`, `CatalogProductCard`,
154
- etc.).
607
+ Block names are unique platform-wide, and the module-id prefix is what makes
608
+ them so: `cms.Text`, `catalog.ProductCard`, `promotions.PromoBanner`. Two
609
+ modules cannot declare the same name — the owner segment must be the
610
+ declaring module's id — and if a collision reaches the registry anyway it
611
+ throws `DuplicateBlockNameError` rather than letting one module's block
612
+ replace another's.
155
613
 
156
614
  ## Context availability (`contexts`)
157
615
 
@@ -165,16 +623,17 @@ Every component declares which Page Builder surfaces may expose it via
165
623
  | `newsletter` | Newsletter campaigns (alias of email-safe set) |
166
624
  | `invoice` | Invoice PDF template editor |
167
625
 
168
- Register on the backend descriptor:
626
+ Declare them on the block in the manifest. `contexts` is required and must
627
+ name at least one surface:
169
628
 
170
629
  ```ts
171
- contexts: ['cms'], // default when omitted in registry — CMS-only
630
+ contexts: ['cms'], // CMS-only
172
631
  ```
173
632
 
174
- In `@endora-commerce/cms-components`, wrap the Puck config with
175
- `definePageBuilderComponent` from `@endora-commerce/page-builder-core` so the admin
176
- palette filter stays in sync. Components without `email` / `invoice` in
177
- `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.
178
637
 
179
638
  ## Responsive props and visibility (CMS only)
180
639
 
@@ -242,7 +701,7 @@ Use `createSpacingField`, `createBorderField`, and `createColorField` from
242
701
 
243
702
  | Priority | Idea | Why |
244
703
  | -------- | ---- | --- |
245
- | Medium | Newsletter ↔ module 048 | Auto-wire channel subscribe endpoint |
704
+ | Medium | Newsletter signup ↔ the `newsletter` module | Auto-wire channel subscribe endpoint |
246
705
  | Low | Contact ↔ forms module | Pick an existing form instead of iframe URL |
247
706
 
248
707
  `Accordion` / `Tabs` already cover FAQ-style sections; prefer those before a
@@ -250,7 +709,7 @@ dedicated FAQ component.
250
709
 
251
710
  ## Testing
252
711
 
253
- The platform ships a TDD scaffold for the SPI in
254
- `backend/test/integration/cms/page-builder-extension.test.ts`. Use the
255
- fixture in `backend/test/fixtures/cms/test-extension-module.ts` as a
256
- 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.