Improve using elements in lists

BlueprintUILists/Sources/Element+HeaderFooter.swift

@@ -0,0 +1,108 @@
+//
+//  Element+HeaderFooter.swift
+//  BlueprintUILists
+//
+//  Created by Kyle Van Essen on 7/24/22.
+//
+
+import BlueprintUI
+import ListableUI
+
+
+// MARK: HeaderFooter / HeaderFooterContent Extensions
+
+
+extension Element {
+
+    /// Converts the given `Element` into a Listable `HeaderFooter`. You many also optionally
+    /// configure the header / footer, setting its values such as the `onTap` callbacks, etc.
+    ///
+    /// ```swift
+    /// MyElement(...)
+    ///     .headerFooter { header in
+    ///         header.onTap = { ... }
+    ///     }
+    /// ```
+    ///
+    /// ## ⚠️ Performance Considerations
+    /// Unless your `Element` conforms to `Equatable` or `IsEquivalentContent`,
+    /// it will return `false` for `isEquivalent` for each content update, which can dramatically
+    /// hurt performance for longer lists (eg, more than 20 items): it will be re-measured for each content update.
+    ///
+    /// It is encouraged for these longer lists, you ensure your `Element` conforms to one of these protocols.
+    public func headerFooter(
+        configure : (inout HeaderFooter<WrappedHeaderFooterContent<Self>>) -> () = { _ in }
+    ) -> HeaderFooter<WrappedHeaderFooterContent<Self>> {
+        HeaderFooter(
+            WrappedHeaderFooterContent(represented: self),
+            configure: configure
+        )
+    }
+}
+
+
+/// Ensures that the `Equatable` initializer for `WrappedHeaderFooterContent` is called.
+extension Element where Self:Equatable {
+
+    public func headerFooter(
+        configure : (inout HeaderFooter<WrappedHeaderFooterContent<Self>>) -> () = { _ in }
+    ) -> HeaderFooter<WrappedHeaderFooterContent<Self>> {
+        HeaderFooter(
+            WrappedHeaderFooterContent(represented: self),
+            configure: configure
+        )
+    }
+}
+
+
+/// Ensures that the `IsEquivalentContent` initializer for `WrappedHeaderFooterContent` is called.
+extension Element where Self:IsEquivalentContent {
+
+    public func headerFooter(
+        configure : (inout HeaderFooter<WrappedHeaderFooterContent<Self>>) -> () = { _ in }
+    ) -> HeaderFooter<WrappedHeaderFooterContent<Self>> {
+        HeaderFooter(
+            WrappedHeaderFooterContent(represented: self),
+            configure: configure
+        )
+    }
+}
+
+
+public struct WrappedHeaderFooterContent<ElementType:Element> : BlueprintHeaderFooterContent
+{
+    public let represented : ElementType
+
+    private let isEquivalent : (Self, Self) -> Bool
+
+    init(represented : ElementType) {
+        self.represented = represented
+
+        self.isEquivalent = { _, _ in false }
+    }
+
+    init(represented : ElementType) where ElementType:Equatable {
+        self.represented = represented
+
+        self.isEquivalent = {
+            $0.represented == $1.represented
+        }
+    }
+
+    init(represented : ElementType) where ElementType:IsEquivalentContent {
+        self.represented = represented
+
+        self.isEquivalent = {
+            $0.represented.isEquivalent(to: $1.represented)
+        }
+    }
+
+    public func isEquivalent(to other: Self) -> Bool {
+        isEquivalent(self, other)
+    }
+
+    public var elementRepresentation: Element {
+        represented
+    }
+}
+

BlueprintUILists/Sources/Element+Item.swift

@@ -0,0 +1,137 @@
+//
+//  Element+Item.swift
+//  BlueprintUILists
+//
+//  Created by Kyle Van Essen on 7/24/22.
+//
+
+import BlueprintUI
+import ListableUI
+
+
+// MARK: Item / ItemContent Extensions
+
+extension Element {
+
+    /// Converts the given `Element` into a Listable `Item` with the provided ID. You can use this ID
+    /// to scroll to or later access the item through the regular list access APIs.
+    /// You many also optionally configure the item, setting its values such as the `onDisplay` callbacks, etc.
+    ///
+    /// ```swift
+    /// MyElement(...)
+    ///     .item(id: "my-provided-id") { item in
+    ///         item.insertAndRemoveAnimations = .scaleUp
+    ///     }
+    /// ```
+    ///
+    /// ## ⚠️ Performance Considerations
+    /// Unless your `Element` conforms to `Equatable` or `IsEquivalentContent`,
+    /// it will return `false` for `isEquivalent` for each content update, which can dramatically
+    /// hurt performance for longer lists (eg, more than 20 items): it will be re-measured for each content update.
+    ///
+    /// It is encouraged for these longer lists, you ensure your `Element` conforms to one of these protocols.
+    public func item(
+        id : AnyHashable = ObjectIdentifier(Self.Type.self),
+        configure : (inout Item<WrappedElementContent<Self>>) -> () = { _ in }
+    ) -> Item<WrappedElementContent<Self>> {
+        Item(
+            WrappedElementContent(
+                identifierValue: id,
+                represented: self
+            ),
+            configure: configure
+        )
+    }
+}
+
+
+/// Ensures that the `Equatable` initializer for `WrappedElementContent` is called.
+extension Element where Self:Equatable {
+
+    public func item(
+        id : AnyHashable = ObjectIdentifier(Self.Type.self),
+        configure : (inout Item<WrappedElementContent<Self>>) -> () = { _ in }
+    ) -> Item<WrappedElementContent<Self>> {
+        Item(
+            WrappedElementContent(
+                identifierValue: id,
+                represented: self
+            ),
+            configure: configure
+        )
+    }
+}
+
+
+/// Ensures that the `IsEquivalentContent` initializer for `WrappedElementContent` is called.
+extension Element where Self:IsEquivalentContent {
+
+    public func item(
+        id : AnyHashable = ObjectIdentifier(Self.Type.self),
+        configure : (inout Item<WrappedElementContent<Self>>) -> () = { _ in }
+    ) -> Item<WrappedElementContent<Self>> {
+        Item(
+            WrappedElementContent(
+                identifierValue: id,
+                represented: self
+            ),
+            configure: configure
+        )
+    }
+}
+
+
+public struct WrappedElementContent<ElementType:Element> : BlueprintItemContent
+{
+    public let identifierValue: AnyHashable
+
+    public let represented : ElementType
+
+    private let isEquivalent : (Self, Self) -> Bool
+
+    init(
+        identifierValue: AnyHashable,
+        represented: ElementType
+    ) {
+        self.represented = represented
+        self.identifierValue = identifierValue
+
+        self.isEquivalent = { _, _ in false }
+    }
+
+    init(
+        identifierValue: AnyHashable,
+        represented: ElementType
+    ) where ElementType:Equatable {
+        self.represented = represented
+        self.identifierValue = identifierValue
+
+        self.isEquivalent = {
+            $0.represented == $1.represented
+        }
+    }
+
+    init(
+        identifierValue: AnyHashable,
+        represented: ElementType
+    ) where ElementType:IsEquivalentContent {
+        self.represented = represented
+        self.identifierValue = identifierValue
+
+        self.isEquivalent = {
+            $0.represented.isEquivalent(to: $1.represented)
+        }
+    }
+
+    public func isEquivalent(to other: Self) -> Bool {
+        isEquivalent(self, other)
+    }
+
+    public func element(with info: ApplyItemContentInfo) -> Element {
+        represented
+    }
+
+    public var reappliesToVisibleView: ReappliesToVisibleView {
+        .ifNotEquivalent
+    }
+}

