@elementor/editor-modal-shell 4.2.0-919

package/dist/index.d.mts

@@ -0,0 +1,56 @@
+import * as React from 'react';
+import { ReactNode } from 'react';
+import { SxProps, Theme } from '@elementor/ui';
+
+declare const MODAL_Z_INDEX = 99999;
+type ModalShellContextValue = {
+    close: () => void;
+};
+declare const useModalShell: () => ModalShellContextValue;
+type ModalShellProps = {
+    children: ReactNode;
+    onClose?: () => void;
+    revealDuration?: number;
+    revealDelay?: number;
+    container?: HTMLElement;
+    sx?: SxProps<Theme>;
+    closeOnEsc?: boolean;
+    closeOnOutsideClick?: boolean;
+    backdrop?: boolean;
+    backdropSx?: SxProps<Theme>;
+    hideCloseButton?: boolean;
+};
+declare const ModalShell: ({ children, onClose, revealDuration, revealDelay, container, sx, closeOnEsc, closeOnOutsideClick, backdrop, backdropSx, hideCloseButton, }: ModalShellProps) => React.JSX.Element;
+
+type ModalHeaderProps = {
+    title: string;
+    content: ReactNode;
+};
+declare const ModalHeader: ({ title, content }: ModalHeaderProps) => React.JSX.Element;
+
+type FooterLinkData = {
+    text: string;
+    url: string;
+};
+type ModalFooterProps = {
+    helpText: string;
+    link: FooterLinkData;
+};
+declare const ModalFooter: ({ helpText, link }: ModalFooterProps) => React.JSX.Element;
+
+type BackgroundLottieProps = {
+    animationData: object;
+    loop?: boolean;
+    autoplay?: boolean;
+    zIndex?: number;
+    backgroundColor?: string;
+    onComplete?: () => void;
+};
+declare function BackgroundLottie({ animationData, loop, autoplay, zIndex, backgroundColor, onComplete, }: BackgroundLottieProps): React.JSX.Element | null;
+
+declare function useAutoplayCarousel<T>(items: T[], intervalMs?: number): {
+    selectedItem: T;
+    selectItem: (item: T) => void;
+};
+
+export { BackgroundLottie, MODAL_Z_INDEX, ModalFooter, ModalHeader, ModalShell, type ModalShellProps, useAutoplayCarousel, useModalShell };

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+import * as React from 'react';
+import { ReactNode } from 'react';
+import { SxProps, Theme } from '@elementor/ui';
+
+declare const MODAL_Z_INDEX = 99999;
+type ModalShellContextValue = {
+    close: () => void;
+};
+declare const useModalShell: () => ModalShellContextValue;
+type ModalShellProps = {
+    children: ReactNode;
+    onClose?: () => void;
+    revealDuration?: number;
+    revealDelay?: number;
+    container?: HTMLElement;
+    sx?: SxProps<Theme>;
+    closeOnEsc?: boolean;
+    closeOnOutsideClick?: boolean;
+    backdrop?: boolean;
+    backdropSx?: SxProps<Theme>;
+    hideCloseButton?: boolean;
+};
+declare const ModalShell: ({ children, onClose, revealDuration, revealDelay, container, sx, closeOnEsc, closeOnOutsideClick, backdrop, backdropSx, hideCloseButton, }: ModalShellProps) => React.JSX.Element;
+
+type ModalHeaderProps = {
+    title: string;
+    content: ReactNode;
+};
+declare const ModalHeader: ({ title, content }: ModalHeaderProps) => React.JSX.Element;
+
+type FooterLinkData = {
+    text: string;
+    url: string;
+};
+type ModalFooterProps = {
+    helpText: string;
+    link: FooterLinkData;
+};
+declare const ModalFooter: ({ helpText, link }: ModalFooterProps) => React.JSX.Element;
+
+type BackgroundLottieProps = {
+    animationData: object;
+    loop?: boolean;
+    autoplay?: boolean;
+    zIndex?: number;
+    backgroundColor?: string;
+    onComplete?: () => void;
+};
+declare function BackgroundLottie({ animationData, loop, autoplay, zIndex, backgroundColor, onComplete, }: BackgroundLottieProps): React.JSX.Element | null;
+
+declare function useAutoplayCarousel<T>(items: T[], intervalMs?: number): {
+    selectedItem: T;
+    selectItem: (item: T) => void;
+};
+
+export { BackgroundLottie, MODAL_Z_INDEX, ModalFooter, ModalHeader, ModalShell, type ModalShellProps, useAutoplayCarousel, useModalShell };

package/dist/index.js

