@endora-commerce/mod-cms 0.108.0 → 0.110.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 (254) hide show
  1. package/README.md +1 -0
  2. package/dist/admin/api/cms-client.d.ts +19 -3
  3. package/dist/admin/api/cms-client.d.ts.map +1 -1
  4. package/dist/admin/api/cms-client.js +23 -2
  5. package/dist/admin/api/cms-client.js.map +1 -1
  6. package/dist/admin/components/AdminCatalogPreviewProvider.d.ts +9 -0
  7. package/dist/admin/components/AdminCatalogPreviewProvider.d.ts.map +1 -1
  8. package/dist/admin/components/AdminCatalogPreviewProvider.js +88 -3
  9. package/dist/admin/components/AdminCatalogPreviewProvider.js.map +1 -1
  10. package/dist/admin/components/BackgroundFields.d.ts +16 -0
  11. package/dist/admin/components/BackgroundFields.d.ts.map +1 -1
  12. package/dist/admin/components/BackgroundFields.js +58 -11
  13. package/dist/admin/components/BackgroundFields.js.map +1 -1
  14. package/dist/admin/components/BrandFontFields.d.ts +17 -0
  15. package/dist/admin/components/BrandFontFields.d.ts.map +1 -0
  16. package/dist/admin/components/BrandFontFields.js +39 -0
  17. package/dist/admin/components/BrandFontFields.js.map +1 -0
  18. package/dist/admin/components/BrandPreview.d.ts +29 -0
  19. package/dist/admin/components/BrandPreview.d.ts.map +1 -0
  20. package/dist/admin/components/BrandPreview.js +130 -0
  21. package/dist/admin/components/BrandPreview.js.map +1 -0
  22. package/dist/admin/components/CarouselAddSlideMenu.d.ts +5 -0
  23. package/dist/admin/components/CarouselAddSlideMenu.d.ts.map +1 -0
  24. package/dist/admin/components/CarouselAddSlideMenu.js +84 -0
  25. package/dist/admin/components/CarouselAddSlideMenu.js.map +1 -0
  26. package/dist/admin/components/CarouselFields.d.ts +6 -0
  27. package/dist/admin/components/CarouselFields.d.ts.map +1 -0
  28. package/dist/admin/components/CarouselFields.js +55 -0
  29. package/dist/admin/components/CarouselFields.js.map +1 -0
  30. package/dist/admin/components/ContentSliderActionBarExtras.d.ts.map +1 -1
  31. package/dist/admin/components/ContentSliderActionBarExtras.js +13 -6
  32. package/dist/admin/components/ContentSliderActionBarExtras.js.map +1 -1
  33. package/dist/admin/components/FormBlockFields.d.ts +15 -0
  34. package/dist/admin/components/FormBlockFields.d.ts.map +1 -0
  35. package/dist/admin/components/FormBlockFields.js +23 -0
  36. package/dist/admin/components/FormBlockFields.js.map +1 -0
  37. package/dist/admin/components/HeroFields.d.ts +47 -0
  38. package/dist/admin/components/HeroFields.d.ts.map +1 -0
  39. package/dist/admin/components/HeroFields.js +92 -0
  40. package/dist/admin/components/HeroFields.js.map +1 -0
  41. package/dist/admin/components/ListingFields.d.ts +6 -0
  42. package/dist/admin/components/ListingFields.d.ts.map +1 -0
  43. package/dist/admin/components/ListingFields.js +54 -0
  44. package/dist/admin/components/ListingFields.js.map +1 -0
  45. package/dist/admin/components/NewsletterSignupFields.d.ts +18 -0
  46. package/dist/admin/components/NewsletterSignupFields.d.ts.map +1 -0
  47. package/dist/admin/components/NewsletterSignupFields.js +38 -0
  48. package/dist/admin/components/NewsletterSignupFields.js.map +1 -0
  49. package/dist/admin/components/PageBuilderActionBar.d.ts.map +1 -1
  50. package/dist/admin/components/PageBuilderActionBar.js +1 -6
  51. package/dist/admin/components/PageBuilderActionBar.js.map +1 -1
  52. package/dist/admin/components/PageBuilderEditor.d.ts +43 -2
  53. package/dist/admin/components/PageBuilderEditor.d.ts.map +1 -1
  54. package/dist/admin/components/PageBuilderEditor.js +218 -123
  55. package/dist/admin/components/PageBuilderEditor.js.map +1 -1
  56. package/dist/admin/components/PageNavigationFields.d.ts +6 -0
  57. package/dist/admin/components/PageNavigationFields.d.ts.map +1 -0
  58. package/dist/admin/components/PageNavigationFields.js +29 -0
  59. package/dist/admin/components/PageNavigationFields.js.map +1 -0
  60. package/dist/admin/components/PreviewBrandTokens.d.ts +25 -0
  61. package/dist/admin/components/PreviewBrandTokens.d.ts.map +1 -0
  62. package/dist/admin/components/PreviewBrandTokens.js +68 -0
  63. package/dist/admin/components/PreviewBrandTokens.js.map +1 -0
  64. package/dist/admin/components/SectionBlockFields.d.ts +44 -0
  65. package/dist/admin/components/SectionBlockFields.d.ts.map +1 -0
  66. package/dist/admin/components/SectionBlockFields.js +114 -0
  67. package/dist/admin/components/SectionBlockFields.js.map +1 -0
  68. package/dist/admin/components/SectionPresetsPanel.d.ts +11 -0
  69. package/dist/admin/components/SectionPresetsPanel.d.ts.map +1 -0
  70. package/dist/admin/components/SectionPresetsPanel.js +82 -0
  71. package/dist/admin/components/SectionPresetsPanel.js.map +1 -0
  72. package/dist/admin/components/SliderPreviewActionBarExtras.d.ts +1 -1
  73. package/dist/admin/components/SliderPreviewActionBarExtras.d.ts.map +1 -1
  74. package/dist/admin/components/SliderPreviewActionBarExtras.js +1 -5
  75. package/dist/admin/components/SliderPreviewActionBarExtras.js.map +1 -1
  76. package/dist/admin/components/admin-catalog-preview-map.d.ts +10 -1
  77. package/dist/admin/components/admin-catalog-preview-map.d.ts.map +1 -1
  78. package/dist/admin/components/admin-catalog-preview-map.js +11 -1
  79. package/dist/admin/components/admin-catalog-preview-map.js.map +1 -1
  80. package/dist/admin/components/block-contributions.d.ts +15 -0
  81. package/dist/admin/components/block-contributions.d.ts.map +1 -1
  82. package/dist/admin/components/block-contributions.js +22 -0
  83. package/dist/admin/components/block-contributions.js.map +1 -1
  84. package/dist/admin/components/page-builder-i18n.d.ts +24 -2
  85. package/dist/admin/components/page-builder-i18n.d.ts.map +1 -1
  86. package/dist/admin/components/page-builder-i18n.js +102 -9
  87. package/dist/admin/components/page-builder-i18n.js.map +1 -1
  88. package/dist/admin/editors/PageEditor.d.ts.map +1 -1
  89. package/dist/admin/editors/PageEditor.js +270 -38
  90. package/dist/admin/editors/PageEditor.js.map +1 -1
  91. package/dist/admin/index.d.ts +1 -1
  92. package/dist/admin/index.d.ts.map +1 -1
  93. package/dist/admin/index.js +28 -1
  94. package/dist/admin/index.js.map +1 -1
  95. package/dist/admin/pages/BrandPage.d.ts +19 -0
  96. package/dist/admin/pages/BrandPage.d.ts.map +1 -0
  97. package/dist/admin/pages/BrandPage.js +316 -0
  98. package/dist/admin/pages/BrandPage.js.map +1 -0
  99. package/dist/admin/pages/PagesListPage.d.ts.map +1 -1
  100. package/dist/admin/pages/PagesListPage.js +4 -1
  101. package/dist/admin/pages/PagesListPage.js.map +1 -1
  102. package/dist/admin/zones/ProductContentEditor.d.ts +27 -0
  103. package/dist/admin/zones/ProductContentEditor.d.ts.map +1 -0
  104. package/dist/admin/zones/ProductContentEditor.js +28 -0
  105. package/dist/admin/zones/ProductContentEditor.js.map +1 -0
  106. package/dist/backend/cli/block-names.d.ts +2 -1
  107. package/dist/backend/cli/block-names.d.ts.map +1 -1
  108. package/dist/backend/cli/block-names.js.map +1 -1
  109. package/dist/backend/entities/cms-brand-tokens.entity.d.ts +20 -0
  110. package/dist/backend/entities/cms-brand-tokens.entity.d.ts.map +1 -0
  111. package/dist/backend/entities/cms-brand-tokens.entity.js +57 -0
  112. package/dist/backend/entities/cms-brand-tokens.entity.js.map +1 -0
  113. package/dist/backend/entities/cms-page.entity.d.ts +32 -1
  114. package/dist/backend/entities/cms-page.entity.d.ts.map +1 -1
  115. package/dist/backend/entities/cms-page.entity.js +63 -0
  116. package/dist/backend/entities/cms-page.entity.js.map +1 -1
  117. package/dist/backend/index.d.ts +8 -1
  118. package/dist/backend/index.d.ts.map +1 -1
  119. package/dist/backend/index.js +90 -10
  120. package/dist/backend/index.js.map +1 -1
  121. package/dist/backend/plugin.d.ts +18 -2
  122. package/dist/backend/plugin.d.ts.map +1 -1
  123. package/dist/backend/plugin.js +23 -1
  124. package/dist/backend/plugin.js.map +1 -1
  125. package/dist/backend/routes.admin.d.ts +2 -0
  126. package/dist/backend/routes.admin.d.ts.map +1 -1
  127. package/dist/backend/routes.admin.js +42 -8
  128. package/dist/backend/routes.admin.js.map +1 -1
  129. package/dist/backend/routes.storefront.d.ts +24 -1
  130. package/dist/backend/routes.storefront.d.ts.map +1 -1
  131. package/dist/backend/routes.storefront.js +55 -2
  132. package/dist/backend/routes.storefront.js.map +1 -1
  133. package/dist/backend/services/anchor-guard.d.ts +10 -0
  134. package/dist/backend/services/anchor-guard.d.ts.map +1 -0
  135. package/dist/backend/services/anchor-guard.js +132 -0
  136. package/dist/backend/services/anchor-guard.js.map +1 -0
  137. package/dist/backend/services/asset-embed-resolver.d.ts +18 -10
  138. package/dist/backend/services/asset-embed-resolver.d.ts.map +1 -1
  139. package/dist/backend/services/asset-embed-resolver.js +35 -30
  140. package/dist/backend/services/asset-embed-resolver.js.map +1 -1
  141. package/dist/backend/services/asset-references.d.ts.map +1 -1
  142. package/dist/backend/services/asset-references.js +46 -30
  143. package/dist/backend/services/asset-references.js.map +1 -1
  144. package/dist/backend/services/brand-tokens-service.d.ts +84 -0
  145. package/dist/backend/services/brand-tokens-service.d.ts.map +1 -0
  146. package/dist/backend/services/brand-tokens-service.js +159 -0
  147. package/dist/backend/services/brand-tokens-service.js.map +1 -0
  148. package/dist/backend/services/channel-language-prefixes.d.ts +11 -0
  149. package/dist/backend/services/channel-language-prefixes.d.ts.map +1 -0
  150. package/dist/backend/services/channel-language-prefixes.js +24 -0
  151. package/dist/backend/services/channel-language-prefixes.js.map +1 -0
  152. package/dist/backend/services/cms-block-read-port.d.ts.map +1 -1
  153. package/dist/backend/services/cms-block-read-port.js +3 -0
  154. package/dist/backend/services/cms-block-read-port.js.map +1 -1
  155. package/dist/backend/services/cms-block-service.d.ts.map +1 -1
  156. package/dist/backend/services/cms-block-service.js +7 -1
  157. package/dist/backend/services/cms-block-service.js.map +1 -1
  158. package/dist/backend/services/cms-cache.d.ts +10 -0
  159. package/dist/backend/services/cms-cache.d.ts.map +1 -1
  160. package/dist/backend/services/cms-cache.js +9 -0
  161. package/dist/backend/services/cms-cache.js.map +1 -1
  162. package/dist/backend/services/cms-content-invalidator.d.ts +13 -4
  163. package/dist/backend/services/cms-content-invalidator.d.ts.map +1 -1
  164. package/dist/backend/services/cms-content-invalidator.js +13 -6
  165. package/dist/backend/services/cms-content-invalidator.js.map +1 -1
  166. package/dist/backend/services/cms-hook-service.d.ts.map +1 -1
  167. package/dist/backend/services/cms-hook-service.js +6 -1
  168. package/dist/backend/services/cms-hook-service.js.map +1 -1
  169. package/dist/backend/services/cms-page-read-port.d.ts +12 -1
  170. package/dist/backend/services/cms-page-read-port.d.ts.map +1 -1
  171. package/dist/backend/services/cms-page-read-port.js +49 -0
  172. package/dist/backend/services/cms-page-read-port.js.map +1 -1
  173. package/dist/backend/services/cms-page-service.d.ts +79 -1
  174. package/dist/backend/services/cms-page-service.d.ts.map +1 -1
  175. package/dist/backend/services/cms-page-service.js +344 -19
  176. package/dist/backend/services/cms-page-service.js.map +1 -1
  177. package/dist/backend/services/cms-template-service.d.ts.map +1 -1
  178. package/dist/backend/services/cms-template-service.js +7 -1
  179. package/dist/backend/services/cms-template-service.js.map +1 -1
  180. package/dist/backend/services/contact-form/contact-form-mail.d.ts +22 -0
  181. package/dist/backend/services/contact-form/contact-form-mail.d.ts.map +1 -0
  182. package/dist/backend/services/contact-form/contact-form-mail.js +64 -0
  183. package/dist/backend/services/contact-form/contact-form-mail.js.map +1 -0
  184. package/dist/backend/services/contact-form/contact-form.service.d.ts +35 -0
  185. package/dist/backend/services/contact-form/contact-form.service.d.ts.map +1 -0
  186. package/dist/backend/services/contact-form/contact-form.service.js +75 -0
  187. package/dist/backend/services/contact-form/contact-form.service.js.map +1 -0
  188. package/dist/backend/services/contact-form/recipients-validator.d.ts +8 -0
  189. package/dist/backend/services/contact-form/recipients-validator.d.ts.map +1 -0
  190. package/dist/backend/services/contact-form/recipients-validator.js +23 -0
  191. package/dist/backend/services/contact-form/recipients-validator.js.map +1 -0
  192. package/dist/backend/services/content-tree-walker.d.ts +12 -0
  193. package/dist/backend/services/content-tree-walker.d.ts.map +1 -1
  194. package/dist/backend/services/content-tree-walker.js +40 -0
  195. package/dist/backend/services/content-tree-walker.js.map +1 -1
  196. package/dist/backend/services/page-builder-registry.d.ts +11 -2
  197. package/dist/backend/services/page-builder-registry.d.ts.map +1 -1
  198. package/dist/backend/services/page-builder-registry.js +10 -1
  199. package/dist/backend/services/page-builder-registry.js.map +1 -1
  200. package/dist/backend/services/page-paths.d.ts +87 -0
  201. package/dist/backend/services/page-paths.d.ts.map +1 -0
  202. package/dist/backend/services/page-paths.js +177 -0
  203. package/dist/backend/services/page-paths.js.map +1 -0
  204. package/dist/backend/services/reserved-segment-registry.d.ts +16 -0
  205. package/dist/backend/services/reserved-segment-registry.d.ts.map +1 -0
  206. package/dist/backend/services/reserved-segment-registry.js +31 -0
  207. package/dist/backend/services/reserved-segment-registry.js.map +1 -0
  208. package/dist/backend/services/storefront-resolver.d.ts +58 -3
  209. package/dist/backend/services/storefront-resolver.d.ts.map +1 -1
  210. package/dist/backend/services/storefront-resolver.js +314 -29
  211. package/dist/backend/services/storefront-resolver.js.map +1 -1
  212. package/dist/backend/services/translation/extract.d.ts.map +1 -1
  213. package/dist/backend/services/translation/extract.js +9 -1
  214. package/dist/backend/services/translation/extract.js.map +1 -1
  215. package/dist/manifest.d.ts +19 -1
  216. package/dist/manifest.d.ts.map +1 -1
  217. package/dist/manifest.js +592 -73
  218. package/dist/manifest.js.map +1 -1
  219. package/dist/migrations/20261022T163218_cms_brand_tokens.d.ts +24 -0
  220. package/dist/migrations/20261022T163218_cms_brand_tokens.d.ts.map +1 -0
  221. package/dist/migrations/20261022T163218_cms_brand_tokens.js +38 -0
  222. package/dist/migrations/20261022T163218_cms_brand_tokens.js.map +1 -0
  223. package/dist/migrations/20261023T052237_cms_page_tree_and_share.d.ts +24 -0
  224. package/dist/migrations/20261023T052237_cms_page_tree_and_share.d.ts.map +1 -0
  225. package/dist/migrations/20261023T052237_cms_page_tree_and_share.js +51 -0
  226. package/dist/migrations/20261023T052237_cms_page_tree_and_share.js.map +1 -0
  227. package/dist/migrations/20261027T165458_cms_page_parent_path_in_url.d.ts +16 -0
  228. package/dist/migrations/20261027T165458_cms_page_parent_path_in_url.d.ts.map +1 -0
  229. package/dist/migrations/20261027T165458_cms_page_parent_path_in_url.js +20 -0
  230. package/dist/migrations/20261027T165458_cms_page_parent_path_in_url.js.map +1 -0
  231. package/dist/migrations/20261028T090524_cms_page_breadcrumbs_overlay.d.ts +14 -0
  232. package/dist/migrations/20261028T090524_cms_page_breadcrumbs_overlay.d.ts.map +1 -0
  233. package/dist/migrations/20261028T090524_cms_page_breadcrumbs_overlay.js +18 -0
  234. package/dist/migrations/20261028T090524_cms_page_breadcrumbs_overlay.js.map +1 -0
  235. package/dist/migrations/20261029T131218_cms_page_translations.d.ts +15 -0
  236. package/dist/migrations/20261029T131218_cms_page_translations.d.ts.map +1 -0
  237. package/dist/migrations/20261029T131218_cms_page_translations.js +19 -0
  238. package/dist/migrations/20261029T131218_cms_page_translations.js.map +1 -0
  239. package/dist/migrations/index.d.ts +6 -1
  240. package/dist/migrations/index.d.ts.map +1 -1
  241. package/dist/migrations/index.js +11 -1
  242. package/dist/migrations/index.js.map +1 -1
  243. package/docs/cms/brand.md +310 -0
  244. package/docs/cms/contact-form.md +161 -0
  245. package/docs/cms/extending-page-builder.md +210 -15
  246. package/docs/cms/index.md +1232 -39
  247. package/docs/cms/page-navigation.md +83 -0
  248. package/i18n/en.json +2787 -45
  249. package/i18n/pl.json +2765 -23
  250. package/package.json +20 -18
  251. package/dist/admin/components/ButtonLinkFields.d.ts +0 -6
  252. package/dist/admin/components/ButtonLinkFields.d.ts.map +0 -1
  253. package/dist/admin/components/ButtonLinkFields.js +0 -127
  254. package/dist/admin/components/ButtonLinkFields.js.map +0 -1
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  title: Extending the Page Builder
3
- sidebar_position: 2
3
+ sidebar_position: 3
4
4
  ---
