vakhokontridze / vcomponents

VComponents is a SwiftUI collection that contains reusable UI components

VComponents

Table of Contents

• Description
• Components
• Guidelines: Customization
• Guidelines: Animations
• Installation
• Compatibility
• Contact

Description

VComponents is a SwiftUI collection that contains reusable UI components.

Components

Buttons

State Pickers

Value Pickers

Inputs

Containers

Modals

Notifications

Indicators (Definite)

Indicators (Indefinite)

Misc

Guidelines: Customization

Components from VComponents are not meant to be customized the same way you would customize atomic SwiftUI components.

Rather than directly modifying them using ViewModifierss, you are supposed to pass an UI model as a parameter to the initializers. All components have default UI models and passing them to initializers is not required. Furthermore, all properties within the UI models have their own default values.

For instance, you can change the foreground color of a VPlainButton by changing the values.

Not Preferred:

var body: some View {
    VPlainButton(
        action: doSomething,
        title: "Lorem Ipsum"
    )
    .foregroundStyle(.primary)
}

Preferred:

let uiModel: VPlainButtonUIModel = {
    var uiModel: VPlainButtonUIModel = .init()
    
    uiModel.titleTextColors = VPlainButtonUIModel.StateColors(
        enabled: Color.primary,
        pressed: Color.secondary,
        disabled: Color.secondary
    )
    
    return uiModel
}()

var body: some View {
    VPlainButton(
        uiModel: uiModel,
        action: doSomething,
        title: "Lorem Ipsum"
    )
}

Alternately, you can create static instances of UI models for reusability.

extension VPlainButtonUIModel {
    static let someUIModel: Self = {
        var uiModel: Self = .init()
        
        uiModel.titleTextColors = StateColors(
            enabled: Color.primary,
            pressed: Color.secondary,
            disabled: Color.secondary
        )
        
        return uiModel
    }()
}

var body: some View {
    VPlainButton(
        uiModel: .someUIModel,
        action: doSomething,
        title: "Lorem Ipsum"
    )
}

Frequently, you will discover pre-configured static factory-initialized UI models associated with each component. It's recommended to investigate UI model files before defining them yourself.

var body: some View {
    VWrappingMarquee(
        uiModel: .insettedGradientMask,
        content: {
            HStack(content: {
                Image(systemName: "swift")
                Text("Lorem ipsum dolor sit amet, consectetur adipiscing elit.")
            })
            .drawingGroup() // For `Image`
        }
    )
}

Guidelines: Animations

VComponents associates animations directly with the components and their UI models, rather than with the external state.

@State private var isOn: Bool = false

var body: some View {
    VStack(content: {
        VToggle(isOn: $isOn)
        
        VPlainButton(
            action: { isOn.toggle() },
            title: "Toggle"
        )
    })
}

By default, the VToggle uses an easeIn animation with a duration of 0.1 to handle state changes. This applies uniformly to both touch interactions, as well as any external modifications of the state. So, to modify state with a different animation, you'll need to provide a custom UI model.

@State private var isOn: Bool = false

var body: some View {
    VStack(content: {
        VToggle(
            uiModel: {
                var uiModel: VToggleUIModel = .init()
                uiModel.stateChangeAnimation = .easeIn(duration: 1)
                return uiModel
            }(),
            isOn: $isOn
        )
        
        VPlainButton(
            action: { isOn.toggle() },
            title: "Toggle"
        )
    })
}

There are two available options for completely cancelling animations.

The first is to set stateChangeAnimation to nil. While this does not completely remove animation, it essentially applies a nil animation.

The second is to set appliesStateChangeAnimation to false. This option ensures that the stateChangeAnimation is not applied at all, thus effectively removing any animation tied to state changes, even nil.

@State private var isOn: Bool = false

var body: some View {
    VStack(content: {
        VToggle(
            uiModel: {
                var uiModel: VToggleUIModel = .init()
                uiModel.stateChangeAnimation = nil
                return uiModel
            }(),
            isOn: $isOn
        )
        
        VPlainButton(
            action: { isOn.toggle() },
            title: "Toggle"
        )
    })
}

or

@State private var isOn: Bool = false

var body: some View {
    VStack(content: {
        VToggle(
            uiModel: {
                var uiModel: VToggleUIModel = .init()
                uiModel.appliesStateChangeAnimation = false
                return uiModel
            }(),
            isOn: $isOn
        )
        
        VPlainButton(
            action: { isOn.toggle() },
            title: "Toggle"
        )
    })
}

