Improve using elements in lists

BlueprintUILists/Sources/Element+HeaderFooter.swift

@@ -0,0 +1,160 @@
+//
+//  Element+HeaderFooter.swift
+//  BlueprintUILists
+//
+//  Created by Kyle Van Essen on 7/24/22.
+//
+
+import BlueprintUI
+@_spi(ListableInternal)
+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.
+    ///
+    /// You may also provide a background and pressed background as well as tap actions.
+    ///
+    /// ```swift
+    /// MyElement(...)
+    ///     .listHeaderFooter { header in
+    ///         header.onTap = { ... }
+    ///     }
+    ///     .background {
+    ///         Box(backgroundColor: ...).inset(...)
+    ///     }
+    ///     .onTap {
+    ///         // Handle the tap event.
+    ///     } show: {
+    ///         Box(backgroundColor: ...).inset(...)
+    ///     }
+    /// ```
+    public func listHeaderFooter(
+        configure : (inout HeaderFooter<WrappedHeaderFooterContent<Self>>) -> () = { _ in }
+    ) -> HeaderFooter<WrappedHeaderFooterContent<Self>> {
+        HeaderFooter(
+            WrappedHeaderFooterContent(represented: self),
+            configure: configure
+        )
+    }
+}
+
+
+extension HeaderFooter where Content : _AnyWrappedHeaderFooterContent {
+
+    /// TODO
+    public func background(_ provider : @escaping () -> Element?) -> Self {
+        var copy = self
+        copy.content._backgroundProvider = provider
+        return copy
+    }
+
+    /// TODO
+    public func onTap(
+        _ onTap : @escaping () -> (),
+        show background : @escaping () -> Element
+    ) -> Self {
+        var copy = self
+        copy.onTap = onTap
+        copy.content._backgroundProvider = background
+        return copy
+    }
+}
+
+
+
+/// Ensures that the `Equatable` initializer for `WrappedHeaderFooterContent` is called.
+extension Element where Self:Equatable {
+
+    public func listHeaderFooter(
+        configure : (inout HeaderFooter<WrappedHeaderFooterContent<Self>>) -> () = { _ in }
+    ) -> HeaderFooter<WrappedHeaderFooterContent<Self>> {
+        HeaderFooter(
+            WrappedHeaderFooterContent(represented: self),
+            configure: configure
+        )
+    }
+}
+
+
+/// Ensures that the `EquivalentComparable` initializer for `WrappedHeaderFooterContent` is called.
+extension Element where Self:EquivalentComparable {
+
+    public func listHeaderFooter(
+        configure : (inout HeaderFooter<WrappedHeaderFooterContent<Self>>) -> () = { _ in }
+    ) -> HeaderFooter<WrappedHeaderFooterContent<Self>> {
+        HeaderFooter(
+            WrappedHeaderFooterContent(represented: self),
+            configure: configure
+        )
+    }
+}
+
+
+public struct WrappedHeaderFooterContent<ElementType:Element> : BlueprintHeaderFooterContent, _AnyWrappedHeaderFooterContent
+{
+    public let represented : ElementType
+
+    private let isEquivalent : (Self, Self) -> Bool
+
+    init(represented : ElementType) {
+        self.represented = represented
+
+        self.isEquivalent = {
+            defaultIsEquivalentImplementation($0.represented, $1.represented)
+        }
+    }
+
+    init(represented : ElementType) where ElementType:Equatable {
+        self.represented = represented
+
+        self.isEquivalent = {
+            $0.represented == $1.represented
+        }
+    }
+
+    init(represented : ElementType) where ElementType:EquivalentComparable {
+        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
+    }
+
+    public var _backgroundProvider : () -> Element? = { nil }
+
+    public var background: Element? {
+        _backgroundProvider()
+    }
+
+    public var _pressedBackgroundProvider : () -> Element? = { nil }
+
+    public var pressedBackground: Element? {
+        _pressedBackgroundProvider()
+    }
+
+    public var reappliesToVisibleView: ReappliesToVisibleView {
+        .ifNotEquivalent
+    }
+}
+
+
+public protocol _AnyWrappedHeaderFooterContent {
+
+    var _backgroundProvider : () -> Element? { get set }
+    var _pressedBackgroundProvider : () -> Element? { get set }
+
+}

BlueprintUILists/Sources/Element+Item.swift