@@ -0,0 +1,251 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BackgroundLottie: () => BackgroundLottie,
+  MODAL_Z_INDEX: () => MODAL_Z_INDEX,
+  ModalFooter: () => ModalFooter,
+  ModalHeader: () => ModalHeader,
+  ModalShell: () => ModalShell,
+  useAutoplayCarousel: () => useAutoplayCarousel,
+  useModalShell: () => useModalShell
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/components/modal-shell.tsx
+var React = __toESM(require("react"));
+var import_react = require("react");
+var import_ui = require("@elementor/ui");
+var MODAL_Z_INDEX = 99999;
+var DEFAULT_WIDTH = 800;
+var DEFAULT_HEIGHT = 400;
+var DEFAULT_REVEAL_DURATION_MS = 500;
+var DEFAULT_REVEAL_DELAY_MS = 0;
+var ModalShellContext = (0, import_react.createContext)(null);
+var useModalShell = () => {
+  const ctx = (0, import_react.useContext)(ModalShellContext);
+  if (!ctx) {
+    throw new Error("useModalShell must be used inside a <ModalShell />");
+  }
+  return ctx;
+};
+var EXIT_TRANSITION_MS = 225;
+var prefersReducedMotion = () => typeof window !== "undefined" && Boolean(window.matchMedia?.("(prefers-reduced-motion: reduce)").matches);
+var ModalShell = ({
+  children,
+  onClose,
+  revealDuration = DEFAULT_REVEAL_DURATION_MS,
+  revealDelay = DEFAULT_REVEAL_DELAY_MS,
+  container,
+  sx = {},
+  closeOnEsc = true,
+  closeOnOutsideClick = true,
+  backdrop = true,
+  backdropSx = {},
+  hideCloseButton = false
+}) => {
+  const portalTarget = container ?? (typeof document !== "undefined" ? document.body : void 0);
+  const reducedMotion = prefersReducedMotion();
+  const consumerOwnsEnter = revealDuration === 0 || reducedMotion;
+  const [open, setOpen] = (0, import_react.useState)(true);
+  const startClose = (0, import_react.useCallback)(() => setOpen(false), []);
+  const contextValue = (0, import_react.useMemo)(() => ({ close: startClose }), [startClose]);
+  const handleDialogClose = (_event, reason) => {
+    if (reason === "escapeKeyDown" && !closeOnEsc) {
+      return;
+    }
+    if (reason === "backdropClick" && !closeOnOutsideClick) {
+      return;
+    }
+    startClose();
+  };
+  const transitionTimeouts = (0, import_react.useMemo)(
+    () => ({ enter: 0, exit: reducedMotion ? 0 : EXIT_TRANSITION_MS }),
+    [reducedMotion]
+  );
+  const animationProps = (0, import_react.useMemo)(
+    () => consumerOwnsEnter ? {} : {
+      animation: `e-modal-shell-reveal ${revealDuration}ms ease ${revealDelay}ms backwards`,
+      "@keyframes e-modal-shell-reveal": {
+        from: { opacity: 0, transform: "scale(0.95)" },
+        to: { opacity: 1, transform: "scale(1)" }
+      }
+    },
+    [consumerOwnsEnter, revealDuration, revealDelay]
+  );
+  return /* @__PURE__ */ React.createElement(
+    import_ui.Dialog,
+    {
+      open,
+      maxWidth: false,
+      onClose: handleDialogClose,
+      container: portalTarget,
+      disableEscapeKeyDown: !closeOnEsc,
+      hideBackdrop: !backdrop,
+      TransitionProps: { onExited: onClose, timeout: transitionTimeouts },
+      slotProps: { backdrop: { transitionDuration: transitionTimeouts, sx: backdropSx } },
+      PaperProps: {
+        sx: {
+          width: DEFAULT_WIDTH,
+          height: DEFAULT_HEIGHT,
+          maxWidth: "100%",
+          overflow: "hidden",
+          ...animationProps,
+          ...sx
+        }
+      },
+      sx: {
+        zIndex: MODAL_Z_INDEX
+      }
+    },
+    /* @__PURE__ */ React.createElement(ModalShellContext.Provider, { value: contextValue }, /* @__PURE__ */ React.createElement(import_ui.Box, { sx: { display: "contents" } }, children, !hideCloseButton && /* @__PURE__ */ React.createElement(
+      import_ui.CloseButton,
+      {
+        onClick: startClose,
+        sx: {
+          position: "absolute",
+          right: 16,
+          top: 16,
+          zIndex: 3
+        }
+      }
+    )))
+  );
+};
+
+// src/components/modal-header.tsx
+var React2 = __toESM(require("react"));
+var import_ui2 = require("@elementor/ui");
+var ModalHeader = ({ title, content }) => {
+  return /* @__PURE__ */ React2.createElement(import_ui2.Stack, { gap: 0.75 }, /* @__PURE__ */ React2.createElement(import_ui2.Typography, { variant: "h4", color: "text.primary" }, title), /* @__PURE__ */ React2.createElement(import_ui2.Typography, { variant: "subtitle2", color: "text.primary" }, content));
+};
+
+// src/components/modal-footer.tsx
+var React3 = __toESM(require("react"));
+var import_ui3 = require("@elementor/ui");
+var ModalFooter = ({ helpText, link }) => {
+  return /* @__PURE__ */ React3.createElement(import_ui3.Stack, { direction: "row", alignItems: "center", gap: 1 }, /* @__PURE__ */ React3.createElement(import_ui3.Typography, { variant: "caption", color: "text.tertiary", sx: { fontSize: "11px", lineHeight: "normal" } }, helpText), /* @__PURE__ */ React3.createElement(
+    import_ui3.Button,
+    {
+      href: link.url,
+      target: "_blank",
+      variant: "text",
+      size: "small",
+      color: "info",
+      sx: { fontSize: "11px" }
+    },
+    link.text
+  ));
+};
+
+// src/components/background-lottie.tsx
+var React4 = __toESM(require("react"));
+var import_react2 = require("react");
+var import_lottie_react = __toESM(require("lottie-react"));
+function BackgroundLottie({
+  animationData,
+  loop = false,
+  autoplay = true,
+  zIndex = MODAL_Z_INDEX - 1,
+  backgroundColor = "transparent",
+  onComplete = () => {
+  }
+}) {
+  const prefersReducedMotion2 = typeof window !== "undefined" && window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+  (0, import_react2.useEffect)(() => {
+    if (prefersReducedMotion2) {
+      onComplete?.();
+    }
+  }, [prefersReducedMotion2, onComplete]);
+  if (prefersReducedMotion2) {
+    return null;
+  }
+  return /* @__PURE__ */ React4.createElement(
+    import_lottie_react.default,
+    {
+      animationData,
+      loop,
+      autoplay,
+      onComplete: loop ? void 0 : onComplete,
+      onDataFailed: onComplete,
+      rendererSettings: {
+        preserveAspectRatio: "xMidYMid slice"
+      },
+      style: {
+        position: "fixed",
+        inset: 0,
+        width: "100vw",
+        height: "100vh",
+        zIndex,
+        backgroundColor,
+        pointerEvents: "none"
+      }
+    }
+  );
+}
+
+// src/hooks/use-autoplay-carousel.ts
+var import_react3 = require("react");
+var DEFAULT_INTERVAL_MS = 4e3;
+function useAutoplayCarousel(items, intervalMs = DEFAULT_INTERVAL_MS) {
+  const [selectedItem, setSelectedItem] = (0, import_react3.useState)(items[0]);
+  const [isAutoPlaying, setIsAutoPlaying] = (0, import_react3.useState)(true);
+  const advanceToNextItem = (0, import_react3.useCallback)(() => {
+    setSelectedItem((current) => {
+      const currentIndex = items.indexOf(current);
+      const nextIndex = (currentIndex + 1) % items.length;
+      return items[nextIndex];
+    });
+  }, [items]);
+  (0, import_react3.useEffect)(() => {
+    if (!isAutoPlaying) {
+      return;
+    }
+    const id = setInterval(advanceToNextItem, intervalMs);
+    return () => clearInterval(id);
+  }, [isAutoPlaying, advanceToNextItem, intervalMs]);
+  const selectItem = (0, import_react3.useCallback)((item) => {
+    setSelectedItem(item);
+    setIsAutoPlaying(false);
+  }, []);
+  return { selectedItem, selectItem };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BackgroundLottie,
+  MODAL_Z_INDEX,
+  ModalFooter,
+  ModalHeader,
+  ModalShell,
+  useAutoplayCarousel,
+  useModalShell
+});
+//# sourceMappingURL=index.js.map

