Update README for V3.0. Adopt left:right and top:bottom for HSplit and VSplit init. Fix previews.

Author: stevengharris

Demo/SplitDemo/DemoApp.swift

@@ -18,8 +18,8 @@ struct DemoApp: View {
             switch demoID {
             case .simpleDefaults:
                 HSplit(
-                    primary: { Color.green },
-                    secondary: { Color.red }
+                    left: { Color.green },
+                    right: { Color.red }
                 )
             case .simpleAdjustable:
                 Split(

Demo/SplitDemo/DemoModel.swift

@@ -23,8 +23,8 @@ enum DemoID: String, CaseIterable {
 /// The `label` is used for the Menu, `description` for the Text at the bottom.
 ///
 /// The `holders` identify the LayoutHolder and SideHolders that can be used to control
-/// the various SplitViews in the demo. These need to be defined once, so that the
-/// DemoToolbar at the top and the individual SplitViews are holding onto the same
+/// the various Split views in the demo. These need to be defined once, so that the
+/// DemoToolbar at the top and the individual Split views are holding onto the same
 /// ObservableObject.
 let demos: [DemoID : Demo] = [
     .simpleDefaults :
@@ -70,14 +70,14 @@ let demos: [DemoID : Demo] = [
 ]
 
 /// Demo holds onto the labels for the Menu and descriptions for the Text at the bottom, along with
-/// the SplitStateHolders that are used by the DemoToolbar buttons and the SplitViews themselves.
+/// the SplitStateHolders that are used by the DemoToolbar buttons and the Split views themselves.
 struct Demo {
     var label: String
     var description: String
     var holders: [SplitStateHolder] = []
 }
 
-/// The combination of LayoutHolder and SideHolder used in one SplitView.
+/// The combination of LayoutHolder and SideHolder used in one Split view.
 ///
 /// Has to be Identifiable because we ForEach over the `demo.holders` to create the
 /// Buttons dynamically.

Demo/SplitDemo/DemoSplitter.swift

@@ -11,7 +11,7 @@ import SplitView
 /// A custom splitter for the `.customSplitter` demo.
 ///
 /// Note a custom splitter must conform to SplitDivider protocol, which means it is a View that can tell the
-/// SplitView what its `visibleThickness` is. The SplitView separates the `primary` and `secondary`
+/// Split view what its `visibleThickness` is. The Split view separates the `primary` and `secondary`
 /// views by the `visibleThickness` of the SplitDivider.
 ///
 /// A custom splitter should be sensitive to the layout, because if the layout changes, then the splitter needs to

README.md

@@ -18,7 +18,7 @@ public struct HSplit<P: View, D: View, S: View>: View {
 
     public var body: some View {
         Split(primary: { primary }, secondary: { secondary })
-            .layout(.horizontal)
+            .layout(LayoutHolder(.horizontal))
             .styling(styling)
             .constraints(constraints)
             .splitter {
@@ -29,12 +29,12 @@ public struct HSplit<P: View, D: View, S: View>: View {
             .hide(hide)
     }
 
-    public init(@ViewBuilder primary: @escaping ()->P, @ViewBuilder secondary: @escaping ()->S) where D == Splitter {
+    public init(@ViewBuilder left: @escaping ()->P, @ViewBuilder right: @escaping ()->S) where D == Splitter {
         let fraction = FractionHolder()
         let hide = SideHolder()
         let styling = SplitStyling()
         let constraints = SplitConstraints()
-        self.init(fraction: fraction, hide: hide, styling: styling, constraints: constraints, primary: { primary() }, splitter: { D() }, secondary: { secondary() })
+        self.init(fraction: fraction, hide: hide, styling: styling, constraints: constraints, primary: { left() }, splitter: { D() }, secondary: { right() })
     }
 
     private init(fraction: FractionHolder, hide: SideHolder, styling: SplitStyling, constraints: SplitConstraints, @ViewBuilder primary: @escaping ()->P, @ViewBuilder splitter: @escaping ()->D, @ViewBuilder secondary: @escaping ()->S) {
@@ -63,11 +63,13 @@ public struct HSplit<P: View, D: View, S: View>: View {
         return HSplit<P, T, S>(fraction: fraction, hide: hide, styling: styling, constraints: constraints, primary: { primary }, splitter: splitter, secondary: { secondary })
     }
 
+    ///  Return a new instance of HSplit with `constraints` set to these values.
     public func constraints(minPFraction: CGFloat? = nil, minSFraction: CGFloat? = nil, priority: SplitSide? = nil) -> HSplit {
         let constraints = SplitConstraints(minPFraction: minPFraction, minSFraction: minSFraction, priority: priority)
         return HSplit(fraction: fraction, hide: hide, styling: styling, constraints: constraints, primary: { primary }, splitter: { splitter }, secondary: { secondary })
     }
 
+    ///  Return a new instance of HSplit with `styling` set to these values.
     public func styling(color: Color? = nil, inset: CGFloat? = nil, visibleThickness: CGFloat? = nil, invisibleThickness: CGFloat? = nil) -> HSplit {
         let styling = SplitStyling(color: color, inset: inset, visibleThickness: visibleThickness, invisibleThickness: invisibleThickness)
         return HSplit(fraction: fraction, hide: hide, styling: styling, constraints: constraints, primary: { primary }, splitter: { splitter }, secondary: { secondary })
@@ -94,3 +96,31 @@ public struct HSplit<P: View, D: View, S: View>: View {
     }
 
 }
+
+struct HSplit_Previews: PreviewProvider {
+    static var previews: some View {
+        HSplit(
+            left: { Color.green },
+            right: {
+                VSplit(
+                    top: { Color.red },
+                    bottom: {
+                        HSplit(
+                            left: { Color.blue },
+                            right: { Color.yellow }
+                        )
+                    }
+                )
+            }
+        )
+        
+        HSplit(
+            left: {
+                VSplit(top: { Color.red }, bottom: { Color.green })
+            },
+            right: {
+                VSplit(top: { Color.yellow }, bottom: { Color.blue })
+            }
+        )
+    }
+}

Sources/SplitView/HSplit.swift

@@ -205,10 +205,9 @@ public struct Split<P: View, D: View, S: View>: View {
     private func isDraggable() -> Bool {
         guard hide.side != nil || minPFraction != nil || minSFraction != nil else { return true }
         guard let side = hide.side else { return true }
-        switch side {
-        case .primary:
+        if side.isPrimary {
             return minPFraction == nil
-        case .secondary:
+        } else {
             return minSFraction == nil
         }
     }
@@ -250,7 +249,7 @@ public struct Split<P: View, D: View, S: View>: View {
 
     /// Return a new Split with the `splitter` set to a new type.
     ///
-    /// If the splitter is a SplitDivider, get its `visibleThickness` and set that in `styling` before returning.
+    /// If the splitter is a SplitDivider, then get its `visibleThickness` and set it in `styling` before returning.
     public func splitter<T>(@ViewBuilder _ splitter: @escaping ()->T) -> Split<P, T, S> where T: View {
         let newSplitter = splitter()
         if let splitDivider = newSplitter as? (any SplitDivider) {
@@ -259,82 +258,94 @@ public struct Split<P: View, D: View, S: View>: View {
         return Split<P, T, S>(layout, fraction: fraction, hide: hide, styling: styling, constraints: constraints, primary: { primary }, splitter: splitter, secondary: { secondary })
     }
 
+    /// Return a new instance of Split with `constraints` set to a SplitConstraints holding these values.
     public func constraints(minPFraction: CGFloat? = nil, minSFraction: CGFloat? = nil, priority: SplitSide? = nil) -> Split {
         let constraints = SplitConstraints(minPFraction: minPFraction, minSFraction: minSFraction, priority: priority)
         return Split(layout, fraction: fraction, hide: hide, styling: styling, constraints: constraints, primary: { primary }, splitter: { splitter }, secondary: { secondary })
     }
 
+    /// Return a new instance of Split with `constraints` set to this SplitConstraints.
+    ///
+    /// This is a convenience method for HSplit and VSplit.
     public func constraints(_ constraints: SplitConstraints) -> Split {
         self.constraints(minPFraction: constraints.minPFraction, minSFraction: constraints.minSFraction, priority: constraints.priority)
     }
 
+    /// Return a new instance of Split with `styling` set to a SplitStyling holding these values.
+    ///
+    /// This is a convenience method for `Splitter.line()` which is also used by `Splitter.invisible()`.
     public func styling(color: Color? = nil, inset: CGFloat? = nil, visibleThickness: CGFloat? = nil, invisibleThickness: CGFloat? = nil) -> Split {
         let styling = SplitStyling(color: color, inset: inset, visibleThickness: visibleThickness, invisibleThickness: invisibleThickness)
         return Split(layout, fraction: fraction, hide: hide, styling: styling, constraints: constraints, primary: { primary }, splitter: { splitter }, secondary: { secondary })
     }
 
+    /// Return a new instance of Split with `styling` set to this SplitStyling.
+    ///
+    /// This is a convenience method for HSplit and VSplit.
     public func styling(_ styling: SplitStyling) -> Split {
         self.styling(color: styling.color, inset: styling.inset, visibleThickness: styling.visibleThickness, invisibleThickness: styling.invisibleThickness)
     }
 
-    /// Return a new instance of Split with `layout` set to this LayoutHolder
+    /// Return a new instance of Split with `layout` set to this LayoutHolder.
+    ///
+    /// Split only supports `layout` specified using a LayoutHolder because if you are not going
+    /// to change the `layout`, then you should just use HSplit or VSplit.
     public func layout(_ layout: LayoutHolder) -> Split {
         Split(layout, fraction: fraction, hide: hide, styling: styling, constraints: constraints, primary: { primary }, splitter: { splitter }, secondary: { secondary })
     }
 
-    /// Return a new instance of Split with `layout` set to a LayoutHolder holding onto this SplitLayout
-    public func layout(_ layout: SplitLayout) -> Split {
-        self.layout(LayoutHolder(layout))
-    }
-    
-    /// Return a new instance of Split with `fraction` set to this FractionHolder
+    /// Return a new instance of Split with `fraction` set to this FractionHolder.
     public func fraction(_ fraction: FractionHolder) -> Split {
         Split(layout, fraction: fraction, hide: hide, styling: styling, constraints: constraints, primary: { primary }, splitter: { splitter }, secondary: { secondary })
     }
 
-    /// Return a new instance of Split with `fraction` set to a FractionHolder holding onto this CGFloat
+    /// Return a new instance of Split with `fraction` set to a FractionHolder holding onto this CGFloat.
     public func fraction(_ fraction: CGFloat) -> Split {
         self.fraction(FractionHolder(fraction))
     }
 
-    /// Return a new instance of Split with `hide` set to this SideHolder
+    /// Return a new instance of Split with `hide` set to this SideHolder.
     public func hide(_ side: SideHolder) -> Split {
         Split(layout, fraction: fraction, hide: side, styling: styling, constraints: constraints, primary: { primary }, splitter: { splitter }, secondary: { secondary })
     }
 
-    /// Return a new instance of Split with `hide` set to a SideHolder holding onto this SplitSide
+    /// Return a new instance of Split with `hide` set to a SideHolder holding onto this SplitSide.
     public func hide(_ side: SplitSide) -> Split {
         self.hide(SideHolder(side))
     }
 
 }
 
-//struct Split_Previews: PreviewProvider {
-//    static var previews: some View {
-//        Split(.horizontal,
-//            fraction: FractionHolder(0.75),
-//            primary: { Color.red },
-//            splitter: { Splitter.horizontal },
-//            secondary: {
-//                Split(.vertical,
-//                    primary: { Color.blue },
-//                    splitter: { Splitter.vertical },
-//                    secondary: {
-//                        Split(.vertical,
-//                            primary: { Color.green },
-//                            splitter: { Splitter.vertical },
-//                            secondary: { Color.yellow }
-//                        )
-//                    }
-//                )
-//            }
-//        )
-//        .frame(width: 400, height: 400)
-//        Split(.horizontal,
-//            primary: { Split(.vertical, primary: { Color.red }, splitter: { Splitter.vertical }, secondary: { Color.green }) },
-//            splitter: { Splitter.horizontal },
-//            secondary: { Split(.horizontal, primary: { Color.blue }, splitter: { Splitter.horizontal }, secondary: { Color.yellow }) }
-//        )
-//        .frame(width: 400, height: 400)
-//    }
-//}
+struct Split_Previews: PreviewProvider {
+    static var previews: some View {
+        Split(
+            primary: { Color.green },
+            secondary: {
+                Split(
+                    primary: { Color.red },
+                    secondary: {
+                        Split(
+                            primary: { Color.blue },
+                            secondary: { Color.yellow }
+                        )
+                        .layout(LayoutHolder(.horizontal))
+                    }
+                )
+                .layout(LayoutHolder(.vertical))
+            }
+        )
+        .layout(LayoutHolder(.horizontal))
+        
+        Split(
+            primary: {
+                Split(primary: { Color.red }, secondary: { Color.green })
+                    .layout(LayoutHolder(.vertical))
+            },
+            secondary: {
+                Split(primary: { Color.yellow }, secondary: { Color.blue })
+                    .layout(LayoutHolder(.vertical))
+            }
+        )
+        .layout(LayoutHolder(.horizontal))
+    }
+}

Sources/SplitView/Split.swift

@@ -15,13 +15,22 @@ public enum SplitLayout: String, CaseIterable {
 
 /// The two sides of a SplitView.
 ///
-/// For `SplitLayout.Horizontal`, `Primary` is left, `Secondary` is right.
-/// For `SplitLayout.Vertical`, `Primary` is top, `Secondary` is bottom.
-/// Used to identify the side (if any) which is hidden.
+/// Use `isPrimary` and `isSecondary` rather than accessing the cases directly.
+///
+/// For `SplitLayout.horizontal`, `primary` is left, `secondary` is right.
+/// For `SplitLayout.vertical`, `primary` is top, `secondary` is bottom.
+///
+/// For convenience and clarity when creating and constraining an HSplit view, you can use
+/// `left` and `right` instead of `primary` and `secondary`. Similarly you can
+/// use `top` and `bottom` when creating and constraining a VSplit view.
 public enum SplitSide: String {
     case primary
     case secondary
+    case left
+    case right
+    case top
+    case bottom
 
-    var isPrimary: Bool { self == .primary }
-    var isSecondary: Bool { self == .secondary }
+    var isPrimary: Bool { self == .primary || self == .left || self == .top }
+    var isSecondary: Bool { self == .secondary || self == .right || self == .bottom }
 }

Sources/SplitView/SplitEnums.swift

@@ -7,7 +7,7 @@
 
 import Foundation
 
-/// An ObservableObject that `SplitView` observes to change what its `layout` is.
+/// An ObservableObject that `Split` view observes to change what its `layout` is.
 ///
 /// Use the static `usingUserDefaults` method to save state automatically in `UserDefaults.standard`.
 public class LayoutHolder: ObservableObject {
@@ -51,7 +51,7 @@ public class LayoutHolder: ObservableObject {
 
 }
 
-/// An ObservableObject that `SplitView` observes to change what fraction of the width/height the `splitter`
+/// An ObservableObject that `Split` view observes to change what fraction of the width/height the `splitter`
 /// will be positioned at upon open.
 ///
 /// Use the static `usingUserDefaults` method to save state automatically in `UserDefaults.standard`.
@@ -79,7 +79,7 @@ public class FractionHolder: ObservableObject {
     }
 }
 
-/// An ObservableObject that `SplitView` observes to change whether  one of the `SplitSide`s is hidden.
+/// An ObservableObject that `Split` view observes to change whether  one of the `SplitSide`s is hidden.
 ///
 /// Use the static `usingUserDefaults` method to save state automatically in `UserDefaults.standard`.
 public class SideHolder: ObservableObject {

Sources/SplitView/SplitHolders.swift

@@ -77,3 +77,26 @@ public struct Splitter: SplitDivider {
     }
 
 }
+
+struct Splitter_Previews: PreviewProvider {
+    static var previews: some View {
+        Splitter()
+            .environmentObject(LayoutHolder(.horizontal))
+            .environmentObject(SplitStyling())
+        Splitter(color: Color.red, inset: 2, visibleThickness: 8, invisibleThickness: 30)
+            .environmentObject(LayoutHolder(.horizontal))
+            .environmentObject(SplitStyling())
+        Splitter.line()
+            .environmentObject(LayoutHolder(.horizontal))
+            .environmentObject(SplitStyling())
+        Splitter()
+            .environmentObject(LayoutHolder(.vertical))
+            .environmentObject(SplitStyling())
+        Splitter(color: Color.red, inset: 2, visibleThickness: 8, invisibleThickness: 30)
+            .environmentObject(LayoutHolder(.vertical))
+            .environmentObject(SplitStyling())
+        Splitter.line()
+            .environmentObject(LayoutHolder(.vertical))
+            .environmentObject(SplitStyling())
+    }
+}