refactor: deprecate onFailureImage in favor of onFailureView

Remove usage of `onFailureImage` in LoadingFailureDemo.swift and
promote `onFailureView` for better flexibility. This change aligns
with updated API guidelines to favor SwiftUI views over static images
for failure handling. The `onFailureImage` API is now marked as deprecated
and will be removed in a future release.

Demo/Demo/Kingfisher-Demo/SwiftUIViews/LoadingFailureDemo.swift

@@ -45,7 +45,6 @@ struct LoadingFailureDemo: View {
     var body: some View {
         VStack {
             KFImage(url)
-                .onFailureImage(warningImage) // onFailureImage should not work
                 .onFailureView {
                     ZStack {
                         RoundedRectangle(cornerRadius: 20)
@@ -59,15 +58,6 @@ struct LoadingFailureDemo: View {
                 .frame(width: 200, height: 200)
             Text("onFailureView")
             Spacer().frame(height: 20)
-            
-            KFImage(url)
-                .onFailureImage(warningImage)
-                .frame(width: 200, height: 200)
-                .background(
-                    RoundedRectangle(cornerRadius: 20)
-                        .fill(Color.red.opacity(0.5))
-                )
-            Text("onFailureImage")
         }
     }
 }

Sources/SwiftUI/KFImageOptions.swift

@@ -125,8 +125,8 @@ extension KFImageProtocol {
 
     /// Sets a failure `View` that is displayed when the image fails to load.
     ///
-    /// Use this modifier to provide a custom view when image loading fails. This offers more flexibility than
-    /// `onFailureImage` by allowing any SwiftUI view as the failure placeholder.
+    /// Use this modifier to provide a custom view when image loading fails. This offers more flexibility than the
+    /// deprecated `onFailureImage` API by allowing any SwiftUI view as the failure placeholder.
     ///
     /// Example:
     /// ```swift
@@ -144,7 +144,7 @@ extension KFImageProtocol {
     ///     }
     /// ```
     ///
-    /// - Note: If both `onFailureImage` and `onFailureView` are set, `onFailureView` takes precedence.
+    /// - Note: If both deprecated `onFailureImage` and `onFailureView` are set, `onFailureView` takes precedence.
     /// 
     /// - Parameter content: A view builder that creates the failure view.
     /// - Returns: A Kingfisher-compatible image view that displays the provided `content` when image loading fails.
@@ -153,6 +153,17 @@ extension KFImageProtocol {
         return self
     }
 
+    /// Sets an image to display when the loading fails.
+    ///
+    /// - Deprecated: Use ``onFailureView(_:)`` instead, which lets you return any SwiftUI `View` and guarantees
+    ///   consistent behavior across SwiftUI platforms. The image-based fallback modifier is maintained purely for
+    ///   backward compatibility and will be removed in a future major release.
+    @available(*, deprecated, message: "Use `onFailureView(_:)` to customize SwiftUI failure placeholders instead.")
+    public func onFailureImage(_ image: KFCrossPlatformImage?) -> Self {
+        options.onFailureImage = .some(image)
+        return self
+    }
+
     /// Enables canceling the download task associated with `self` when the view disappears.
     ///
     /// - Parameter flag: A boolean value indicating whether to cancel the task.