package/dist/index.mjs

@@ -0,0 +1,208 @@
+// src/components/modal-shell.tsx
+import * as React from "react";
+import { createContext, useCallback, useContext, useMemo, useState } from "react";
+import { Box, CloseButton, Dialog } from "@elementor/ui";
+var MODAL_Z_INDEX = 99999;
+var DEFAULT_WIDTH = 800;
+var DEFAULT_HEIGHT = 400;
+var DEFAULT_REVEAL_DURATION_MS = 500;
+var DEFAULT_REVEAL_DELAY_MS = 0;
+var ModalShellContext = createContext(null);
+var useModalShell = () => {
+  const ctx = useContext(ModalShellContext);
+  if (!ctx) {
+    throw new Error("useModalShell must be used inside a <ModalShell />");
+  }
+  return ctx;
+};
+var EXIT_TRANSITION_MS = 225;
+var prefersReducedMotion = () => typeof window !== "undefined" && Boolean(window.matchMedia?.("(prefers-reduced-motion: reduce)").matches);
+var ModalShell = ({
+  children,
+  onClose,
+  revealDuration = DEFAULT_REVEAL_DURATION_MS,
+  revealDelay = DEFAULT_REVEAL_DELAY_MS,
+  container,
+  sx = {},
+  closeOnEsc = true,
+  closeOnOutsideClick = true,
+  backdrop = true,
+  backdropSx = {},
+  hideCloseButton = false
+}) => {
+  const portalTarget = container ?? (typeof document !== "undefined" ? document.body : void 0);
+  const reducedMotion = prefersReducedMotion();
+  const consumerOwnsEnter = revealDuration === 0 || reducedMotion;
+  const [open, setOpen] = useState(true);
+  const startClose = useCallback(() => setOpen(false), []);
+  const contextValue = useMemo(() => ({ close: startClose }), [startClose]);
+  const handleDialogClose = (_event, reason) => {
+    if (reason === "escapeKeyDown" && !closeOnEsc) {
+      return;
+    }
+    if (reason === "backdropClick" && !closeOnOutsideClick) {
+      return;
+    }
+    startClose();
+  };
+  const transitionTimeouts = useMemo(
+    () => ({ enter: 0, exit: reducedMotion ? 0 : EXIT_TRANSITION_MS }),
+    [reducedMotion]
+  );
+  const animationProps = useMemo(
+    () => consumerOwnsEnter ? {} : {
+      animation: `e-modal-shell-reveal ${revealDuration}ms ease ${revealDelay}ms backwards`,
+      "@keyframes e-modal-shell-reveal": {
+        from: { opacity: 0, transform: "scale(0.95)" },
+        to: { opacity: 1, transform: "scale(1)" }
+      }
+    },
+    [consumerOwnsEnter, revealDuration, revealDelay]
+  );
+  return /* @__PURE__ */ React.createElement(
+    Dialog,
+    {
+      open,
+      maxWidth: false,
+      onClose: handleDialogClose,
+      container: portalTarget,
+      disableEscapeKeyDown: !closeOnEsc,
+      hideBackdrop: !backdrop,
+      TransitionProps: { onExited: onClose, timeout: transitionTimeouts },
+      slotProps: { backdrop: { transitionDuration: transitionTimeouts, sx: backdropSx } },
+      PaperProps: {
+        sx: {
+          width: DEFAULT_WIDTH,
+          height: DEFAULT_HEIGHT,
+          maxWidth: "100%",
+          overflow: "hidden",
+          ...animationProps,
+          ...sx
+        }
+      },
+      sx: {
+        zIndex: MODAL_Z_INDEX
+      }
+    },
+    /* @__PURE__ */ React.createElement(ModalShellContext.Provider, { value: contextValue }, /* @__PURE__ */ React.createElement(Box, { sx: { display: "contents" } }, children, !hideCloseButton && /* @__PURE__ */ React.createElement(
+      CloseButton,
+      {
+        onClick: startClose,
+        sx: {
+          position: "absolute",
+          right: 16,
+          top: 16,
+          zIndex: 3
+        }
+      }
+    )))
+  );
+};
+
+// src/components/modal-header.tsx
+import * as React2 from "react";
+import { Stack, Typography } from "@elementor/ui";
+var ModalHeader = ({ title, content }) => {
+  return /* @__PURE__ */ React2.createElement(Stack, { gap: 0.75 }, /* @__PURE__ */ React2.createElement(Typography, { variant: "h4", color: "text.primary" }, title), /* @__PURE__ */ React2.createElement(Typography, { variant: "subtitle2", color: "text.primary" }, content));
+};
+
+// src/components/modal-footer.tsx
+import * as React3 from "react";
+import { Button, Stack as Stack2, Typography as Typography2 } from "@elementor/ui";
+var ModalFooter = ({ helpText, link }) => {
+  return /* @__PURE__ */ React3.createElement(Stack2, { direction: "row", alignItems: "center", gap: 1 }, /* @__PURE__ */ React3.createElement(Typography2, { variant: "caption", color: "text.tertiary", sx: { fontSize: "11px", lineHeight: "normal" } }, helpText), /* @__PURE__ */ React3.createElement(
+    Button,
+    {
+      href: link.url,
+      target: "_blank",
+      variant: "text",
+      size: "small",
+      color: "info",
+      sx: { fontSize: "11px" }
+    },
+    link.text
+  ));
+};
+
+// src/components/background-lottie.tsx
+import * as React4 from "react";
+import { useEffect } from "react";
+import Lottie from "lottie-react";
+function BackgroundLottie({
+  animationData,
+  loop = false,
+  autoplay = true,
+  zIndex = MODAL_Z_INDEX - 1,
+  backgroundColor = "transparent",
+  onComplete = () => {
+  }
+}) {
+  const prefersReducedMotion2 = typeof window !== "undefined" && window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+  useEffect(() => {
+    if (prefersReducedMotion2) {
+      onComplete?.();
+    }
+  }, [prefersReducedMotion2, onComplete]);
+  if (prefersReducedMotion2) {
+    return null;
+  }
+  return /* @__PURE__ */ React4.createElement(
+    Lottie,
+    {
+      animationData,
+      loop,
+      autoplay,
+      onComplete: loop ? void 0 : onComplete,
+      onDataFailed: onComplete,
+      rendererSettings: {
+        preserveAspectRatio: "xMidYMid slice"
+      },
+      style: {
+        position: "fixed",
+        inset: 0,
+        width: "100vw",
+        height: "100vh",
+        zIndex,
+        backgroundColor,
+        pointerEvents: "none"
+      }
+    }
+  );
+}
+
+// src/hooks/use-autoplay-carousel.ts
+import { useCallback as useCallback2, useEffect as useEffect2, useState as useState2 } from "react";
+var DEFAULT_INTERVAL_MS = 4e3;
+function useAutoplayCarousel(items, intervalMs = DEFAULT_INTERVAL_MS) {
+  const [selectedItem, setSelectedItem] = useState2(items[0]);
+  const [isAutoPlaying, setIsAutoPlaying] = useState2(true);
+  const advanceToNextItem = useCallback2(() => {
+    setSelectedItem((current) => {
+      const currentIndex = items.indexOf(current);
+      const nextIndex = (currentIndex + 1) % items.length;
+      return items[nextIndex];
+    });
+  }, [items]);
+  useEffect2(() => {
+    if (!isAutoPlaying) {
+      return;
+    }
+    const id = setInterval(advanceToNextItem, intervalMs);
+    return () => clearInterval(id);
+  }, [isAutoPlaying, advanceToNextItem, intervalMs]);
+  const selectItem = useCallback2((item) => {
+    setSelectedItem(item);
+    setIsAutoPlaying(false);
+  }, []);
+  return { selectedItem, selectItem };
+}
+export {
+  BackgroundLottie,
+  MODAL_Z_INDEX,
+  ModalFooter,
+  ModalHeader,
+  ModalShell,
+  useAutoplayCarousel,
+  useModalShell
+};
+//# sourceMappingURL=index.mjs.map

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@elementor/editor-modal-shell",
+  "description": "Reusable modal shell primitives for Elementor editor promotional and announcement modals",
+  "version": "4.2.0-919",
+  "private": false,
+  "author": "Elementor Team",
+  "homepage": "https://elementor.com/",
+  "license": "GPL-3.0-or-later",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/elementor/elementor.git",
+    "directory": "packages/libs/editor-modal-shell"
+  },
+  "bugs": {
+    "url": "https://github.com/elementor/elementor/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup --config=../../tsup.build.ts",
+    "dev": "tsup --config=../../tsup.dev.ts"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "dependencies": {
+    "@elementor/icons": "~1.75.1",
+    "@elementor/ui": "1.37.5",
+    "lottie-react": "^2.4.1"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5"
+  }
+}

