Merge pull request #150 from kyleve/kve/element-to-content

Rename "Element" to "Content"

BlueprintLists/Sources/Deprecations.swift

@@ -0,0 +1,58 @@
+//
+//  Deprecations.swift
+//  BlueprintLists
+//
+//  Created by Kyle Van Essen on 5/29/20.
+//
+
+import BlueprintUI
+
+
+///
+/// This file contains deprecations which have occurred in BlueprintLists, for which there are reasonable
+/// forward-moving defaults (eg, renames), to ease transitions for consumers when they update their library version.
+///
+/// To add new deprecations and changes:
+/// ------------------------------------
+/// 1) Add a new `MARK: Deprecated <Date>` section for the deprecations you are adding.
+///
+/// 2) Add deprecation annotations like so:
+///    ```
+///    @available(*, deprecated, renamed: "ItemContent")
+///    public typealias ItemElement = ItemContent
+///    ```
+///
+///    Or, when deprecating properties, add a passthrough like so:
+///    ```
+///    public extension Item {
+///       @available(*, deprecated, renamed: "content")
+///       var element : Content {
+///          self.content
+///       }
+///    }
+///    ```
+///
+/// 3) After 1-2 months has passed, mark the previously `deprecated` items as `unavailable`:
+///    ```
+///    @available(*, unavailable, renamed: "ItemContent")
+///    ```
+///
+/// 4) After another 1-2 months have passed, feel free to remove the `MARK: Deprecated` section you added.
+///
+
+//
+// MARK: Deprecated May 29, 2019
+//
+
+@available(*, deprecated, renamed: "BlueprintItemContent")
+public typealias BlueprintItemElement = BlueprintItemContent
+
+@available(*, deprecated, renamed: "BlueprintHeaderFooterContent")
+public typealias BlueprintHeaderFooterElement = BlueprintHeaderFooterContent
+
+public extension BlueprintHeaderFooterContent {
+    @available(*, deprecated, renamed: "elementRepresentation")
+    var element : Element {
+        self.elementRepresentation
+    }
+}

BlueprintLists/Sources/HeaderFooter.swift

@@ -6,33 +6,28 @@
 //
 
 import BlueprintUI
-
 import Listable
 
-//
-// MARK: Blueprint Elements
-//
 
-public protocol BlueprintHeaderFooterElement : HeaderFooterElement where ContentView == BlueprintView
+public protocol BlueprintHeaderFooterContent : HeaderFooterContent where ContentView == BlueprintView
 {
     //
     // MARK: Creating Blueprint Element Representations
     //
 
-    var element : BlueprintUI.Element { get }
+    var elementRepresentation : Element { get }
 }
 
 
