diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..37cf455 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2022 Twelve Products LLC + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/Package.resolved b/Package.resolved new file mode 100644 index 0000000..a918e2b --- /dev/null +++ b/Package.resolved @@ -0,0 +1,16 @@ +{ + "object": { + "pins": [ + { + "package": "SwiftFoundationExtensions", + "repositoryURL": "https://github.com/xiiagency/SwiftFoundationExtensions", + "state": { + "branch": null, + "revision": "7c821dc666239bcf956d5b91a2610db61d8b5fdf", + "version": "1.0.0" + } + } + ] + }, + "version": 1 +} diff --git a/Package.swift b/Package.swift index 4052cbb..090efa1 100644 --- a/Package.swift +++ b/Package.swift @@ -19,7 +19,7 @@ let package = .package( name: "SwiftFoundationExtensions", url: "https://github.com/xiiagency/SwiftFoundationExtensions", - .branchItem("main") + .upToNextMinor(from: "1.0.0") ), ], targets: [ @@ -29,10 +29,5 @@ let package = "SwiftFoundationExtensions" ] ), - // NOTE: Re-enable when tests are added. -// .testTarget( -// name: "SwiftUIHapticsTests", -// dependencies: ["SwiftUIHaptics"] -// ), ] ) diff --git a/README.md b/README.md index adf88c2..8f4b3dc 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,211 @@ -# SwiftUIHaptics +# SwiftUIHaptics Library -Provides a common service to use in projects that require haptics feedback. +[![GitHub](https://img.shields.io/github/license/xiiagency/SwiftUIHaptics?style=for-the-badge)](./LICENSE) + +An open source library that provides a common service to use in projects that require haptics feedback. + +Developed as re-usable components for various projects at +[XII's](https://github.com/xiiagency) iOS, macOS, and watchOS applications. + +## Installation + +### Swift Package Manager + +1. In Xcode, select File > Swift Packages > Add Package Dependency. +2. Follow the prompts using the URL for this repository +3. Select the `SwiftUIHaptics` library to add to your project + +## Dependencies + +- [xiiagency/SwiftFoundationExtensions](https://github.com/xiiagency/SwiftFoundationExtensions) + +## License + +See the [LICENSE](LICENSE) file. + +## Supported Platforms + +This library is compatible with the iOS, watchOS, and macOS platforms. On iOS/watchOS the haptics engine is used to play various haptic events. However, on macOS all events are simply skipped. MacOS support is provided simply to allow the same piece of SwiftUI code to interact with the haptics service, without having to "gate" its logic using an OS check. + +## Defining haptic events ([Source](Sources/SwiftUIHaptics/HapticEvent.swift)) + +```Swift +struct HapticEvent { + let underlyingEvents: [CHHapticEvent] +} +``` + +A struct containing a series of `CHHapticEvent`s to be played via the `HapticsService`. + +## Creating haptic events ([Source](Sources/SwiftUIHaptics/HapticEvent.swift)) + +### Single events + +```Swift +extension HapticEvent { + static func single( + intensity: Float? = nil, + sharpness: Float? = nil, + attack: Float? = nil, + decay: Float? = nil, + release: Float? = nil, + sustained: Float? = nil, + relativeTime: TimeInterval = 0.0, + duration: TimeInterval = 0.0 + ) -> HapticEvent +} +``` + +Creates a single `HapticEvent`, with the ability to specify all the parameters and defaulting others. + +### Patterns + +```Swift +extension HapticEvent { + static func pattern(events: [HapticEvent]) -> HapticEvent + + static func pattern(_ events: HapticEvent...) -> HapticEvent +} +``` + +Creates a pattern of haptic events by combining all underlying events for the provided `HapticEvent` instances. + +### From an existing `HapticEvent` + +``` Swift +extension HapticEvent { + func timeShifted( + relativeTime: TimeInterval, + duration: TimeInterval + ) -> HapticEvent +} +``` + +Returns a time shifted `HapticEvent` with the provided relative time and play duration specified. + +## `HapticsService` ([Source](Sources/SwiftUIHaptics/HapticsService.swift)) + +```Swift +class HapticsService : ObservableObject { + var isAvailable: Bool { get } + + init() + + func play(event: HapticEvent) { +} +``` + +## Usage Example + +### Define your events + +```Swift +extension HapticEvent { + static let strong: HapticEvent = + .single(intensity: 0.75, sharpness: 0.75, decay: -0.5) + + static let normal: HapticEvent = + .single(intensity: 0.5, sharpness: 0.5, decay: -0.5) + + static let ripPattern: HapticEvent = .pattern( + events: (0..<12).map { index in + HapticEvent.normal + .timeShifted( + relativeTime: Double(index) * 0.025, + duration: 0.1 + ) + } + ) +} +``` + +### Wire up the `HapticsService` + +```Swift +import SwiftUI +import SwiftUIHaptics + +@main +struct FooApplication : App { + @StateObject private var hapticsService = HapticsService() + + var body: some Scene { + WindowGroup { + ContentView() + .environmentObject(hapticsService) + } + } +} +``` + +### Fire events in your `View`s + +```Swift +struct ContentView : View { + @EnvironmentObject private var hapticsService: HapticsService + + var body: some View { + VStack { + Spacer() + + Button("Normal") { + hapticsService.play(event: .normal) + } + .buttonStyle(BorderedButtonStyle()) + .padding(20) + + Button("Strong") { + hapticsService.play(event: .strong) + } + .buttonStyle(BorderedButtonStyle()) + .padding(20) + + Button("Rip!!!") { + hapticsService.play(event: .ripPattern) + } + .buttonStyle(BorderedButtonStyle()) + .padding(20) + + Spacer() + } + } +} +``` + + + +### Supporting mocking + +Mocking of the service can be useful in previews as well as other applications. The `HapticsService` is shipped with mocking support that can be used in debug builds as follows: + +```Swift +#if DEBUG +struct ContentView_Previews : PreviewProvider { + static var previews: some View { + PreviewView() + } +} + +struct PreviewView : View { + @StateObject private var mockHapticsService = MockHapticsService() + + @State private var eventsPlayed: Int = 0 + + var body: some View { + VStack { + Text("# of events played: \(eventsPlayed)") + + ContentView() + .environmentObject(mockHapticsService as HapticsService) + } + .onAppear { + mockHapticsService.playCallback = { _ in + eventsPlayed += 1 + } + } + } +} +#endif +``` + + \ No newline at end of file diff --git a/images/mocking-example-1.png b/images/mocking-example-1.png new file mode 100644 index 0000000..304f07e Binary files /dev/null and b/images/mocking-example-1.png differ diff --git a/images/usage-example-1.png b/images/usage-example-1.png new file mode 100644 index 0000000..56d6dea Binary files /dev/null and b/images/usage-example-1.png differ