package/src/components/__tests__/background-lottie.test.tsx

@@ -0,0 +1,60 @@
+import * as React from 'react';
+import { render, screen } from '@testing-library/react';
+
+import { BackgroundLottie } from '../background-lottie';
+
+const LOTTIE_LABEL = 'mock-lottie-player';
+
+jest.mock( 'lottie-react', () => ( {
+	__esModule: true,
+	default: () => <div aria-label={ LOTTIE_LABEL } />,
+} ) );
+
+function mockMatchMedia( reducedMotion: boolean ) {
+	Object.defineProperty( window, 'matchMedia', {
+		writable: true,
+		configurable: true,
+		value: jest.fn().mockImplementation( ( query: string ) => ( {
+			matches: query === '(prefers-reduced-motion: reduce)' ? reducedMotion : false,
+			media: query,
+			addListener: jest.fn(),
+			removeListener: jest.fn(),
+			addEventListener: jest.fn(),
+			removeEventListener: jest.fn(),
+			dispatchEvent: jest.fn(),
+			onchange: null,
+		} ) ),
+	} );
+}
+
+describe( 'BackgroundLottie', () => {
+	const animationData = {};
+
+	it( 'should render the Lottie player by default', () => {
+		mockMatchMedia( false );
+
+		render( <BackgroundLottie animationData={ animationData } /> );
+
+		expect( screen.getByLabelText( LOTTIE_LABEL ) ).toBeInTheDocument();
+	} );
+
+	describe( 'when prefers-reduced-motion is reduce', () => {
+		beforeEach( () => {
+			mockMatchMedia( true );
+		} );
+
+		it( 'should not render the Lottie player', () => {
+			render( <BackgroundLottie animationData={ animationData } /> );
+
+			expect( screen.queryByLabelText( LOTTIE_LABEL ) ).not.toBeInTheDocument();
+		} );
+
+		it( 'should call onComplete from a side-effect, not during render', () => {
+			const onComplete = jest.fn();
+
+			render( <BackgroundLottie animationData={ animationData } onComplete={ onComplete } /> );
+
+			expect( onComplete ).toHaveBeenCalledTimes( 1 );
+		} );
+	} );
+} );

