Skip to content

Commit

Permalink
Merge pull request #726 from kiwicom/697-update-documentation-comments
Browse files Browse the repository at this point in the history 
Update documentation comments
  • Loading branch information
@PavelHolec
PavelHolec authored Dec 4, 2023
2 parents 23064fb + 0053766 commit 70b55f0
Show file tree
Hide file tree
Showing 120 changed files with 2,031 additions and 1,055 deletions.
54 changes: 32 additions & 22 deletions Sources/Orbit/Components/Alert.swift
View file
Original file line number Diff line number Diff line change
@@ -1,38 +1,48 @@
import SwiftUI

/// Breaks the main user flow to present information.
/// Orbit component that breaks the main user flow to present information.
///
/// There are times when just simple information isn’t enough and the user needs
/// to take additional steps to resolve the problem or get additional details.
/// An ``Alert`` consists of a title, description, icon, optional custom content and at most two actions.
///
/// In such cases, provide additional actions for your message.
/// Alerts use special status buttons to match the button color with the alert color.
/// ```swift
/// Alert("Alert") {
/// Button("Primary") { /* Tap action */ }
/// Button("Secondary") { /* Tap action */ }
/// }
/// ```
///
/// ### Customizing appearance
///
/// The title and icon colors can be modified by ``textColor(_:)`` and ``iconColor(_:)`` modifiers.
/// The icon size can be modified by ``iconSize(custom:)`` modifier.
///
/// Use at most two actions in each Alert: one primary and one subtle.
/// A default ``Status/info`` status can be modified by ``status(_:)`` modifier:
///
/// ```swift
/// Alert("Alert", description: "Description") {
/// customContent
/// } buttons: {
/// Button("Primary") { /* */ }
/// Button("Secondary") { /* */ }
/// }
/// .status(.warning)
/// Alert("Alert", description: "Please check your <applink1>visa</applink1>")
/// .status(.warning)
/// ```
///
/// The button priority can be overridden by using `buttonPriority()` modifier.
/// The default button priority can be overridden by ``buttonPriority(_:)`` modifier:
///
/// ```swift
/// Alert("Alert") {
/// customContent
/// content
/// } buttons: {
/// Button("Secondary Only") { /* */ }
/// .buttonPriority(.secondary)
/// Button("Secondary Only") {
/// // Tap action
/// }
/// .buttonPriority(.secondary)
/// }
/// ```
///
/// - Note: [Orbit definition](https://orbit.kiwi/components/alert/)
/// - Important: Component expands horizontally unless prevented by `fixedSize` or `idealSize` modifier.
/// For compact variant, use ``AlertInline`` component.
///
/// ### Layout
///
/// Component expands horizontally unless prevented by native `fixedSize()` or ``idealSize()`` modifier.
///
/// - Note: [Orbit.kiwi documentation](https://orbit.kiwi/components/alert/)
public struct Alert<Content: View, Icon: View, Buttons: View>: View {

private let title: String
Expand All @@ -56,7 +66,7 @@ public struct Alert<Content: View, Icon: View, Buttons: View>: View {

public extension Alert {

/// Creates Orbit Alert component.
/// Creates Orbit ``Alert`` component.
init(
_ title: String = "",
description: String = "",
Expand All @@ -73,7 +83,7 @@ public extension Alert {
}
}

/// Creates Orbit Alert component with no buttons.
/// Creates Orbit ``Alert`` component with no buttons.
init(
_ title: String = "",
description: String = "",
Expand All @@ -89,7 +99,7 @@ public extension Alert {
}
}

/// Creates Orbit Alert component with custom content and icon.
/// Creates Orbit ``Alert`` component with custom content and icon.
init(
_ title: String = "",
description: String = "",
Expand Down
40 changes: 33 additions & 7 deletions Sources/Orbit/Components/AlertInline.swift
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,38 @@
import SwiftUI

/// Breaks the main user flow to present information.
/// Orbit component that breaks the main user flow to present information.
///
/// There are times when just simple information isn’t enough and the user needs
/// to take additional steps to resolve the problem or get additional details.
/// An ``AlertInline`` (an inline variant of ``Alert``) consists of a title, icon and a single action.
///
/// - Note: [Orbit definition](https://orbit.kiwi/components/alert/)
/// - Important: Component expands horizontally unless prevented by `fixedSize` or `idealSize` modifier.
/// ```swift
/// AlertInline("Alert") {
/// Button("Primary") {
/// // Tap action
/// }
/// }
/// ```
///
/// ### Customizing appearance
///
/// The title and icon colors can be modified by ``textColor(_:)`` and ``iconColor(_:)`` modifiers.
/// The icon size can be modified by ``iconSize(custom:)`` modifier.
///
/// A default ``Status/info`` status can be modified by ``status(_:)`` modifier:
///
/// ```swift
/// AlertInline("Alert") {
/// Button("Primary") {
/// // Tap action
/// }
/// }
/// .status(.warning)
/// ```
///
/// ### Layout
///
/// Component expands horizontally unless prevented by native `fixedSize()` or ``idealSize()`` modifier.
///
/// - Note: [Orbit.kiwi documentation](https://orbit.kiwi/components/alert/)
public struct AlertInline<Icon: View, Button: View>: View {

private let title: String
Expand All @@ -28,7 +54,7 @@ public struct AlertInline<Icon: View, Button: View>: View {

public extension AlertInline {

/// Creates Orbit AlertInline component.
/// Creates Orbit ``AlertInline`` component.
init(
_ title: String = "",
icon: Icon.Symbol? = nil,
Expand All @@ -40,7 +66,7 @@ public extension AlertInline {
}
}

/// Creates Orbit AlertInline component with custom content and icon.
/// Creates Orbit ``AlertInline`` component with custom content and icon.
init(
_ title: String = "",
isSubtle: Bool = false,
Expand Down
67 changes: 45 additions & 22 deletions Sources/Orbit/Components/Badge.swift
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,37 @@
import SwiftUI

/// Presents users with short, relevant information.
/// Orbit component that displays non-actionable, short and static information.
///
/// Badges are indicators of static information.
/// They can be updated when a status changes, but they should not be actionable.
/// A ``Badge`` consists of a title and up to two icons.
///
/// - Note: [Orbit definition](https://orbit.kiwi/components/badge/)
/// ```swift
/// Badge("Label", icon: .grid, type: .lightInverted)
/// ```
///
/// ### Customizing appearance
///
/// The label and icon colors can be modified by ``textColor(_:)`` and ``iconColor(_:)`` modifiers.
/// The icon size can be modified by ``iconSize(custom:)`` modifier.
///
/// ```swift
/// Badge("Label", type: .status(nil))
/// .textColor(.inkNormal)
/// .iconColor(.redNormal)
/// .iconSize(.small)
/// ```
///
/// When type is set to ``BadgeType/status(_:inverted:)`` with a `nil` value, the default ``Status/info`` status can be modified by ``status(_:)`` modifier:
///
/// ```swift
/// Badge("Label", type: .status(nil))
/// .status(.warning)
/// ```
///
/// ### Layout
///
/// When the provided content is empty, the component results in `EmptyView` so that it does not take up any space in the layout.
///
/// - Note: [Orbit.kiwi documentation](https://orbit.kiwi/components/badge/)
public struct Badge<LeadingIcon: View, TrailingIcon: View>: View, PotentiallyEmptyView {

@Environment(\.backgroundShape) private var backgroundShape
Expand Down Expand Up @@ -47,19 +73,23 @@ public struct Badge<LeadingIcon: View, TrailingIcon: View>: View, PotentiallyEmp
}
}

@ViewBuilder var resolvedBackground: some View {
@ViewBuilder private var resolvedBackground: some View {
if let backgroundShape {
backgroundShape.inactiveView
} else {
defaultBackgroundColor
}
}

var resolvedLabelColor: Color {
var isEmpty: Bool {
leadingIcon.isEmpty && label.isEmpty && trailingIcon.isEmpty
}

private var resolvedLabelColor: Color {
textColor ?? labelColor
}

var labelColor: Color {
private var labelColor: Color {
switch type {
case .light: return .inkDark
case .lightInverted: return .whiteNormal
Expand All @@ -69,7 +99,7 @@ public struct Badge<LeadingIcon: View, TrailingIcon: View>: View, PotentiallyEmp
}
}

var defaultBackgroundColor: Color {
private var defaultBackgroundColor: Color {
switch type {
case .light: return .whiteDarker
case .lightInverted: return .inkDark
Expand All @@ -79,26 +109,19 @@ public struct Badge<LeadingIcon: View, TrailingIcon: View>: View, PotentiallyEmp
}
}

var minTextWidth: CGFloat {
private var minTextWidth: CGFloat {
Text.Size.small.lineHeight * sizeCategory.ratio - .xSmall
}

var isEmpty: Bool {
leadingIcon.isEmpty && label.isEmpty && trailingIcon.isEmpty
}

var defaultStatus: Status {
private var defaultStatus: Status {
status ?? .info
}
}

// MARK: - Inits
public extension Badge {

/// Creates Orbit Badge component.
///
/// - Parameters:
/// - type: A visual style of component. A `status` style can be optionally modified using `status()` modifier when `nil` value is provided.
/// Creates Orbit ``Badge`` component.
init(
_ label: String = "",
icon: Icon.Symbol? = nil,
Expand All @@ -112,10 +135,7 @@ public extension Badge {
}
}

/// Creates Orbit Badge component with custom icons.
///
/// - Parameters:
/// - style: A visual style of component. A `status` style can be optionally modified using `status()` modifier when `nil` value is provided.
/// Creates Orbit ``Badge`` component with custom icons.
init(
_ label: String = "",
type: BadgeType = .neutral,
Expand All @@ -130,13 +150,16 @@ public extension Badge {
}

// MARK: - Types

/// A type of Orbit ``Badge`` and ``NotificationBadge``.
public enum BadgeType {

case light
case lightInverted
case neutral
case status(_ status: Status? = nil, inverted: Bool = false)

/// An Orbit ``BadgeType`` `status` type with no value provided.
public static var status: Self {
.status(nil)
}
Expand Down
Loading

0 comments on commit 70b55f0

Please sign in to comment.