@@ -0,0 +1,184 @@
+//
+//  Element+Item.swift
+//  BlueprintUILists
+//
+//  Created by Kyle Van Essen on 7/24/22.
+//
+
+import BlueprintUI
+@_spi(ListableInternal)
+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.
+    ///
+    /// You can also provide a background or selected background via the `background` and `selectedBackground` modifiers.
+    ///
+    /// ```swift
+    /// MyElement(...)
+    ///     .listItem(id: "my-provided-id") { item in
+    ///         item.insertAndRemoveAnimations = .scaleUp
+    ///     }
+    ///     .background {
+    ///         Box(backgroundColor: ...).inset(...)
+    ///     }
+    ///     .selectedBackground(.tappable) {
+    ///         Box(backgroundColor: ...).inset(...)
+    ///     }
+    /// ```
+    public func listItem(
+        id : AnyHashable? = nil,
+        configure : (inout Item<WrappedElementContent<Self>>) -> () = { _ in }
+    ) -> Item<WrappedElementContent<Self>> {
+        Item(
+            WrappedElementContent(
+                identifierValue: id,
+                represented: self
+            ),
+            configure: configure
+        )
+    }
+}
+
+
+extension Item where Content : _AnyWrappedElementContent {
+
+    /// TODO
+    public func background(_ provider : @escaping (ApplyItemContentInfo) -> Element?) -> Self {
+        var copy = self
+        copy.content._backgroundProvider = provider
+        return copy
+    }
+
+    /// TODO
+    public func selectedBackground(
+        _ selectionStyle : ItemSelectionStyle,
+        selectedBackground : @escaping (ApplyItemContentInfo) -> Element?
+    ) -> Self {
+        var copy = self
+        copy.selectionStyle = selectionStyle
+        copy.content._backgroundProvider = selectedBackground
+        return copy
+    }
+}
+
+
+/// Ensures that the `Equatable` initializer for `WrappedElementContent` is called.
+extension Element where Self:Equatable {
+
+    public func listItem(
+        id : AnyHashable? = nil,
+        configure : (inout Item<WrappedElementContent<Self>>) -> () = { _ in }
+    ) -> Item<WrappedElementContent<Self>> {
+        Item(
+            WrappedElementContent(
+                identifierValue: id,
+                represented: self
+            ),
+            configure: configure
+        )
+    }
+}
+
+
+/// Ensures that the `EquivalentComparable` initializer for `WrappedElementContent` is called.
+extension Element where Self:EquivalentComparable {
+
+    public func listItem(
+        id : AnyHashable? = nil,
+        configure : (inout Item<WrappedElementContent<Self>>) -> () = { _ in }
+    ) -> Item<WrappedElementContent<Self>> {
+        Item(
+            WrappedElementContent(
+                identifierValue: id,
+                represented: self
+            ),
+            configure: configure
+        )
+    }
+}
+
+
+public struct WrappedElementContent<ElementType:Element> : BlueprintItemContent, _AnyWrappedElementContent
+{
+    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 = {
+            defaultIsEquivalentImplementation($0.represented, $1.represented)
+        }
+    }
+
+    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:EquivalentComparable {
+        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 _backgroundProvider: (ApplyItemContentInfo) -> Element? = { _ in nil }
+
+    public func backgroundElement(with info: ApplyItemContentInfo) -> Element? {
+        _backgroundProvider(info)
+    }
+
+    public var _selectedBackgroundProvider: (ApplyItemContentInfo) -> Element? = { _ in nil }
+
+    public func selectedBackgroundElement(with info: ApplyItemContentInfo) -> Element? {
+        _selectedBackgroundProvider(info)
+    }
+
+    public var reappliesToVisibleView: ReappliesToVisibleView {
+        .ifNotEquivalent
+    }
+}
+
+
+public protocol _AnyWrappedElementContent {
+
+    var _backgroundProvider : (ApplyItemContentInfo) -> Element? { get set }
+    var _selectedBackgroundProvider : (ApplyItemContentInfo) -> Element? { get set }
+
+}

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.listHeaderFooter(...)` 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.listHeaderFooter(...)` 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.listItem(...)` 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.listItem(...)` instead.
+/// 
 /// Provides a way to create an `Item` for your Blueprint elements without
 /// requiring the creation of a new `BlueprintItemContent` struct.
 ///