package/src/components/__tests__/modal-shell.test.tsx

@@ -0,0 +1,167 @@
+import * as React from 'react';
+import { act, fireEvent, render, renderHook, screen } from '@testing-library/react';
+
+import { ModalShell, useModalShell } from '../modal-shell';
+
+const EXIT_TRANSITION_MS = 225;
+
+function mockMatchMedia( reducedMotion: boolean ) {
+	Object.defineProperty( window, 'matchMedia', {
+		writable: true,
+		configurable: true,
+		value: jest.fn().mockImplementation( ( query: string ) => ( {
+			matches: query === '(prefers-reduced-motion: reduce)' ? reducedMotion : false,
+			media: query,
+			addListener: jest.fn(),
+			removeListener: jest.fn(),
+			addEventListener: jest.fn(),
+			removeEventListener: jest.fn(),
+			dispatchEvent: jest.fn(),
+			onchange: null,
+		} ) ),
+	} );
+}
+
+beforeEach( () => {
+	mockMatchMedia( false );
+	jest.useFakeTimers();
+} );
+
+afterEach( () => {
+	if ( jest.isMockFunction( setTimeout ) ) {
+		jest.runOnlyPendingTimers();
+	}
+
+	jest.useRealTimers();
+} );
+
+describe( 'ModalShell', () => {
+	it( 'should render children inside the dialog', () => {
+		render(
+			<ModalShell>
+				<div>shell content</div>
+			</ModalShell>
+		);
+
+		expect( screen.getByRole( 'dialog' ) ).toBeInTheDocument();
+		expect( screen.getByText( 'shell content' ) ).toBeInTheDocument();
+	} );
+
+	it( 'should render the close button by default', () => {
+		render(
+			<ModalShell>
+				<div>x</div>
+			</ModalShell>
+		);
+
+		expect( screen.getByRole( 'button', { name: /close/i } ) ).toBeInTheDocument();
+	} );
+
+	it( 'should not render the close button when hideCloseButton is true', () => {
+		render(
+			<ModalShell hideCloseButton>
+				<div>x</div>
+			</ModalShell>
+		);
+
+		expect( screen.queryByRole( 'button', { name: /close/i } ) ).not.toBeInTheDocument();
+	} );
+
+	it( 'should call onClose only after the exit transition completes', () => {
+		const onClose = jest.fn();
+
+		render(
+			<ModalShell onClose={ onClose }>
+				<div>x</div>
+			</ModalShell>
+		);
+
+		fireEvent.click( screen.getByRole( 'button', { name: /close/i } ) );
+
+		expect( onClose ).not.toHaveBeenCalled();
+
+		act( () => {
+			jest.advanceTimersByTime( EXIT_TRANSITION_MS );
+		} );
+
+		expect( onClose ).toHaveBeenCalledTimes( 1 );
+	} );
+
+	it( 'should ignore Escape key when closeOnEsc is false', () => {
+		const onClose = jest.fn();
+
+		render(
+			<ModalShell onClose={ onClose } closeOnEsc={ false }>
+				<div>x</div>
+			</ModalShell>
+		);
+
+		fireEvent.keyDown( screen.getByRole( 'dialog' ), { key: 'Escape' } );
+
+		act( () => {
+			jest.advanceTimersByTime( EXIT_TRANSITION_MS );
+		} );
+
+		expect( onClose ).not.toHaveBeenCalled();
+	} );
+
+	it( 'should expose a close() function via useModalShell context', () => {
+		const onClose = jest.fn();
+		const ChildCta = () => {
+			const { close } = useModalShell();
+			return (
+				<button type="button" onClick={ close }>
+					trigger
+				</button>
+			);
+		};
+
+		render(
+			<ModalShell onClose={ onClose }>
+				<ChildCta />
+			</ModalShell>
+		);
+
+		fireEvent.click( screen.getByRole( 'button', { name: 'trigger' } ) );
+
+		act( () => {
+			jest.advanceTimersByTime( EXIT_TRANSITION_MS );
+		} );
+
+		expect( onClose ).toHaveBeenCalledTimes( 1 );
+	} );
+
+	it( 'should throw when useModalShell is used outside a provider', () => {
+		const consoleError = jest.spyOn( console, 'error' ).mockImplementation( () => {} );
+
+		expect( () => renderHook( () => useModalShell() ) ).toThrow(
+			'useModalShell must be used inside a <ModalShell />'
+		);
+
+		consoleError.mockRestore();
+	} );
+
+	describe( 'when prefers-reduced-motion is reduce', () => {
+		beforeEach( () => {
+			mockMatchMedia( true );
+		} );
+
+		it( 'should close without waiting for an exit transition', () => {
+			const onClose = jest.fn();
+
+			render(
+				<ModalShell onClose={ onClose }>
+					<div>x</div>
+				</ModalShell>
+			);
+
+			fireEvent.click( screen.getByRole( 'button', { name: /close/i } ) );
+
+			act( () => {
+				jest.advanceTimersByTime( 0 );
+			} );
+
+			expect( onClose ).toHaveBeenCalledTimes( 1 );
+		} );
+	} );
+} );

