@inappstory/js-sdk 3.6.2 → 3.7.0-rc.0

package/plugins/banners/types/bannerPlace.d.ts

@@ -0,0 +1,186 @@
+import { Banner } from "./banner";
+import { BannerPlaceAppearance } from "./bannerPlaceAppearance";
+
+/**
+ * Events emitted by BannerPlaceViewModel
+ * @enum {string}
+ */
+export enum BannerPlaceViewModelEvent {
+    /** Emitted when playback starts */
+    Play = "play",
+    /** Emitted when playback stops */
+    Stop = "stop",
+    /** Emitted when banner loading starts */
+    LoadStart = "loadStart",
+    /** Emitted when banner loading completes */
+    LoadEnd = "loadEnd",
+    /** Emitted when banner loading fails */
+    LoadError = "loadError"
+}
+
+/**
+ * Banner slider autoplay control
+ */
+export interface IBannerPlaceSliderAutoplay {
+    /**
+     * Gets whether autoplay is currently paused
+     * @returns {boolean} True if autoplay is paused
+     */
+    isPaused(): boolean;
+
+    /**
+     * Resumes the autoplay
+     */
+    resume(): void;
+
+    /**
+     * Pauses the autoplay
+     */
+    pause(): void;
+
+    /**
+     * Starts autoplay
+     */
+    start(duration: number): void;
+
+    /**
+     * Starts autoplay with specified duration
+     * @param {number} delay - Duration between slides in milliseconds
+     */
+    setDelay(delay: number): void;
+
+    /**
+     * Stops the autoplay completely
+     */
+    stop(): void;
+}
+
+/**
+ * Banner slider controller
+ */
+export interface IBannerPlaceSliderController {
+    /**
+     * Autoplay control instance
+     * @type {IBannerPlaceSliderAutoplay}
+     */
+    readonly autoplay: IBannerPlaceSliderAutoplay;
+
+    /**
+     * Gets total number of slides
+     * @returns {number} Total slides count
+     */
+    getTotalPages(): number;
+
+    /**
+     * Gets currently active slide index
+     * @returns {number} Active slide index
+     */
+    getActiveIndex(): number;
+
+    /**
+     * Navigates to next slide
+     */
+    toNextSlide(): void;
+
+    /**
+     * Navigates to previous slide
+     */
+    toPrevSlide(): void;
+
+    /**
+     * Slides to specific index
+     * @param {number} index - Target slide index
+     * @param {number} [speed] - Optional transition speed in milliseconds
+     */
+    slideTo(index: number, speed?: number): void;
+}
+
+/**
+ * ViewModel for managing banner place state and behavior
+ */
+export interface BannerPlace {
+    /**
+     * Gets the banner place identifier
+     * @returns {string}
+     */
+    get id(): string;
+
+    /**
+     * Gets the current banners
+     * @returns {Banner[]}
+     */
+    get banners(): Banner[];
+
+    /**
+     * Gets the median content ratio of all banners
+     * @returns {number}
+     */
+    get contentRatio(): number;
+
+    /**
+     * Gets whether banners are currently loading
+     * @returns {boolean}
+     */
+    get isLoading(): boolean;
+
+    /**
+     * Gets the slider controller instance
+     * @returns {IBannerPlaceSliderController}
+     */
+    get slider(): IBannerPlaceSliderController;
+
+    /**
+     * Gets the index of currently active banner
+     * @returns {number}
+     */
+    get activeIndex(): number;
+
+    /**
+     * Sets the slider controller implementation
+     * @param {IBannerPlaceSliderController} sliderController - The slider controller to use
+     */
+    setSliderController(sliderController: IBannerPlaceSliderController): void;
+
+    /**
+     * Updates appearance options from DTO
+     * @param {BannerPlaceAppearance} appearance - Appearance configuration
+     */
+    updateAppearance(appearance: BannerPlaceAppearance): void;
+
+    /**
+     * Starts playback of all banners
+     */
+    play(): void;
+
+    /**
+     * Stops playback of all banners
+     */
+    stop(): void;
+
+    /**
+     * Reloads banners for this place
+     * @returns {Promise<Banner[]>}
+     */
+    reload(): Promise<Banner[]>;
+
+    /**
+     * Cleans up resources and destroys all banners
+     */
+    destroy(): void;
+
+    /**
+     * Updates user-specific data for this banner place
+     * @param {string} data - User data to store
+     * @returns {Promise<void>}
+     */
+    updateUserData(data: string): Promise<void>;
+
+    /**
+     * Fetches banners from store and creates view models
+     * @returns {Promise<Banner[]>}
+     * @emits BannerPlaceViewModelEvent.LoadStart
+     * @emits BannerPlaceViewModelEvent.LoadEnd
+     * @emits BannerPlaceViewModelEvent.LoadError
+     */
+    fetchBanners(): Promise<Banner[]>;
+}