5
5
 
6
6
  # Extending the Page Builder
@@ -9,8 +9,8 @@ The CMS module ships built-in components — `Row`, `Columns`, `Text`,
9
9
  `Heading`, `Button`, `InsertBlock`, and others — but every other
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
- palette.) The `cms`, `catalog`, `orders`, `invoices` and `transactional_emails`
13
- modules already declare their blocks this way. Their renderers are still the
12
+ palette.) The `cms`, `catalog`, `blog`, `newsletter`, `orders`, `invoices` and
13
+ `transactional_emails` modules already declare their blocks this way. Their renderers are still the
14
14
  built-in ones in `@endora-commerce/cms-components` and
15
15
  `@endora-commerce/email-components`; a module package outside the platform
16
16
  ships its own, as section 2 describes. A contributing module participates in
@@ -604,6 +604,11 @@ nothing is written to the stored content:
604
604
  | 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 |
605
605
  | Admin editors | a stored block is a visible placeholder that keeps its props; the block is not offered in the palette |
606
606
 
607
+ The editors find a stored block by its place in the document — an object with
608
+ a `type` beside its `props` — so the nodes inside a rich-text value (a
609
+ paragraph, an image, a mark) are never taken for blocks and never become
610
+ placeholders.
611
+
607
612
  Switching the module back on restores all three, with no document changed in