package/src/components/background-lottie.tsx

@@ -0,0 +1,57 @@
+import * as React from 'react';
+import { useEffect } from 'react';
+import Lottie from 'lottie-react';
+
+import { MODAL_Z_INDEX } from './modal-shell';
+
+type BackgroundLottieProps = {
+	animationData: object;
+	loop?: boolean;
+	autoplay?: boolean;
+	zIndex?: number;
+	backgroundColor?: string;
+	onComplete?: () => void;
+};
+
+export function BackgroundLottie( {
+	animationData,
+	loop = false,
+	autoplay = true,
+	zIndex = MODAL_Z_INDEX - 1,
+	backgroundColor = 'transparent',
+	onComplete = () => {},
+}: BackgroundLottieProps ) {
+	const prefersReducedMotion =
+		typeof window !== 'undefined' && window.matchMedia?.( '(prefers-reduced-motion: reduce)' ).matches;
+
+	useEffect( () => {
+		if ( prefersReducedMotion ) {
+			onComplete?.();
+		}
+	}, [ prefersReducedMotion, onComplete ] );
+	if ( prefersReducedMotion ) {
+		return null;
+	}
+
+	return (
+		<Lottie
+			animationData={ animationData }
+			loop={ loop }
+			autoplay={ autoplay }
+			onComplete={ loop ? undefined : onComplete }
+			onDataFailed={ onComplete }
+			rendererSettings={ {
+				preserveAspectRatio: 'xMidYMid slice',
+			} }
+			style={ {
+				position: 'fixed',
+				inset: 0,
+				width: '100vw',
+				height: '100vh',
+				zIndex,
+				backgroundColor,
+				pointerEvents: 'none',
+			} }
+		/>
+	);
+}