package/plugins/banners/types/bannerPlaceAppearance.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Banner place appearance settings
+ */
+export interface BannerPlaceAppearance {
+    /**  Set to true to enable continuous loop mode.
+     * Because of nature of how the loop mode works (it will rearrange slides), total number of slides must be
+     * more than or equal to slidesPerView + 1 */
+    loop?: boolean;
+    /** Space between slides */
+    gap?: number;
+    /** Enables autoplay */
+    autoplay?: boolean;
+    /** Slides per view */
+    slidesPerView?: number;
+    /** Transition duration (in ms) */
+    animationSpeed?: number;
+    /** Navigation params */
+    navigation?: {
+        /** Control default navigation */
+        enabled?: boolean;
+    };
+    /** Pagination params */
+    pagination?: {
+        /** Control default pagination */
+        enabled?: boolean;
+    };
+    /** Banner card appearance options */
+    banner?: {
+        /** Border radius of banner */
+        borderRadius?: number;
+    };
+}

package/plugins/banners/types/iasBannerPlace.d.ts

@@ -0,0 +1,77 @@
+import { BannerPlace } from "./bannerPlace";
+import { BannerPlaceAppearance } from "./bannerPlaceAppearance";
+
+/**
+ * Props for IasBannerPlace component
+ * @interface
+ */
+interface IasBannerPlaceProps {
+    /**
+     * Unique identifier for the banner place
+     * @optional
+     */
+    placeId?: string;
+
+    /**
+     * Appearance configuration options for the banner place
+     * @optional
+     * @type {BannerPlaceAppearance}
+     */
+    appearance?: BannerPlaceAppearance;
+
+    /**
+     * Inline CSS styles for the banner place
+     * @optional
+     * @type {React.CSSProperties}
+     */
+    style?: React.CSSProperties;
+
+    /**
+     * CSS class name(s) for the banner place
+     * @optional
+     * @type {string}
+     */
+    className?: string;
+
+    /**
+     * Callback triggered when banner loading starts
+     * @optional
+     */
+    onLoadStart?: () => void;
+
+    /**
+     * Callback triggered when banner loading completes
+     * @optional
+     */
+    onLoadEnd?: () => void;
+
+    /**
+     * Callback triggered when banner loading fails
+     * @param {Error} error - The error that occurred
+     * @optional
+     */
+    onLoadError?: (error: Error) => void;
+
+    /**
+     * Callback triggered when banner place is ready
+     * @param {BannerPlace} bannerPlace - The initialized banner place instance
+     * @optional
+     */
+    onReady?: (bannerPlace: BannerPlace) => void;
+}
+
+/**
+ * React component for displaying a banner place
+ * @component
+ * @param {IasBannerPlaceProps} props - Component properties
+ * @returns {JSX.Element} Banner place component
+ *
+ * @example
+ * <IasBannerPlace
+ *   placeId="main-banner"
+ *   appearanceOptions={appearanceOptions}
+ *   onReady={(place) => console.log('Banner ready', place)}
+ *   onLoadError={(error) => console.error('Load failed', error)}
+ * />
+ */
+export declare const IasBannerPlace: (props: IasBannerPlaceProps) => JSX.Element;

package/plugins/banners/types/iasBannerPreview.d.ts

