Pull in OpenNet changes

.swiftpm/xcode/xcshareddata/xcschemes/ComposedUI.xcscheme

@@ -26,8 +26,19 @@
       buildConfiguration = "Debug"
       selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
       selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
-      shouldUseLaunchSchemeArgsEnv = "YES">
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      codeCoverageEnabled = "YES">
       <Testables>
+         <TestableReference
+            skipped = "NO">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "ComposedUITests"
+               BuildableName = "ComposedUITests"
+               BlueprintName = "ComposedUITests"
+               ReferencedContainer = "container:">
+            </BuildableReference>
+         </TestableReference>
       </Testables>
    </TestAction>
    <LaunchAction

Package.swift

@@ -18,24 +18,24 @@ let package = Package(
             targets: ["ComposedUI"]),
     ],
     dependencies: [
-        .package(name: "Quick", url: "https://github.com/Quick/Quick.git", from: "3.0.0"),
-        .package(name: "Nimble", url: "https://github.com/Quick/Nimble.git", from: "9.0.0"),
+        .package(name: "Quick", url: "https://github.com/Quick/Quick.git", from: "4.0.0"),
+        .package(name: "Nimble", url: "https://github.com/Quick/Nimble.git", from: "9.2.1"),
     ],
     targets: [
         .target(name: "Composed"),
         .testTarget(
             name: "ComposedTests",
             dependencies: ["Quick", "Nimble", "Composed"]),
 
-        .target(
-            name: "ComposedLayouts",
-            dependencies: ["Composed", "ComposedUI"]),
-
         .target(
             name: "ComposedUI",
             dependencies: ["Composed"]),
         .testTarget(
             name: "ComposedUITests",
-            dependencies: ["Quick", "Nimble", "ComposedUI"]),
+            dependencies: ["Quick", "Nimble", "ComposedLayouts", "ComposedUI"]),
+
+        .target(
+            name: "ComposedLayouts",
+            dependencies: ["Composed", "ComposedUI"]),
     ]
 )

README.md

@@ -1,62 +1,105 @@
 <img src="composed.png" width=20%/>
 
-**Composed** is a protocol oriented framework for composing data from various sources in our app. It provides various concrete implementations for common use cases.
+`Composed` is a protocol oriented framework for composing data from multiple sources and building flexible UIs that display the data.
+
+The primary benefits of using Composed include:
+
+- The library makes heavy use of protocol-oriented design allowing your types to opt-in to behaviour rather than inherit it by default.
+- Each section is isolated from the others, removing the need to think about how the data is composed.
 
 > If you prefer to look at code, there's a demo project here: [ComposedDemo](http://github.com/composed-swift/composed-demo)
 
-The library bases everything on just 2 primitives, `Section` and `SectionProvider`.
+The package contains 3 libraries, each built on top of each other:
 
-The primary benefits of using Composed include:
+- Composed
+- ComposedUI
+- ComposedLayouts
 
-- The library makes heavy use of protocol-oriented design allowing your types to opt-in to behaviour rather than inherit it by default.
-- From an API perspective you generally only care about a single section at a time, and so it's irrelevant to you how it's being composed.
+## Composed
 
