feat(VCST-4933): support Shared Components in Page Builder preview

[ToxaKZ]

Description

Adds the Storefront preview support required by Page Builder Shared Components.

The published Storefront does not resolve or fetch Shared Components at runtime. The Page Builder module expands componentRef placements before Pages indexing, so public Storefront routes continue to receive ordinary Page Builder blocks.

This PR implements the authoring-preview side:

• reactive VPPageBuilder content replacement;
• a strict Designer/Storefront preview protocol;
• one visual boundary around every multi-section Shared Component placement;
• hover, selection, and scroll synchronization between Designer and preview;
• reliable iframe reconnect behavior;
• trusted endpoint-origin validation.

Companion PageBuilder module PR

VirtoCommerce/vc-module-pagebuilder#159

Reactive Page Builder content

vp-page-builder.vue reparses incoming content whenever the Pages document changes. It updates the rendered page for cache/network replacements, validates the expected Page Builder shape, clears stale content when the new payload is empty or malformed, and preserves ordinary block rendering.

Preview protocol and security

The preview postMessage contract is centralized and validated.

Messages are accepted only when:

• the source is the current parent Designer window;
• the origin matches the configured Designer origin;
• the payload has the expected source;
• the message type and fields conform to the protocol.

Asynchronous handling is serialized so an older locale or navigation update cannot overwrite newer preview state.

The ep query parameter accepts only valid HTTP(S) URLs and is reduced to its clean origin. Malformed values and javascript:/file: endpoints are rejected.

Shared Component placement overlay

Designer sends a resolved template together with placement metadata:

{
  placementId,
  componentRef,
  startIndex,
  count,
  label
}

The preview:

1. creates stable anchors around rendered Page Builder sections;
2. maps each boundary to its first section and following section/end anchor;
3. draws one boundary around all sections belonging to the placement;
4. recalculates geometry after content, layout, or viewport changes;
5. sends placement-level hover and selection events back to Designer;
6. scrolls to the complete placement when Designer selects it.

sequenceDiagram
    participant D as Page Builder Designer
    participant I as Storefront preview iframe
    participant O as Shared Component overlay

    I->>D: preview loaded and supported blocks
    D->>I: resolved template and placement boundaries
    I->>O: render anchors and boundaries
    O->>D: hover/select placementId
    D->>I: select/hover placementId
    I->>O: highlight or scroll to placement

Loading

Overlay elements are authoring-only and are not part of business content.

Iframe lifecycle

A newly loaded or replaced iframe must complete its own preview-loaded handshake before queued messages are sent. Ready state from an old iframe is not reused.

This prevents updates from being posted before the new iframe has installed its listener.

Published-page behavior

flowchart LR
    PB["Page Builder raw content"] -->|"resolve componentRef"| PI["Pages index"]
    PI -->|"ordinary expanded blocks"| SF["Storefront VPPageBuilder"]

Loading

There is no production-time Storefront request to the Shared Components API. A component update becomes visible after the PageBuilder propagation job causes Pages to reindex affected published documents.

Verification

Covered scenarios include VPPageBuilder content replacement, malformed content clearing, protocol validation, message ordering, iframe reconnect, boundary normalization, overlay rendering/resize/hover/click/selection/scrolling, and endpoint validation.

References

QA-test:

Assume the Page Builder module and this Storefront build are already installed and configured.

1. Ordinary content regression

1. Open a Page Builder page containing only ordinary sections.
2. Verify Designer preview loads and renders every block.
3. Add, edit, remove, reorder, hover, and select ordinary sections.
4. Verify preview updates and bidirectional selection still work.
5. Publish and verify the normal public Storefront route renders correctly.

2. Shared Component preview boundary

1. Open a page containing a Shared Component with at least three visible sections.
2. Verify all sections render in preview.
3. Verify one boundary surrounds the complete component rather than each individual section.
4. Resize the preview and change content height; verify the boundary realigns.
5. Place the same component twice and verify two independent boundaries.

3. Selection and navigation synchronization

1. Hover the component in Designer and verify its preview boundary highlights.
2. Hover/click the boundary and verify Designer receives placement hover/selection.
3. Select an off-screen component in Designer and verify preview scrolls to the beginning of the full placement.
4. Verify ordinary sections retain section-level selection and scrolling.

4. Live component editing

1. Open Edit original for a Shared Component.
2. Edit individual sections/blocks, including an image.
3. Add, remove, and reorder component sections.
4. Save and verify preview redraws the updated component and correct boundary.
5. Detach one placement and verify its boundary disappears while its independent blocks remain visible.

5. Iframe lifecycle

1. Open Designer and wait for preview.
2. Reload or recreate the preview iframe.
3. Immediately perform several page edits.
4. Verify messages are applied only after the new iframe announces readiness.
5. Verify no edit is lost and old iframe state is not reused.
6. Navigate quickly between pages/components and verify the newest state wins.

6. Published Storefront integration

1. Publish a page containing a Shared Component and wait for Pages indexing.
2. Open the regular public Storefront URL, not /designer-preview.
3. Verify the component renders as ordinary blocks.
4. Verify no preview boundary, blocker, anchors, or Designer messaging appears.
5. Edit the component original, wait for propagation/reindexing, and reload the public page.
6. Verify the updated component appears without republishing the page.
7. Verify ordinary page content remains unchanged.

7. Security validation

1. Open Designer through the expected platform URL and verify preview connects.
2. Verify malformed, javascript:, and file: ep values do not establish a trusted Designer origin.
3. Verify a valid HTTP(S) endpoint is normalized to its origin.
4. Verify messages from an unexpected origin or window are ignored.

Jira-link:

https://virtocommerce.atlassian.net/browse/VCST-4933

Artifact URL:

https://vc3prerelease.blob.core.windows.net/packages/vc-theme-b2b-vue-2.55.0-pr-2410-5afe-5afebbb3.zip

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud