WhatsNewKit

https://github.com/sventiigi/whatsnewkit
Admin
WhatsNewKit is a Swift Package designed to easily showcase new app features, offering full...
Tokens:3,212
Snippets:21
Trust Score:8.5
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Configure WhatsNewEnvironment in App Entry Point

Source: https://github.com/sventiigi/whatsnewkit/blob/main/README.md

This example shows how to configure the `WhatsNewEnvironment` within the main App struct. It sets up the `versionStore` (defaulting to `UserDefaultsWhatsNewVersionStore`) and provides the `whatsNewCollection` by conforming the App to `WhatsNewCollectionProvider`.

```swift
extension App: SwiftUI.App {

    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(
                    \WhatsNew.whatsNew,
                    WhatsNewEnvironment(
                        // Specify in which way the presented WhatsNew Versions are stored.
                        // In default the `UserDefaultsWhatsNewVersionStore` is used.
                        versionStore: UserDefaultsWhatsNewVersionStore(),
                        // Pass a `WhatsNewCollectionProvider` or an array of WhatsNew instances
                        whatsNewCollection: self
                    )
                )
        }
    }

}

// MARK: - App+WhatsNewCollectionProvider

extension App: WhatsNewCollectionProvider {

    /// Declare your WhatsNew instances per version
    var whatsNewCollection: WhatsNewCollection {
        WhatsNew(
            version: "1.0.0",
            // ...
        )
        WhatsNew(
            version: "1.1.0",
            // ...
        )
        WhatsNew(
            version: "1.2.0",
            // ...
        )
    }

}
```

--------------------------------

### Swift: WhatsNew.SecondaryAction Examples

Source: https://github.com/sventiigi/whatsnewkit/blob/main/README.md

Demonstrates creating secondary actions for WhatsNew, including presenting a view, opening a URL, and custom actions. These actions provide additional interactivity alongside the primary action.

```swift
let secondaryActionPresentAboutView = WhatsNew.SecondaryAction(
    title: "Learn more",
    foregroundColor: .blue,
    hapticFeedback: .selection,
    action: .present {
        AboutView()
    }
)

let secondaryActionOpenURL = WhatsNew.SecondaryAction(
    title: "Read more",
    foregroundColor: .blue,
    hapticFeedback: .selection,
    action: .open(
        url: .init(string: "https://github.com/SvenTiigi/WhatsNewKit")
    )
)

let secondaryActionCustom = WhatsNew.SecondaryAction(
    title: "Custom",
    action: .custom { presentationMode in
        // ...
    }
)
```

--------------------------------

### WhatsNewVersionStore Implementations

Source: https://github.com/sventiigi/whatsnewkit/blob/main/README.md

Provides examples of initializing the three predefined implementations of `WhatsNewVersionStore`: `UserDefaultsWhatsNewVersionStore`, `NSUbiquitousKeyValueWhatsNewVersionStore`, and `InMemoryWhatsNewVersionStore`. These implementations cater to different storage needs, from local persistence to in-memory storage for testing.

```swift
// Persists presented versions in the UserDefaults
let userDefaultsWhatsNewVersionStore = UserDefaultsWhatsNewVersionStore()

// Persists presented versions in iCloud using the NSUbiquitousKeyValueStore
let ubiquitousKeyValueWhatsNewVersionStore = NSUbiquitousKeyValueWhatsNewVersionStore()

// Stores presented versions in memory. Perfect for testing purposes
let inMemoryWhatsNewVersionStore = InMemoryWhatsNewVersionStore()
```

--------------------------------

### WhatsNew.Title Initialization

Source: https://github.com/sventiigi/whatsnewkit/blob/main/README.md

Demonstrates how to initialize `WhatsNew.Title` for displaying text at the top of the new feature announcement. Examples cover initialization with a simple string, a string with a specified foreground color, and using Markdown for styled text on iOS 15 and later.