In certain scenarios, the distinction between these two can be substantial. For example, we could set the appliesStateChangeAnimation flag to false and subsequently mutate the state with an external animation.

@State private var isOn: Bool = false

var body: some View {
    VStack(content: {
        VToggle(
            uiModel: {
                var uiModel: VToggleUIModel = .init()
                uiModel.appliesStateChangeAnimation = false
                return uiModel
            }(),
            isOn: $isOn
        )
        
        VPlainButton(
            action: { 
                withAnimation(.easeInOut(duration: 1), {
                    isOn.toggle()
                })
            },
            title: "Toggle"
        )
    })
}

Installation

Swift Package Manager

Add https://github.com/VakhoKontridze/VComponents as a Swift Package in Xcode and follow the instructions.

Compatibility

Platform and Version Support

Package provides limited macOS, tvOS, watchOS, and visionOS support.

Versions with different majors are not directly compatible. When a new major is released, deprecated symbols are removed.

Versioning

Major. Major changes, such as big overhauls

Minor. Minor changes, such as new component, types, or properties in UI models

Patch. Bug fixes and improvements

History

Ver	Release Date	Swift	SDK	VCore	Comment
6.0	2024 02 18	5.10 (6.0.1 - 6.x.x) 5.9 (6.0.0)	iOS 15.0 macOS 12.0 tvOS 15.0 watchOS 8.0 visionOS 1.0	6.0.0 - 6.x.x	API changes. visionOS support.
5.0	2023 10 08	5.9	iOS 15.0 macOS 12.0 tvOS 15.0 watchOS 8.0	5.0.0 - 5.x.x	New SDK. API changes.
4.0	2023 04 09	5.8	iOS 13.0 macOS 10.15 tvOS 13.0 watchOS 6.0	4.7.0 - 4.x.x	iOS 13.0 support. Multiplatform support. RTL language support.
3.0	2022 10 02	5.7	iOS 16.0	4.1.0 - 4.x.x	New SDK. API changes.
2.0	2022 05 26	5.6	iOS 15.0	3.2.0 - 3.x.x	New SDK. API changes. SPM support.
1.0	2021 02 07	5.3	iOS 14.0	-	-

For additional info, refer to the CHANGELOG.

Contact

e-mail: [email protected]

vcomponents's Issues

View extensions don't change colorscheme automatic

The vAlert and vToast don't respond to theme changes automatically they stay in light mode and won't change self
The colours are set in my Assets file

Example:

extension VAlertUIModel {
    
    public static var error: Self {
        var uiModel: Self = .init()
        
        uiModel.backgroundColor = Color("AlertBGColor", bundle: .none)
        uiModel.titleTextColor = Color("AlertTextColor", bundle: .none)
        uiModel.messageTextColor = Color("AlertTextColor", bundle: .none)
        
        return uiModel
    }
}

Amazing components - TextView Input Field above the Keyboards?

Hi,

Thank you for this amazing implementation of the components, learning so much from it.

I am just woundering if we have a Form with a number of textfields and the last one is a TextView field is there a solution to make sure where any TextField or TextView field scrolls up to be above the keyboard whenever the user starts to ente text?

Thanks.

Wael

Bug When Presenting vAlert in UIHostingViewController

Environment

• VComponents v4.0.4
• Xcode 14.3
• iOS 16.2

Description

I have a UIHostingViewController with a SwiftUI rootView, where the rootView calls .vAlert() and results in the following:

VTextField - onChange handler fired before value is committed

I have a VTextField with an onChange handler where the bound String variable is always one key stroke behind the actual string value. In UIKitTextFieldCoordinator.textFieldDidChange() there's code to commit the text change before the changeHandler is called. However, UIKitTextFieldRepresentable.commitText() is called asynchronously and is executed after the change handler is called.

This code is all running on the main thread so is there a reason to wrap the commitText string assignment in a DispatchQueue.main.async?

If it has to be assigned asynchronously, the changeHandler should be run as a completion handler in the async closure.

Test in terminal keeps failing

Keep getting this error after testing with the terminal

Command: xcodebuild -project test.xcodeproj -scheme test -sdk iphonesimulator -destination 'platform=iOS Simulator,name=iPhone 15 pro,OS=17.2' test | xcbeautify

VComponents 3.2.3 and VCore 4.11.0 not compatible

When I use both versions, I get an error.