@endora-commerce/mod-cms 0.108.0 → 0.109.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 (227) 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.map +1 -1
  7. package/dist/admin/components/AdminCatalogPreviewProvider.js +51 -0
  8. package/dist/admin/components/AdminCatalogPreviewProvider.js.map +1 -1
  9. package/dist/admin/components/BackgroundFields.d.ts +16 -0
  10. package/dist/admin/components/BackgroundFields.d.ts.map +1 -1
  11. package/dist/admin/components/BackgroundFields.js +58 -11
  12. package/dist/admin/components/BackgroundFields.js.map +1 -1
  13. package/dist/admin/components/BrandFontFields.d.ts +17 -0
  14. package/dist/admin/components/BrandFontFields.d.ts.map +1 -0
  15. package/dist/admin/components/BrandFontFields.js +39 -0
  16. package/dist/admin/components/BrandFontFields.js.map +1 -0
  17. package/dist/admin/components/BrandPreview.d.ts +29 -0
  18. package/dist/admin/components/BrandPreview.d.ts.map +1 -0
  19. package/dist/admin/components/BrandPreview.js +130 -0
  20. package/dist/admin/components/BrandPreview.js.map +1 -0
  21. package/dist/admin/components/CarouselAddSlideMenu.d.ts +5 -0
  22. package/dist/admin/components/CarouselAddSlideMenu.d.ts.map +1 -0
  23. package/dist/admin/components/CarouselAddSlideMenu.js +84 -0
  24. package/dist/admin/components/CarouselAddSlideMenu.js.map +1 -0
  25. package/dist/admin/components/CarouselFields.d.ts +6 -0
  26. package/dist/admin/components/CarouselFields.d.ts.map +1 -0
  27. package/dist/admin/components/CarouselFields.js +55 -0
  28. package/dist/admin/components/CarouselFields.js.map +1 -0
  29. package/dist/admin/components/ContentSliderActionBarExtras.d.ts.map +1 -1
  30. package/dist/admin/components/ContentSliderActionBarExtras.js +13 -6
  31. package/dist/admin/components/ContentSliderActionBarExtras.js.map +1 -1
  32. package/dist/admin/components/HeroFields.d.ts +47 -0
  33. package/dist/admin/components/HeroFields.d.ts.map +1 -0
  34. package/dist/admin/components/HeroFields.js +92 -0
  35. package/dist/admin/components/HeroFields.js.map +1 -0
  36. package/dist/admin/components/ListingFields.d.ts +6 -0
  37. package/dist/admin/components/ListingFields.d.ts.map +1 -0
  38. package/dist/admin/components/ListingFields.js +54 -0
  39. package/dist/admin/components/ListingFields.js.map +1 -0
  40. package/dist/admin/components/NewsletterSignupFields.d.ts +18 -0
  41. package/dist/admin/components/NewsletterSignupFields.d.ts.map +1 -0
  42. package/dist/admin/components/NewsletterSignupFields.js +38 -0
  43. package/dist/admin/components/NewsletterSignupFields.js.map +1 -0
  44. package/dist/admin/components/PageBuilderActionBar.d.ts.map +1 -1
  45. package/dist/admin/components/PageBuilderActionBar.js +1 -6
  46. package/dist/admin/components/PageBuilderActionBar.js.map +1 -1
  47. package/dist/admin/components/PageBuilderEditor.d.ts +43 -2
  48. package/dist/admin/components/PageBuilderEditor.d.ts.map +1 -1
  49. package/dist/admin/components/PageBuilderEditor.js +207 -121
  50. package/dist/admin/components/PageBuilderEditor.js.map +1 -1
  51. package/dist/admin/components/PageNavigationFields.d.ts +6 -0
  52. package/dist/admin/components/PageNavigationFields.d.ts.map +1 -0
  53. package/dist/admin/components/PageNavigationFields.js +29 -0
  54. package/dist/admin/components/PageNavigationFields.js.map +1 -0
  55. package/dist/admin/components/PreviewBrandTokens.d.ts +25 -0
  56. package/dist/admin/components/PreviewBrandTokens.d.ts.map +1 -0
  57. package/dist/admin/components/PreviewBrandTokens.js +68 -0
  58. package/dist/admin/components/PreviewBrandTokens.js.map +1 -0
  59. package/dist/admin/components/SectionBlockFields.d.ts +44 -0
  60. package/dist/admin/components/SectionBlockFields.d.ts.map +1 -0
  61. package/dist/admin/components/SectionBlockFields.js +114 -0
  62. package/dist/admin/components/SectionBlockFields.js.map +1 -0
  63. package/dist/admin/components/SectionPresetsPanel.d.ts +11 -0
  64. package/dist/admin/components/SectionPresetsPanel.d.ts.map +1 -0
  65. package/dist/admin/components/SectionPresetsPanel.js +82 -0
  66. package/dist/admin/components/SectionPresetsPanel.js.map +1 -0
  67. package/dist/admin/components/SliderPreviewActionBarExtras.d.ts +1 -1
  68. package/dist/admin/components/SliderPreviewActionBarExtras.d.ts.map +1 -1
  69. package/dist/admin/components/SliderPreviewActionBarExtras.js +1 -5
  70. package/dist/admin/components/SliderPreviewActionBarExtras.js.map +1 -1
  71. package/dist/admin/components/admin-catalog-preview-map.d.ts +9 -0
  72. package/dist/admin/components/admin-catalog-preview-map.d.ts.map +1 -1
  73. package/dist/admin/components/admin-catalog-preview-map.js +10 -0
  74. package/dist/admin/components/admin-catalog-preview-map.js.map +1 -1
  75. package/dist/admin/components/page-builder-i18n.d.ts +24 -2
  76. package/dist/admin/components/page-builder-i18n.d.ts.map +1 -1
  77. package/dist/admin/components/page-builder-i18n.js +102 -9
  78. package/dist/admin/components/page-builder-i18n.js.map +1 -1
  79. package/dist/admin/editors/PageEditor.d.ts.map +1 -1
  80. package/dist/admin/editors/PageEditor.js +270 -38
  81. package/dist/admin/editors/PageEditor.js.map +1 -1
  82. package/dist/admin/index.d.ts +1 -1
  83. package/dist/admin/index.d.ts.map +1 -1
  84. package/dist/admin/index.js +21 -1
  85. package/dist/admin/index.js.map +1 -1
  86. package/dist/admin/pages/BrandPage.d.ts +19 -0
  87. package/dist/admin/pages/BrandPage.d.ts.map +1 -0
  88. package/dist/admin/pages/BrandPage.js +316 -0
  89. package/dist/admin/pages/BrandPage.js.map +1 -0
  90. package/dist/admin/pages/PagesListPage.d.ts.map +1 -1
  91. package/dist/admin/pages/PagesListPage.js +4 -1
  92. package/dist/admin/pages/PagesListPage.js.map +1 -1
  93. package/dist/backend/cli/block-names.d.ts +2 -1
  94. package/dist/backend/cli/block-names.d.ts.map +1 -1
  95. package/dist/backend/cli/block-names.js.map +1 -1
  96. package/dist/backend/entities/cms-brand-tokens.entity.d.ts +20 -0
  97. package/dist/backend/entities/cms-brand-tokens.entity.d.ts.map +1 -0
  98. package/dist/backend/entities/cms-brand-tokens.entity.js +57 -0
  99. package/dist/backend/entities/cms-brand-tokens.entity.js.map +1 -0
  100. package/dist/backend/entities/cms-page.entity.d.ts +32 -1
  101. package/dist/backend/entities/cms-page.entity.d.ts.map +1 -1
  102. package/dist/backend/entities/cms-page.entity.js +63 -0
  103. package/dist/backend/entities/cms-page.entity.js.map +1 -1
  104. package/dist/backend/index.d.ts +5 -1
  105. package/dist/backend/index.d.ts.map +1 -1
  106. package/dist/backend/index.js +78 -8
  107. package/dist/backend/index.js.map +1 -1
  108. package/dist/backend/plugin.d.ts +16 -2
  109. package/dist/backend/plugin.d.ts.map +1 -1
  110. package/dist/backend/plugin.js +20 -1
  111. package/dist/backend/plugin.js.map +1 -1
  112. package/dist/backend/routes.admin.d.ts +2 -0
  113. package/dist/backend/routes.admin.d.ts.map +1 -1
  114. package/dist/backend/routes.admin.js +39 -4
  115. package/dist/backend/routes.admin.js.map +1 -1
  116. package/dist/backend/routes.storefront.d.ts +24 -1
  117. package/dist/backend/routes.storefront.d.ts.map +1 -1
  118. package/dist/backend/routes.storefront.js +55 -2
  119. package/dist/backend/routes.storefront.js.map +1 -1
  120. package/dist/backend/services/anchor-guard.d.ts +10 -0
  121. package/dist/backend/services/anchor-guard.d.ts.map +1 -0
  122. package/dist/backend/services/anchor-guard.js +132 -0
  123. package/dist/backend/services/anchor-guard.js.map +1 -0
  124. package/dist/backend/services/asset-references.d.ts.map +1 -1
  125. package/dist/backend/services/asset-references.js +46 -30
  126. package/dist/backend/services/asset-references.js.map +1 -1
  127. package/dist/backend/services/brand-tokens-service.d.ts +84 -0
  128. package/dist/backend/services/brand-tokens-service.d.ts.map +1 -0
  129. package/dist/backend/services/brand-tokens-service.js +159 -0
  130. package/dist/backend/services/brand-tokens-service.js.map +1 -0
  131. package/dist/backend/services/channel-language-prefixes.d.ts +11 -0
  132. package/dist/backend/services/channel-language-prefixes.d.ts.map +1 -0
  133. package/dist/backend/services/channel-language-prefixes.js +24 -0
  134. package/dist/backend/services/channel-language-prefixes.js.map +1 -0
  135. package/dist/backend/services/cms-block-service.d.ts.map +1 -1
  136. package/dist/backend/services/cms-block-service.js +3 -0
  137. package/dist/backend/services/cms-block-service.js.map +1 -1
  138. package/dist/backend/services/cms-cache.d.ts +10 -0
  139. package/dist/backend/services/cms-cache.d.ts.map +1 -1
  140. package/dist/backend/services/cms-cache.js +9 -0
  141. package/dist/backend/services/cms-cache.js.map +1 -1
  142. package/dist/backend/services/cms-content-invalidator.d.ts +13 -4
  143. package/dist/backend/services/cms-content-invalidator.d.ts.map +1 -1
  144. package/dist/backend/services/cms-content-invalidator.js +13 -6
  145. package/dist/backend/services/cms-content-invalidator.js.map +1 -1
  146. package/dist/backend/services/cms-page-read-port.d.ts +6 -1
  147. package/dist/backend/services/cms-page-read-port.d.ts.map +1 -1
  148. package/dist/backend/services/cms-page-read-port.js +27 -0
  149. package/dist/backend/services/cms-page-read-port.js.map +1 -1
  150. package/dist/backend/services/cms-page-service.d.ts +72 -1
  151. package/dist/backend/services/cms-page-service.d.ts.map +1 -1
  152. package/dist/backend/services/cms-page-service.js +317 -17
  153. package/dist/backend/services/cms-page-service.js.map +1 -1
  154. package/dist/backend/services/cms-template-service.d.ts.map +1 -1
  155. package/dist/backend/services/cms-template-service.js +3 -0
  156. package/dist/backend/services/cms-template-service.js.map +1 -1
  157. package/dist/backend/services/contact-form/contact-form-mail.d.ts +22 -0
  158. package/dist/backend/services/contact-form/contact-form-mail.d.ts.map +1 -0
  159. package/dist/backend/services/contact-form/contact-form-mail.js +64 -0
  160. package/dist/backend/services/contact-form/contact-form-mail.js.map +1 -0
  161. package/dist/backend/services/contact-form/contact-form.service.d.ts +35 -0
  162. package/dist/backend/services/contact-form/contact-form.service.d.ts.map +1 -0
  163. package/dist/backend/services/contact-form/contact-form.service.js +75 -0
  164. package/dist/backend/services/contact-form/contact-form.service.js.map +1 -0
  165. package/dist/backend/services/contact-form/recipients-validator.d.ts +8 -0
  166. package/dist/backend/services/contact-form/recipients-validator.d.ts.map +1 -0
  167. package/dist/backend/services/contact-form/recipients-validator.js +23 -0
  168. package/dist/backend/services/contact-form/recipients-validator.js.map +1 -0
  169. package/dist/backend/services/content-tree-walker.d.ts +12 -0
  170. package/dist/backend/services/content-tree-walker.d.ts.map +1 -1
  171. package/dist/backend/services/content-tree-walker.js +40 -0
  172. package/dist/backend/services/content-tree-walker.js.map +1 -1
  173. package/dist/backend/services/page-builder-registry.d.ts +11 -2
  174. package/dist/backend/services/page-builder-registry.d.ts.map +1 -1
  175. package/dist/backend/services/page-builder-registry.js +10 -1
  176. package/dist/backend/services/page-builder-registry.js.map +1 -1
  177. package/dist/backend/services/page-paths.d.ts +87 -0
  178. package/dist/backend/services/page-paths.d.ts.map +1 -0
  179. package/dist/backend/services/page-paths.js +177 -0
  180. package/dist/backend/services/page-paths.js.map +1 -0
  181. package/dist/backend/services/storefront-resolver.d.ts +53 -2
  182. package/dist/backend/services/storefront-resolver.d.ts.map +1 -1
  183. package/dist/backend/services/storefront-resolver.js +313 -22
  184. package/dist/backend/services/storefront-resolver.js.map +1 -1
  185. package/dist/backend/services/translation/extract.d.ts.map +1 -1
  186. package/dist/backend/services/translation/extract.js +9 -1
  187. package/dist/backend/services/translation/extract.js.map +1 -1
  188. package/dist/manifest.d.ts +13 -1
  189. package/dist/manifest.d.ts.map +1 -1
  190. package/dist/manifest.js +592 -73
  191. package/dist/manifest.js.map +1 -1
  192. package/dist/migrations/20261022T163218_cms_brand_tokens.d.ts +24 -0
  193. package/dist/migrations/20261022T163218_cms_brand_tokens.d.ts.map +1 -0
  194. package/dist/migrations/20261022T163218_cms_brand_tokens.js +38 -0
  195. package/dist/migrations/20261022T163218_cms_brand_tokens.js.map +1 -0
  196. package/dist/migrations/20261023T052237_cms_page_tree_and_share.d.ts +24 -0
  197. package/dist/migrations/20261023T052237_cms_page_tree_and_share.d.ts.map +1 -0
  198. package/dist/migrations/20261023T052237_cms_page_tree_and_share.js +51 -0
  199. package/dist/migrations/20261023T052237_cms_page_tree_and_share.js.map +1 -0
  200. package/dist/migrations/20261027T165458_cms_page_parent_path_in_url.d.ts +16 -0
  201. package/dist/migrations/20261027T165458_cms_page_parent_path_in_url.d.ts.map +1 -0
  202. package/dist/migrations/20261027T165458_cms_page_parent_path_in_url.js +20 -0
  203. package/dist/migrations/20261027T165458_cms_page_parent_path_in_url.js.map +1 -0
  204. package/dist/migrations/20261028T090524_cms_page_breadcrumbs_overlay.d.ts +14 -0
  205. package/dist/migrations/20261028T090524_cms_page_breadcrumbs_overlay.d.ts.map +1 -0
  206. package/dist/migrations/20261028T090524_cms_page_breadcrumbs_overlay.js +18 -0
  207. package/dist/migrations/20261028T090524_cms_page_breadcrumbs_overlay.js.map +1 -0
  208. package/dist/migrations/20261029T131218_cms_page_translations.d.ts +15 -0
  209. package/dist/migrations/20261029T131218_cms_page_translations.d.ts.map +1 -0
  210. package/dist/migrations/20261029T131218_cms_page_translations.js +19 -0
  211. package/dist/migrations/20261029T131218_cms_page_translations.js.map +1 -0
  212. package/dist/migrations/index.d.ts +6 -1
  213. package/dist/migrations/index.d.ts.map +1 -1
  214. package/dist/migrations/index.js +11 -1
  215. package/dist/migrations/index.js.map +1 -1
  216. package/docs/cms/brand.md +310 -0
  217. package/docs/cms/contact-form.md +161 -0
  218. package/docs/cms/extending-page-builder.md +210 -15
  219. package/docs/cms/index.md +1232 -39
  220. package/docs/cms/page-navigation.md +83 -0
  221. package/i18n/en.json +2758 -22
  222. package/i18n/pl.json +2758 -22
  223. package/package.json +18 -16
  224. package/dist/admin/components/ButtonLinkFields.d.ts +0 -6
  225. package/dist/admin/components/ButtonLinkFields.d.ts.map +0 -1
  226. package/dist/admin/components/ButtonLinkFields.js +0 -127
  227. package/dist/admin/components/ButtonLinkFields.js.map +0 -1