```swift
// Initialize by string literal
let title: WhatsNew.Title = "Continue"

// Initialize with text and foreground color
let title = WhatsNew.Title(
    text: "Continue",
    foregroundColor: .primary
)

// On >= iOS 15 initialize with AttributedString using Markdown
let title = WhatsNew.Title(
    text: try AttributedString(
        markdown: "What's **New**"
    )
)
```

--------------------------------

### Swift: Sheet Layout with Footer Action Spacing

Source: https://github.com/sventiigi/whatsnewkit/blob/main/README.md

Provides an example of applying a custom layout, specifically for footer action spacing, when presenting a modal sheet using the `.sheet` modifier with WhatsNew integration.

```swift
.sheet(
    whatsNew: self.$whatsNew,
    layout: WhatsNew.Layout(
        footerActionSpacing: 20
    )
)
```

--------------------------------

### Initialize WhatsNewEnvironment with WhatsNew Instances

Source: https://github.com/sventiigi/whatsnewkit/blob/main/README.md

Demonstrates two ways to initialize `WhatsNewEnvironment`. The first uses a direct array of `WhatsNew` objects, defaulting to `UserDefaultsWhatsNewVersionStore`. The second initializes with `NSUbiquitousKeyValueWhatsNewVersionStore` and provides `WhatsNew` objects via a closure.

```swift
// Initialize WhatsNewEnvironment by passing an array of WhatsNew Instances.
// UserDefaultsWhatsNewVersionStore is used as default WhatsNewVersionStore
let whatsNewEnvironment = WhatsNewEnvironment(
    whatsNewCollection: [
        WhatsNew(
            version: "1.0.0",
            // ...
        )
    ]
)

// Initialize WhatsNewEnvironment with NSUbiquitousKeyValueWhatsNewVersionStore
// which stores the presented versions in iCloud.
// WhatsNewCollection is provided by a `WhatsNewBuilder` closure
let whatsNewEnvironment = WhatsNewEnvironment(
    versionStore: NSUbiquitousKeyValueWhatsNewVersionStore(),
    whatsNewCollection: {
        WhatsNew(
            version: "1.0.0",
            // ...
        )
    }
)
```

--------------------------------

### WhatsNew Struct Initialization

Source: https://github.com/sventiigi/whatsnewkit/blob/main/README.md

Shows how to initialize the `WhatsNew` struct, which defines the content and behavior of a new feature announcement. This includes setting the version, title, features (with images, titles, and subtitles), and primary/secondary actions.

```swift
let whatsnew = WhatsNew(
    // The Version that relates to the features you want to showcase
    version: "1.0.0",
    // The title that is shown at the top
    title: "What's New",
    // The features you want to showcase
    features: [
        WhatsNew.Feature(
            image: .init(systemName: "star.fill"),
            title: "Title",
            subtitle: "Subtitle"
        )
    ],
    // The primary action that is used to dismiss the WhatsNewView
    primaryAction: WhatsNew.PrimaryAction(
        title: "Continue",
        backgroundColor: .accentColor,
        foregroundColor: .white,
        hapticFeedback: .notification(.success),
        onDismiss: {
            print("WhatsNewView has been dismissed")
        }
    ),
    // The optional secondary action that is displayed above the primary action
    secondaryAction: WhatsNew.SecondaryAction(
        title: "Learn more",
        foregroundColor: .accentColor,
        hapticFeedback: .selection,
        action: .openURL(
            .init(string: "https://github.com/SvenTiigi/WhatsNewKit")
        )
    )
)
```

--------------------------------

### Swift: WhatsNewViewController Initialization

Source: https://github.com/sventiigi/whatsnewkit/blob/main/README.md

Shows the initialization of `WhatsNewViewController` for UIKit/AppKit integration, including setting the `WhatsNew` content and a custom `WhatsNew.Layout` for presentation.

```swift
let whatsNewViewController = WhatsNewViewController(
    whatsNew: WhatsNew(
        version: "1.0.0",
        // ...
    ),
    layout: WhatsNew.Layout(
        contentSpacing: 80
    )
)
```

--------------------------------

### WhatsNew.Feature Initialization

Source: https://github.com/sventiigi/whatsnewkit/blob/main/README.md

