Improve using elements in lists

BlueprintUILists/Sources/Element+HeaderFooter.swift

@@ -0,0 +1,89 @@
+//
+//  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
+        )
+    }
+
+    /// Used by internal Listable methods to  convert type-erased `Element` instances into `Item` instances.
+    func toHeaderFooterConvertible() -> AnyHeaderFooterConvertible {
+        /// We use `type(of:)` to ensure we get the actual type, not just `Element`.
+        WrappedHeaderFooterContent(
+            represented: self
+        )
+    }
+}
+
+
+public struct WrappedHeaderFooterContent<ElementType:Element> : BlueprintHeaderFooterContent
+{
+    public let represented : ElementType
+
+    public func isEquivalent(to other: Self) -> Bool {
+        false
+    }
+
+    public var elementRepresentation: Element {
+        represented
+    }
+}
+
+
+extension WrappedHeaderFooterContent where ElementType : Equatable {
+
+    public func isEquivalent(to other: Self) -> Bool {
+        represented == other.represented
+    }
+
+    public var reappliesToVisibleView: ReappliesToVisibleView {
+        .ifNotEquivalent
+    }
+}
+
+
+extension WrappedHeaderFooterContent where ElementType : IsEquivalentContent {
+
+    public func isEquivalent(to other: Self) -> Bool {
+        represented.isEquivalent(to: other.represented)
+    }
+
+    public var reappliesToVisibleView: ReappliesToVisibleView {
+        .ifNotEquivalent
+    }
+}

BlueprintUILists/Sources/Element+Item.swift

