@shopgate/engage 7.32.0-beta.2 → 7.32.0-beta.20

package/page/components/Widgets/WidgetContext.d.ts

@@ -1,42 +1,36 @@
-import { type Context } from 'react';
-import {
-  type WidgetDefinitionLayout,
-  type WidgetDefinitionVisibility,
-  type WidgetDefinition,
-} from './types'
-
-export { WidgetDefinition } from './types';
-
-export interface WidgetContextType<C = Record<string, any>> {
-  /**
-   * The unique code of the widget instance
-   */
-  code: string;
-  /**
-   * The name of the widget
-   */
-  name: string;
-  /**
-   * The widget configuration
-   */
-  config: C;
-  /**
-   * The widget layout settings
-   */
-  layout: WidgetDefinitionLayout;
-  /**
-   * The widget visibility settings
-   */
-  visibility: WidgetDefinitionVisibility;
-  /**
-   * Whether the widget is rendered in preview mode
-   */
-  isPreview: boolean;
+import { type WidgetDefinitionVisibility, type WidgetLayout } from './types';
+export { type WidgetDefinition } from './types';
+/**
+ * Context value provided by the {@link WidgetContext} for a single widget instance.
+ */
+export interface WidgetContextType<C = Record<string, unknown>> {
+    /**
+     * The unique code of the widget instance.
+     */
+    code: string;
+    /**
+     * The name of the widget.
+     */
+    name: string;
+    /**
+     * The widget configuration.
+     */
+    config: C;
+    /**
+     * The resolved margins of the widget container.
+     */
+    layout: WidgetLayout;
+    /**
+     * The widget visibility settings.
+     */
+    visibility: WidgetDefinitionVisibility;
+    /**
+     * Whether the widget is rendered in preview mode.
+     */
+    isPreview: boolean;
 }
-
 /**
  * React context for widgets.
  */
-declare const WidgetContext: Context<WidgetContextType>;
-
-export default WidgetContext;
+export declare const WidgetContext: import("react").Context<WidgetContextType<Record<string, unknown>>>;
+//# sourceMappingURL=WidgetContext.d.ts.map

package/page/components/Widgets/WidgetContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WidgetContext.d.ts","sourceRoot":"","sources":["../../../../page/components/Widgets/WidgetContext.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,0BAA0B,EAC/B,KAAK,YAAY,EAClB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC5D;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,MAAM,EAAE,CAAC,CAAC;IACV;;OAEG;IACH,MAAM,EAAE,YAAY,CAAC;IACrB;;OAEG;IACH,UAAU,EAAE,0BAA0B,CAAC;IACvC;;OAEG;IACH,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,qEAA4D,CAAC"}

package/page/components/Widgets/WidgetContext.js

@@ -1,16 +1,10 @@
 import { createContext } from 'react';
 
 /**
- * @typedef {import('./Widgets.jsx').WidgetDefinition} WidgetDefinition
+ * Context value provided by the {@link WidgetContext} for a single widget instance.
  */
 
 /**
- * @typedef {Object} WidgetContextType
- * @property {WidgetDefinition['code']} code The unique widget code.
- * @property {WidgetDefinition['widgetConfig']} config The widget configuration.
- * @property {WidgetDefinition['layout']} layout The widget layout settings.
- * @property {WidgetDefinition['visibility']} visibility The widget visibility settings.
+ * React context for widgets.
  */
-
-/** @type {React.Context<WidgetContextType>} */
 export const WidgetContext = /*#__PURE__*/createContext({});

package/page/components/Widgets/WidgetProvider.d.ts

@@ -0,0 +1,29 @@
+import { type ReactNode } from 'react';
+import { type WidgetDefinition, type WidgetLayout } from './types';
+/**
+ * Props of the {@link WidgetProvider} component.
+ */
+export interface WidgetProviderProps {
+    /**
+     * The child components to render.
+     */
+    children: ReactNode;
+    /**
+     * The widget definition data.
+     */
+    definition: WidgetDefinition;
+    /**
+     * Whether the widget is in preview mode.
+     */
+    isPreview: boolean;
+    /**
+     * The resolved margins of the widget container.
+     */
+    layout: WidgetLayout;
+}
+/**
+ * The WidgetProvider component provides the context for a single widget.
+ */
+declare const WidgetProvider: ({ children, definition, isPreview, layout, }: WidgetProviderProps) => import("react").JSX.Element;
+export default WidgetProvider;
+//# sourceMappingURL=WidgetProvider.d.ts.map

package/page/components/Widgets/WidgetProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WidgetProvider.d.ts","sourceRoot":"","sources":["../../../../page/components/Widgets/WidgetProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAEhD,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IACpB;;OAEG;IACH,UAAU,EAAE,gBAAgB,CAAC;IAC7B;;OAEG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB;;OAEG;IACH,MAAM,EAAE,YAAY,CAAC;CACtB;AAED;;GAEG;AACH,QAAA,MAAM,cAAc,GAAI,8CAErB,mBAAmB,gCAoBrB,CAAC;AAEF,eAAe,cAAc,CAAC"}

package/page/components/Widgets/WidgetProvider.js

@@ -1,29 +1,22 @@
-import React, { useMemo } from 'react';
-import PropTypes from 'prop-types';
+import { useMemo } from 'react';
 import { WidgetContext } from "./WidgetContext";
 
-/**  @typedef {import('./WidgetContext').WidgetContextType} WidgetContextType */
-/**  @typedef {import('./WidgetContext').WidgetDefinition} WidgetDefinition */
-
 /**
- * The WidgetProvider component provides the context for a single widget.
- * @param {Object} props The component props.
- * @param {WidgetDefinition} props.definition The widget definition data.
- * @param {boolean} props.isPreview Whether the widget is in preview mode.
- * @param {React.ReactNode} props.children The child components to render.
- * @returns {JSX.Element}
+ * Props of the {@link WidgetProvider} component.
  */
 import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The WidgetProvider component provides the context for a single widget.
+ */
 const WidgetProvider = ({
   children,
   definition,
-  isPreview
+  isPreview,
+  layout
 }) => {
-  /** @type {WidgetContextType} */
   const value = useMemo(() => {
     const {
       widgetConfig,
-      layout,
       visibility,
       code,
       widgetConfigDefinitionCode
@@ -36,7 +29,7 @@ const WidgetProvider = ({
       visibility,
       isPreview
     };
-  }, [definition, isPreview]);
+  }, [definition, isPreview, layout]);
   return /*#__PURE__*/_jsx(WidgetContext.Provider, {
     value: value,
     children: children

package/page/components/Widgets/Widgets.d.ts

@@ -0,0 +1,16 @@
+import { type WidgetDefinition } from './types';
+/**
+ * Props of the {@link Widgets} component.
+ */
+export interface WidgetsProps {
+    /**
+     * The list of widgets to render.
+     */
+    widgets?: WidgetDefinition[];
+}
+/**
+ * The Widgets component renders a list of widgets.
+ */
+declare const Widgets: ({ widgets: widgetsProp, }: WidgetsProps) => import("react").JSX.Element | null;
+export default Widgets;
+//# sourceMappingURL=Widgets.d.ts.map

package/page/components/Widgets/Widgets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Widgets.d.ts","sourceRoot":"","sources":["../../../../page/components/Widgets/Widgets.tsx"],"names":[],"mappings":"AAWA,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAYhD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC9B;AAED;;GAEG;AACH,QAAA,MAAM,OAAO,GAAI,2BAEd,YAAY,uCA+Dd,CAAC;AAEF,eAAe,OAAO,CAAC"}

package/page/components/Widgets/Widgets.js

@@ -1,5 +1,4 @@
-import React, { useMemo, useRef } from 'react';
-import PropTypes from 'prop-types';
+import { useMemo, useRef } from 'react';
 import { makeStyles } from '@shopgate/engage/styles';
 import { useRoute, useThemeWidgets } from '@shopgate/engage/core/hooks';
 import { PAGE_PREVIEW_PATTERN } from '@shopgate/engage/page/constants';
@@ -10,10 +9,6 @@ import Widget from "./Widget";
 import Overlay from "./Overlay";
 import { checkScheduled } from "./helpers";
 import { usePreviewIframeCommunication } from "./hooks";
-
-/**
- * @typedef {import('./types').WidgetDefinition} WidgetDefinition
- */
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const PLACEHOLDER_COMPONENT = '@shopgate/widgetsInternal/Placeholder';
 const useStyles = makeStyles()({
@@ -24,11 +19,12 @@ const useStyles = makeStyles()({
   }
 });
 
+/**
+ * Props of the {@link Widgets} component.
+ */
+
 /**
  * The Widgets component renders a list of widgets.
- * @param {Object} props The component props.
- * @param {Array<WidgetDefinition>} props.widgets The list of widgets to render.
- * @returns {JSX.Element}
  */
 const Widgets = ({
   widgets: widgetsProp = []
@@ -85,7 +81,4 @@ const Widgets = ({
     })
   });
 };
-Widgets.defaultProps = {
-  widgets: null
-};
 export default Widgets;

package/page/components/Widgets/WidgetsPreviewContext.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Sets the active widget in the preview context.
+ * @param code The code of the widget to set as active.
+ * @param highlight Whether to highlight the widget after setting it as active.
+ */
+export type SetActiveWidget = (code: string, highlight?: boolean) => void;
+/**
+ * Context value provided by the {@link WidgetsPreviewContext}.
+ */
+export interface WidgetsPreviewContextType {
+    /**
+     * The code of the currently active widget.
+     */
+    activeWidget: string | null;
+    /**
+     * A function to set the active widget code.
+     */
+    setActiveWidget: SetActiveWidget;
+}
+export declare const WidgetsPreviewContext: import("react").Context<WidgetsPreviewContextType>;
+//# sourceMappingURL=WidgetsPreviewContext.d.ts.map

package/page/components/Widgets/WidgetsPreviewContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WidgetsPreviewContext.d.ts","sourceRoot":"","sources":["../../../../page/components/Widgets/WidgetsPreviewContext.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;AAE1E;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;OAEG;IACH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;OAEG;IACH,eAAe,EAAE,eAAe,CAAC;CAClC;AAED,eAAO,MAAM,qBAAqB,oDAGhC,CAAC"}

package/page/components/Widgets/WidgetsPreviewContext.js

@@ -1,18 +1,16 @@
 import _noop from "lodash/noop";
 import { createContext } from 'react';
+
 /**
- * @callback SetActiveWidget
- * @param {string} code The code of the widget to set as active.
- * @param {boolean} [highlight=false] Whether to highlight the widget after setting it as active.
+ * Sets the active widget in the preview context.
+ * @param code The code of the widget to set as active.
+ * @param highlight Whether to highlight the widget after setting it as active.
  */
 
 /**
- * @typedef {Object} WidgetsPreviewContextType
- * @property {string} activeWidget The code of the currently active widget.
- * @property {SetActiveWidget} setActiveWidget A function to set the active widget code
+ * Context value provided by the {@link WidgetsPreviewContext}.
  */
 
-/** @type {React.Context<WidgetsPreviewContextType>} */
 export const WidgetsPreviewContext = /*#__PURE__*/createContext({
   activeWidget: null,
   setActiveWidget: _noop

package/page/components/Widgets/WidgetsPreviewProvider.d.ts

@@ -0,0 +1,18 @@
+import { type ReactNode } from 'react';
+/**
+ * Props of the {@link WidgetsPreviewProvider} component.
+ */
+export interface WidgetsPreviewProviderProps {
+    /**
+     * The child components to render.
+     */
+    children: ReactNode;
+}
+/**
+ * The WidgetsPreviewProvider component is used by the Widgets component when it's rendered
+ * in preview mode. It provides functionality for the Widget component that's needed when
+ * the widgets are rendered in the preview iframe.
+ */
+declare const WidgetsPreviewProvider: ({ children }: WidgetsPreviewProviderProps) => import("react").JSX.Element;
+export default WidgetsPreviewProvider;
+//# sourceMappingURL=WidgetsPreviewProvider.d.ts.map

package/page/components/Widgets/WidgetsPreviewProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WidgetsPreviewProvider.d.ts","sourceRoot":"","sources":["../../../../page/components/Widgets/WidgetsPreviewProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAC2B,KAAK,SAAS,EAC/C,MAAM,OAAO,CAAC;AAOf;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;GAIG;AACH,QAAA,MAAM,sBAAsB,GAAI,cAAc,2BAA2B,gCAyBxE,CAAC;AAEF,eAAe,sBAAsB,CAAC"}

package/page/components/Widgets/WidgetsPreviewProvider.js

@@ -1,17 +1,16 @@
-import React, { useMemo, useState, useCallback } from 'react';
-import PropTypes from 'prop-types';
+import { useMemo, useState, useCallback } from 'react';
 import { useWidgetPreviewEvent, dispatchWidgetPreviewEvent } from "./events";
 import { WidgetsPreviewContext } from "./WidgetsPreviewContext";
 
+/**
+ * Props of the {@link WidgetsPreviewProvider} component.
+ */
+import { jsx as _jsx } from "react/jsx-runtime";
 /**
  * The WidgetsPreviewProvider component is used by the Widgets component when it's rendered
  * in preview mode. It provides functionality for the Widget component that's needed when
  * the widgets are rendered in the preview iframe.
- * @param {Object} props The component props.
- * @param {React.ReactNode} props.children The child components to render.
- * @returns {JSX.Element}
  */
-import { jsx as _jsx } from "react/jsx-runtime";
 const WidgetsPreviewProvider = ({
   children
 }) => {

package/page/components/Widgets/constants.d.ts

@@ -0,0 +1,18 @@
+import { type MediaMarginSettings } from '@shopgate/engage/settings/types/appSettings';
+/**
+ * Whether to consider vertical margins when calculating the overlay position.
+ */
+export declare const CONSIDER_CONTAINER_MARGINS_ON_SCROLL_DEFAULT = false;
+/**
+ * The margin sides of a widget container.
+ */
+export declare const MARGIN_SIDES: readonly ["marginTop", "marginBottom", "marginLeft", "marginRight"];
+/**
+ * The media widget margin side that belongs to each margin of a widget container.
+ */
+export declare const MARGIN_SIDE_SETTINGS: Record<typeof MARGIN_SIDES[number], keyof MediaMarginSettings>;
+/**
+ * The sides of the media widget margins.
+ */
+export declare const MEDIA_MARGIN_SIDES: (keyof MediaMarginSettings)[];
+//# sourceMappingURL=constants.d.ts.map

package/page/components/Widgets/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../page/components/Widgets/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,6CAA6C,CAAC;AAEvF;;GAEG;AACH,eAAO,MAAM,4CAA4C,QAAQ,CAAC;AAElE;;GAEG;AACH,eAAO,MAAM,YAAY,qEAAsE,CAAC;AAEhG;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CACvC,OAAO,YAAY,CAAC,MAAM,CAAC,EAC3B,MAAM,mBAAmB,CAM1B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,+BAAsC,CAAC"}

package/page/components/Widgets/constants.js

@@ -1,2 +1,24 @@
-// Whether to consider vertical margins when calculating the overlay position.
-export const CONSIDER_CONTAINER_MARGINS_ON_SCROLL_DEFAULT = false;
+/**
+ * Whether to consider vertical margins when calculating the overlay position.
+ */
+export const CONSIDER_CONTAINER_MARGINS_ON_SCROLL_DEFAULT = false;
+
+/**
+ * The margin sides of a widget container.
+ */
+export const MARGIN_SIDES = ['marginTop', 'marginBottom', 'marginLeft', 'marginRight'];
+
+/**
+ * The media widget margin side that belongs to each margin of a widget container.
+ */
+export const MARGIN_SIDE_SETTINGS = {
+  marginTop: 'top',
+  marginBottom: 'bottom',
+  marginLeft: 'left',
+  marginRight: 'right'
+};
+
+/**
+ * The sides of the media widget margins.
+ */
+export const MEDIA_MARGIN_SIDES = Object.values(MARGIN_SIDE_SETTINGS);

package/page/components/Widgets/events.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Names of the events that are dispatched in the context of widget preview iframe communication.
+ */
+export type WidgetPreviewEventName = 'highlight-widget' | 'widget-clicked' | 'set-active-widget-id';
+/**
+ * Detail payload of a widget preview event.
+ */
+export interface WidgetPreviewEventDetail {
+    /**
+     * The code of the widget related to the event.
+     */
+    widgetCode: string;
+    /**
+     * Optional payload data related to the event.
+     */
+    payload?: unknown;
+}
+/**
+ * Handler for a widget preview event.
+ */
+export type WidgetPreviewEventHandler = (event: CustomEvent<WidgetPreviewEventDetail>) => void;
+/**
+ * Hook to listen for widget preview events.
+ * These events are dispatched in the context of iFrame communication at the widget preview.
+ * @param eventName Name of the listened event
+ * @param handler A callback function to handle the event
+ */
+export declare const useWidgetPreviewEvent: (eventName: WidgetPreviewEventName, handler: WidgetPreviewEventHandler) => void;
+/**
+ * Dispatches widget preview related events.
+ * Used to trigger iFrame postMessage events to the parent window or to react on incoming
+ * postMessage events from the parent window.
+ * @param eventName Name of the event to dispatch
+ * @param widgetCode Code of the widget to dispatch the event for
+ * @param payload Optional payload to include with the event
+ */
+export declare const dispatchWidgetPreviewEvent: (eventName: WidgetPreviewEventName, widgetCode: string, payload?: unknown) => void;
+//# sourceMappingURL=events.d.ts.map

package/page/components/Widgets/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../../page/components/Widgets/events.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,kBAAkB,GAAG,gBAAgB,GAAG,sBAAsB,CAAC;AAEpG;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,KAAK,EAAE,WAAW,CAAC,wBAAwB,CAAC,KAAK,IAAI,CAAC;AAE/F;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAChC,WAAW,sBAAsB,EACjC,SAAS,yBAAyB,SASnC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,GACrC,WAAW,sBAAsB,EACjC,YAAY,MAAM,EAClB,UAAS,OAAc,SAUxB,CAAC"}

package/page/components/Widgets/events.js

@@ -1,26 +1,22 @@
 import { useEffect } from 'react';
 
 /**
- * @typedef {"highlight-widget"|"widget-clicked"|"set-active-widget-id"} WidgetPreviewEventName
+ * Names of the events that are dispatched in the context of widget preview iframe communication.
  */
 
 /**
- * @typedef {Object} WidgetPreviewEventDetail
- * @property {string} widgetCode The code of the widget related to the event.
- * @property {any} [payload] Optional payload data related to the event.
+ * Detail payload of a widget preview event.
  */
 
 /**
- * @callback WidgetPreviewEventHandler
- * @param {CustomEvent<WidgetPreviewEventDetail>} event The custom event dispatched for the widget
- * preview.
+ * Handler for a widget preview event.
  */
 
 /**
  * Hook to listen for widget preview events.
  * These events are dispatched in the context of iFrame communication at the widget preview.
- * @param {WidgetPreviewEventName} eventName Name of the listened event
- * @param {WidgetPreviewEventHandler} handler A callback function to handle the event
+ * @param eventName Name of the listened event
+ * @param handler A callback function to handle the event
  */
 export const useWidgetPreviewEvent = (eventName, handler) => {
   useEffect(() => {
@@ -35,9 +31,9 @@ export const useWidgetPreviewEvent = (eventName, handler) => {
  * Dispatches widget preview related events.
  * Used to trigger iFrame postMessage events to the parent window or to react on incoming
  * postMessage events from the parent window.
- * @param {WidgetPreviewEventName} eventName Name of the event to dispatch
- * @param {string} widgetCode Code of the widget to dispatch the event for
- * @param {Object} [payload] Optional payload to include with the event
+ * @param eventName Name of the event to dispatch
+ * @param widgetCode Code of the widget to dispatch the event for
+ * @param payload Optional payload to include with the event
  */
 export const dispatchWidgetPreviewEvent = (eventName, widgetCode, payload = null) => {
   const event = new CustomEvent(`widget-preview-${eventName}`, {

package/page/components/Widgets/helpers.d.ts

@@ -0,0 +1,69 @@
+import { type MediaMarginSettings } from '@shopgate/engage/settings/types/appSettings';
+import { type AppliedMediaMargins, type WidgetDefinitionLayout, type WidgetLayout } from './types';
+/**
+ * Retrieves the scroll container for the current page. Depending on the PWA mode this can be
+ * a scrollable article element or the window.
+ * @returns The scroll container element, or null if it could not be found.
+ */
+export declare const getScrollContainer: () => HTMLElement | null;
+/**
+ * Parameters for {@link checkScheduled}.
+ */
+export interface ScheduledParams {
+    /**
+     * The start date of the scheduling in ISO format.
+     */
+    from?: string;
+    /**
+     * The end date of the scheduling in ISO format.
+     */
+    to?: string;
+    /**
+     * The timezone offset in minutes. If not provided, the local timezone offset will be used.
+     */
+    timezoneOffset?: number;
+}
+/**
+ * The scheduling status of a widget.
+ */
+export interface ScheduledStatus {
+    /**
+     * Indicates if the widget is scheduled.
+     */
+    isScheduled: boolean;
+    /**
+     * Indicates if the widget is currently active within the scheduled time frame.
+     */
+    isActive: boolean;
+    /**
+     * Indicates if the scheduled time frame has expired.
+     */
+    isExpired: boolean;
+}
+/**
+ * Retrieves the scheduling status of a widget based on the provided parameters.
+ * @param params The parameters for the function.
+ * @param params.from The start date of the scheduling in ISO format.
+ * @param params.to The end date of the scheduling in ISO format.
+ * @param params.timezoneOffset The timezone offset in minutes.
+ * @returns An object containing the scheduling status.
+ */
+export declare function checkScheduled({ from, to, timezoneOffset }?: ScheduledParams): ScheduledStatus;
+/**
+ * Retrieves the sides on which a widget gets the media widget margins. Widgets declare them in a
+ * "config.json" inside their folder, which the build adds to the widget mapping. A widget that
+ * declares nothing keeps the margins of its own configuration.
+ * @param name The name of the widget.
+ * @returns The sides that get the media widget margins.
+ */
+export declare function getAppliedMediaMargins(name: string): AppliedMediaMargins;
+/**
+ * Resolves the margins of a widget container. The configuration of the widget instance wins over
+ * the media widget margin, which only applies to the sides the widget asked for.
+ * @param definitionLayout The layout settings of the widget instance.
+ * @param appliedMediaMargins The sides on which the widget gets the media widget margins.
+ * @param settings The media widget margins.
+ * @returns The resolved margins.
+ */
+export declare function resolveWidgetLayout(definitionLayout: Partial<WidgetDefinitionLayout> | undefined, appliedMediaMargins: AppliedMediaMargins, settings: MediaMarginSettings): WidgetLayout;
+//# sourceMappingURL=helpers.d.ts.map

package/page/components/Widgets/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../../page/components/Widgets/helpers.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,6CAA6C,CAAC;AACvF,OAAO,EACL,KAAK,mBAAmB,EAExB,KAAK,sBAAsB,EAC3B,KAAK,YAAY,EAClB,MAAM,SAAS,CAAC;AAGjB;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,QAAO,WAAW,GAAG,IACwC,CAAC;AAE7F;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB;;OAEG;IACH,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,EAAE,IAAI,EAAE,EAAE,EAAE,cAAc,EAAE,GAAE,eAAoB,GACjD,eAAe,CAqBjB;AAkBD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAgBxE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,gBAAgB,EAAE,OAAO,CAAC,sBAAsB,CAAC,GAAG,SAAS,EAC7D,mBAAmB,EAAE,mBAAmB,EACxC,QAAQ,EAAE,mBAAmB,GAC5B,YAAY,CAUd"}

package/page/components/Widgets/helpers.js

@@ -1,33 +1,31 @@
+import "core-js/modules/es.array.reduce.js";
 import "core-js/modules/es.string.replace.js";
+import { componentsConfig } from '@shopgate/pwa-common/helpers/config';
 import { PAGE_PREVIEW_PATTERN } from '@shopgate/engage/page/constants';
+import { MARGIN_SIDES, MARGIN_SIDE_SETTINGS, MEDIA_MARGIN_SIDES } from "./constants";
 
 /**
  * Retrieves the scroll container for the current page. Depending on the PWA mode this can be
  * a scrollable article element or the window.
- * @returns {HTMLElement|null}
+ * @returns The scroll container element, or null if it could not be found.
  */
 export const getScrollContainer = () => document.querySelector(`.route__${PAGE_PREVIEW_PATTERN.replace(/^\/+/, '')}`);
 
 /**
- * @typedef {Object} ScheduledParams
- * @property {string} [from] The start date of the scheduling in ISO format.
- * @property {string} [to] The end date of the scheduling in ISO format.
- * @property {number} [timezoneOffset] The timezone offset in minutes. If not provided, the local
- * timezone offset will be used.
+ * Parameters for {@link checkScheduled}.
  */
 
 /**
- * @typedef {Object} ScheduledStatus
- * @property {boolean} isScheduled Indicates if the widget is scheduled.
- * @property {boolean} isActive Indicates if the widget is currently active within the
- * scheduled time frame.
- * @property {boolean} isExpired Indicates if the scheduled time frame has expired.
+ * The scheduling status of a widget.
  */
 
 /**
  * Retrieves the scheduling status of a widget based on the provided parameters.
- * @param {ScheduledParams} [params] The parameters for the function.
- * @returns {ScheduledStatus} An object containing the scheduling status.
+ * @param params The parameters for the function.
+ * @param params.from The start date of the scheduling in ISO format.
+ * @param params.to The end date of the scheduling in ISO format.
+ * @param params.timezoneOffset The timezone offset in minutes.
+ * @returns An object containing the scheduling status.
  */
 export function checkScheduled({
   from,
@@ -50,4 +48,51 @@ export function checkScheduled({
     isActive,
     isExpired
   };
+}
+
+/**
+ * The widget mapping of the components config, reduced to what the layout resolution reads. The
+ * config itself comes from untyped JS, so the shape is described here at the consumption boundary.
+ */
+
+/**
+ * Retrieves the sides on which a widget gets the media widget margins. Widgets declare them in a
+ * "config.json" inside their folder, which the build adds to the widget mapping. A widget that
+ * declares nothing keeps the margins of its own configuration.
+ * @param name The name of the widget.
+ * @returns The sides that get the media widget margins.
+ */
+export function getAppliedMediaMargins(name) {
+  const {
+    widgetsV2
+  } = componentsConfig;
+  const declared = widgetsV2?.[name]?.config?.layout?.applyMediaMargins;
+  if (declared === true) {
+    return MEDIA_MARGIN_SIDES.reduce((sides, side) => ({
+      ...sides,
+      [side]: true
+    }), {});
+  }
+  if (declared && typeof declared === 'object') {
+    return declared;
+  }
+  return {};
+}
+
+/**
+ * Resolves the margins of a widget container. The configuration of the widget instance wins over
+ * the media widget margin, which only applies to the sides the widget asked for.
+ * @param definitionLayout The layout settings of the widget instance.
+ * @param appliedMediaMargins The sides on which the widget gets the media widget margins.
+ * @param settings The media widget margins.
+ * @returns The resolved margins.
+ */
+export function resolveWidgetLayout(definitionLayout, appliedMediaMargins, settings) {
+  return MARGIN_SIDES.reduce((layout, side) => {
+    const mediaSide = MARGIN_SIDE_SETTINGS[side];
+    return {
+      ...layout,
+      [side]: definitionLayout?.[side] ?? (appliedMediaMargins?.[mediaSide] ? settings?.[mediaSide] ?? 0 : 0)
+    };
+  }, {});
 }