package/src/components/modal-footer.tsx

@@ -0,0 +1,32 @@
+import * as React from 'react';
+import { Button, Stack, Typography } from '@elementor/ui';
+
+type FooterLinkData = {
+	text: string;
+	url: string;
+};
+
+type ModalFooterProps = {
+	helpText: string;
+	link: FooterLinkData;
+};
+
+export const ModalFooter = ( { helpText, link }: ModalFooterProps ) => {
+	return (
+		<Stack direction="row" alignItems="center" gap={ 1 }>
+			<Typography variant="caption" color="text.tertiary" sx={ { fontSize: '11px', lineHeight: 'normal' } }>
+				{ helpText }
+			</Typography>
+			<Button
+				href={ link.url }
+				target="_blank"
+				variant="text"
+				size="small"
+				color="info"
+				sx={ { fontSize: '11px' } }
+			>
+				{ link.text }
+			</Button>
+		</Stack>
+	);
+};

package/src/components/modal-header.tsx

@@ -0,0 +1,21 @@
+import * as React from 'react';
+import { type ReactNode } from 'react';
+import { Stack, Typography } from '@elementor/ui';
+
+type ModalHeaderProps = {
+	title: string;
+	content: ReactNode;
+};
+
+export const ModalHeader = ( { title, content }: ModalHeaderProps ) => {
+	return (
+		<Stack gap={ 0.75 }>
+			<Typography variant="h4" color="text.primary">
+				{ title }
+			</Typography>
+			<Typography variant="subtitle2" color="text.primary">
+				{ content }
+			</Typography>
+		</Stack>
+	);
+};

package/src/components/modal-shell.tsx

@@ -0,0 +1,144 @@
+import * as React from 'react';
+import { createContext, type ReactNode, useCallback, useContext, useMemo, useState } from 'react';
+import { Box, CloseButton, Dialog, type SxProps, type Theme } from '@elementor/ui';
+
+export const MODAL_Z_INDEX = 99999;
+
+const DEFAULT_WIDTH = 800;
+const DEFAULT_HEIGHT = 400;
+const DEFAULT_REVEAL_DURATION_MS = 500;
+const DEFAULT_REVEAL_DELAY_MS = 0;
+
+type CloseReason = 'escapeKeyDown' | 'backdropClick';
+
+type ModalShellContextValue = {
+	close: () => void;
+};
+
+const ModalShellContext = createContext< ModalShellContextValue | null >( null );
+
+export const useModalShell = (): ModalShellContextValue => {
+	const ctx = useContext( ModalShellContext );
+
+	if ( ! ctx ) {
+		throw new Error( 'useModalShell must be used inside a <ModalShell />' );
+	}
+
+	return ctx;
+};
+
+const EXIT_TRANSITION_MS = 225;
+
+const prefersReducedMotion = (): boolean =>
+	typeof window !== 'undefined' && Boolean( window.matchMedia?.( '(prefers-reduced-motion: reduce)' ).matches );
+
+export type ModalShellProps = {
+	children: ReactNode;
+	onClose?: () => void;
+	revealDuration?: number;
+	revealDelay?: number;
+	container?: HTMLElement;
+	sx?: SxProps< Theme >;
+	closeOnEsc?: boolean;
+	closeOnOutsideClick?: boolean;
+	backdrop?: boolean;
+	backdropSx?: SxProps< Theme >;
+	hideCloseButton?: boolean;
+};
+
+export const ModalShell = ( {
+	children,
+	onClose,
+	revealDuration = DEFAULT_REVEAL_DURATION_MS,
+	revealDelay = DEFAULT_REVEAL_DELAY_MS,
+	container,
+	sx = {},
+	closeOnEsc = true,
+	closeOnOutsideClick = true,
+	backdrop = true,
+	backdropSx = {},
+	hideCloseButton = false,
+}: ModalShellProps ) => {
+	const portalTarget = container ?? ( typeof document !== 'undefined' ? document.body : undefined );
+	const reducedMotion = prefersReducedMotion();
+	const consumerOwnsEnter = revealDuration === 0 || reducedMotion;
+	const [ open, setOpen ] = useState( true );
+
+	const startClose = useCallback( () => setOpen( false ), [] );
+
+	const contextValue = useMemo< ModalShellContextValue >( () => ( { close: startClose } ), [ startClose ] );
+
+	const handleDialogClose = ( _event: object, reason: CloseReason ) => {
+		if ( reason === 'escapeKeyDown' && ! closeOnEsc ) {
+			return;
+		}
+
+		if ( reason === 'backdropClick' && ! closeOnOutsideClick ) {
+			return;
+		}
+
+		startClose();
+	};
+
+	const transitionTimeouts = useMemo(
+		() => ( { enter: 0, exit: reducedMotion ? 0 : EXIT_TRANSITION_MS } ),
+		[ reducedMotion ]
+	);
+
+	const animationProps = useMemo(
+		() =>
+			consumerOwnsEnter
+				? {}
+				: {
+						animation: `e-modal-shell-reveal ${ revealDuration }ms ease ${ revealDelay }ms backwards`,
+						'@keyframes e-modal-shell-reveal': {
+							from: { opacity: 0, transform: 'scale(0.95)' },
+							to: { opacity: 1, transform: 'scale(1)' },
+						},
+				  },
+		[ consumerOwnsEnter, revealDuration, revealDelay ]
+	);
+
+	return (
+		<Dialog
+			open={ open }
+			maxWidth={ false }
+			onClose={ handleDialogClose }
+			container={ portalTarget }
+			disableEscapeKeyDown={ ! closeOnEsc }
+			hideBackdrop={ ! backdrop }
+			TransitionProps={ { onExited: onClose, timeout: transitionTimeouts } }
+			slotProps={ { backdrop: { transitionDuration: transitionTimeouts, sx: backdropSx } } }
+			PaperProps={ {
+				sx: {
+					width: DEFAULT_WIDTH,
+					height: DEFAULT_HEIGHT,
+					maxWidth: '100%',
+					overflow: 'hidden',
+					...animationProps,
+					...sx,
+				},
+			} }
+			sx={ {
+				zIndex: MODAL_Z_INDEX,
+			} }
+		>
+			<ModalShellContext.Provider value={ contextValue }>
+				<Box sx={ { display: 'contents' } }>
+					{ children }
+					{ ! hideCloseButton && (
+						<CloseButton
+							onClick={ startClose }
+							sx={ {
+								position: 'absolute',
+								right: 16,
+								top: 16,
+								zIndex: 3,
+							} }
+						/>
+					) }
+				</Box>
+			</ModalShellContext.Provider>
+		</Dialog>
+	);
+};