-//
-// MARK: Applying Blueprint Elements
-//
-
-
-public extension BlueprintHeaderFooterElement
+public extension BlueprintHeaderFooterContent
 {
+    //
+    // MARK: HeaderFooterContent
+    //
+
     func apply(to view: ContentView, reason: ApplyReason)
     {
-        view.element = self.element
+        view.element = self.elementRepresentation
     }
 
     static func createReusableHeaderFooterView(frame: CGRect) -> ContentView

BlueprintLists/Sources/Item.swift

@@ -15,11 +15,11 @@ import Listable
 //
 
 ///
-/// An `ItemElement` specialized for use with Blueprint. Instead of providing
+/// An `ItemContent` specialized for use with Blueprint. Instead of providing
 /// a custom view from `createReusableContentView`, and then updating it in `apply(to:)`,
 /// you instead provide Blueprint element trees, and `Listable` handles mapping this to an underlying `BlueprintView`.
 ///
-public protocol BlueprintItemElement : ItemElement
+public protocol BlueprintItemContent : ItemContent
     where
     ContentView == BlueprintView,
     BackgroundView == BlueprintView,
@@ -29,75 +29,75 @@ public protocol BlueprintItemElement : ItemElement
     // MARK: Creating Blueprint Element Representations
     //
 
-    /// Required. Create and return the element used to represent the content of the element.
+    /// Required. Create and return the Blueprint element used to represent the content.
     ///
-    /// You can use the provided `ApplyItemElementInfo` to vary the appearance of your content
-    /// based on the current state of the element.
+    /// You can use the provided `ApplyItemContentInfo` to vary the appearance of the element
+    /// based on the current state of the item.
     ///
-    func element(with info : ApplyItemElementInfo) -> BlueprintUI.Element
+    func element(with info : ApplyItemContentInfo) -> Element
 
-    /// Optional. Create and return the element used to represent the background of the element.
-    /// You usually provide this method alongside `selectedBackgroundElement`, if your element
+    /// Optional. Create and return the Blueprint element used to represent the background of the content.
+    /// You usually provide this method alongside `selectedBackgroundElement`, if your content
     /// supports selection or highlighting.
     ///
-    /// You can use the provided `ApplyItemElementInfo` to vary the appearance of your content
-    /// based on the current state of the element.
+    /// You can use the provided `ApplyItemContentInfo` to vary the appearance of the element
+    /// based on the current state of the item.
     ///
     /// Note
     /// ----
     /// The default implementation of this method returns nil, and provides no background.
     ///
-    func backgroundElement(with info : ApplyItemElementInfo) -> BlueprintUI.Element?
+    func backgroundElement(with info : ApplyItemContentInfo) -> Element?
 
-    /// Optional. Create and return the element used to represent the background of the element when it is selected or highlighted.
-    /// You usually provide this method alongside `backgroundElement`, if your element supports selection or highlighting.
+    /// Optional. Create and return the Blueprint element used to represent the background of the content when it is selected or highlighted.
+    /// You usually provide this method alongside `backgroundElement`, if your content supports selection or highlighting.
     ///
-    /// You can use the provided `ApplyItemElementInfo` to vary the appearance of your content
-    /// based on the current state of the element.
+    /// You can use the provided `ApplyItemContentInfo` to vary the appearance of the element
+    /// based on the current state of the item.
     ///
     /// Note
     /// ----
     /// The default implementation of this method returns nil, and provides no selected background.
     ///
-    func selectedBackgroundElement(with info : ApplyItemElementInfo) -> BlueprintUI.Element?
+    func selectedBackgroundElement(with info : ApplyItemContentInfo) -> Element?
 }
 
 
-public extension BlueprintItemElement
+public extension BlueprintItemContent
 {
     //
     // MARK: Default Implementations
     //
 
-    /// By default, elements have no background.
-    func backgroundElement(with info : ApplyItemElementInfo) -> BlueprintUI.Element?
+    /// By default, content has no background.
+    func backgroundElement(with info : ApplyItemContentInfo) -> Element?
     {
         nil
     }
 
-    /// By default, elements have no selected background.
-    func selectedBackgroundElement(with info : ApplyItemElementInfo) -> BlueprintUI.Element?
+    /// By default, content has no selected background.
+    func selectedBackgroundElement(with info : ApplyItemContentInfo) -> Element?
     {
         nil
     }
 }
 
 
