Add param keepViewControllersStackedAbove to fluidPop/removeSelf/removeViewController (#170)

keepViewControllersStackedAbove: if true and if there are view
controllers stacked above this view controller, they will be kept

---------

Co-authored-by: Muukii <[email protected]>

Author: kenjitayama

Sources/FluidStack/Helper/FluidExtentionViewController.swift

@@ -209,7 +209,8 @@ extension FluidExtentionViewController {
    - Parameters:
    - transition: You may set ``AnyRemovingTransition/noAnimation`` to disable animation, nil runs transition given view controller provides (if it's ``FluidTransitionViewController``).
    - fowardingToParent: Forwards to parent to pop if current stack do not have view controller to pop. No effects if the current stack prevents it by ``FluidStackController/Configuration-swift.struct/preventsFowardingPop``
-   
+   - cascadesToChildren: if true and if there are view controllers stacked above this view controller, they will be removed as well
+
    - Warning: To run this method to ``FluidStackController`` does not mean to pop the current top view controller.
    A way to pop the top view controller:
    ```
@@ -220,6 +221,7 @@ extension FluidExtentionViewController {
     transition: AnyRemovingTransition? = nil,
     transitionForBatch: AnyBatchRemovingTransition? = .crossDissolve,
     forwardingToParent: Bool = true,
+    removingRule: RemovingRule = .cascade,
     completion: ((RemovingTransitionContext.CompletionEvent) -> Void)? = nil
   ) {
 
@@ -235,7 +237,8 @@ extension FluidExtentionViewController {
     _fluidPop(
       transition: transition,
       transitionForBatch: transitionForBatch,
-      forwardingToParent: forwardingToParent,
+      forwardingToParent: forwardingToParent, 
+      removingRule: removingRule,
       completion: completion
     )
 
@@ -247,7 +250,8 @@ extension FluidExtentionViewController {
    - Parameters:
    - transition: You may set ``AnyRemovingTransition/noAnimation`` to disable animation, nil runs transition given view controller provides (if it's ``FluidTransitionViewController``).
    - fowardingToParent: Forwards to parent to pop if current stack do not have view controller to pop. No effects if the current stack prevents it by ``FluidStackController/Configuration-swift.struct/preventsFowardingPop``
-   
+   - cascadesToChildren: if true and if there are view controllers stacked above this view controller, they will be removed as well
+
    - Warning: To run this method to ``FluidStackController`` does not mean to pop the current top view controller.
    A way to pop the top view controller:
    ```
@@ -258,7 +262,8 @@ extension FluidExtentionViewController {
   public func fluidPop(
     transition: AnyRemovingTransition? = nil,
     transitionForBatch: AnyBatchRemovingTransition? = .crossDissolve,
-    forwardingToParent: Bool = true
+    forwardingToParent: Bool = true,
+    removingRule: RemovingRule = .cascade
   ) async -> RemovingTransitionContext.CompletionEvent {
 
     await withCheckedContinuation { continuation in
@@ -267,6 +272,7 @@ extension FluidExtentionViewController {
         transition: transition,
         transitionForBatch: transitionForBatch,
         forwardingToParent: forwardingToParent,
+        removingRule: removingRule,
         completion: { event in
           continuation.resume(returning: event)
       })
@@ -278,6 +284,7 @@ extension FluidExtentionViewController {
     transition: AnyRemovingTransition?,
     transitionForBatch: AnyBatchRemovingTransition?,
     forwardingToParent: Bool,
+    removingRule: RemovingRule,
     completion: ((RemovingTransitionContext.CompletionEvent) -> Void)?
   ) {
 
@@ -302,13 +309,15 @@ extension FluidExtentionViewController {
         transition: transition,
         transitionForBatch: transitionForBatch,
         forwardingToParent: forwardingToParent,
+        removingRule: removingRule,
         completion: completion
       )
 
     } else {
 
       fluidStackContext
         .removeSelf(
+          removingRule: removingRule,
           transition: transition,
           transitionForBatch: transitionForBatch,
           completion: completion

Sources/FluidStack/ViewController/FluidStackContext.swift

@@ -49,8 +49,9 @@ public final class FluidStackContext: Equatable {
   /// Removes the target view controller in ``FluidStackController``.
   /// - Parameter transition: if not nil, it would be used override parameter.
   ///
-  /// See detail in ``FluidStackController/removeViewController(_:transition:)``
+  /// See detail in ``FluidStackController/removeViewController(_:transition:transitionForBatch:cascadesToChildren:completion:)``
   public func removeSelf(
+    removingRule: RemovingRule = .cascade,
     transition: AnyRemovingTransition?,
     transitionForBatch: AnyBatchRemovingTransition? = .crossDissolve,
     completion: ((RemovingTransitionContext.CompletionEvent) -> Void)? = nil
@@ -60,6 +61,7 @@ public final class FluidStackContext: Equatable {
     }
     fluidStackController?.removeViewController(
       targetViewController,
+      removingRule: removingRule,
       transition: transition,
       transitionForBatch: transitionForBatch,
       completion: completion

Sources/FluidStack/ViewController/FluidStackController.swift

@@ -24,6 +24,13 @@ public enum FluidStackAction {
   case willBecomeTop
 }
 
+public enum RemovingRule {
+  /// Removes all of view controllers above itself.
+  case cascade
+  /// Removes only itself, leaving view controllers above itself.
+  case single
+}
+
 /// A struct that configures how to display in ``FluidStackController``
 public struct FluidStackContentConfiguration {
 
@@ -223,6 +230,7 @@ open class FluidStackController: UIViewController {
 
     removeViewController(
       wrapperView.viewController,
+      removingRule: .cascade,
       transition: transition,
       completion: completion
     )
@@ -556,9 +564,11 @@ open class FluidStackController: UIViewController {
    Removes given view controller with transition.
 
    Switches to batch removing if there are multiple view controllers on top of the given view controller.
+   - Parameters:
    */
   public func removeViewController(
     _ viewControllerToRemove: UIViewController,
+    removingRule: RemovingRule = .cascade,
     transition: AnyRemovingTransition?,
     transitionForBatch: @autoclosure @escaping () -> AnyBatchRemovingTransition? = .crossDissolve,
     completion: (@MainActor (RemovingTransitionContext.CompletionEvent) -> Void)? = nil
@@ -578,35 +588,42 @@ open class FluidStackController: UIViewController {
       assertionFailure("Not found wrapper view to manage \(viewControllerToRemove)")
       return
     }
-    
-    if stackingItems.last?.viewController != viewControllerToRemove {
-      
-      // Removes view controllers with batch
-      
-      let transition = transitionForBatch()
-      
-      Log.debug(
-        .stack,
-        "The removing view controller is not displaying on top. it's behind of the other view controllers. Switches to batch-removing using transition: \(transition as Any)"
-      )
-      
-      removeAllViewController(
-        from: viewToRemove.viewController,
-        transition: transition,
-        completion: { event in
-          
-          switch event {
-          case .succeeded:
-            completion?(.succeeded)
-          case .interrupted:
-            completion?(.interrupted)
+
+    switch removingRule {
+    case .cascade:
+
+      if stackingItems.last?.viewController != viewControllerToRemove {
+
+        // Removes view controllers with batch
+
+        let transition = transitionForBatch()
+
+        Log.debug(
+          .stack,
+          "The removing view controller is not displaying on top. it's behind of the other view controllers. Switches to batch-removing using transition: \(transition as Any)"
+        )
+
+        removeAllViewController(
+          from: viewToRemove.viewController,
+          transition: transition,
+          completion: { event in
+
+            switch event {
+            case .succeeded:
+              completion?(.succeeded)
+            case .interrupted:
+              completion?(.interrupted)
+            }
+
           }
-          
-        }
-      )
-      return
+        )
+        return
+      }
+
+    case .single:
+      break
     }
-    
+
     // Removes view controller
 
     let transitionContext = _startRemoving(viewToRemove, completion: completion)