package/src/hooks/__tests__/use-autoplay-carousel.test.ts

@@ -0,0 +1,59 @@
+import { act, renderHook } from '@testing-library/react';
+
+import { useAutoplayCarousel } from '../use-autoplay-carousel';
+
+const ITEMS = [ 'a', 'b', 'c' ];
+const INTERVAL_MS = 4000;
+
+beforeEach( () => {
+	jest.useFakeTimers();
+} );
+
+afterEach( () => {
+	jest.runOnlyPendingTimers();
+	jest.clearAllTimers();
+} );
+
+describe( 'useAutoplayCarousel', () => {
+	it( 'should initialize with the first item selected', () => {
+		const { result } = renderHook( () => useAutoplayCarousel( ITEMS ) );
+
+		expect( result.current.selectedItem ).toBe( 'a' );
+	} );
+
+	it( 'should advance to the next item after the default interval', () => {
+		const { result } = renderHook( () => useAutoplayCarousel( ITEMS ) );
+
+		act( () => {
+			jest.advanceTimersByTime( INTERVAL_MS );
+		} );
+
+		expect( result.current.selectedItem ).toBe( 'b' );
+	} );
+
+	it( 'should cycle back to the first item after reaching the last', () => {
+		const { result } = renderHook( () => useAutoplayCarousel( ITEMS ) );
+
+		act( () => {
+			jest.advanceTimersByTime( INTERVAL_MS * ITEMS.length );
+		} );
+
+		expect( result.current.selectedItem ).toBe( 'a' );
+	} );
+
+	it( 'should stop autoplay when an item is manually selected', () => {
+		const { result } = renderHook( () => useAutoplayCarousel( ITEMS ) );
+
+		act( () => {
+			result.current.selectItem( 'c' );
+		} );
+
+		expect( result.current.selectedItem ).toBe( 'c' );
+
+		act( () => {
+			jest.advanceTimersByTime( 10_000 );
+		} );
+
+		expect( result.current.selectedItem ).toBe( 'c' );
+	} );
+} );

package/src/hooks/use-autoplay-carousel.ts

@@ -0,0 +1,33 @@
+import { useCallback, useEffect, useState } from 'react';
+
+const DEFAULT_INTERVAL_MS = 4000;
+
+export function useAutoplayCarousel< T >( items: T[], intervalMs = DEFAULT_INTERVAL_MS ) {
+	const [ selectedItem, setSelectedItem ] = useState< T >( items[ 0 ] );
+	const [ isAutoPlaying, setIsAutoPlaying ] = useState( true );
+
+	const advanceToNextItem = useCallback( () => {
+		setSelectedItem( ( current ) => {
+			const currentIndex = items.indexOf( current );
+			const nextIndex = ( currentIndex + 1 ) % items.length;
+			return items[ nextIndex ];
+		} );
+	}, [ items ] );
+
+	useEffect( () => {
+		if ( ! isAutoPlaying ) {
+			return;
+		}
+
+		const id = setInterval( advanceToNextItem, intervalMs );
+
+		return () => clearInterval( id );
+	}, [ isAutoPlaying, advanceToNextItem, intervalMs ] );
+
+	const selectItem = useCallback( ( item: T ) => {
+		setSelectedItem( item );
+		setIsAutoPlaying( false );
+	}, [] );
+
+	return { selectedItem, selectItem };
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export { ModalShell, MODAL_Z_INDEX, type ModalShellProps, useModalShell } from './components/modal-shell';
+export { ModalHeader } from './components/modal-header';
+export { ModalFooter } from './components/modal-footer';
+export { BackgroundLottie } from './components/background-lottie';
+export { useAutoplayCarousel } from './hooks/use-autoplay-carousel';