608
613
  between. The storefront decides from the modules the backend **reports** as not
609
614
  present, so a block whose owner the backend does not know — an overlay
@@ -692,6 +697,17 @@ Default breakpoints (configurable via Settings
692
697
  - Tablet: 768–1023px
693
698
  - Desktop: ≥ 1024px
694
699
 
700
+ A responsive value is stored either plain (one value for every breakpoint) or
701
+ as `{ base, tablet?, desktop? }`, where `base` is the mobile value. The editor
702
+ always writes `base`. A value written without it — through the API or an
703
+ import, for example `{ "desktop": 2 }` — means **no value below the first
704
+ breakpoint that has one**: the breakpoints below render as if the option were
705
+ unset, and that breakpoint and the ones above it take the value.
706
+ `normalizeResponsive` and `resolveResponsive` from
707
+ `@endora-commerce/page-builder-core` read it that way, so a renderer that goes
708
+ through them needs nothing more; an object whose keys are not only `base`,
709
+ `tablet` and `desktop` is a plain value, never a responsive one.
710
+
695
711
  Email and invoice builders use a single layout width and do not expose
696
712
  responsive fields.
697
713
 
@@ -703,7 +719,11 @@ fields reuse the CMS color palette.
703
719
  ## Nesting (slots)
704
720
 
705
721
  Layout components (`Row`, `Columns`) use Puck **slot** fields — nested
706
- content is stored in `props`, not the legacy `zones` map.
722
+ content is stored in `props`, not the legacy `zones` map. Since feature 163 the
723
+ panels of `cms.Tabs` and `cms.Accordion` are slots too (`items[].panel`, which
724
+ refuses `cms.Column`, `cms.Tabs` and `cms.Accordion`), and the Carousel's
725
+ `slides` slot takes the four carousel item blocks besides `cms.Slide`. Do not
726
+ declare a slot prop as `translatable`: the blocks inside it declare their own.
707
727
 
708
728
  ## Box model (CMS layout + content)
709
729
 
@@ -715,6 +735,183 @@ count (1–12 per breakpoint) with equal-width tracks.
715
735
  Use `createSpacingField`, `createBorderField`, and `createColorField` from
716
736
  `@endora-commerce/page-builder-core` when adding new CMS components.
717
737
 
738
+ ## Sections
739
+
740
+ Section settings — anchor, colour scheme, background, spacing, width, content
741
+ position and entrance reveal — live on one block, **`cms.Section`**, as its own
742
+ top-level props beside a slot that holds any other blocks (the CMS module page
743
+ describes what an editor sees): `anchor`, `scheme`, `background`, `width`,
744
+ `customMaxWidthPx`, `reveal`, and per breakpoint `spaceTop`, `spaceBottom` and
745
+ `contentPosition`. The three per-breakpoint props are the block's
746
+ `responsiveFields`; their fields carry `PB_RESPONSIVE_METADATA`, so the editor
747
+ shows them on its Responsive tab and they edit the breakpoint its scope
748
+ switcher selects. `@endora-commerce/page-builder-core` exports the custom
749
+ fields the plain Puck ones cannot express — `createSectionBackgroundField`,
750
+ `createSectionSpaceField` (responsive), `createSectionAnchorField`,
751
+ `createSectionRevealField` — and `isSectionBackgroundField`, by which the
752
+ admin gives the background its asset picker. No other block carries section
753
+ settings: a block outside a Section renders exactly as it does on its own, and
754
+ a full-bleed look is a Section with the **Bleed** or **Full** width around the
755
+ block.
756
+
757
+ An aspect ratio per breakpoint as a block's own prop (`cms.Video.aspectRatio`,
758
+ `cms.Image.ratio`) is `createAspectRatioField({ label, defaultRatio, allowAuto })`
759
+ from the same package: a responsive field on the Responsive tab, offering every
760
+ aspect token and a custom `w:h`. A ratio nested in a composite value (the
761
+ hero's or the media-and-text video) uses `ResponsiveRatioControl` from
762
+ `@endora-commerce/page-builder-admin`, the image field's in-field switch.
763
+
764
+ A Section stands only at the top level of a page:
765
+
766
+ - every slot of every block refuses it — list `cms.Section` in a new slot's
767
+ `disallow` (or leave it out of its `allow`), as the built-in slots do;
768
+ - the editor guard `shouldRevertPuckAction` from
769
+ `@endora-commerce/page-builder-core/editor/puck-guards` reverts an insert or
770
+ a move of a root-only block (`ROOT_ONLY_TYPES`) into any zone but the page's
771
+ own list;
772
+ - a Section stored nested anyway renders its children with no section wrapper.
773
+
774
+ The one exception is **`cms.SectionGroup`**, a top-level container whose slot
775
+ `allow`s `cms.Section` only. It is root-only too (in `ROOT_ONLY_TYPES`, so list
776
+ it beside `cms.Section` in a new slot's `disallow`); the guard lets a Section
777
+ into a group's `content` zone and nothing else
778
+ (`isSectionGroupContentZone`, `SECTION_GROUP_CHILD_TYPES`). It renders through
779
+ `SectionGroupFrame`: a `<div class="cmsc-section-group">` with the group's
780
+ anchor, scheme and spacing (`--cmsc-group-p(t|b)(-md|-lg)`) and one
781
+ `.cmsc-section-group__paint` layer — scheme background, paint, media and the
782
+ decorative layer, spanning the window — behind all its Sections. A Section in
783
+ it renders as a top-level Section (`data-in-group`), transparent
784
+ (`data-transparent`) when the group paints and the Section has no background
785
+ of its own and no other scheme.
786
+
787
+ The block renders through `SectionFrame` from `@endora-commerce/cms-components`,
788
+ which at the top level (or directly in a top-level group) draws
789
+ `<section class="cmsc-section" id=… data-cmsb-scheme=… data-width=…>` with the
790
+ background layer, the padding and the content frame, and nested elsewhere
791
+ renders the children only. An image background is a `<picture>` (`object-fit`
792
+ `cover`, or `contain`) unless its `size` is `auto`, px or % or it has a
793
+ `repeat`: then it is one `.cmsc-section__tile` in the media layer, painted as a
794
+ CSS background from `--cmsc-tile-image` (`--cmsc-tile-image-mobile` below
795
+ 768 px). The decorative layer's `decorativeSize`, `decorativeRepeat` and
796
+ `decorativePosition` are written inline on the section or the group's paint.
797
+
798
+ A renderer that needs to know where it stands reads `useSectionContext()` from
799
+ `@endora-commerce/page-builder-core`: `{depth, topLevel}`. The hero uses it to
800
+ load its media eagerly only as the page's lead block — the first top-level
801
+ block, the first block of a first top-level Section, or the first block of the
802
+ first Section of a first top-level Section group. The depth comes from
803
+ `withHideOn`, which every block carries; `EmbeddedBlockDepth` lets
804
+ `cms.InsertBlock` render an embedded tree at its own depth, so a Section in an
805
+ embed at the top level is a section and the same embed inside a column is not.
806
+ A block that sends the visitor back to the page reads `useSectionAnchor()` for
807
+ the anchor of the Section it stands in; `newsletter.Signup` does.
808
+
809
+ ## Brand variables (`--cmsb-*`)
810
+
811
+ The brand settings reach the page as CSS custom properties prefixed
812
+ `--cmsb-` — colours, the scheme colours, fonts, the type scale, button shape,
813
+ spacing and widths. The full list is on the CMS module's Brand settings page.
814
+ A block stylesheet that should follow the brand reads them, **always with a
815
+ literal fallback**:
816
+
817
+ ```css
818
+ .acme_promotions-banner {
819
+ color: var(--cmsb-fg, #15202b);
820
+ background: var(--cmsb-bg, #ffffff);
821
+ border: 1px solid var(--cmsb-border, #d9e0e7);
822
+ font-family: var(--cmsb-font-body, Inter, system-ui, sans-serif);
823
+ padding-block: var(--cmsb-space-m, 24px);
824
+ }
825
+ .acme_promotions-banner__cta {
826
+ background: var(--cmsb-color-primary, #1261a6);
827
+ color: var(--cmsb-color-on-primary, #ffffff);
828
+ border-radius: var(--cmsb-btn-radius, 8px);
829
+ }
830
+ ```
831
+
832
+ - The fallback is what the block looks like with no brand settings — the
833
+ `cms` module switched off, a failed read, or a surface that does not inject
834
+ them, such as the e-mail editor. Use the value the block had before it read
835
+ the variable, so introducing the variable changes nothing on an instance
836
+ that never opens the Brand screen.
837
+ - Read the scheme variables (`--cmsb-fg`, `--cmsb-bg`, `--cmsb-fg-muted`,
838
+ `--cmsb-border`, `--cmsb-link`) rather than fixed colours for text and
839
+ borders. A Section with a colour scheme rebinds them, so the block follows a
840
+ dark Section with no code of its own.
841
+ - A colour prop may hold a brand colour reference, `token:<role>`.
842
+ `resolveColorValue(value)` from `@endora-commerce/page-builder-core` turns it
843
+ into `var(--cmsb-color-<role>, <built-in>)` and leaves a hex value as it is.
844
+ - The built-in blocks follow the same rule:
845
+ `packages/cms-components/src/brand/fallback-parity.test.tsx` renders them with
846
+ no brand settings and compares the result with the values they had before.
847
+
848
+ ## Server-read data: the block-data seam
849
+
850
+ A block that shows data from another module — products, categories, blog posts
851
+ — must have that data in the server-rendered HTML (Principle VII), so the read
852
+ is lifted out of the block:
853
+
854
+ 1. The block **declares** its request as data. The kinds are a closed union in
855
+ `@endora-commerce/cms-components/utils/block-data`
856
+ (`packages/cms-components/src/utils/block-data.ts`):
857
+ `products-by-slugs`, `products-list` and `categories` (owner `catalog`) and
858
+ `blog-posts` (owner `blog`).
859
+ 2. The storefront **resolves** every request on the page before rendering —
860
+ `resolveBlockDataFor(documents, ctx, modules)` in
861
+ `storefront/lib/page-builder/block-data.ts`, mounted through
862
+ `storefront/components/BlockData.tsx` — and skips a request whose owner
863
+ module is absent (`blockDataOwnerOf`), so a module that is switched off costs
864
+ the page nothing. A failed read is left out; the block renders its empty
865
+ state and the rest of the page is unaffected.
866
+ 3. The block **reads** its answer with `useBlockData(request)` from
867
+ `@endora-commerce/cms-components/hooks/use-block-data` (the key is
868
+ `blockDataKey(request)`). In the admin editor, which has no server render,
869
+ the same hook fetches through the preview readers that
870
+ `AdminCatalogPreviewProvider` registers.
871
+
872
+ The seam was catalog-only before feature 163 and was generalised for
873
+ `blog.LatestPosts`. Its old subpath,
874
+ `@endora-commerce/cms-components/utils/catalog-block-data`, is kept as a
875
+ **deprecated** re-export under the old names (`collectCatalogBlockDataRequests`,
876
+ `resolveCatalogBlockData`, `CatalogBlockDataSource` and the rest), because a
877
+ storefront created by an earlier release imports it. New code imports
878
+ `utils/block-data`.
879
+
880
+ The union is closed: a module package cannot add a request kind of its own
881
+ today. A module-owned server-data hook is on the follow-up list below.
882
+
883
+ ## Changing a block that is already in use: extend, don't narrow
884
+
885
+ A built-in block may be reshaped, but an editor must never lose an option they
886
+ had. Feature 163 reshaped the hero, heading, button, feature list, stats,
887
+ testimonial, tabs, accordion, carousel and product listings under these
888
+ rules, and a block author changing any block should apply them too:
889
+
890
+ 1. **Keep a superset of the options.** Every field the block had keeps the same
891
+ or an equivalent control. Ask of every change: "what can an editor do
892
+ before this change that they cannot do after it?" — the answer must be
893
+ "nothing".
894
+ 2. **Tokens are defaults, not a cage.** Where a block starts reading a brand
895
+ token (size, font, colour, spacing), keep a **Custom** literal override (px,
896
+ hex, font family) in an "Advanced" group.
897
+ 3. **Neutral defaults.** New props default to today's look: no overlay
898
+ without media, start alignment unless the block was centred, section
899
+ headings at `h2`/`h3` sizes, one primary button.
900
+ 4. **Old content keeps rendering.** Map the earlier props to the new shape in
901
+ a pure function (the built-in blocks call it `<block>FromLegacy`), apply it
902
+ when rendering and in the block's `resolveData`, and make it idempotent. A
903
+ stored page then renders as before, and the editor converts it the next
904
+ time it is opened (see *Keep old content rendering* above).
905
+ 5. **Prove it.** Add the block's case to the option-parity test,
906
+ `packages/cms-components/src/components/option-parity.test.ts`, before the
907
+ reshape: it records the fields the block had as literals and fails while
908
+ any of them has no counterpart. Add the block's default render to the
909
+ fallback-parity test.
910
+ 6. **Remove a block only with a full equivalent.** `cms.ImageSlider` was
911
+ removed only once its parity case showed that **Carousel image** items carry
912
+ every option it had. Stored content of a removed block degrades to the
913
+ missing-block placeholder; the name is never reused.
914
+
718
915
  ## Built-in Icons / Social
719
916
 
720
917
  - **`Icons`** — curated Lucide allowlist (~100 icons) in
@@ -727,24 +924,22 @@ Use `createSpacingField`, `createBorderField`, and `createColorField` from
727
924
 
728
925
  ## Additional landing components
729
926
 
927
+ The full block list, with what each block offers, is on the CMS module page.
928
+ Two of them are often confused:
929
+
730
930
  | Component | Purpose |
731
931
  | --------- | ------- |
732
- | `Spacer` | Vertical space + optional divider |
733
- | `FeatureList` | Icon + title + description columns |
734
- | `Hero` | Background + heading + CTA first-fold |
735
- | `LogoStrip` | Partner / trust logos |
736
- | `Testimonial` | Quote + author |
737
- | `Stats` | KPI strip |
738
- | `AnnouncementBar` | Thin promo strip |
739
- | `SimpleTable` | Pipe-separated headers/rows |
740
- | `NewsletterSignup` | Email form (wire `actionUrl` to newsletter) |
741
- | `ContactFormEmbed` | Iframe embed or mailto fallback |
932
+ | `newsletter.Signup` | Subscribes through the `newsletter` module: topics as tags, a required consent, works without JavaScript. Present only while `newsletter` is. |
933
+ | `cms.NewsletterSignup` | Posts to any external form endpoint (`actionUrl`), for a newsletter service outside the platform. |
742
934
 
743
935
  ## Suggested follow-up (deeper integrations)
744
936
 
745
937
  | Priority | Idea | Why |
746
938
  | -------- | ---- | --- |
747
- | Medium | Newsletter signup ↔ the `newsletter` module | Auto-wire channel subscribe endpoint |
939
+ | Done (feature 163) | Newsletter signup ↔ the `newsletter` module | `newsletter.Signup` posts to the storefront's `/newsletter/subscribe`, which subscribes in the request's sales channel with source `cms-block`. |
940
+ | Medium | A module-owned server-data hook | Let a module's `./storefront` layer declare an async resolver for its own blocks, instead of adding a kind to the closed block-data union in `cms-components`. It changes the server-rendering boundary of the Page Builder renderer, so it needs its own specification. |
941
+ | Medium | Islands for static blocks | The whole Page Builder tree hydrates today. Rendering static blocks as server-only islands would cut the JavaScript a page sends and the work done on hydration. |
942
+ | Medium | `hreflang` with per-language URLs | One storefront URL serves every language, so pages announce their other languages as `og:locale:alternate` only. `hreflang` alternates need language-specific URLs first. |
748
943
  | Low | Contact ↔ forms module | Pick an existing form instead of iframe URL |
749
944
 
750
945
  `Accordion` / `Tabs` already cover FAQ-style sections; prefer those before a