-public extension BlueprintItemElement
+public extension BlueprintItemContent
 {
     //
-    // MARK: ItemElement
+    // MARK: ItemContent
     //
 
-    /// Maps the `BlueprintItemElement` methods into the underlying `BlueprintView`s used to render the element.
-    func apply(to views : ItemElementViews<Self>, for reason: ApplyReason, with info : ApplyItemElementInfo)
+    /// Maps the `BlueprintItemContent` methods into the underlying `BlueprintView`s used to render the element.
+    func apply(to views : ItemContentViews<Self>, for reason: ApplyReason, with info : ApplyItemContentInfo)
     {
         views.content.element = self.element(with: info)
         views.background.element = self.backgroundElement(with: info)
         views.selectedBackground.element = self.selectedBackgroundElement(with: info)
     }
 
-    /// Creates the `BlueprintView` used to render the content of the element.
+    /// Creates the `BlueprintView` used to render the content of the item.
     static func createReusableContentView(frame: CGRect) -> ContentView
     {
         let view = BlueprintView(frame: frame)
@@ -106,7 +106,7 @@ public extension BlueprintItemElement
         return view
     }
 
-    /// Creates the `BlueprintView` used to render the background of the element.
+    /// Creates the `BlueprintView` used to render the background of the item.
     static func createReusableBackgroundView(frame: CGRect) -> BackgroundView
     {
         let view = BlueprintView(frame: frame)

BlueprintLists/Sources/List.swift

@@ -10,7 +10,7 @@ import BlueprintUI
 import Listable
 
 
-public struct List : BlueprintUI.Element
+public struct List : Element
 {
     public var listDescription : ListDescription
 
@@ -34,7 +34,7 @@ public struct List : BlueprintUI.Element
     }
 
     //
-    // MARK: BlueprintUI.Element
+    // MARK: Element
     //
 
     public var content : ElementContent {

Demo/Sources/Demos/Demo Screens/AutoScrollingViewController.swift

@@ -87,15 +87,15 @@ final class AutoScrollingViewController : UIViewController
 }
 
 
-struct BottomPinnedItem : BlueprintItemElement, Equatable
+struct BottomPinnedItem : BlueprintItemContent, Equatable
 {
     var text : String
 
     var identifier: Identifier<BottomPinnedItem> {
         return .init(self.text)
     }
 
-    func element(with info : ApplyItemElementInfo) -> Element
+    func element(with info : ApplyItemContentInfo) -> Element
     {
         var box = Box(
             backgroundColor: .white,

Demo/Sources/Demos/Demo Screens/BlueprintListDemoViewController.swift

@@ -65,15 +65,15 @@ final class BlueprintListDemoViewController : UIViewController
     }
 }
 
-struct PodcastRow : BlueprintItemElement, Equatable
+struct PodcastRow : BlueprintItemContent, Equatable
 {
     var podcast : Podcast
 
     var identifier: Identifier<PodcastRow> {
         return .init(self.podcast.name)
     }
 
-    func element(with info : ApplyItemElementInfo) -> Element
+    func element(with info : ApplyItemContentInfo) -> Element
     {
 
         Row { row in

Demo/Sources/Demos/Demo Screens/CollectionViewAppearance.swift

@@ -39,11 +39,11 @@ extension UIColor
 }
 
 
-struct DemoHeader : BlueprintHeaderFooterElement, Equatable
+struct DemoHeader : BlueprintHeaderFooterContent, Equatable
 {
     var title : String
 
-    var element: Element {
+    var elementRepresentation: Element {
         Label(text: self.title) {
             $0.font = .systemFont(ofSize: 20.0, weight: .bold)
         }
@@ -56,11 +56,11 @@ struct DemoHeader : BlueprintHeaderFooterElement, Equatable
     }
 }
 
-struct DemoHeader2 : BlueprintHeaderFooterElement, Equatable
+struct DemoHeader2 : BlueprintHeaderFooterContent, Equatable
 {
     var title : String
 
-    var element: Element {
+    var elementRepresentation: Element {
         Label(text: self.title) {
             $0.font = .systemFont(ofSize: 20.0, weight: .bold)
         }
@@ -74,7 +74,7 @@ struct DemoHeader2 : BlueprintHeaderFooterElement, Equatable
 }
 
 
-struct DemoItem : BlueprintItemElement, Equatable
+struct DemoItem : BlueprintItemContent, Equatable
 {
     var text : String
 
@@ -84,7 +84,7 @@ struct DemoItem : BlueprintItemElement, Equatable
 
     typealias SwipeActionsView = DefaultSwipeActionsView
 
-    func element(with info : ApplyItemElementInfo) -> Element
+    func element(with info : ApplyItemContentInfo) -> Element
     {
         Label(text: self.text) {
             $0.font = .systemFont(ofSize: 16.0, weight: .medium)
@@ -93,7 +93,7 @@ struct DemoItem : BlueprintItemElement, Equatable
         .inset(horizontal: 15.0, vertical: 10.0)
     }
 
-    func backgroundElement(with info: ApplyItemElementInfo) -> Element?
+    func backgroundElement(with info: ApplyItemContentInfo) -> Element?
     {
         Box(
             backgroundColor: .white,
@@ -102,7 +102,7 @@ struct DemoItem : BlueprintItemElement, Equatable
         )
     }
 
-    func selectedBackgroundElement(with info: ApplyItemElementInfo) -> Element?
+    func selectedBackgroundElement(with info: ApplyItemContentInfo) -> Element?
     {
         Box(
             backgroundColor: info.state.isSelected ? .white(0.9) : .white(0.95),
@@ -113,11 +113,11 @@ struct DemoItem : BlueprintItemElement, Equatable
 }
 
 
-struct DemoFooter : BlueprintHeaderFooterElement, Equatable
+struct DemoFooter : BlueprintHeaderFooterContent, Equatable
 {
     var text : String
 
-    var element: Element {
+    var elementRepresentation: Element {
         return Centered(Label(text: self.text))
     }
 }