BlueprintUILists/Sources/HeaderFooter.swift → BlueprintUILists/Sources/ElementHeaderFooter.swift

@@ -1,5 +1,5 @@
 //
-//  HeaderFooter.swift
+//  ElementHeaderFooter.swift
 //  BlueprintUILists
 //
 //  Created by Kyle Van Essen on 10/9/20.
@@ -9,6 +9,8 @@ import ListableUI
 import BlueprintUI
 
 
+///
+/// ⚠️ This method is soft-deprecated! Consider using `myElement.headerFooter(...)` instead.
 ///
 /// Provides a way to create a `HeaderFooter` for your Blueprint elements without
 /// requiring the creation of a new `BlueprintHeaderFooterContent` struct.
@@ -62,6 +64,8 @@ public func ElementHeaderFooter<Represented>(
     )
 }
 
+///
+/// ⚠️ This method is soft-deprecated! Consider using `myElement.headerFooter(...)` instead.
 ///
 /// Provides a way to create a `HeaderFooter` for your Blueprint elements without
 /// requiring the creation of a new `BlueprintHeaderFooterContent` struct.

BlueprintUILists/Sources/Item.swift → BlueprintUILists/Sources/ElementItem.swift

@@ -1,5 +1,5 @@
 //
-//  Item.swift
+//  ElementItem.swift
 //  BlueprintUILists
 //
 //  Created by Kyle Van Essen on 9/10/20.
@@ -9,6 +9,8 @@ import ListableUI
 import BlueprintUI
 
 
+///
+/// ⚠️ This method is soft-deprecated! Consider using `myElement.item(...)` instead.
 ///
 /// Provides a way to create an `Item` for your Blueprint elements without
 /// requiring the creation of a new `BlueprintItemContent` struct.
@@ -68,6 +70,8 @@ public func ElementItem<Represented, IdentifierValue:Hashable>(
 
 
 ///
+/// ⚠️ This method is soft-deprecated! Consider using `myElement.item(...)` instead.
+/// 
 /// Provides a way to create an `Item` for your Blueprint elements without
 /// requiring the creation of a new `BlueprintItemContent` struct.
 ///

BlueprintUILists/Sources/List.swift

@@ -59,7 +59,7 @@ public struct List : Element
     //
     // MARK: Initialization
     //
-        
+
     /// Create a new list, configured with the provided properties,
     /// configured with the provided `ListProperties` builder.
     public init(
@@ -76,13 +76,26 @@ public struct List : Element
     public init(
         measurement : List.Measurement = .fillParent,
         configure : ListProperties.Configure = { _ in },
-        @ListableBuilder<Section> sections : () -> [Section]
+        @ListableArrayBuilder<Section> sections : () -> [Section],
+        @ListableValueBuilder<AnyHeaderFooterConvertible> containerHeader : () -> AnyHeaderFooterConvertible? = { nil },
+        @ListableValueBuilder<AnyHeaderFooterConvertible> header : () -> AnyHeaderFooterConvertible? = { nil },
+        @ListableValueBuilder<AnyHeaderFooterConvertible> footer : () -> AnyHeaderFooterConvertible? = { nil },
+        @ListableValueBuilder<AnyHeaderFooterConvertible> overscrollFooter : () -> AnyHeaderFooterConvertible? = { nil }
     ) {
         self.measurement = measurement
 
-        self.properties = .default(with: configure)
+        var properties = ListProperties.default {
+            $0.sections = sections()
+
+            $0.containerHeader = containerHeader()
+            $0.header = header()
+            $0.footer = footer()
+            $0.overscrollFooter = overscrollFooter()
+        }
+
+        configure(&properties)
 
-        self.properties.sections += sections()
+        self.properties = properties
     }
 
     //