@@ -0,0 +1,310 @@
1
+ ---
2
+ title: Brand settings
3
+ sidebar_label: Brand
4
+ sidebar_position: 2
5
+ description: One set of colours, colour schemes, fonts, type scale, buttons and spacing that every Page Builder block uses, set globally and optionally per sales channel
6
+ ---
7
+
8
+ # Brand settings
9
+
10
+ The **Brand** screen holds the design decisions every Page Builder block
11
+ follows on the storefront: the colour palette, the three colour schemes, the
12
+ heading and body fonts, the type scale, the button shape and the spacing and
13
+ layout widths. Change the primary colour or the body font here once, and every
14
+ page built with the Page Builder follows — no page is edited and nothing is
15
+ rebuilt or redeployed.
16
+
17
+ Until somebody saves the screen, the built-in values apply, and they reproduce
18
+ the look the blocks had before the screen existed.
19
+
20
+ ## Opening the screen
21
+
22
+ - **Navigation**: **Brand** (`/cms/brand`), next to the other CMS screens.
23
+ - **Command palette**: ⌘K / CTRL+K → "Brand settings" (also found by *brand*,
24
+ *fonts*, *colours*, *colors*, *typography* or *theme*).
25
+ - **Permissions**: any role with **View CMS content** (`cms.read`) can open and
26
+ read the screen. Saving needs **Edit brand settings** (`cms.brand`), which
27
+ itself requires `cms.read`. Without it the fields are read-only and there is
28
+ no Save button.
29
+
30
+ ## What you can set
31
+
32
+ | Section | Settings |
33
+ | --- | --- |
34
+ | Colours | Primary and secondary colours with their hover colours, the text colour on each, a neutral scale from 50 to 900, and the **accent gradient** (start, end and angle) used by gradient highlights in headings. |
35
+ | Colour schemes | Light, muted and dark. Each has a background, text, muted text, border and link colour. The dark scheme can also have a **decorative backdrop**, an image a dark section may paint behind its content. A section chooses its scheme in the Page Builder, and every block inside it takes the scheme's colours. |
36
+ | Typography | The heading font and the body font (see [Fonts](#fonts)), and the type scale: Display, Heading 1–6, Lead, Body and Small, each with a mobile and a desktop size, line height, weight, letter spacing and whether it uses the heading or the body font. Heading 1–6 also apply to the headings written inside rich text (a Rich Content block, a block's rich body). |
37
+ | Buttons | Corner shape (square, rounded or pill), the heights of small, medium and large buttons, the label weight and the label case. |
38
+ | Spacing | The named steps a section's top and bottom spacing is chosen from — none, extra small, small, medium, large, extra large, largest — each with a mobile and a desktop size. |
39
+ | Layout | The content width, the wide content width, and the side margin on mobile and on desktop. The content width is the page container — 1360 px, side margins included, until changed; set it wider for a wider frame on every CMS page: Contained sections, content held in the page container, and the page's breadcrumb trail all follow it. Two optional factors scale the type and the spacing steps between breakpoints: **Type and spacing scale on a tablet (768–1023 px)** multiplies the mobile sizes there (for example 1.15 for 15 % larger), and **Type and spacing scale on a small desktop (1024–1279 px)** the desktop sizes. Empty is 1: nothing changes. Sizes a block sets in pixels of its own (a **Custom (px)** size or space) are not scaled. Two further optional settings, off by default: **Grow the desktop sizes with the window after the small desktop** makes the sizes grow with the window width from the small-desktop factor at 1280 px to the full desktop sizes at **Full desktop sizes from (px, default the page container width)**; **Scale button heights with the type and spacing** applies the factors to the button heights too (an icon-only button follows, as it is sized from them). |
40
+
41
+ A **Preview** shows a sample in each of the three schemes with the values on
42
+ screen, before you save.
43
+
44
+ Blocks still accept a value of their own where it matters: a colour field can
45
+ hold a brand colour (stored as a reference such as `token:primary`, which
46
+ follows later brand changes) or any hex colour, and a heading can override its
47
+ size, font, weight or line height in its **Advanced** group.
48
+
49
+ ## Global settings and channel overrides
50
+
51
+ The **Scope** card chooses what you edit:
52
+
53
+ - **All channels (global settings)** — the settings every sales channel uses
54
+ unless it has an override.
55
+ - **A sales channel** — that channel's own brand. A channel without one shows
56
+ **Inherits global**. **Override for this channel** starts the override as a
57
+ **complete copy** of the global settings; nothing is applied until you save.
58
+
59
+ An override is a full copy, not a list of differences. **A later change to the
60
+ global settings does not reach a channel that has an override**; the screen
61
+ says so on every overridden channel. **Reset to global** (after a
62
+ confirmation) deletes the override, and the channel follows the global
63
+ settings again.
64
+
65
+ The storefront uses the effective set of the request's sales channel: the
66
+ channel's override, else the global settings, else the built-in values. The
67
+ Page Builder preview uses the effective set of the page's first assigned sales
68
+ channel, so an editor sees the channel's brand on the canvas.
69
+
70
+ ## Contrast warnings
71
+
72
+ The screen warns, in a **Low contrast** notice, when a colour pair falls below
73
+ the WCAG 2.2 AA contrast ratio:
74
+
75
+ - each scheme's text, muted text and link against its background — 4.5:1;
76
+ - the text on primary and on secondary against the button fill and its hover
77
+ fill — 4.5:1;
78
+ - each accent-gradient colour against each scheme's background — 3:1, the
79
+ large-text threshold, because gradient highlights are used in large
80
+ headings.
81
+
82
+ A warning never blocks saving: the brand owner decides. The save response
83
+ returns the same list.
84
+
85
+ ## The decorative backdrop
86
+
87
+ The dark scheme's **Decorative backdrop** is any image from the Assets
88
+ Library, an SVG included. A Section with the dark scheme and **Decorative
89
+ backdrop** switched on paints it behind its content, covering the section from
90
+ its top centre.
91
+
92
+ How the backdrop is drawn is set on the section (or the section group) beside
93
+ the **Decorative backdrop** switch, not on this screen: **Backdrop size**
94
+ (Cover, the default; Contain; Natural size; or a width in px or %),
95
+ **Backdrop repeat** (none, the default; tile; across; down) and **Backdrop
96
+ position** (top, the default; centre, bottom, left or right). A tall group
97
+ covered by one image scales it to the group's height, which makes its details
98
+ large and soft; a width in px with **Repeat down** keeps the backdrop at its
99
+ own scale down the whole column, and keeps that size on every screen width.
100
+
101
+ The backdrop can also be given by address, in **Decorative backdrop URL**: an
102
+ `https://` address, or a path on your own site starting with `/` (for example
103
+ `/media/backdrop.svg`, which is loaded from the shop's API address, as a
104
+ library file is). The screen refuses any other address when you save. When
105
+ both are set, the file from the library is used.
106
+
107
+ - **Per section, or once for a group.** Each section paints its own copy, so
108
+ two dark sections next to each other each show the backdrop from their own
109
+ top, with an edge between them. To run one backdrop behind several sections,
110
+ put them in a **Section group** with the dark scheme and **Decorative
111
+ backdrop** switched on: the group paints it once, from its top, behind all its
112
+ sections (see the CMS module page, "Section groups").
113
+ - **Animated SVG.** An SVG can carry its own CSS animation (soft moving lights,
114
+ for example). The browser draws it as an image: it runs no script and loads
115
+ nothing from outside the file, so keep everything — shapes, gradients and the
116
+ `<style>` — inside the SVG.
117
+ - **Reduced motion.** The page cannot stop an animation inside an image, so the
118
+ SVG has to: put the animation inside
119
+ `@media (prefers-reduced-motion: no-preference)`, and a visitor who asks for
120
+ reduced motion sees the static drawing — **where the browser evaluates that
121
+ media query inside an SVG drawn as an image**. Support for it differs between
122
+ browsers and versions, and a browser that does not evaluate it plays the
123
+ animation, so check the asset in the browsers your shop supports and keep the
124
+ motion slow and subtle. Animate with CSS, not with SMIL (`<animate>`), which
125
+ the media query cannot stop.
126
+
127
+ An example that drifts a soft light slowly and stays still under reduced motion:
128
+
129
+ ```xml
130
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 900" preserveAspectRatio="xMidYMid slice">
131
+ <style>
132
+ .glow { transform-origin: 800px 450px; }
133
+ @media (prefers-reduced-motion: no-preference) {
134
+ .glow { animation: drift 24s ease-in-out infinite alternate; }
135
+ }
136
+ @keyframes drift { to { transform: translateX(120px) scale(1.15); } }
137
+ </style>
138
+ <defs>
139
+ <radialGradient id="g" cx="50%" cy="40%" r="50%">
140
+ <stop offset="0" stop-color="#1d4ed8" stop-opacity="0.55"/>
141
+ <stop offset="1" stop-color="#1d4ed8" stop-opacity="0"/>
142
+ </radialGradient>
143
+ </defs>
144
+ <rect class="glow" x="0" y="0" width="1600" height="900" fill="url(#g)"/>
145
+ </svg>
146
+ ```
147
+
148
+ ## Fonts
149
+
150
+ The heading font and the body font are each one of three kinds:
151
+
152
+ | Kind | What you enter | How it loads |
153
+ | --- | --- | --- |
154
+ | **System font** | A stack: sans-serif, serif or monospace. | Nothing is downloaded. |
155
+ | **Font files from the asset library** | A family name (for example `Acme Sans`), a fallback (sans-serif or serif) and up to eight font files, each with a weight (100–900) and a style (normal or italic). The picker lists Assets Library files whose type is `font/*`; prefer `woff2`. | The storefront writes one `@font-face` rule per file with `font-display: swap`, and preloads the regular upright face of the body font. |
156
+ | **Font service stylesheet** | A family name, a fallback, and the `https://` address of the service's stylesheet, for example `https://fonts.example.com/css?family=Acme+Sans`. | The storefront links the stylesheet in the page head. |
157
+
158
+ The fallback generic family always ends the font stack, so text renders while
159
+ the font loads or if it fails. A family name may hold letters, digits, spaces
160
+ and `-`, `_`, `.`; a stylesheet address must be `https:`. Font licensing is the
161
+ deployment's responsibility.
162
+
163
+ ### Cross-origin font loading
164
+
165
+ Browsers load a font from another origin only when that origin allows it with
166
+ CORS. Asset-library fonts are served by the API (`/assets/file/<id>` on the
167
+ public API address), which is usually a different origin from the storefront:
168
+
169
+ - **`CORS_ALLOWED_ORIGINS`** in the API's environment must include the
170
+ storefront's origin (for example `https://shop.example.com`). The
171
+ storefront's other browser calls already need it there. The Brand screen's
172
+ preview and the Page Builder canvas load the same files from the admin, so
173
+ an admin served from another origin than the API needs its origin in the
174
+ list too — which its own API calls already require.
175
+ - **Cloud storage**: when the Assets Library's storage backend answers with a
176
+ redirect to a bucket URL, the bucket itself must send CORS headers that allow
177
+ the storefront and admin origins. Configure that on the bucket.
178
+ - **Font services** send their own CORS headers; nothing is needed on your
179
+ side.
180
+
181
+ A font blocked by CORS does not break the page: the fallback family is used.
182
+
183
+ ## Saving, auditing and caching
184
+
185
+ - **Concurrent edits**: each scope has a version. If someone else saved the
186
+ same scope since you loaded it, the save is refused, the latest version is
187
+ loaded, and your changes are not applied.
188
+ - **Validation**: a value out of range is refused and the fields are named.
189
+ - **Audit**: each save is one Command, `cms.brand_tokens.update`, with exactly
190
+ one audit entry on the object `cms_brand_tokens` (id `global` or the sales
191
+ channel's id) carrying the settings before and after.
192
+ - **Storefront**: after the save commits, the storefront cache tag
193
+ `cms:brand` is revalidated, so the next request uses the new settings. If
194
+ revalidation is not configured or fails, the storefront picks the change up
195
+ within five minutes. The manual cache flush in Settings revalidates the same
196
+ tag (namespace `cms-brand`).
197
+
198
+ ## For engineers
199
+
200
+ ### Where the settings live
201
+
202
+ - **Table** `cms_brand_tokens`, owned by the `cms` module: one row per scope,
203
+ `sales_channel_id` null for the global row (unique, nulls not distinct),
204
+ `tokens` (JSONB, a complete set), `version`, `updated_at`. Reset deletes the
205
+ scope's row.
206
+ - **Schema** `cmsBrandTokensSchema`, the built-in set `DEFAULT_BRAND_TOKENS`
207
+ and the contrast check `assessBrandContrast` in
208
+ `packages/contracts/src/cms-brand.ts`. The dark scheme's backdrop is
209
+ `schemes.dark.decorativeAssetId` (a library asset) or
210
+ `schemes.dark.decorativeUrl` (`brandMediaUrlSchema`: `https:` or a path
211
+ starting with `/`, at most 2048 characters, with no quotes, parentheses,
212
+ backslashes, angle brackets or whitespace); the asset wins when both are set.
213
+ How a section or a group draws it is that block's: `decorativeSize`,
214
+ `decorativeRepeat` and `decorativePosition` of its `background` value
215
+ (`sectionBackgroundSchema` in `packages/contracts/src/page-builder-props.ts`),
216
+ written inline as `background-size`, `background-repeat` and
217
+ `background-position` over the stylesheet's `cover`, `no-repeat` and
218
+ `top center`.
219
+ - **Service** `src/backend/services/brand-tokens-service.ts` and the screen
220
+ `src/admin/pages/BrandPage.tsx`, both in the `cms` module's package.
221
+
222
+ ### HTTP
223
+
224
+ | Method and path | Gate | Answers |
225
+ | --- | --- | --- |
226
+ | `GET /api/v1/admin/cms/brand-tokens[?salesChannelId=]` | `cms.read` | `{global, channel?, effective, warnings}` |
227
+ | `PUT /api/v1/admin/cms/brand-tokens` | `cms.brand` | Body `{scope: {kind: 'all'} \| {kind: 'channel', salesChannelId}, tokens \| null, expectedVersion}`; `200 {version, warnings}`, `409 VERSION_CONFLICT`, `400 VALIDATION_FAILED`, `404 UNKNOWN_SALES_CHANNEL`. `tokens: null` removes a channel override, or resets the global set to the built-in values. |
228
+ | `GET /api/v1/storefront/cms/brand-tokens` | public | The effective set of the resolved sales channel (the system default channel without a header); `cache-control: public, max-age=60`. |
229
+ | `GET /api/v1/admin/cms/page-builder/config?salesChannelId=` | `cms.read` | The descriptor's `brandTokens`, used by the editor preview. |
230
+
231
+ ### Tokens as CSS variables
232
+
233
+ `brandTokensToCss(tokens, {assetUrl, mediaUrl})` in `@endora-commerce/cms-components`
234
+ (`packages/cms-components/src/brand/brand-css.ts`) turns a set into CSS
235
+ variables plus the font links. The storefront renders the result server-side
236
+ in `<head>` as `<style id="cmsb">` (`storefront/lib/theme/StorefrontDocument.tsx`),
237
+ fetched in `getServerContext()` with `revalidate: 300` and the tag `cms:brand`.
238
+ The admin injects the same output into the Page Builder iframe and into the
239
+ Brand screen's preview. Both pass `mediaUrl`, which rebases a backdrop URL
240
+ starting with `/` onto the public API address, as they do a relative video URL.
241
+
242
+ | Variables | From |
243
+ | --- | --- |
244
+ | `--cmsb-color-primary`, `-primary-hover`, `-secondary`, `-secondary-hover`, `-on-primary`, `-on-secondary` | Colours |
245
+ | `--cmsb-n-50` … `--cmsb-n-900` | Neutral scale |
246
+ | `--cmsb-grad` | Accent gradient |
247
+ | `--cmsb-fg`, `--cmsb-bg`, `--cmsb-fg-muted`, `--cmsb-border`, `--cmsb-link`, `--cmsb-decorative` | The light scheme on `:root`, rebound by each `[data-cmsb-scheme="light\|muted\|dark"]` rule |
248
+ | `--cmsb-font-heading`, `--cmsb-font-body` | Fonts |
249
+ | `--cmsb-t-<token>-size`, `-lh`, `-w`, `-ls`, `-font` | Type scale (`display`, `h1`–`h6`, `lead`, `body`, `small`) |
250
+ | `--cmsb-btn-radius`, `--cmsb-btn-h-s`, `-h-m`, `-h-l`, `--cmsb-btn-weight`, `--cmsb-btn-transform` | Buttons |
251
+ | `--cmsb-space-<step>` | Spacing (`none` … `xxl`) |
252
+ | `--cmsb-container`, `--cmsb-wide`, `--cmsb-gutter` | Layout |
253
+
254
+ Sizes that differ on desktop are rebound inside one
255
+ `@media (min-width: 1024px)` block. With a tablet factor other than 1
256
+ (`tierScale.tablet`), a `@media (min-width: 768px) and (max-width: 1023.98px)`
257
+ block before it rebinds every `--cmsb-t-<token>-size` and `--cmsb-space-<step>`
258
+ to the mobile value times the factor; with a small-desktop factor
259
+ (`tierScale.smallDesktop`), a `@media (min-width: 1024px) and (max-width:
260
+ 1279.98px)` block after it does the same from the desktop values. The gutter
261
+ and the container are not scaled. Without factors neither block is written,
262
+ so the output is byte for byte the same as before. Two further optional
263
+ settings extend these blocks (each writes nothing while unset):
264
+
265
+ - `tierScale.fluidDesktop: true`, with a small-desktop factor below 1, adds a
266
+ block from the small-desktop end to `tierScale.fluidUntilPx` (else
267
+ `layout.containerMaxPx`) where every desktop type size and spacing step is
268
+ `clamp(<value × factor>px, <value × 100 / end>vw, <value>px)` — the factor
269
+ rising with the window width to 1 at the end;
270
+ - `tierScale.buttons: true` writes `--cmsb-btn-h-s|m|l` into the tablet,
271
+ small-desktop and fluid blocks too, scaled the same way.
272
+
273
+ The small-desktop range always ends at 1279.98 px, as every block's
274
+ stylesheet assumes, and the gutter and the page container are the same at
275
+ every tier between phone and desktop. A block's own **Custom (px)** values are
276
+ written as literal px and are not scaled. Keys an earlier draft of this screen
277
+ stored (`smallDesktopUntilPx`, `blockPx`, `buttonLabels`, the per-tier
278
+ gutters and container, `fluidContainer`, `breadcrumbsPaddingYPx`,
279
+ `trackingMobileEm`) are dropped the next time the brand is saved and write
280
+ nothing meanwhile. For each heading level `h1`–`h6` whose
281
+ type style is set, the output also holds one rule giving that level's headings
282
+ inside rich text (`.cmsc-pb-rich-content`, `.cmsc-pb-rich`,
283
+ `.cmsc-pb-hero__body`, `.cmsc-pb-feature-list__body`) the level's size, line
284
+ height, weight and letter spacing. It is written here rather than in the
285
+ stylesheet because, with no brand, a rich body's headings take the host page's
286
+ own heading styles, which no fallback literal could restate. The storefront also sets
287
+ `--cmsb-header-offset`, the height of its sticky header, which anchored
288
+ sections use as their `scroll-margin-top`.
289
+
290
+ **Every use carries a fallback.** `packages/cms-components/styles/cms-components.css`
291
+ reads each variable as `var(--cmsb-…, <built-in literal>)`, and the built-in
292
+ literals equal `DEFAULT_BRAND_TOKENS`. A page rendered without
293
+ `<style id="cmsb">` — the `cms` module switched off, a failed read, or the
294
+ e-mail editor, which shares the stylesheet — therefore looks exactly as it did
295
+ before brand settings existed. The fallback-parity test
296
+ (`packages/cms-components/src/brand/fallback-parity.test.tsx`) holds that.
297
+ A block author writes the same way; see *Brand variables* in the
298
+ [Extending the Page Builder](./extending-page-builder.md) guide.
299
+
300
+ `brandTokensToCss` treats the set as untrusted: a non-hex colour, a family name
301
+ outside the allowed alphabet, a non-`https:` stylesheet address or a backdrop
302
+ URL the schema would refuse is dropped (the fallback then applies), asset and
303
+ backdrop URLs are written as escaped CSS strings, and no `<` can reach the
304
+ output.
305
+
306
+ ### When the module is off
307
+
308
+ While `cms` is switched off, its brand routes do not answer, the storefront
309
+ renders without `<style id="cmsb">` and the fallbacks apply. The stored rows
310
+ are kept and apply again when the module is switched back on.
@@ -0,0 +1,161 @@
1
+ ---
2
+ title: Contact form
3
+ sidebar_label: Contact form
4
+ sidebar_position: 5
5
+ description: A Page Builder block that e-mails a visitor's message to the addresses set per sales channel, with optional newsletter sign-up, and stores nothing
6
+ ---
7
+
8
+ # Contact form
9
+
10
+ The **Contact form** block (`cms.ContactForm`) puts a contact form on any Page Builder page.
11
+ A visitor fills it in, and the shop receives the message by e-mail at the addresses you set
12
+ for the sales channel. **Nothing is stored**: there is no list of submissions in the admin
13
+ and no table of messages — the e-mail in your inbox is the only copy.
14
+
15
+ The block is different from **Contact / form embed** (`cms.ContactFormEmbed`), which shows a
16
+ form hosted somewhere else in a frame.
17
+
18
+ ## Before you start: who receives the messages
19
+
20
+ The recipients are a setting, not part of the page, so an address never appears in the
21
+ page's content or anywhere on the storefront.
22
+
23
+ - **Where**: **Settings** → group **Contact form** → **Contact form recipients**.
24
+ - **Command palette**: ⌘K / CTRL+K → "Contact form recipients" (also found by *contact*,
25
+ *form*, *recipients*, *kontakt* or *formularz*).
26
+ - **Permissions**: reading the Settings screen needs **View settings** (`settings:read`);
27
+ changing a value needs **Edit settings** (`settings:write`).
28
+ - **Per sales channel**: set one list for all channels, or override it for a single channel.
29
+ The form sends to the list of the channel the visitor is shopping on.
30
+ - **Rules**: at most 10 addresses, each a valid e-mail address. Anything else is refused
31
+ when you save.
32
+
33
+ While a channel has no recipients, the form on that channel answers that it is unavailable,
34
+ and the visitor sees the block's "Unavailable" message.
35
+
36
+ ## Building a contact page
37
+
38
+ A typical contact page is made of blocks that already exist:
39
+
40
+ 1. A **Section** with a **Row** of two **Columns**.
41
+ 2. In the first column, a **Heading** and a short **Rich content** lead, then the **Contact
42
+ form**.
43
+ 3. In the second column, the contact details (addresses, phone numbers, opening hours) as
44
+ **Rich content**, or a **Map**.
45
+ 4. Optionally a **Tabs** block with two tabs — "Contact form" holding the **Contact form**
46
+ and "Newsletter" holding the **Newsletter sign-up** block (when the newsletter module is
47
+ installed).
48
+
49
+ Give the Section an anchor if you link to the form from elsewhere on the page; after a
50
+ visitor sends the form without JavaScript, the browser returns to that anchor.
51
+
52
+ ## Fields
53
+
54
+ The field set is fixed — the server knows every field, so it can check what arrives:
55
+
56
+ | Field | Shown | Required |
57
+ | --- | --- | --- |
58
+ | Name | by default | optional |
59
+ | E-mail | always | always |
60
+ | Phone | on request | optional |
61
+ | Company | on request | optional |
62
+ | Subject | on request | optional |
63
+ | Select (a list you define, e.g. regions or departments) | on request | optional |
64
+ | Message | always | always |
65
+ | Privacy consent | always | always |
66
+ | Marketing consent | on request | never |
67
+
68
+ For every field you can change the **label** and the **placeholder**; for the optional ones
69
+ also **Show** and **Required**. The select needs at least one option — without one it is
70
+ not shown. Its chosen option is sent with the select's label, so the e-mail reads, for
71
+ example, "Region: North".
72
+
73
+ Labels you leave empty show the storefront's own wording in the page's language.
74
+
75
+ **Privacy consent**: write its label and link it to your privacy policy — the editor shows a
76
+ warning until you do. Until then the visitor reads a short default sentence without a link.
77
+
78
+ **Marketing consent**: switch it on to ask whether the visitor wants news and offers. See
79
+ [Newsletter sign-up from the form](#newsletter-sign-up-from-the-form).
80
+
81
+ ## Layout and look
82
+
83
+ The block follows the colour scheme of the section it is in. The options are presets, so a
84
+ page looks right without measurements:
85
+
86
+ - **Columns** — one, or two from tablet width up (one on phones). With two columns, each
87
+ field's **Width** is half or full; the message is full width unless you change it.
88
+ - **Labels** — above the field, or hidden. Hidden labels are still read by screen readers,
89
+ and the label is shown as the placeholder when you wrote none.
90
+ - **Field look** — **Boxed** (a frame), **Underline** (a line under the field) or **Pill**
91
+ (fully rounded; the message box keeps softer corners).
92
+ - **Button** — the same look options as every other Page Builder button (style, fill, size,
93
+ icon) and its own label. **Button alignment** places it at the start, centre or end, or
94
+ makes it full width.
95
+ - **Messages** — the texts shown after sending: **Sent**, **Not accepted** (the server
96
+ refused what was sent) and **Unavailable** (no recipients, too many attempts, or a
97
+ temporary failure).
98
+ - **Form name** — the name screen readers announce for the form.
99
+ - Outer and inner spacing, border, and hiding the block per screen size work as on every
100
+ block.
101
+
102
+ ## What happens when a visitor sends the form
103
+
104
+ 1. With JavaScript, the form checks the required fields and the e-mail address first, marks
105
+ each field to correct and moves the focus to the first one. What the visitor typed is
106
+ kept until the message is sent.
107
+ 2. The storefront passes the message to the shop's server, which checks it again —
108
+ whatever the block's settings, the server always requires an e-mail address, a message
109
+ (up to 5 000 characters) and the privacy consent.
110
+ 3. The server sends **one e-mail per recipient** of the visitor's sales channel, through the
111
+ platform's mail transport. The e-mail is written in the channel's default language and
112
+ lists the fields that were filled in, the page the form was sent from and both consents.
113
+ Its **Reply-To** is the visitor's address, so answering it reaches the visitor.
114
+ 4. The visitor sees the **Sent** message. Without JavaScript, the browser comes back to the
115
+ same page, in the same language, scrolled to the form.
116
+
117
+ **What is kept**: the platform's e-mail delivery record notes that a message of kind
118
+ `cms.contact_form` went to a recipient, with a fixed subject (the channel's name, never the
119
+ visitor's text) and the outcome. Nothing the visitor typed is stored anywhere.
120
+
121
+ ## Newsletter sign-up from the form
122
+
123
+ When the marketing consent is ticked and the message is sent, the storefront also signs the
124
+ address up to the newsletter of the visitor's sales channel — if the newsletter module is
125
+ installed and switched on. The channel's own opt-in rules apply, so with double opt-in the
126
+ visitor receives a confirmation e-mail first. The subscription is recorded with the source
127
+ `cms-contact-form`. If the sign-up fails, the message has still been sent.
128
+
129
+ Without the newsletter module, the consent is only stated in the e-mail you receive.
130
+
131
+ ## Protection against abuse
132
+
133
+ - **Rate limit** — at most 10 submissions per visitor address in 10 minutes; the eleventh
134
+ is refused and the visitor sees the "Unavailable" message.
135
+ - **Hidden trap field** — a field people never see. A bot that fills it is told the message
136
+ was sent, and nothing is sent.
137
+ - **Behind a proxy** — the reference storefront calls the server on the visitor's behalf
138
+ and forwards the visitor's address in `X-Forwarded-For`. The server only counts that
139
+ address when it trusts the storefront as a proxy: set `TRUSTED_PROXY_HOPS` or
140
+ `TRUSTED_PROXY_ADDRESSES` for your deployment. Without it, every visitor shares the
141
+ storefront's address and the limit applies to all of them together.
142
+
143
+ ## For developers: the endpoint
144
+
145
+ The storefront handler is `POST /forms/contact` (a plain form post answered with `303` back
146
+ to the page, or JSON when the request accepts it). It calls the public endpoint:
147
+
148
+ `POST /api/v1/storefront/cms/contact-form` — body checked against
149
+ `contactFormSubmissionSchema` in `@endora-commerce/contracts`; unknown keys are refused.
150
+
151
+ | Outcome | Status |
152
+ | --- | --- |
153
+ | Sent (also when the trap field is filled) | `200` `{ "data": { "status": "sent" } }` |
154
+ | The body does not match the contract | `400` `VALIDATION_FAILED` |
155
+ | No recipients for the request's sales channel | `409` `CMS_CONTACT_FORM_UNAVAILABLE` |
156
+ | Too many submissions from one address | `429` |
157
+ | Every send failed | `500` `INTERNAL` |
158
+ | The CMS module is switched off | `503` `MODULE_DISABLED` |
159
+
160
+ The answer never contains the recipients or the submitted values. With the CMS module
161
+ switched off the block disappears from every page and the storefront handler answers `404`.