documentation

Sources/LCEssentials/SwiftUI/LCENavigationView.swift

@@ -1,4 +1,4 @@
-//  
+//
 // Copyright (c) 2024 Loverde Co.
 //
 // Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -21,28 +21,49 @@
 #if canImport(SwiftUI)
 import SwiftUI
 
+/// `LCENavigationState` is an `ObservableObject` that manages the state for `LCENavigationView`.
+/// It includes published properties for managing button images, text, actions,
+/// navigation bar visibility, and title/subtitle views.
 @available(iOS 15, *)
 class LCENavigationState: ObservableObject {
+    /// The image view for the right button.
     @Published var rightButtonImage: AnyView? = nil
+    /// The text for the right button.
     @Published var rightButtonText: Text = Text("")
+    /// The action to perform when the right button is tapped.
     @Published var rightButtonAction: () -> Void = {}
     
+    /// The image view for the left button.
     @Published var leftButtonImage: AnyView? = nil
+    /// The text for the left button.
     @Published var leftButtonText: Text = Text("")
+    /// The action to perform when the left button is tapped.
     @Published var leftButtonAction: () -> Void = {}
     
+    /// A boolean value that controls the visibility of the navigation bar.
     @Published var hideNavigationBar: Bool = false
     
+    /// The title view of the navigation bar.
     @Published var title: (any View) = Text("")
+    /// The subtitle view of the navigation bar.
     @Published var subTitle: (any View) = Text("")
 }
 
+/// `LCENavigationView` is a SwiftUI `View` that provides a customizable navigation bar.
+/// It allows setting left and right buttons, a title, and a subtitle.
 @available(iOS 15, *)
 public struct LCENavigationView<Content: View>: View {
+    /// The observed state object for the navigation view.
     @ObservedObject private var state: LCENavigationState
     
+    /// The content view displayed below the navigation bar.
     let content: Content
     
+    /// Initializes a new `LCENavigationView` instance.
+    /// - Parameters:
+    ///   - title: The title view for the navigation bar. Defaults to an empty `Text`.
+    ///   - subTitle: The subtitle view for the navigation bar. Defaults to an empty `Text`.
+    ///   - content: A `ViewBuilder` that provides the content to be displayed below the navigation bar.
     public init(
         title: (any View) = Text(""),
         subTitle: (any View) = Text(""),
@@ -56,6 +77,7 @@ public struct LCENavigationView<Content: View>: View {
         self.state.subTitle = subTitle
     }
     
+    /// The body of the `LCENavigationView`.
     public var body: some View {
         VStack {
             if !state.hideNavigationBar {
@@ -66,6 +88,7 @@ public struct LCENavigationView<Content: View>: View {
         .navigationBarHidden(true)
     }
 
+    /// The private `NavigationBarView` that lays out the navigation bar components.
     private var NavigationBarView: some View {
         HStack {
             NavLeftButton
@@ -81,6 +104,7 @@ public struct LCENavigationView<Content: View>: View {
         }
     }
     
+    /// The private `TitleView` that displays the title and subtitle.
     private var TitleView: some View {
         VStack {
             AnyView(state.title)
@@ -90,6 +114,7 @@ public struct LCENavigationView<Content: View>: View {
         }
     }
     
+    /// The private `NavLeftButton` view.
     private var NavLeftButton: some View {
         Button(action: state.leftButtonAction) {
             HStack {
@@ -101,6 +126,7 @@ public struct LCENavigationView<Content: View>: View {
         }
     }
     
+    /// The private `NavRightButton` view.
     private var NavRightButton: some View {
         Button(action: state.rightButtonAction) {
             HStack {
@@ -112,6 +138,12 @@ public struct LCENavigationView<Content: View>: View {
         }
     }
     
+    /// Sets the configuration for the right button of the navigation bar.
+    /// - Parameters:
+    ///   - text: The `Text` to display on the button. Defaults to an empty `Text`.
+    ///   - image: An optional `View` to use as the button's icon. Defaults to `nil`.
+    ///   - action: The closure to execute when the button is tapped.
+    /// - Returns: The `LCENavigationView` instance for chaining.
     public func setRightButton(
         text: Text = Text(""),
         image: (any View)? = nil,
@@ -135,6 +167,12 @@ public struct LCENavigationView<Content: View>: View {
         return self
     }
     
+    /// Sets the configuration for the left button of the navigation bar.
+    /// - Parameters:
+    ///   - text: The `Text` to display on the button. Defaults to an empty `Text`.
+    ///   - image: An optional `View` to use as the button's icon. Defaults to `nil`.
+    ///   - action: The closure to execute when the button is tapped.
+    /// - Returns: The `LCENavigationView` instance for chaining.
     public func setLeftButton(
         text: Text = Text(""),
         image: (any View)? = nil,
@@ -158,6 +196,11 @@ public struct LCENavigationView<Content: View>: View {
         return self
     }
     
+    /// Sets the title and optional subtitle for the navigation bar.
+    /// - Parameters:
+    ///   - text: The `View` to use as the main title. Defaults to an empty `Text`.
+    ///   - subTitle: An optional `View` to use as the subtitle. Defaults to `nil`.
+    /// - Returns: The `LCENavigationView` instance for chaining.
     public func setTitle(
         text: (any View) = Text(""),
         subTitle: (any View)? = nil
@@ -167,14 +210,21 @@ public struct LCENavigationView<Content: View>: View {
         return self
     }
     
+    /// Controls the visibility of the navigation bar.
+    /// - Parameter hide: A boolean value indicating whether to hide (`true`) or show (`false`) the navigation bar.
+    /// - Returns: The `LCENavigationView` instance for chaining.
     public func hideNavigationView(_ hide: Bool) -> LCENavigationView {
         state.hideNavigationBar = hide
         return self
     }
 }
 
+/// Extension to `FormatStyle` to format any value as a string.
 @available(iOS 15.0, *)
 extension FormatStyle {
+    /// Formats an input value if it matches the `FormatInput` type.
+    /// - Parameter value: The value to format as `Any`.
+    /// - Returns: The formatted output, or `nil` if the value type does not match.
     func format(any value: Any) -> FormatOutput? {
         if let v = value as? FormatInput {
             return format(v)
@@ -183,8 +233,11 @@ extension FormatStyle {
     }
 }
 
+/// Extension to `LocalizedStringKey` to resolve localized strings.
 @available(iOS 15.0, *)
 extension LocalizedStringKey {
+    /// Resolves the localized string key into a `String`.
+    /// - Returns: The resolved string, or `nil` if resolution fails.
     var resolved: String? {
         let mirror = Mirror(reflecting: self)
         guard let key = mirror.descendant("key") as? String else {
@@ -237,8 +290,11 @@ extension LocalizedStringKey {
     }
 }
 
+/// Extension to `Text` to retrieve its string content.
 @available(iOS 15.0, *)
 extension Text {
+    /// Returns the string representation of the `Text` view.
+    /// - Returns: The string content, or `nil` if it cannot be extracted.
     var string: String? {
         let mirror = Mirror(reflecting: self)
         if let s = mirror.descendant("storage", "verbatim") as? String {