refactor(advanced list): pagination is now available as a modifier, make use of view builder, removed unnecessary self; docs(): added code documentation to public API

Author: Christian Elies

README.md

@@ -297,3 +297,108 @@ AdvancedList(yourData, content: { item in
 }
 ```
 </details>
+
+<details>
+<summary>Migration 4.0 -> 5.0</summary>
+
+`Pagination` is now implemented as a `modifier` 💪 And last but not least the code documentation arrived 😀
+
+**Before:**
+
+```swift
+private lazy var pagination: AdvancedListPagination<AnyView, AnyView> = {
+    .thresholdItemPagination(errorView: { error in
+        AnyView(
+            VStack {
+                Text(error.localizedDescription)
+                    .lineLimit(nil)
+                    .multilineTextAlignment(.center)
+
+                Button(action: {
+                    // load current page again
+                }) {
+                    Text("Retry")
+                }.padding()
+            }
+        )
+    }, loadingView: {
+        AnyView(
+            VStack {
+                Divider()
+                Text("Loading...")
+            }
+        )
+    }, offset: 25, shouldLoadNextPage: {
+        // load next page
+    }, state: .idle)
+}()
+
+@State private var listState: ListState = .items
+
+AdvancedList(yourData, content: { item in
+    Text("Item")
+}, listState: $listState, emptyStateView: {
+    Text("No data")
+}, errorStateView: { error in
+    VStack {
+        Text(error.localizedDescription)
+            .lineLimit(nil)
+        
+        Button(action: {
+            // do something
+        }) {
+            Text("Retry")
+        }
+    }
+}, loadingStateView: {
+    Text("Loading ...")
+}, pagination: pagination)
+
+```
+
+**After:**
+
+```swift
+@State private var listState: ListState = .items
+@State private var paginationState: AdvancedListPaginationState = .idle
+
+AdvancedList(yourData, content: { item in
+    Text("Item")
+}, listState: $listState, emptyStateView: {
+    Text("No data")
+}, errorStateView: { error in
+    VStack {
+        Text(error.localizedDescription)
+            .lineLimit(nil)
+        
+        Button(action: {
+            // do something
+        }) {
+            Text("Retry")
+        }
+    }
+}, loadingStateView: {
+    Text("Loading ...")
+})
+.pagination(.init(type: .lastItem, shouldLoadNextPage: {
+    paginationState = .loading
+    DispatchQueue.main.asyncAfter(deadline: .now() + 2) {
+        items.append(contentsOf: moreItems)
+        paginationState = .idle
+    }
+}) {
+    switch paginationState {
+    case .idle:
+        EmptyView()
+    case .loading:
+        if #available(iOS 14.0, *) {
+            ProgressView()
+        } else {
+            Text("Loading ...")
+        }
+    case let .error(error):
+        Text(error.localizedDescription)
+    }
+})
+```
+</details>

Sources/AdvancedList/private/Models/AdvancedListPaginationType.swift

@@ -0,0 +1,20 @@
+//
+//  AnyAdvancedListPagination.swift
+//  
+//
+//  Created by Christian Elies on 31.07.20.
+//
+
+import SwiftUI
+
+struct AnyAdvancedListPagination {
+    let type: AdvancedListPaginationType
+    let shouldLoadNextPage: () -> Void
+    let content: () -> AnyView
+
+    init<Content: View>(_ pagination: AdvancedListPagination<Content>) {
+        type = pagination.type
+        shouldLoadNextPage = pagination.shouldLoadNextPage
+        content = { AnyView(pagination.content()) }
+    }
+}

Sources/AdvancedList/private/Models/AnyAdvancedListPagination.swift

@@ -0,0 +1,15 @@
+//
+//  ListState+error.swift
+//  
+//
+//  Created by Christian Elies on 02.08.20.
+//
+
+extension ListState {
+    var error: Swift.Error? {
+        guard case let ListState.error(error) = self else {
+            return nil
+        }
+        return error
+    }
+}

Sources/AdvancedList/private/Models/ListState+error.swift

@@ -5,56 +5,27 @@
 //  Created by Christian Elies on 15.08.19.
 //
 
-import Combine
 import SwiftUI
 
-public final class AdvancedListPagination<ErrorView: View, LoadingView: View>: NSObject, ObservableObject {
-    let errorView: (Error) -> ErrorView
-    let loadingView: () -> LoadingView
+/// Represents the pagination configuration.
+public struct AdvancedListPagination<Content: View> {
     let type: AdvancedListPaginationType
     let shouldLoadNextPage: () -> Void
-    
-    public let objectWillChange = PassthroughSubject<Void, Never>()
-    
-    public var state: AdvancedListPaginationState {
-        didSet {
-            objectWillChange.send()
-        }
-    }
-    
-    init(@ViewBuilder errorView: @escaping (Error) -> ErrorView, @ViewBuilder loadingView: @escaping () -> LoadingView, type: AdvancedListPaginationType, shouldLoadNextPage: @escaping () -> Void, state: AdvancedListPaginationState) {
-        self.errorView = errorView
-        self.loadingView = loadingView
+    let content: () -> Content
+
+    /// Initializes the pagination configuration with the given values.
+    ///
+    /// - Parameters:
+    ///   - type: The type of the pagination, choose between `lastItem` or `thresholdItem`.
+    ///   - shouldLoadNextPage: A closure that is called everytime the end of a page is reached.
+    ///   - content: A closure providing a `View` which should be displayed at the end of a page.
+    public init(
+        type: AdvancedListPaginationType,
+        shouldLoadNextPage: @escaping () -> Void,
+        @ViewBuilder content: @escaping () -> Content
+    ) {
         self.type = type
         self.shouldLoadNextPage = shouldLoadNextPage
-        self.state = state
-    }
-}
-
-extension AdvancedListPagination {
-    public static func lastItemPagination(@ViewBuilder errorView: @escaping (Error) -> ErrorView, @ViewBuilder loadingView: @escaping () -> LoadingView, shouldLoadNextPage: @escaping () -> Void, state: AdvancedListPaginationState) -> AdvancedListPagination {
-        AdvancedListPagination(errorView: errorView,
-                               loadingView: loadingView,
-                               type: .lastItem,
-                               shouldLoadNextPage: shouldLoadNextPage,
-                               state: state)
-    }
-    
-    public static func thresholdItemPagination(@ViewBuilder errorView: @escaping (Error) -> ErrorView, @ViewBuilder loadingView: @escaping () -> LoadingView, offset: Int, shouldLoadNextPage: @escaping () -> Void, state: AdvancedListPaginationState) -> AdvancedListPagination {
-        AdvancedListPagination(errorView: errorView,
-                               loadingView: loadingView,
-                               type: .thresholdItem(offset: offset),
-                               shouldLoadNextPage: shouldLoadNextPage,
-                               state: state)
-    }
-}
-
-extension AdvancedListPagination where ErrorView == EmptyView, ErrorView == LoadingView {
-    public static var noPagination: AdvancedListPagination {
-        AdvancedListPagination(errorView: { _ in ErrorView() },
-                               loadingView: { LoadingView() },
-                               type: .noPagination,
-                               shouldLoadNextPage: {},
-                               state: .idle)
+        self.content = content
     }
 }

Sources/AdvancedList/public/Models/AdvancedListPagination.swift

@@ -7,24 +7,12 @@
 
 import Foundation
 
-public enum AdvancedListPaginationState {
-    case error(_ error: Error)
+/// Represents the different states of a pagination.
+public enum AdvancedListPaginationState: Equatable {
+    /// The error state; use this state if an error occurs while loading a page.
+    case error(_ error: NSError)
+    /// The idle state; use this state if no page loading is in progress.
     case idle
+    /// The loading state; use this state if a page is loaded.
     case loading
 }
-
-extension AdvancedListPaginationState: Equatable {
-    public static func ==(lhs: AdvancedListPaginationState,
-                          rhs: AdvancedListPaginationState) -> Bool {
-        switch (lhs, rhs) {
-            case (.error(let lhsError), .error(let rhsError)):
-                return (lhsError as NSError) == (rhsError as NSError)
-            case (.idle, .idle):
-                return true
-            case (.loading, .loading):
-                return true
-            default:
-                return false
-        }
-    }
-}

Sources/AdvancedList/public/Models/AdvancedListPaginationState.swift

@@ -0,0 +1,14 @@
+//
+//  AdvancedListPaginationType.swift
+//  
+//
+//  Created by Christian Elies on 16.08.19.
+//
+
+/// Specifies the different pagination types.
+public enum AdvancedListPaginationType {
+    /// Notifies the pagination configuration object when the last item in the list was reached.
+    case lastItem
+    /// Notifies the pagination configuration object when the given offset was passed.
+    case thresholdItem(offset: Int)
+}

Sources/AdvancedList/public/Models/AdvancedListPaginationType.swift

@@ -8,32 +8,12 @@
 
 import Foundation
 
-public enum ListState {
-    case error(_ error: Error)
+/// Specifies the different states of an `AdvancedList`.
+public enum ListState: Equatable {
+    /// The `error` state; displays the error view instead of the list to the user.
+    case error(_ error: NSError)
+    /// The `items` state (`default`); displays the items or the empty state view (if there are no items) to the user.
     case items
+    /// The `loading` state; displays the loading state view instead of the list to the user.
     case loading
 }
-
-extension ListState {
-    var error: Error? {
-        guard case let ListState.error(error) = self else {
-            return nil
-        }
-        return error
-    }
-}
-
-extension ListState: Equatable {
-    public static func ==(lhs: ListState, rhs: ListState) -> Bool {
-        switch (lhs, rhs) {
-            case (.error(let lhsError), .error(let rhsError)):
-                return (lhsError as NSError) == (rhsError as NSError)
-            case (.items, .items):
-                return true
-            case (.loading, .loading):
-                return true
-            default:
-                return false
-        }
-    }
-}