@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.
- package/README.md +1 -0
- package/dist/admin/api/cms-client.d.ts +19 -3
- package/dist/admin/api/cms-client.d.ts.map +1 -1
- package/dist/admin/api/cms-client.js +23 -2
- package/dist/admin/api/cms-client.js.map +1 -1
- package/dist/admin/components/AdminCatalogPreviewProvider.d.ts +9 -0
- package/dist/admin/components/AdminCatalogPreviewProvider.d.ts.map +1 -1
- package/dist/admin/components/AdminCatalogPreviewProvider.js +88 -3
- package/dist/admin/components/AdminCatalogPreviewProvider.js.map +1 -1
- package/dist/admin/components/BackgroundFields.d.ts +16 -0
- package/dist/admin/components/BackgroundFields.d.ts.map +1 -1
- package/dist/admin/components/BackgroundFields.js +58 -11
- package/dist/admin/components/BackgroundFields.js.map +1 -1
- package/dist/admin/components/BrandFontFields.d.ts +17 -0
- package/dist/admin/components/BrandFontFields.d.ts.map +1 -0
- package/dist/admin/components/BrandFontFields.js +39 -0
- package/dist/admin/components/BrandFontFields.js.map +1 -0
- package/dist/admin/components/BrandPreview.d.ts +29 -0
- package/dist/admin/components/BrandPreview.d.ts.map +1 -0
- package/dist/admin/components/BrandPreview.js +130 -0
- package/dist/admin/components/BrandPreview.js.map +1 -0
- package/dist/admin/components/CarouselAddSlideMenu.d.ts +5 -0
- package/dist/admin/components/CarouselAddSlideMenu.d.ts.map +1 -0
- package/dist/admin/components/CarouselAddSlideMenu.js +84 -0
- package/dist/admin/components/CarouselAddSlideMenu.js.map +1 -0
- package/dist/admin/components/CarouselFields.d.ts +6 -0
- package/dist/admin/components/CarouselFields.d.ts.map +1 -0
- package/dist/admin/components/CarouselFields.js +55 -0
- package/dist/admin/components/CarouselFields.js.map +1 -0
- package/dist/admin/components/ContentSliderActionBarExtras.d.ts.map +1 -1
- package/dist/admin/components/ContentSliderActionBarExtras.js +13 -6
- package/dist/admin/components/ContentSliderActionBarExtras.js.map +1 -1
- package/dist/admin/components/FormBlockFields.d.ts +15 -0
- package/dist/admin/components/FormBlockFields.d.ts.map +1 -0
- package/dist/admin/components/FormBlockFields.js +23 -0
- package/dist/admin/components/FormBlockFields.js.map +1 -0
- package/dist/admin/components/HeroFields.d.ts +47 -0
- package/dist/admin/components/HeroFields.d.ts.map +1 -0
- package/dist/admin/components/HeroFields.js +92 -0
- package/dist/admin/components/HeroFields.js.map +1 -0
- package/dist/admin/components/ListingFields.d.ts +6 -0
- package/dist/admin/components/ListingFields.d.ts.map +1 -0
- package/dist/admin/components/ListingFields.js +54 -0
- package/dist/admin/components/ListingFields.js.map +1 -0
- package/dist/admin/components/NewsletterSignupFields.d.ts +18 -0
- package/dist/admin/components/NewsletterSignupFields.d.ts.map +1 -0
- package/dist/admin/components/NewsletterSignupFields.js +38 -0
- package/dist/admin/components/NewsletterSignupFields.js.map +1 -0
- package/dist/admin/components/PageBuilderActionBar.d.ts.map +1 -1
- package/dist/admin/components/PageBuilderActionBar.js +1 -6
- package/dist/admin/components/PageBuilderActionBar.js.map +1 -1
- package/dist/admin/components/PageBuilderEditor.d.ts +43 -2
- package/dist/admin/components/PageBuilderEditor.d.ts.map +1 -1
- package/dist/admin/components/PageBuilderEditor.js +218 -123
- package/dist/admin/components/PageBuilderEditor.js.map +1 -1
- package/dist/admin/components/PageNavigationFields.d.ts +6 -0
- package/dist/admin/components/PageNavigationFields.d.ts.map +1 -0
- package/dist/admin/components/PageNavigationFields.js +29 -0
- package/dist/admin/components/PageNavigationFields.js.map +1 -0
- package/dist/admin/components/PreviewBrandTokens.d.ts +25 -0
- package/dist/admin/components/PreviewBrandTokens.d.ts.map +1 -0
- package/dist/admin/components/PreviewBrandTokens.js +68 -0
- package/dist/admin/components/PreviewBrandTokens.js.map +1 -0
- package/dist/admin/components/SectionBlockFields.d.ts +44 -0
- package/dist/admin/components/SectionBlockFields.d.ts.map +1 -0
- package/dist/admin/components/SectionBlockFields.js +114 -0
- package/dist/admin/components/SectionBlockFields.js.map +1 -0
- package/dist/admin/components/SectionPresetsPanel.d.ts +11 -0
- package/dist/admin/components/SectionPresetsPanel.d.ts.map +1 -0
- package/dist/admin/components/SectionPresetsPanel.js +82 -0
- package/dist/admin/components/SectionPresetsPanel.js.map +1 -0
- package/dist/admin/components/SliderPreviewActionBarExtras.d.ts +1 -1
- package/dist/admin/components/SliderPreviewActionBarExtras.d.ts.map +1 -1
- package/dist/admin/components/SliderPreviewActionBarExtras.js +1 -5
- package/dist/admin/components/SliderPreviewActionBarExtras.js.map +1 -1
- package/dist/admin/components/admin-catalog-preview-map.d.ts +10 -1
- package/dist/admin/components/admin-catalog-preview-map.d.ts.map +1 -1
- package/dist/admin/components/admin-catalog-preview-map.js +11 -1
- package/dist/admin/components/admin-catalog-preview-map.js.map +1 -1
- package/dist/admin/components/block-contributions.d.ts +15 -0
- package/dist/admin/components/block-contributions.d.ts.map +1 -1
- package/dist/admin/components/block-contributions.js +22 -0
- package/dist/admin/components/block-contributions.js.map +1 -1
- package/dist/admin/components/page-builder-i18n.d.ts +24 -2
- package/dist/admin/components/page-builder-i18n.d.ts.map +1 -1
- package/dist/admin/components/page-builder-i18n.js +102 -9
- package/dist/admin/components/page-builder-i18n.js.map +1 -1
- package/dist/admin/editors/PageEditor.d.ts.map +1 -1
- package/dist/admin/editors/PageEditor.js +270 -38
- package/dist/admin/editors/PageEditor.js.map +1 -1
- package/dist/admin/index.d.ts +1 -1
- package/dist/admin/index.d.ts.map +1 -1
- package/dist/admin/index.js +28 -1
- package/dist/admin/index.js.map +1 -1
- package/dist/admin/pages/BrandPage.d.ts +19 -0
- package/dist/admin/pages/BrandPage.d.ts.map +1 -0
- package/dist/admin/pages/BrandPage.js +316 -0
- package/dist/admin/pages/BrandPage.js.map +1 -0
- package/dist/admin/pages/PagesListPage.d.ts.map +1 -1
- package/dist/admin/pages/PagesListPage.js +4 -1
- package/dist/admin/pages/PagesListPage.js.map +1 -1
- package/dist/admin/zones/ProductContentEditor.d.ts +27 -0
- package/dist/admin/zones/ProductContentEditor.d.ts.map +1 -0
- package/dist/admin/zones/ProductContentEditor.js +28 -0
- package/dist/admin/zones/ProductContentEditor.js.map +1 -0
- package/dist/backend/cli/block-names.d.ts +2 -1
- package/dist/backend/cli/block-names.d.ts.map +1 -1
- package/dist/backend/cli/block-names.js.map +1 -1
- package/dist/backend/entities/cms-brand-tokens.entity.d.ts +20 -0
- package/dist/backend/entities/cms-brand-tokens.entity.d.ts.map +1 -0
- package/dist/backend/entities/cms-brand-tokens.entity.js +57 -0
- package/dist/backend/entities/cms-brand-tokens.entity.js.map +1 -0
- package/dist/backend/entities/cms-page.entity.d.ts +32 -1
- package/dist/backend/entities/cms-page.entity.d.ts.map +1 -1
- package/dist/backend/entities/cms-page.entity.js +63 -0
- package/dist/backend/entities/cms-page.entity.js.map +1 -1
- package/dist/backend/index.d.ts +8 -1
- package/dist/backend/index.d.ts.map +1 -1
- package/dist/backend/index.js +90 -10
- package/dist/backend/index.js.map +1 -1
- package/dist/backend/plugin.d.ts +18 -2
- package/dist/backend/plugin.d.ts.map +1 -1
- package/dist/backend/plugin.js +23 -1
- package/dist/backend/plugin.js.map +1 -1
- package/dist/backend/routes.admin.d.ts +2 -0
- package/dist/backend/routes.admin.d.ts.map +1 -1
- package/dist/backend/routes.admin.js +42 -8
- package/dist/backend/routes.admin.js.map +1 -1
- package/dist/backend/routes.storefront.d.ts +24 -1
- package/dist/backend/routes.storefront.d.ts.map +1 -1
- package/dist/backend/routes.storefront.js +55 -2
- package/dist/backend/routes.storefront.js.map +1 -1
- package/dist/backend/services/anchor-guard.d.ts +10 -0
- package/dist/backend/services/anchor-guard.d.ts.map +1 -0
- package/dist/backend/services/anchor-guard.js +132 -0
- package/dist/backend/services/anchor-guard.js.map +1 -0
- package/dist/backend/services/asset-embed-resolver.d.ts +18 -10
- package/dist/backend/services/asset-embed-resolver.d.ts.map +1 -1
- package/dist/backend/services/asset-embed-resolver.js +35 -30
- package/dist/backend/services/asset-embed-resolver.js.map +1 -1
- package/dist/backend/services/asset-references.d.ts.map +1 -1
- package/dist/backend/services/asset-references.js +46 -30
- package/dist/backend/services/asset-references.js.map +1 -1
- package/dist/backend/services/brand-tokens-service.d.ts +84 -0
- package/dist/backend/services/brand-tokens-service.d.ts.map +1 -0
- package/dist/backend/services/brand-tokens-service.js +159 -0
- package/dist/backend/services/brand-tokens-service.js.map +1 -0
- package/dist/backend/services/channel-language-prefixes.d.ts +11 -0
- package/dist/backend/services/channel-language-prefixes.d.ts.map +1 -0
- package/dist/backend/services/channel-language-prefixes.js +24 -0
- package/dist/backend/services/channel-language-prefixes.js.map +1 -0
- package/dist/backend/services/cms-block-read-port.d.ts.map +1 -1
- package/dist/backend/services/cms-block-read-port.js +3 -0
- package/dist/backend/services/cms-block-read-port.js.map +1 -1
- package/dist/backend/services/cms-block-service.d.ts.map +1 -1
- package/dist/backend/services/cms-block-service.js +7 -1
- package/dist/backend/services/cms-block-service.js.map +1 -1
- package/dist/backend/services/cms-cache.d.ts +10 -0
- package/dist/backend/services/cms-cache.d.ts.map +1 -1
- package/dist/backend/services/cms-cache.js +9 -0
- package/dist/backend/services/cms-cache.js.map +1 -1
- package/dist/backend/services/cms-content-invalidator.d.ts +13 -4
- package/dist/backend/services/cms-content-invalidator.d.ts.map +1 -1
- package/dist/backend/services/cms-content-invalidator.js +13 -6
- package/dist/backend/services/cms-content-invalidator.js.map +1 -1
- package/dist/backend/services/cms-hook-service.d.ts.map +1 -1
- package/dist/backend/services/cms-hook-service.js +6 -1
- package/dist/backend/services/cms-hook-service.js.map +1 -1
- package/dist/backend/services/cms-page-read-port.d.ts +12 -1
- package/dist/backend/services/cms-page-read-port.d.ts.map +1 -1
- package/dist/backend/services/cms-page-read-port.js +49 -0
- package/dist/backend/services/cms-page-read-port.js.map +1 -1
- package/dist/backend/services/cms-page-service.d.ts +79 -1
- package/dist/backend/services/cms-page-service.d.ts.map +1 -1
- package/dist/backend/services/cms-page-service.js +344 -19
- package/dist/backend/services/cms-page-service.js.map +1 -1
- package/dist/backend/services/cms-template-service.d.ts.map +1 -1
- package/dist/backend/services/cms-template-service.js +7 -1
- package/dist/backend/services/cms-template-service.js.map +1 -1
- package/dist/backend/services/contact-form/contact-form-mail.d.ts +22 -0
- package/dist/backend/services/contact-form/contact-form-mail.d.ts.map +1 -0
- package/dist/backend/services/contact-form/contact-form-mail.js +64 -0
- package/dist/backend/services/contact-form/contact-form-mail.js.map +1 -0
- package/dist/backend/services/contact-form/contact-form.service.d.ts +35 -0
- package/dist/backend/services/contact-form/contact-form.service.d.ts.map +1 -0
- package/dist/backend/services/contact-form/contact-form.service.js +75 -0
- package/dist/backend/services/contact-form/contact-form.service.js.map +1 -0
- package/dist/backend/services/contact-form/recipients-validator.d.ts +8 -0
- package/dist/backend/services/contact-form/recipients-validator.d.ts.map +1 -0
- package/dist/backend/services/contact-form/recipients-validator.js +23 -0
- package/dist/backend/services/contact-form/recipients-validator.js.map +1 -0
- package/dist/backend/services/content-tree-walker.d.ts +12 -0
- package/dist/backend/services/content-tree-walker.d.ts.map +1 -1
- package/dist/backend/services/content-tree-walker.js +40 -0
- package/dist/backend/services/content-tree-walker.js.map +1 -1
- package/dist/backend/services/page-builder-registry.d.ts +11 -2
- package/dist/backend/services/page-builder-registry.d.ts.map +1 -1
- package/dist/backend/services/page-builder-registry.js +10 -1
- package/dist/backend/services/page-builder-registry.js.map +1 -1
- package/dist/backend/services/page-paths.d.ts +87 -0
- package/dist/backend/services/page-paths.d.ts.map +1 -0
- package/dist/backend/services/page-paths.js +177 -0
- package/dist/backend/services/page-paths.js.map +1 -0
- package/dist/backend/services/reserved-segment-registry.d.ts +16 -0
- package/dist/backend/services/reserved-segment-registry.d.ts.map +1 -0
- package/dist/backend/services/reserved-segment-registry.js +31 -0
- package/dist/backend/services/reserved-segment-registry.js.map +1 -0
- package/dist/backend/services/storefront-resolver.d.ts +58 -3
- package/dist/backend/services/storefront-resolver.d.ts.map +1 -1
- package/dist/backend/services/storefront-resolver.js +314 -29
- package/dist/backend/services/storefront-resolver.js.map +1 -1
- package/dist/backend/services/translation/extract.d.ts.map +1 -1
- package/dist/backend/services/translation/extract.js +9 -1
- package/dist/backend/services/translation/extract.js.map +1 -1
- package/dist/manifest.d.ts +19 -1
- package/dist/manifest.d.ts.map +1 -1
- package/dist/manifest.js +592 -73
- package/dist/manifest.js.map +1 -1
- package/dist/migrations/20261022T163218_cms_brand_tokens.d.ts +24 -0
- package/dist/migrations/20261022T163218_cms_brand_tokens.d.ts.map +1 -0
- package/dist/migrations/20261022T163218_cms_brand_tokens.js +38 -0
- package/dist/migrations/20261022T163218_cms_brand_tokens.js.map +1 -0
- package/dist/migrations/20261023T052237_cms_page_tree_and_share.d.ts +24 -0
- package/dist/migrations/20261023T052237_cms_page_tree_and_share.d.ts.map +1 -0
- package/dist/migrations/20261023T052237_cms_page_tree_and_share.js +51 -0
- package/dist/migrations/20261023T052237_cms_page_tree_and_share.js.map +1 -0
- package/dist/migrations/20261027T165458_cms_page_parent_path_in_url.d.ts +16 -0
- package/dist/migrations/20261027T165458_cms_page_parent_path_in_url.d.ts.map +1 -0
- package/dist/migrations/20261027T165458_cms_page_parent_path_in_url.js +20 -0
- package/dist/migrations/20261027T165458_cms_page_parent_path_in_url.js.map +1 -0
- package/dist/migrations/20261028T090524_cms_page_breadcrumbs_overlay.d.ts +14 -0
- package/dist/migrations/20261028T090524_cms_page_breadcrumbs_overlay.d.ts.map +1 -0
- package/dist/migrations/20261028T090524_cms_page_breadcrumbs_overlay.js +18 -0
- package/dist/migrations/20261028T090524_cms_page_breadcrumbs_overlay.js.map +1 -0
- package/dist/migrations/20261029T131218_cms_page_translations.d.ts +15 -0
- package/dist/migrations/20261029T131218_cms_page_translations.d.ts.map +1 -0
- package/dist/migrations/20261029T131218_cms_page_translations.js +19 -0
- package/dist/migrations/20261029T131218_cms_page_translations.js.map +1 -0
- package/dist/migrations/index.d.ts +6 -1
- package/dist/migrations/index.d.ts.map +1 -1
- package/dist/migrations/index.js +11 -1
- package/dist/migrations/index.js.map +1 -1
- package/docs/cms/brand.md +310 -0
- package/docs/cms/contact-form.md +161 -0
- package/docs/cms/extending-page-builder.md +210 -15
- package/docs/cms/index.md +1232 -39
- package/docs/cms/page-navigation.md +83 -0
- package/i18n/en.json +2787 -45
- package/i18n/pl.json +2765 -23
- package/package.json +20 -18
- package/dist/admin/components/ButtonLinkFields.d.ts +0 -6
- package/dist/admin/components/ButtonLinkFields.d.ts.map +0 -1
- package/dist/admin/components/ButtonLinkFields.js +0 -127
- 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:
|
|
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
|
|
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
|
-
| `
|
|
733
|
-
| `
|
|
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
|
-
|
|
|
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
|