Shows how to initialize `WhatsNew.Feature`, which represents an individual new feature. This includes providing an image (using SF Symbols), a title, and a subtitle that can be styled using Markdown for rich text presentation.

```swift
let feature = WhatsNew.Feature(
    image: .init(
        systemName: "wand.and.stars"
    ),
    title: "New Design",
    subtitle: .init(
        try AttributedString(
            markdown: "An awesome new _Design_"
        )
    )
)
```

--------------------------------

### WhatsNewVersionStore Protocol Usage

Source: https://github.com/sventiigi/whatsnewkit/blob/main/README.md

Demonstrates how to use the `WhatsNewVersionStore` protocol to save and retrieve presented versions of an app. It shows saving a version, retrieving all presented versions, and checking if a specific version has been presented.

```swift
let whatsNewVersionStore: WhatsNewVersionStore

// Save presented versions
whatsNewVersionStore.save(presentedVersion: "1.0.0")

// Retrieve presented versions
let presentedVersions = whatsNewVersionStore.presentedVersions

// Retrieve bool value if a given version has already been presented
let hasPresented = whatsNewVersionStore.hasPresented("1.0.0")
```

--------------------------------

### Swift: Environment Layout Configuration

Source: https://github.com/sventiigi/whatsnewkit/blob/main/README.md

Illustrates configuring a default layout within the SwiftUI environment when initializing `WhatsNewEnvironment`. This sets up layout properties like scroll view indicators and feature list spacing.

```swift
.environment(
    \.whatsNew,
    .init(
        defaultLayout: WhatsNew.Layout(
            showsScrollViewIndicators: true,
            featureListSpacing: 35
        ),
        whatsNew: self
    )
)
```

--------------------------------

### SwiftPM Dependency Declaration

Source: https://github.com/sventiigi/whatsnewkit/blob/main/README.md

Shows how to add WhatsNewKit as a dependency to your project using Swift Package Manager in the `Package.swift` file.

```swift
dependencies: [
    .package(url: "https://github.com/SvenTiigi/WhatsNewKit.git", from: "2.0.0")
]
```

--------------------------------

### WhatsNew.Version Initialization

Source: https://github.com/sventiigi/whatsnewkit/blob/main/README.md

Illustrates different ways to initialize the `WhatsNew.Version` type, which represents the version of an app associated with new features. It includes initialization by major, minor, and patch numbers, direct string literal assignment, and using the current bundle version.

```swift
// Initialize with major, minor, and patch
let version = WhatsNew.Version(
    major: 1,
    minor: 0,
    patch: 0
)

// Initialize by string literal
let version: WhatsNew.Version = "1.0.0"

// Initialize WhatsNew Version by using the current version of your bundle
let version: WhatsNew.Version = .current()
```

--------------------------------

### WhatsNew.PrimaryAction Initialization

Source: https://github.com/sventiigi/whatsnewkit/blob/main/README.md

Details the initialization of `WhatsNew.PrimaryAction`, which configures the main button used to dismiss the `WhatsNewView`. It allows customization of the button's title, background and foreground colors, haptic feedback, and defining an action to be performed upon dismissal.

```swift
let primaryAction = WhatsNew.PrimaryAction(
    title: "Continue",
    backgroundColor: .blue,
    foregroundColor: .white,
    hapticFeedback: .notification(.success),
    onDismiss: {
        print("WhatsNewView has been dismissed")
    }
)
```

--------------------------------

### Swift: Conditional WhatsNewViewController Presentation

Source: https://github.com/sventiigi/whatsnewkit/blob/main/README.md

Illustrates a convenience failable initializer for `WhatsNewViewController` that checks if a version has already been presented. It uses a `versionStore` (like `UserDefaultsWhatsNewVersionStore`) to manage this state.

```swift
guard let whatsNewViewController = WhatsNewViewController(
    whatsNew: WhatsNew(
        version: "1.0.0",
        // ...
    ),
    versionStore: UserDefaultsWhatsNewVersionStore()
) else {
    // Version of WhatsNew has already been presented
    return
}

// Present WhatsNewViewController
// Version will be automatically saved in the provided
// WhatsNewVersionStore when the WhatsNewViewController gets dismissed
self.present(whatsNewViewController, animated: true)
```