-1. [Getting Started](#Getting-Started)
-2. [Behind the Scenes](#Behind-the-Scenes)
-3. [User Interfaces](http://github.com/composed-swift/composedui)
+The `Composed` library provides the data layer. `Composed` is centered around primitives, `Section` and `SectionProvider`.
 
 ## Getting Started
 
 Composed includes 3 pre-defined sections as well as 2 providers that should satisfy a large majority of applications.
 
 ### Sections
 
-**ArraySection**
-Represents a section that manages its elements via an `Array`. This type of section is useful for representing in-memory data.
+A `Section` is a collection of data with a simple set of requirements:
+
+```swift
+/// Represents a single section of data.
+public protocol Section: AnyObject {
+    /// The number of elements in this section
+    var numberOfElements: Int { get }
+
+    /// The delegate that will respond to updates
+    var updateDelegate: SectionUpdateDelegate? { get set }
+}
+```
+
+`Composed` provides some sections that should cover a majority of use cases.
+
+#### `ArraySection`
+
+Represents a section that manages a collection of same-type elements by using an `Array` backing store. This type of section is useful for representing in-memory data, e.g. data loaded from a network or read from the file system.
+
+#### `SingleElementSection`
+
+Represents a section that manages a single element. This section is useful when only have a single element to manage.
+
+If the stored value is `nil` it will return `0` for `numberOfElements`, allowing for any UI elements the section provides to be hidden (more on this later).
+
+#### `FlatSection`
+
+A `FlatSection` behaved similarly to a `ComposedSectionProvider` but rather than providing a collections of sections it returns a single section that contains every element in the flattened collection of `Section`s and `SectionProvider`s. This has limited use for data alone but proves useful when representing the data in the UI; `FlatSection` allows for multiple sections to be displayed in a single UI section, enabling features such as headers that pin to visible bounds ("sticky headers").
+
+#### `ManagedSection`
+
+`ManagedSection` wraps an `NSManagedObjectContext` and responds to the `NSFetchedResultsControllerDelegate` functions by forwarding them to the `SectionUpdateDelegate`. This enables a single data hierarchy to include a mixture of sections that are backed by core data and other storage mechanisms.
+
+### `SectionProvider`s
+
+`SectionProvider`s are the next layer up, dealing with `Section`s directly by providing an ordered collection of sections:
+
+```swift
+/// Represents a collection of `Section`'s.
+public protocol SectionProvider: AnyObject {
+    /// The child sections contained in this provider
+    var sections: [Section] { get }
 
-**ManagedSection**
-Represents a section that provides its elements via an `NSFetchedResultsController`. This section is useful for representing data managed by CoreData.
+    /// The delegate that will respond to updates
+    var updateDelegate: SectionProviderUpdateDelegate? { get set }
+}
+```
 
-**SingleElementSection**
-Represents a section that manages a single element. This section is useful when only have a single element to manage. Hint: Use `Optional<T>` to represent an element that may or may not exist.
+#### `ComposedSectionProvider`
 
-### Providers
+Represents an collection of `Section`'s and `SectionProvider`'s. The provider supports infinite nesting, including other `ComposedSectionProvider`'s, by providing a flattened hierarchy.
 
-**ComposedSectionProvider**
-Represents an collection of `Section`'s and `SectionProvider`'s. The provider supports infinite nesting, including other `ComposedSectionProvider`'s. All children will be active at all times, so `numberOfSections` and `numberOfElements(in:)` will return values representative of all children.
+#### `SegmentedSectionProvider`
 
-**SegmentedSectionProvider**
-Represents an collection of `Section`'s and `SectionProvider`'s. The provider supports infinite nesting, including other `SegmentedSectionProvider`'s. One or zero children may be active at any time, so `numberOfSections` and `numberOfElements(in:)` will return values representative of the currenly active child only.
+Provides the same nesting support as `ComposedSectionProvider` but allows for different segments of children to be active. This could be used to represent a series of tabs with different section providers in each tab.
 
 ### Example
 
 Lets say we wanted to represent a users contacts library. Our contacts will have 2 groups, family and friends. Using Composed, we can easily model that as such:
- 
+
 ```swift
 let family = ArraySection<Person>()
 family.append(Person(name: "Dad"))
 family.append(Person(name: "Mum"))
 
-let friends = ArraySection<Person>()
-friends.append(Person(name: "Best mate"))
+let businesses = ArraySection<Business>()
+businesses.append(Person(name: "ACME Inc."))
 ```
 
 At this point we have 2 separate sections for representing our 2 groups of contacts. Now we can use a provider to compose these 2 together:
 
 ```swift
 let contacts = ComposedSectionProvider()
 contacts.append(family)
-contacts.append(friends)
+contacts.append(businesses)
 ```
 
 That's it! Now we can query our data using the provider without either of the individual sections even being aware that they're now contained in a larger structure:
@@ -66,75 +109,25 @@ contacts.numberOfSections        // 2
 contacts.numberOfElements(in: 1) // 1
 ```
 
-If we want to query individual data in a section (assuming we don't already have a reference to it):
+Swapping to a `FlatSection` would flatten these sections while maintaining all the data:
 
 ```swift
-let people = contacts.sections[0] as? ArraySection<Person>
-people.element(at: 1)            // Mum
-```
-
-> Note: we have to cast the section to a known type because SectionProvider's can contain _any_ type of section as well as other nested providers.
-
-### Opt-In Behaviours
-
-If we now subclass ArraySection, we can extend our section through protocol conformance to do something more interesting:
-
-```swift
-final class People: ArraySection<Person> { ... }
-
-protocol SelectionHandling: Section { 
-    func didSelect(at index: Int)
-}
-
-extension People: SelectionHandling {
-	func didSelect(at index: Int) {
-		let person = element(at: index)
-		print(person.name)
-	}
-}
-```
-
-In order to make this work, _something_ needs to call `didSelect`, so for the purposes of this example we'll leave out some details but to give you a preview for how you can build something like this yourself:
-
-```swift
-// Assume we want to select the 2nd element in the 1st section
-let section = provider.sections[0] as? SelectionHandling
-section?.didSelect(at: 1)        // Mum
+let contacts = FlatSection()
+contacts.append(family)
+contacts.append(businesses)
+contacts.numberOfElements // 3
 ```
 
-Composed is handling all of the mapping and structure, allowing us to focus entirely on behavious and extension.
-
-## Behind the Scenes
+## ComposedUI
 
-### Section
+The `ComposedUI` library builds on top of `Composed` by providing protocols that enable `Section`s to provide UI elements that can then be displayed by a view coordinator.
 
-A section represents exactly what it says, a single section. The best thing about that is that we have no need for `IndexPath`'s within a section. Just indexes!
+### UI Coordinators
 
-### SectionProvider
+Various coordinators are provided that enable interfacing with `UIKit` by adding extra protocol conformances to your `Section`s.
 
-A section provider is a container type that contains either sections or other providers. Allowing infinite nesting and therefore infinite possibilities.
-
-### Mappings
-
-Mappings provide the glue between your 'tree' structure and the resulting `flattened` structure. Lets take a look at an example.
-
-```swift
-
-// we can define our structure as such:
-- Provider
-    - Section 1
-    - Provider
-        - Section 2
-        - Section 3
-    - Section 4
-
-// mappings will then convert this to:
-- Section 1
-- Section 2
-- Section 3
-- Section 4
-```
+#### `CollectionCoordinator`
 
-Furthermore, mappings take care of the conversion from local to global indexes and more importantly `IndexPath`'s which allows for even more interesting use cases.
+`CollectionCoordinator` allows for the most flexible UIs by coordinating with a `UICollectionView`.
 
-> To find out more, checkout [ComposedUI](http://github.com/composed-swift/ComposedUI) which provides user interface implementations that work with `UICollectionView` and `UITableView`, allowing you to power an entire screen from simple reusable `Section`s.
+View the [`CollectionCoordinator` README.md](./Sources/ComposedUI/CollectionView/README.md) to learn more.

Sources/Composed/Core/Section.swift

@@ -2,33 +2,49 @@ import Foundation
 import CoreGraphics
 
 /// Represents a single section of data.
-public protocol Section: class {
-
+public protocol Section: AnyObject {
     /// The number of elements in this section
     var numberOfElements: Int { get }
 
     /// The delegate that will respond to updates
     var updateDelegate: SectionUpdateDelegate? { get set }
-
 }
 
 public extension Section {
-
     /// Returns true if the section contains no elements, false otherwise
     var isEmpty: Bool { return numberOfElements == 0 }
 
+    /// Perform multiple updates in a single batch, ensuring a single layout pass and animation is used for all updates.
+    ///
+    /// Changes will be reduced in to the minimal total changes required, based on the calls made to the `updateDelegate`. If
+    /// no `updateDelegate` has been set the `updates` closure is called with `nil`, allowing changes to still be made.
+    ///
+    /// Some updates are not correct reduced, or you may wish to avoid this batching behaviour. To enable this the `forceReloadData`
+    /// parameter can be set to `true`. Note that passing `true` is not supported if another batch updates that does not force reload
+    /// data is currently being performed.
+    ///
+    /// - Parameter forceReloadData: If `true` all updates will be ignored and `reloadData` will be called after all updates are applied.
+    /// - Parameter updates: A closure that applies the updates.
+    func performBatchUpdates(forceReloadData: Bool = false, _ updates: (_ updateDelegate: SectionUpdateDelegate?) -> Void) {
+        if let updateDelegate = updateDelegate {
+            updateDelegate.section(self, willPerformBatchUpdates: {
+                updates(updateDelegate)
+            }, forceReloadData: forceReloadData)
+        } else {
+            updates(nil)
+        }
+    }
 }
 
 /// A delegate that will respond to update events from a `Section`
-public protocol SectionUpdateDelegate: class {
-
-    /// Notifies the delegate before a section will process updates
-    /// - Parameter section: The section that will be updated
-    func willBeginUpdating(_ section: Section)
-
-    /// Notifies the delegate after a section has processed updates
-    /// - Parameter section: The section that was updated
-    func didEndUpdating(_ section: Section)
+public protocol SectionUpdateDelegate: AnyObject {
+    /// Notifies the delegate that the section will perform a series of updates.
+    ///
+    /// The delegate must call the `updates` closure synchronously.
+    ///
+    /// - Parameter section: The section that will be updated.
+    /// - Parameter updates: A closure that will perform the updates.
+    func section(_ section: Section, willPerformBatchUpdates updates: () -> Void, forceReloadData: Bool)
 
     /// Notifies the delegate that all sections should be invalidated, ignoring individual updates
     /// - Parameter section: The section that requested the invalidation
@@ -82,4 +98,13 @@ public protocol SectionUpdateDelegate: class {
     ///   - destinationIndex: The final index where the element will be moved to
     func section(_ section: Section, move sourceIndex: Int, to destinationIndex: Int)
 
+    /// Notifies the delegate that the section invalidated its header.
+    /// - Parameters:
+    ///   - section: The section that invalidated its header.
+    func sectionDidInvalidateHeader(_ section: Section)
+
+    /// Notifies the delegate that the section invalidated its footer.
+    /// - Parameters:
+    ///   - section: The section that invalidated its footer.
+    func sectionDidInvalidateFooter(_ section: Section)
 }