@@ -0,0 +1,58 @@
+import { BannerPlace } from "./bannerPlace";
+/**
+ * Props for IasBannerPreview component
+ * @interface
+ */
+interface IasBannerPreviewProps {
+    /**
+     * Unique identifier of the banner to preview
+     * @type {string | number}
+     * @required
+     */
+    bannerId: string | number;
+
+    /**
+     * Callback triggered when banner preview loading starts
+     * @optional
+     */
+    onLoadStart?: () => void;
+
+    /**
+     * Callback triggered when banner preview loading completes
+     * @optional
+     */
+    onLoadEnd?: () => void;
+
+    /**
+     * Callback triggered when banner preview loading fails
+     * @param {Error} error - The error that occurred during loading
+     * @optional
+     */
+    onLoadError?: (error: Error) => void;
+
+    /**
+     * Callback triggered when banner preview is ready
+     * @param {BannerPlace} bannerPlace - The initialized banner place instance
+     * @optional
+     */
+    onReady?: (bannerPlace: BannerPlace) => void;
+}
+
+/**
+ * React component for displaying a banner preview
+ * @component
+ * @param {IasBannerPreviewProps} props - Component properties
+ * @returns {JSX.Element} Banner preview component
+ *
+ * @example
+ * <IasBannerPreview
+ *   bannerId="12345"
+ *   onReady={(place) => console.log('Preview ready', place)}
+ *   onLoadError={(error) => console.error('Preview load failed', error)}
+ * />
+ *
+ * @example
+ * // Minimal usage
+ * <IasBannerPreview bannerId={42} />
+ */
+export declare const IasBannerPreview: (props: IasBannerPreviewProps) => JSX.Element;

package/plugins/banners/types/iasBannersProvider.d.ts

@@ -0,0 +1,52 @@
+import { BannerPlace } from "./bannerPlace";
+import { BannerPlaceAppearance } from "./bannerPlaceAppearance";
+
+export interface BannerPlaceWidget extends BannerPlace {}
+
+export interface IasBannersProvider {
+    /**
+     * Clears all banner places by destroying them and resetting the collection.
+     * @example
+     * inAppStoryManager.banners.clear();
+     */
+    clear(): void;
+
+    /**
+     * Creates a new banner place instance with optional place ID.
+     * @param {string | number} [placeId] - Optional identifier for the banner place
+     * @returns {BannerPlace} New banner place view model instance
+     * @example
+     * const bannerPlace = inAppStoryManager.banners.createBannerPlace('your-banner-place');
+     */
+    createBannerPlace(placeId?: string | number): BannerPlace;
+
+    /**
+     * Mounts a banner place component to the specified DOM element.
+     * @param {string} mountSelector - CSS selector for the mount element
+     * @param {Object} [params] - Optional parameters
+     * @param {string} [params.placeId="default"] - Identifier for the banner place (defaults to "default" if not provided)
+     * @param {BannerPlaceAppearance} [params.appearance] - Appearance configuration (optional)
+     * @throws {Error} If mount point not found
+     * @returns {BannerPlaceWidget} The created banner place instance
+     * @example
+     * // Minimal usage with defaults
+     * inAppStoryManager.banners.mountBannerPlace('#banner-container');
+     *
+     * @example
+     * // With appearance configuration
+     * inAppStoryManager.banners.mountBannerPlace('#banner-container', {
+     *   appearance: { /* appearance options *\/ }
+     * });
+     *
+     * @example
+     * // With custom placeId and appearance
+     * inAppStoryManager.banners.mountBannerPlace('#banner-container', {
+     *   placeId: 'header-banner',
+     *   appearance: { /* appearance options *\/ }
+     * });
+     */
+    mountBannerPlace(
+        mountSelector: string,
+        params?: { placeId?: string; appearance?: BannerPlaceAppearance }
+    ): BannerPlaceWidget;
+}

package/plugins/banners/types/index.d.ts

@@ -0,0 +1,29 @@
+export * from "./banner";
+export * from "./bannerPlace";
+export * from "./bannerPlaceAppearance";
+export * from "./iasBannerPlace";
+export * from "./iasBannerPreview";
+export * from "./iasBannersProvider";
+
+import { IasBannersProvider } from "./iasBannersProvider";
+
+declare module "@inappstory/js-sdk" {
+    interface InAppStoryManager {
+        banners: IasBannersProvider;
+    }
+}
+
+declare module "@inappstory/react-sdk" {
+    interface StoryManager {
+        banners: IasBannersProvider;
+    }
+}
+
+export declare class IasBannersPlugin {
+    name: string;
+    install(storyManager: any): void;
+    uninstall(): void;
+}
+
+declare const pluginInstance: IasBannersPlugin;
+export default pluginInstance;