--------------------------------

### SwiftUI: Manual Feature Presentation

Source: https://github.com/sventiigi/whatsnewkit/blob/main/README.md

Illustrates manually presenting a `WhatsNewView` using the `.sheet(whatsNew:)` modifier in SwiftUI. This involves managing the presentation state with `@State` and providing the `WhatsNew` content.

```swift
struct ContentView: View {

    @State
    var whatsNew: WhatsNew? = WhatsNew(
        title: "WhatsNewKit",
        features: [
            .init(
                image: .init(
                    systemName: "star.fill",
                    foregroundColor: .orange
                ),
                title: "Showcase your new App Features",
                subtitle: "Present your new app features..."
            ),
            // ...
        ]
    )

    var body: some View {
        NavigationView {
            // ...
        }
        .sheet(
            whatsNew: self.$whatsNew
        )
    }

}
```

--------------------------------

### SwiftUI: Automatic Feature Presentation

Source: https://github.com/sventiigi/whatsnewkit/blob/main/README.md

Demonstrates how to automatically present new app features using the `.whatsNewSheet()` modifier in SwiftUI. This requires the WhatsNewKit package to be imported.

```swift
import SwiftUI
import WhatsNewKit

struct ContentView: View {

    var body: some View {
        NavigationView {
            // ...
        }
        .whatsNewSheet()
    }

}
```

--------------------------------

### Subclass WhatsNewEnvironment for Custom Behavior

Source: https://github.com/sventiigi/whatsnewkit/blob/main/README.md

This code shows how to create a custom `WhatsNewEnvironment` by subclassing `WhatsNewEnvironment` and overriding the `whatsNew()` function. This allows for custom logic in determining which `WhatsNew` object to present, accessing current version, collection, and version store.

```swift
class MyCustomWhatsNewEnvironment: WhatsNewEnvironment {

    /// Retrieve a WhatsNew that should be presented to the user, if available.
    override func whatsNew() -> WhatsNew? {
        // The current version
        let currentVersion = self.currentVersion
        // Your declared WhatsNew objects
        let whatsNewCollection = self.whatsNewCollection
        // The WhatsNewVersionStore used to determine the already presented versions
        let versionStore = self.whatsNewVersionStore
        // TODO: Determine WhatsNew that should be presented to the user...
    }

}
```

--------------------------------

### Swift: WhatsNewSheet Layout Customization

Source: https://github.com/sventiigi/whatsnewkit/blob/main/README.md

Demonstrates how to pass a custom `WhatsNew.Layout` directly to the `.whatsNewSheet` presentation modifier. This allows for specific layout adjustments like content padding.

```swift
.whatsNewSheet(
    layout: WhatsNew.Layout(
        contentPadding: .init(
            top: 80,
            leading: 0,
            bottom: 0,
            trailing: 0
        )
    )
)
```

--------------------------------

### Swift: Modifying Default Layout

Source: https://github.com/sventiigi/whatsnewkit/blob/main/README.md

Shows how to adjust the default layout for WhatsNewKit components by mutating the `WhatsNew.Layout.default` instance. This affects all subsequent presentations unless overridden.

```swift
WhatsNew.Layout.default.featureListSpacing = 35
```

--------------------------------

### Add .whatsNewSheet() Modifier to ContentView

Source: https://github.com/sventiigi/whatsnewkit/blob/main/README.md

This code snippet demonstrates how to attach the `.whatsNewSheet()` modifier to a SwiftUI View. This modifier enables the automatic presentation of the `WhatsNewView` when needed, using the `WhatsNewEnvironment` to determine the content.

```swift
struct ContentView: View {

    var body: some View {
        NavigationView {
            // ...
        }
        // Automatically present a WhatsNewView, if needed.
        // The WhatsNew that should be presented to the user
        // is automatically retrieved from the `WhatsNewEnvironment`
        .whatsNewSheet()
    }

}
```
Tokens:
Raw