@@ -0,0 +1,122 @@
+//
+//  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`. You many also optionally
+    /// configure the item, setting its values such as the `onDisplay` callbacks, etc.
+    ///
+    /// ```swift
+    /// MyElement(...)
+    ///     .item { 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(
+        configure : (inout Item<WrappedElementContent<Self, ObjectIdentifier>>) -> () = { _ in }
+    ) -> Item<WrappedElementContent<Self, ObjectIdentifier>> {
+        Item(
+            WrappedElementContent(
+                represented: self,
+                identifierValue: ObjectIdentifier(Self.Type.self)
+            ),
+            configure: configure
+        )
+    }
+
+    /// 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:Hashable>(
+        id : ID,
+        configure : (inout Item<WrappedElementContent<Self, ID>>) -> () = { _ in }
+    ) -> Item<WrappedElementContent<Self, ID>> {
+        Item(
+            WrappedElementContent(
+                represented: self,
+                identifierValue: id
+            ),
+            configure: configure
+        )
+    }
+
+    /// Used by internal Listable methods to  convert type-erased `Element` instances into `Item` instances.
+    func toAnyItemConvertible() -> AnyItemConvertible {
+        /// We use `type(of:)` to ensure we get the actual type, not just `Element`.
+        WrappedElementContent(
+            represented: self,
+            identifierValue: ObjectIdentifier(type(of: self))
+        )
+    }
+}
+
+
+public struct WrappedElementContent<ElementType:Element, IdentifierValue:Hashable> : BlueprintItemContent
+{
+    public let represented : ElementType
+
+    public let identifierValue: IdentifierValue
+
+    public func isEquivalent(to other: Self) -> Bool {
+        false
+    }
+
+    public func element(with info: ApplyItemContentInfo) -> Element {
+        represented
+    }
+}
+
+
+extension WrappedElementContent where ElementType : Equatable {
+
+    public func isEquivalent(to other: Self) -> Bool {
+        represented == other.represented
+    }
+
+    public var reappliesToVisibleView: ReappliesToVisibleView {
+        .ifNotEquivalent
+    }
+}
+
+
+extension WrappedElementContent where ElementType : IsEquivalentContent {
+
+    public func isEquivalent(to other: Self) -> Bool {
+        represented.isEquivalent(to: other.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]
+        @ListableBuilder<Section> sections : () -> [Section],
+        @ListableOptionalBuilder<AnyHeaderFooterConvertible> containerHeader : () -> AnyHeaderFooterConvertible? = { nil },
+        @ListableOptionalBuilder<AnyHeaderFooterConvertible> header : () -> AnyHeaderFooterConvertible? = { nil },
+        @ListableOptionalBuilder<AnyHeaderFooterConvertible> footer : () -> AnyHeaderFooterConvertible? = { nil },
+        @ListableOptionalBuilder<AnyHeaderFooterConvertible> overscrollFooter : () -> AnyHeaderFooterConvertible? = { nil }
     ) {
         self.measurement = measurement
 
-        self.properties = .default(with: configure)
+        var properties = ListProperties.default {
+            $0.sections = sections()
+
+            $0.content.containerHeader = containerHeader()
+            $0.content.header = header()
+            $0.content.footer = footer()
+            $0.content.overscrollFooter = overscrollFooter()
+        }
+
+        configure(&properties)
 
-        self.properties.sections += sections()
+        self.properties = properties
     }
 
     //

BlueprintUILists/Sources/ListableBuilder+Element.swift

@@ -0,0 +1,82 @@
+//
+//  ListableBuilder+Element.swift
+//  BlueprintUILists
+//
+//  Created by Kyle Van Essen on 7/24/22.
+//
+
+import BlueprintUI
+import ListableUI
+
+
+/// Adds `Element` support when building `AnyItemConvertible` arrays, which allows:
+///
+/// ```swift
+/// Section("3") { section in
+///     TestContent1() // An ItemContent
+///
+///     Element1() // An Element
+///     Element2() // An Element
+/// }
+/// ```
+///
+/// ## Note
+/// Takes advantage of `@_disfavoredOverload` to avoid ambiguous method resolution with the default implementations.
+/// See more here: https://github.com/apple/swift/blob/main/docs/ReferenceGuides/UnderscoredAttributes.md#_disfavoredoverload
+///
+public extension ListableBuilder where ContentType == AnyItemConvertible {
+
+    /// Required by every result builder to build combined results from statement blocks.
+    @_disfavoredOverload static func buildBlock(_ components: [Element]...) -> Component {
+        components.reduce(into: []) { $0 += $1.map { $0.toAnyItemConvertible() } }
+    }
+
+    /// If declared, provides contextual type information for statement expressions to translate them into partial results.
+    @_disfavoredOverload static func buildExpression(_ expression: Element) -> Component {
+        [expression.toAnyItemConvertible()]
+    }
+
+    /// If declared, provides contextual type information for statement expressions to translate them into partial results.
+    @_disfavoredOverload static func buildExpression(_ expression: [Element]) -> Component {
+        expression.map { $0.toAnyItemConvertible() }
+    }
+
+    /// Enables support for `if` statements that do not have an `else`.
+    @_disfavoredOverload static func buildOptional(_ component: [Element]?) -> Component {
+        component?.map { $0.toAnyItemConvertible() } ?? []
+    }
+
+    /// With buildEither(second:), enables support for 'if-else' and 'switch' statements by folding conditional results into a single result.
+    @_disfavoredOverload static func buildEither(first component: [Element]) -> Component {
+        component.map { $0.toAnyItemConvertible() }
+    }
+
+    /// With buildEither(first:), enables support for 'if-else' and 'switch' statements by folding conditional results into a single result.
+    @_disfavoredOverload static func buildEither(second component: [Element]) -> Component {
+        component.map { $0.toAnyItemConvertible() }
+    }
+
+    /// Enables support for 'for..in' loops by combining the results of all iterations into a single result.
+    @_disfavoredOverload static func buildArray(_ components: [[Element]]) -> Component {
+        components.flatMap { $0.map { $0.toAnyItemConvertible() } }
+    }
+
+    /// If declared, this will be called on the partial result of an `if #available` block to allow the result builder to erase type information.
+    @_disfavoredOverload static func buildLimitedAvailability(_ component: [Element]) -> Component {
+        component.map { $0.toAnyItemConvertible() }
+    }
+
+    /// If declared, this will be called on the partial result from the outermost block statement to produce the final returned result.
+    @_disfavoredOverload static func buildFinalResult(_ component: [Element]) -> FinalResult {
+        component.map { $0.toAnyItemConvertible() }
+    }
+}
+
+
+public extension ListableOptionalBuilder where ContentType == AnyHeaderFooterConvertible {
+
+    static func buildBlock(_ content: Element) -> ContentType {
+        return content.toHeaderFooterConvertible()
+    }
+}
+