From c0236a433cf11ca163e74bf2a67831dc88af7981 Mon Sep 17 00:00:00 2001 From: Matt Bruce Date: Wed, 30 Aug 2023 10:08:28 -0500 Subject: [PATCH] documentation Signed-off-by: Matt Bruce --- .../TileContainer/TileContainer.swift | 20 +++++++++-- VDS/Components/Tilelet/Tilelet.swift | 32 +++++++++++------ .../Tilelet/TileletBadgeModel.swift | 10 ++++++ .../Tilelet/TileletIconModels.swift | 9 +++++ .../Tilelet/TileletSubTitleModel.swift | 11 +++++- .../Tilelet/TileletTitleModel.swift | 9 ++++- VDS/Components/TitleLockup/TitleLockup.swift | 11 ++++++ .../TitleLockup/TitleLockupEyebrowModel.swift | 12 ++++++- .../TitleLockupStyleConfiguration.swift | 34 +++++++++++++++++++ .../TitleLockupSubTitleModel.swift | 11 +++++- .../TitleLockup/TitleLockupTextStyle.swift | 17 ++++------ .../TitleLockup/TitleLockupTitleModel.swift | 9 +++++ 12 files changed, 158 insertions(+), 27 deletions(-) diff --git a/VDS/Components/TileContainer/TileContainer.swift b/VDS/Components/TileContainer/TileContainer.swift index a61be378..bc363df7 100644 --- a/VDS/Components/TileContainer/TileContainer.swift +++ b/VDS/Components/TileContainer/TileContainer.swift @@ -31,6 +31,7 @@ open class TileContainer: Control { //-------------------------------------------------- // MARK: - Enums //-------------------------------------------------- + /// Background color choices used for this component. public enum BackgroundColor: String, CaseIterable { case white case black @@ -38,6 +39,7 @@ open class TileContainer: Control { case transparent } + /// Padding choices used for this component. public enum Padding: String, CaseIterable { case padding2X case padding4X @@ -61,6 +63,7 @@ open class TileContainer: Control { } } + /// Aspect ratios used for this component. public enum AspectRatio: String, CaseIterable { case ratio1x1 = "1:1" case ratio3x4 = "3:4" @@ -86,25 +89,33 @@ open class TileContainer: Control { //-------------------------------------------------- // MARK: - Public Properties //-------------------------------------------------- + /// This takes an image source url and applies it as a background image. open var backgroundImage: UIImage? { didSet{ setNeedsUpdate() } } + /// This is the container in which views will be pinned. open var containerView = View().with { $0.isUserInteractionEnabled = false } + /// This is the view used to show the high light color for a onClick. open var highlightView = View().with { $0.isUserInteractionEnabled = false } + /// This controls the aspect ratio for the component. + open var aspectRatio: AspectRatio = .ratio1x1 { didSet{ setNeedsUpdate() } } + + /// Sets the background color for the component. open var color: BackgroundColor = .white { didSet{ setNeedsUpdate() } } + /// Sets the inside padding for the component open var padding: Padding = .padding4X { didSet{ setNeedsUpdate() } } - - open var aspectRatio: AspectRatio = .ratio1x1 { didSet{ setNeedsUpdate() } } + /// Applies a background color if backgroundImage prop fails or has trouble loading. open var imageFallbackColor: Surface = .light { didSet{ setNeedsUpdate() } } private var _width: CGFloat? + /// Sets the width for the component. Accepts a pixel value. open var width: CGFloat? { get { return _width } set { @@ -118,6 +129,7 @@ open class TileContainer: Control { } private var _height: CGFloat? + /// Sets the height for the component. Accepts a pixel value. open var height: CGFloat? { get { return _height } set { @@ -130,8 +142,10 @@ open class TileContainer: Control { } } + /// If true, a border is rendered around the container. open var showBorder: Bool = false { didSet{ setNeedsUpdate() } } + /// Determines if there is a drop shadow or not. open var showDropShadows: Bool = false { didSet{ setNeedsUpdate() } } //-------------------------------------------------- @@ -273,6 +287,8 @@ open class TileContainer: Control { //-------------------------------------------------- // MARK: - Public Methods //-------------------------------------------------- + + /// This will place a view within the contentView of this component. public func addContentView(_ view: UIView, shouldPin: Bool = true) { containerView.addSubview(view) if shouldPin { diff --git a/VDS/Components/Tilelet/Tilelet.swift b/VDS/Components/Tilelet/Tilelet.swift index e6692a66..e6f85127 100644 --- a/VDS/Components/Tilelet/Tilelet.swift +++ b/VDS/Components/Tilelet/Tilelet.swift @@ -36,11 +36,17 @@ open class Tilelet: TileContainer { //-------------------------------------------------- // MARK: - Enums //-------------------------------------------------- + /// Enum to represent the Vertical Layout of the Text. public enum TextPosition: String, CaseIterable { case top case bottom } + /// Enum to represent the Width of the Text. + public enum TextWidth { + case value(CGFloat) + case percentage(CGFloat) + } //-------------------------------------------------- // MARK: - Private Properties //-------------------------------------------------- @@ -73,6 +79,7 @@ open class Tilelet: TileContainer { } } + /// Title lockup positioned in the contentView. open var titleLockup = TitleLockup().with { $0.standardStyleConfiguration = .init(styleConfigurations: [ .init(deviceType: .iPhone, @@ -120,21 +127,19 @@ open class Tilelet: TileContainer { ]) } + /// Badge positioned in the contentView. open var badge = Badge().with { $0.fillColor = .red } + /// Descriptive Icon positioned in the contentView. open var descriptiveIcon = Icon() + /// Directional Icon positioned in the contentView. open var directionalIcon = Icon().with { $0.name = .rightArrow } - - public enum TextWidth { - case value(CGFloat) - case percentage(CGFloat) - } - + private var _textWidth: TextWidth? /// If provided, width of Button components will be rendered based on this value. If omitted, default button widths are rendered. @@ -159,15 +164,22 @@ open class Tilelet: TileContainer { } } + /// Determines where the text aligns vertically. open var textPostion: TextPosition = .top { didSet { setNeedsUpdate() }} - //models + /// If set, this is used to render the badge. open var badgeModel: BadgeModel? { didSet { setNeedsUpdate() }} + + /// If set, this is used to render the titleLabel of the TitleLockup. open var titleModel: TitleModel? { didSet { setNeedsUpdate() }} + + /// If set, this is used to render the subTitleLabel of the TitleLockup. open var subTitleModel: SubTitleModel? { didSet { setNeedsUpdate() }} //only 1 Icon can be active private var _descriptiveIconModel: DescriptiveIcon? + + /// If set, this is used to render the descriptive icon. open var descriptiveIconModel: DescriptiveIcon? { get { _descriptiveIconModel } set { @@ -178,6 +190,8 @@ open class Tilelet: TileContainer { } private var _directionalIconModel: DirectionalIcon? + + /// If set, this is used to render the directional icon. open var directionalIconModel: DirectionalIcon? { get { _directionalIconModel } set { @@ -185,9 +199,7 @@ open class Tilelet: TileContainer { _descriptiveIconModel = nil setNeedsUpdate() } - } - //icons - + } //-------------------------------------------------- // MARK: - Constraints diff --git a/VDS/Components/Tilelet/TileletBadgeModel.swift b/VDS/Components/Tilelet/TileletBadgeModel.swift index a56d034a..f58c134c 100644 --- a/VDS/Components/Tilelet/TileletBadgeModel.swift +++ b/VDS/Components/Tilelet/TileletBadgeModel.swift @@ -8,12 +8,22 @@ import Foundation extension Tilelet { + + /// Model that represents the options available for the badge. public struct BadgeModel { + /// Text that will be used for the badge. public var text: String = "" + + /// Fill color that will be used for the badge. public var fillColor: Badge.FillColor + /// Current Surface and this is used to pass down to child objects that implement Surfacable public var surface: Surface + + /// Number of lines that will be used for the badge. public var numberOfLines: Int + + /// Max width that will be used for the badge. public var maxWidth: CGFloat? public init(text: String, fillColor: Badge.FillColor = .red, surface: Surface = .light, numberOfLines: Int = 0, maxWidth: CGFloat? = nil) { diff --git a/VDS/Components/Tilelet/TileletIconModels.swift b/VDS/Components/Tilelet/TileletIconModels.swift index eb9e444e..e3a89a5b 100644 --- a/VDS/Components/Tilelet/TileletIconModels.swift +++ b/VDS/Components/Tilelet/TileletIconModels.swift @@ -10,9 +10,14 @@ import UIKit extension Tilelet { + /// Model that represents the options available for the descriptive icon. public struct DescriptiveIcon { + /// A representation that will be used to render the icon with corresponding name. public var name: Icon.Name + + /// Enum for a preset height and width for the icon. public var size: Icon.Size + /// Current Surface and this is used to pass down to child objects that implement Surfacable public var surface: Surface @@ -23,8 +28,12 @@ extension Tilelet { } } + /// Model that represents the options available for the directional icon. public struct DirectionalIcon { + /// Enum for a preset height and width for the icon. public var size: Icon.Size + + /// Current Surface and this is used to pass down to child objects that implement Surfacable public var surface: Surface public init(size: Icon.Size = .medium, surface: Surface = .dark) { diff --git a/VDS/Components/Tilelet/TileletSubTitleModel.swift b/VDS/Components/Tilelet/TileletSubTitleModel.swift index 2a2c7c6f..cb2b34bb 100644 --- a/VDS/Components/Tilelet/TileletSubTitleModel.swift +++ b/VDS/Components/Tilelet/TileletSubTitleModel.swift @@ -8,10 +8,12 @@ import Foundation extension Tilelet { + /// Model that represents the options available for the sub title label. public struct SubTitleModel { //-------------------------------------------------- // MARK: - Enums //-------------------------------------------------- + /// Enum for the textStyle of the subTitle label. public enum StandardStyle: String, EnumSubset { case bodyLarge case bodyMedium @@ -22,10 +24,16 @@ extension Tilelet { //-------------------------------------------------- // MARK: - Public Properties //-------------------------------------------------- + /// Text that will be used for the subTitle label. public var text: String = "" + + /// Text style that will be used for the subTitle label. public var standardStyle: StandardStyle = .bodySmall - /// Array of LabelAttributeModel objects used in rendering the text. + + /// Text attributes that will be used for the subTitle label. public var textAttributes: [any LabelAttributeModel]? + + /// Text color that will be used for the subTitle label. public var textColor: Use = .primary //-------------------------------------------------- @@ -44,6 +52,7 @@ extension Tilelet { //-------------------------------------------------- // MARK: - Public Methods //-------------------------------------------------- + /// Converts this type of model to a TitleLockup.SubTitleModel. public func toTitleLockupSubTitleModel() -> TitleLockup.SubTitleModel { TitleLockup.SubTitleModel(text: text, standardStyle: standardStyle.value, diff --git a/VDS/Components/Tilelet/TileletTitleModel.swift b/VDS/Components/Tilelet/TileletTitleModel.swift index 84e77529..728de07b 100644 --- a/VDS/Components/Tilelet/TileletTitleModel.swift +++ b/VDS/Components/Tilelet/TileletTitleModel.swift @@ -8,10 +8,12 @@ import Foundation extension Tilelet { + /// Model that represents the options available for the title label. public struct TitleModel { //-------------------------------------------------- // MARK: - Enums //-------------------------------------------------- + /// Enum for the textStyle of the title label. public enum StandardStyle: String, EnumSubset { case titleXLarge case titleLarge @@ -23,9 +25,13 @@ extension Tilelet { //-------------------------------------------------- // MARK: - Public Properties //-------------------------------------------------- + /// Text that will be used for the title label. public var text: String = "" - /// Array of LabelAttributeModel objects used in rendering the text. + + /// Text attributes that will be used for the title label. public var textAttributes: [any LabelAttributeModel]? + + /// Text style that will be used for the title label. public var standardStyle: StandardStyle = .titleSmall //-------------------------------------------------- @@ -42,6 +48,7 @@ extension Tilelet { //-------------------------------------------------- // MARK: - Public Methods //-------------------------------------------------- + /// Converts this type of model to a TitleLockup.TitleModel. public func toTitleLockupTitleModel() -> TitleLockup.TitleModel { TitleLockup.TitleModel(text: text, textAttributes: textAttributes, diff --git a/VDS/Components/TitleLockup/TitleLockup.swift b/VDS/Components/TitleLockup/TitleLockup.swift index 7ddd43ef..4f727678 100644 --- a/VDS/Components/TitleLockup/TitleLockup.swift +++ b/VDS/Components/TitleLockup/TitleLockup.swift @@ -66,30 +66,41 @@ open class TitleLockup: View { //-------------------------------------------------- // MARK: - Public Properties //-------------------------------------------------- + /// Aligns TitleLockup's subcomponent's text open var textPosition: TextPosition = .left { didSet { setNeedsUpdate() }} //first row + /// Label used to render the eyebrow model. open var eyebrowLabel = Label().with { $0.setContentCompressionResistancePriority(.required, for: .vertical) } + + /// Model used in rendering the eyebrow label. open var eyebrowModel: EyebrowModel? { didSet { setNeedsUpdate() }} //second row + /// Label used to render the title model. open var titleLabel = Label().with { $0.setContentCompressionResistancePriority(.required, for: .vertical) } + + /// Model used in rendering the title label. open var titleModel: TitleModel? { didSet { setNeedsUpdate() }} //third row + /// Label used to render the subtitle model. open var subTitleLabel = Label().with { $0.setContentCompressionResistancePriority(.required, for: .vertical) } + + /// Model used in rendering the subtitle label. open var subTitleModel: SubTitleModel? { didSet { setNeedsUpdate() }} //-------------------------------------------------- // MARK: - Configuration Properties //-------------------------------------------------- // Sizes are from InVision design specs. + /// Configuration that will set the spacing between labels based off their textStyles. open var standardStyleConfiguration: StandardStyleConfigurationProvider = StandardStyleConfigurationProvider(styleConfigurations: [ .init(deviceType: .iPad, diff --git a/VDS/Components/TitleLockup/TitleLockupEyebrowModel.swift b/VDS/Components/TitleLockup/TitleLockupEyebrowModel.swift index 4f92ca7e..28305bfd 100644 --- a/VDS/Components/TitleLockup/TitleLockupEyebrowModel.swift +++ b/VDS/Components/TitleLockup/TitleLockupEyebrowModel.swift @@ -8,12 +8,21 @@ import Foundation extension TitleLockup { + /// Model that represents the options available for the eyebrow label. public struct EyebrowModel { + /// Text that will be used for the eyebrow label. public var text: String + + /// Used in combination with standardStyle to set the textStyle that will be used for the eyebrow label. public var isBold: Bool - /// Array of LabelAttributeModel objects used in rendering the text. + + /// Array of LabelAttributeModel objects used in rendering the text in the eyebrow label. public var textAttributes: [any LabelAttributeModel]? + + /// Standard style that will be used for the eyebrow label. public var standardStyle: OtherStandardStyle + + /// Number of lines that will be used for the eyebrow label. public var numberOfLines: Int public init(text: String, @@ -28,6 +37,7 @@ extension TitleLockup { self.numberOfLines = numberOfLines } + /// Text style that will be used for the eyebrow label. public var textStyle: TextStyle { isBold ? standardStyle.value.bold : standardStyle.value.regular } } } diff --git a/VDS/Components/TitleLockup/TitleLockupStyleConfiguration.swift b/VDS/Components/TitleLockup/TitleLockupStyleConfiguration.swift index 7940d91a..4ab8bb99 100644 --- a/VDS/Components/TitleLockup/TitleLockupStyleConfiguration.swift +++ b/VDS/Components/TitleLockup/TitleLockupStyleConfiguration.swift @@ -10,36 +10,59 @@ import UIKit extension TitleLockup { + /// Configuration that will set the spacing between labels based off their textStyles. public struct StandardStyleConfigurationProvider { + /// Array of standard style configurations. public var styleConfigurations: [StandardStyleConfiguration] public init(styleConfigurations: [StandardStyleConfiguration]) { self.styleConfigurations = styleConfigurations } + + /// Will find a standard style configuration for the title standard style against the running device type. + /// - titleStandardStyle: title standard style + /// - Returns: Standard Style configuration that matches public func configuration(for titleStandardStyle: TitleStandardStyle) -> StandardStyleConfiguration? { let deviceType: StandardStyleConfiguration.DeviceType = UIDevice.isIPad ? .iPad : .iPhone guard let config: StandardStyleConfiguration = styleConfigurations.first(where: { return titleStandardStyle.isWithin($0.titleStandardStyles) && ($0.deviceType == deviceType || $0.deviceType == .all )}) else { return nil } return config } + /// Determines if there is a configuration for this title style as well as a matching spacing configuration against the other standard style. + /// - Parameters: + /// - otherStandardStyle: other standard style + /// - titleStandardStyle: title standard style + /// - Returns: Whether or not there is a public func isValid(otherStandardStyle: OtherStandardStyle, for titleStandardStyle: TitleStandardStyle) -> Bool { guard let config = configuration(for: titleStandardStyle) else { return false } return otherStandardStyle.isWithin(config.spacingConfigurations.flatMap {$0.otherStandardStyles}) } + /// Will find the spacing for a specific title standard style against a other standard style. If one isn't found a default spacing is returned. + /// - Parameters: + /// - titleStandardStyle: title standard style + /// - otherStandardStyle: other standard style + /// - Returns: Tuple of the standard style as well as the top and bottom spacing. public func spacing(for titleStandardStyle: TitleStandardStyle, otherStandardStyle: OtherStandardStyle) -> (otherStandardStyle: OtherStandardStyle, topSpacing: CGFloat, bottomSpacing: CGFloat)? { guard let config = configuration(for: titleStandardStyle) else { return nil } return config.styleSpacing(for: otherStandardStyle) } } + /// Configuration that will set the spacing between labels based off the device type and their textStyles. public struct StandardStyleConfiguration { + /// Enum for the devices for this configuration. public enum DeviceType { case iPhone, iPad, all } + /// Device type for this configuration. public var deviceType: DeviceType + + /// Array of title standard styles, first style is always the default. public var titleStandardStyles:[TitleStandardStyle] + + /// Array of spacing configurations for spacing. public var spacingConfigurations: [SpacingConfiguration] public init(deviceType: DeviceType, titleStandardStyles: [TitleStandardStyle], spacingConfigurations: [SpacingConfiguration]) { @@ -48,10 +71,15 @@ extension TitleLockup { self.spacingConfigurations = spacingConfigurations } + /// Flattend array of all spacingConfigurations array of other standard styles. public var allOtherStandardStyles: [OtherStandardStyle] { spacingConfigurations.flatMap {$0.otherStandardStyles} } + + /// Takes a other standard style and will either find the spacing configuration that matches or returns a default top and bottom spacing. + /// - Parameter otherStandardStyle: other standard style you need to find the configuration for top and bottom spacing + /// - Returns: Tuple of the other standard style passed in and the configuration for top and bottom spacing. public func styleSpacing(for otherStandardStyle: OtherStandardStyle) -> (otherStandardStyle: OtherStandardStyle, topSpacing: CGFloat, bottomSpacing: CGFloat) { //set default return other style what you pass in var realOtherStyle = otherStandardStyle @@ -71,9 +99,15 @@ extension TitleLockup { } } + /// Configuration to define spacing for an array of standard styles. public struct SpacingConfiguration { + /// Array of other standard styles public var otherStandardStyles: [OtherStandardStyle] + + /// Configuration of topSpacing for the other standard styles public var topSpacing: CGFloat + + /// Configuration of bottomSpacing for the other standard styles public var bottomSpacing: CGFloat public init(otherStandardStyles: [OtherStandardStyle], topSpacing: CGFloat, bottomSpacing: CGFloat) { diff --git a/VDS/Components/TitleLockup/TitleLockupSubTitleModel.swift b/VDS/Components/TitleLockup/TitleLockupSubTitleModel.swift index 7bea3a3c..3ba6c7ff 100644 --- a/VDS/Components/TitleLockup/TitleLockupSubTitleModel.swift +++ b/VDS/Components/TitleLockup/TitleLockupSubTitleModel.swift @@ -8,12 +8,21 @@ import Foundation extension TitleLockup { + /// Model that represents the options available for the sub title label. public struct SubTitleModel { + /// Text that will be used for the subTitle label. public var text: String + + /// Standard style that will be used for the subTitle label. public var standardStyle: OtherStandardStyle + + /// Text color used in the subtitle label. public var textColor: Use - /// Array of LabelAttributeModel objects used in rendering the text. + + /// Array of LabelAttributeModel objects used in rendering the text in the subtitle label. public var textAttributes: [any LabelAttributeModel]? + + /// Number of lines used in the subtitle label. public var numberOfLines: Int public init(text: String, diff --git a/VDS/Components/TitleLockup/TitleLockupTextStyle.swift b/VDS/Components/TitleLockup/TitleLockupTextStyle.swift index 0b5c7875..4c4c48a9 100644 --- a/VDS/Components/TitleLockup/TitleLockupTextStyle.swift +++ b/VDS/Components/TitleLockup/TitleLockupTextStyle.swift @@ -11,7 +11,8 @@ extension TitleLockup { //-------------------------------------------------- // MARK: - Enums //-------------------------------------------------- - public enum TitleStandardStyle: String, CaseIterable { + /// Enum that represents the textStyle avaiable for the title label. + public enum TitleStandardStyle: String, EnumSubset { case featureMedium case featureSmall @@ -28,14 +29,11 @@ extension TitleLockup { case bodySmall public var defaultValue: TextStyle.StandardStyle {.featureXSmall } - - public var value: TextStyle.StandardStyle { - TextStyle.StandardStyle(rawValue: self.rawValue) ?? defaultValue - } - + } - public enum OtherStandardStyle: String, CaseIterable { + /// Enum that represents the textStyle avaiable for the eyebrow and subtitle label. + public enum OtherStandardStyle: String, EnumSubset { case bodySmall case bodyMedium case bodyLarge @@ -45,9 +43,6 @@ extension TitleLockup { case titleXLarge public var defaultValue: TextStyle.StandardStyle { .bodyLarge } - - public var value: TextStyle.StandardStyle { - TextStyle.StandardStyle(rawValue: self.rawValue) ?? defaultValue - } + } } diff --git a/VDS/Components/TitleLockup/TitleLockupTitleModel.swift b/VDS/Components/TitleLockup/TitleLockupTitleModel.swift index fc1660b2..2b957276 100644 --- a/VDS/Components/TitleLockup/TitleLockupTitleModel.swift +++ b/VDS/Components/TitleLockup/TitleLockupTitleModel.swift @@ -8,12 +8,21 @@ import Foundation extension TitleLockup { + /// Model that represents the options available for the sub title label. public struct TitleModel { + /// Text that will be used for the title label. public var text: String + /// Array of LabelAttributeModel objects used in rendering the text. public var textAttributes: [any LabelAttributeModel]? + + /// Used in combination with standardStyle to set the textStyle that will be used for the title label. public var isBold: Bool + + /// Text style that will be used for the title label. public var standardStyle: TitleStandardStyle + + /// Number of lines that will be used for the title label. public var numberOfLines: Int public init(text: String,