add docs

Author: mikhailChelbaev

Sources/ComponentsKit/Shared/ComponentColor.swift

@@ -1,14 +1,26 @@
 import Foundation
 
+/// A structure that defines a color set for components.
 public struct ComponentColor: Hashable {
-  // MARK: Properties
+  // MARK: - Properties
 
+  /// The primary color used for the component.
   public let main: UniversalColor
+
+  /// The contrast color, typically used for text or elements displayed on top of the `main` color.
   public let contrast: UniversalColor
+
+  /// The background color for the component.
   public let background: UniversalColor
 
-  // MARK: Initialization
+  // MARK: - Initialization
 
+  /// Initializer.
+  ///
+  /// - Parameters:
+  ///   - main: The primary color for the component.
+  ///   - contrast: The color that contrasts with the `main` color, typically used for text or icons.
+  ///   - background: The background color for the component. Defaults to `main` color with 15% opacity if `nil`.
   public init(
     main: UniversalColor,
     contrast: UniversalColor,

Sources/ComponentsKit/Shared/ComponentSize.swift

@@ -1,7 +1,11 @@
 import Foundation
 
+/// An enumeration that defines size options for a component.
 public enum ComponentSize: Hashable {
+  /// A small-sized component.
   case small
+  /// A medium-sized component.
   case medium
+  /// A large-sized component.
   case large
 }

Sources/ComponentsKit/Shared/UKComponent.swift

@@ -1,9 +1,21 @@
 import UIKit
 
+/// A protocol that defines a UIKit component with a configurable model.
+///
+/// Types conforming to `UKComponent` are responsible for updating their appearance
+/// based on changes to their associated model.
 public protocol UKComponent: UIView {
+  /// A type of the model that defines the appearance properties.
   associatedtype Model
 
+  /// A model that defines the appearance properties.
   var model: Model { get set }
 
+  /// Updates the component when the model changes.
+  ///
+  /// This method is called when the `model` property changes, providing an opportunity
+  /// to compare the new and old models and update the component's appearance.
+  ///
+  /// - Parameter oldModel: The previous model before the update.
   func update(_ oldModel: Model)
 }

Sources/ComponentsKit/Shared/UniversalColor.swift

@@ -1,14 +1,34 @@
 import SwiftUI
 import UIKit
 
+/// A structure that represents an universal color that can be used in both UIKit and SwiftUI,
+/// with light and dark theme variants.
 public struct UniversalColor: Hashable {
-  // MARK: ColorRepresentable
+  // MARK: - ColorRepresentable
 
+  /// An enumeration that defines the possible representations of a color.
   public enum ColorRepresentable: Hashable {
+    /// A color defined by its RGBA components.
+    ///
+    /// - Parameters:
+    ///   - r: The red component (0–255).
+    ///   - g: The green component (0–255).
+    ///   - b: The blue component (0–255).
+    ///   - a: The alpha (opacity) component (0.0–1.0).
     case rgba(r: CGFloat, g: CGFloat, b: CGFloat, a: CGFloat)
+
+    /// A color represented by a `UIColor` instance.
     case uiColor(UIColor)
+
+    /// A color represented by a SwiftUI `Color` instance.
     case color(Color)
 
+    /// Creates a `ColorRepresentable` instance from a hexadecimal string.
+    ///
+    /// - Parameter value: A hex string representing the color (e.g., `"#FFFFFF"` or `"FFFFFF"`).
+    /// - Returns: A `ColorRepresentable` instance with the corresponding RGBA values.
+    /// - Note: This method assumes the input string has exactly six hexadecimal characters.
+    /// - Warning: This method will trigger an assertion failure if the input is invalid.
     public static func hex(_ value: String) -> Self {
       let start: String.Index
       if value.hasPrefix("#") {
@@ -28,10 +48,17 @@ public struct UniversalColor: Hashable {
 
         return .rgba(r: r, g: g, b: b, a: 1.0)
       } else {
-        fatalError("Unable to initialize color from the provided hex value: \(value)")
+        assertionFailure(
+          "Unable to initialize color from the provided hex value: \(value)"
+        )
+        return .rgba(r: 0, g: 0, b: 0, a: 1.0)
       }
     }
 
+    /// Returns a new `ColorRepresentable` with the specified opacity.
+    ///
+    /// - Parameter alpha: The desired opacity (0.0–1.0).
+    /// - Returns: A `ColorRepresentable` instance with the adjusted opacity.
     fileprivate func withOpacity(_ alpha: CGFloat) -> Self {
       switch self {
       case .rgba(let r, let g, let b, _):
@@ -43,6 +70,7 @@ public struct UniversalColor: Hashable {
       }
     }
 
+    /// Converts the `ColorRepresentable` to a `UIColor` instance.
     fileprivate var uiColor: UIColor {
       switch self {
       case .rgba(let red, let green, let blue, let alpha):
@@ -59,6 +87,7 @@ public struct UniversalColor: Hashable {
       }
     }
 
+    /// Converts the `ColorRepresentable` to a SwiftUI `Color` instance.
     fileprivate var color: Color {
       switch self {
       case .rgba(let r, let g, let b, let a):
@@ -76,41 +105,63 @@ public struct UniversalColor: Hashable {
     }
   }
 
-  // MARK: Properties
+  // MARK: - Properties
 
+  /// The color used in light mode.
   let light: ColorRepresentable
+
+  /// The color used in dark mode.
   let dark: ColorRepresentable
 
-  // MARK: Initialization
+  // MARK: - Initialization
 
+  /// Creates a `UniversalColor` with distinct light and dark mode colors.
+  ///
+  /// - Parameters:
+  ///   - light: The color to use in light mode.
+  ///   - dark: The color to use in dark mode.
+  /// - Returns: A new `UniversalColor` instance.
   public static func themed(
     light: ColorRepresentable,
     dark: ColorRepresentable
   ) -> Self {
     return Self(light: light, dark: dark)
   }
 
+  /// Creates a `UniversalColor` with a single color used for both light and dark modes.
+  ///
+  /// - Parameter universal: The universal color to use.
+  /// - Returns: A new `UniversalColor` instance.
   public static func universal(_ universal: ColorRepresentable) -> Self {
     return Self(light: universal, dark: universal)
   }
 
-  // MARK: Methods
+  // MARK: - Methods
 
+  /// Returns a new `UniversalColor` with the specified opacity.
+  ///
+  /// - Parameter alpha: The desired opacity (0.0–1.0).
+  /// - Returns: A new `UniversalColor` instance with the adjusted opacity.
   public func withOpacity(_ alpha: CGFloat) -> Self {
     return .init(
       light: self.light.withOpacity(alpha),
       dark: self.dark.withOpacity(alpha)
     )
   }
 
+  /// Returns a disabled version of the color based on a global opacity configuration.
+  ///
+  /// - Parameter isEnabled: A Boolean value indicating whether the color should be enabled.
+  /// - Returns: A new `UniversalColor` instance with reduced opacity if `isEnabled` is `false`.
   public func enabled(_ isEnabled: Bool) -> Self {
     return isEnabled
     ? self
     : self.withOpacity(ComponentsKitConfig.shared.layout.disabledOpacity)
   }
 
-  // MARK: Colors
+  // MARK: - Colors
 
+  /// Returns the `UIColor` representation of the color, adapting to the current system theme.
   public var uiColor: UIColor {
     return UIColor { trait in
       switch trait.userInterfaceStyle {
@@ -124,6 +175,10 @@ public struct UniversalColor: Hashable {
     }
   }
 
+  /// Returns the `Color` representation of the color for a given SwiftUI `ColorScheme`.
+  ///
+  /// - Parameter colorScheme: The current color scheme (`.light` or `.dark`).
+  /// - Returns: The corresponding `Color` instance.
   public func color(for colorScheme: ColorScheme) -> Color {
     switch colorScheme {
     case .light:

Sources/ComponentsKit/Shared/UniversalFont.swift

@@ -1,35 +1,66 @@
 import SwiftUI
 import UIKit
 
+/// A structure that represents an universal font that can be used in both UIKit and SwiftUI,
+/// with support for custom and system fonts.
 public enum UniversalFont: Hashable {
+  /// An enumeration that defines the weight of a font.
   public enum Weight: Hashable {
+    /// Ultra-light font weight.
     case ultraLight
+    /// Thin font weight.
     case thin
+    /// Light font weight.
     case light
+    /// Regular font weight.
     case regular
+    /// Medium font weight.
     case medium
+    /// Semi-bold font weight.
     case semibold
+    /// Bold font weight.
     case bold
+    /// Heavy font weight.
     case heavy
+    /// Black (extra-bold) font weight.
     case black
   }
+
+  /// A custom font with a specific name and size.
+  ///
+  /// - Parameters:
+  ///   - name: The name of the font.
+  ///   - size: The size of the font.
   case custom(name: String, size: CGFloat)
+
+  /// A system font with a specific size and weight.
+  ///
+  /// - Parameters:
+  ///   - size: The size of the font.
+  ///   - weight: The weight of the font, defined by `UniversalFont.Weight`.
   case system(size: CGFloat, weight: Weight)
 
   // MARK: Fonts
 
+  /// Converts the `UniversalFont` to a `UIFont` instance.
+  ///
+  /// - Returns: A `UIFont` representation of the `UniversalFont`.
   public var uiFont: UIFont {
     switch self {
     case .custom(let name, let size):
       guard let font = UIFont(name: name, size: size) else {
-        fatalError("Unable to initialize font '\(name)'")
+        assertionFailure("Unable to initialize font '\(name)'")
+        return UIFont.systemFont(ofSize: size)
       }
       return font
     case let .system(size, weight):
       return UIFont.systemFont(ofSize: size, weight: weight.uiFontWeight)
     }
   }
 
+  /// Converts the `UniversalFont` to a SwiftUI `Font` instance.
+  ///
+  /// - Returns: A `Font` representation of the `UniversalFont`.
   public var font: Font {
     switch self {
     case .custom(let name, let size):
@@ -41,6 +72,10 @@ public enum UniversalFont: Hashable {
 
   // MARK: Helpers
 
+  /// Returns a new `UniversalFont` with the specified size.
+  ///
+  /// - Parameter size: The new size for the font.
+  /// - Returns: A new `UniversalFont` instance with the updated size.
   public func withSize(_ size: CGFloat) -> Self {
     switch self {
     case .custom(let name, _):
@@ -50,6 +85,10 @@ public enum UniversalFont: Hashable {
     }
   }
 
+  /// Returns a new `UniversalFont` with a size adjusted by a relative value.
+  ///
+  /// - Parameter shift: The amount to adjust the font size by.
+  /// - Returns: A new `UniversalFont` instance with the adjusted size.
   public func withRelativeSize(_ shift: CGFloat) -> Self {
     switch self {
     case .custom(let name, let size):
@@ -63,6 +102,7 @@ public enum UniversalFont: Hashable {
 // MARK: Helpers
 
 extension UniversalFont.Weight {
+  /// Converts `UniversalFont.Weight` to `UIFont.Weight`.
   var uiFontWeight: UIFont.Weight {
     switch self {
     case .ultraLight:
@@ -88,6 +128,7 @@ extension UniversalFont.Weight {
 }
 
 extension UniversalFont.Weight {
+  /// Converts `UniversalFont.Weight` to SwiftUI `Font.Weight`.
   var swiftUIFontWeight: Font.Weight {
     switch self {
     case .ultraLight:
@@ -115,42 +156,54 @@ extension UniversalFont.Weight {
 // MARK: - UniversalFont + Config
 
 extension UniversalFont {
+  /// Small headline font.
   public static var smHeadline: UniversalFont {
     return ComponentsKitConfig.shared.layout.typography.headline.small
   }
+  /// Medium headline font.
   public static var mdHeadline: UniversalFont {
     return ComponentsKitConfig.shared.layout.typography.headline.medium
   }
+  /// Large headline font.
   public static var lgHeadline: UniversalFont {
     return ComponentsKitConfig.shared.layout.typography.headline.large
   }
 
+  /// Small body font.
   public static var smBody: UniversalFont {
     return ComponentsKitConfig.shared.layout.typography.body.small
   }
+  /// Medium body font.
   public static var mdBody: UniversalFont {
     return ComponentsKitConfig.shared.layout.typography.body.medium
   }
+  /// Large body font.
   public static var lgBody: UniversalFont {
     return ComponentsKitConfig.shared.layout.typography.body.large
   }
 
+  /// Small button font.
   public static var smButton: UniversalFont {
     return ComponentsKitConfig.shared.layout.typography.button.small
   }
+  /// Medium button font.
   public static var mdButton: UniversalFont {
     return ComponentsKitConfig.shared.layout.typography.button.medium
   }
+  /// Large button font.
   public static var lgButton: UniversalFont {
     return ComponentsKitConfig.shared.layout.typography.button.large
   }
 
+  /// Small caption font.
   public static var smCaption: UniversalFont {
     return ComponentsKitConfig.shared.layout.typography.caption.small
   }
+  /// Medium caption font.
   public static var mdCaption: UniversalFont {
     return ComponentsKitConfig.shared.layout.typography.caption.medium
   }
+  /// Large caption font.
   public static var lgCaption: UniversalFont {
     return ComponentsKitConfig.shared.layout.typography.caption.large
   }