### Full-Featured PermissionFlow Setup

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/MODULES.md

Use this setup for all permissions with preflight status checking. Add the specified products to your Package.swift file.

```swift
import PermissionFlow
import PermissionFlowExtendedStatus

// Add to Package.swift:
.product(name: "PermissionFlow", package: "PermissionFlow"),
.product(name: "PermissionFlowExtendedStatus", package: "PermissionFlow")
```

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

### System Settings Navigation Only Setup

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/MODULES.md

Use this setup for deeplinks to System Settings without permission guidance. Add the specified product to your Package.swift file.

```swift
import SystemSettingsKit

// Add to Package.swift:
.product(name: "SystemSettingsKit", package: "PermissionFlow")
```

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

### Recommended Setup: Register Selectively

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/extension-modules.md

Registers only the necessary extension modules during app initialization.

```swift
@main
struct MyApp: App {
    init() {
        // Only register the providers you need
        PermissionFlowBluetoothStatus.register()
        PermissionFlowScreenRecordingStatus.register()
    }
    
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}
```

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

### Examples of System Settings URLs

Source: https://github.com/jaywcjlove/permissionflow/blob/main/README.md

Illustrates how to construct URLs to open specific system settings panes and their anchors.

```text
x-apple.systempreferences:com.apple.Wallpaper-Settings.extension
x-apple.systempreferences:com.apple.settings.PrivacySecurity.extension?Privacy_Advertising
x-apple.systempreferences:com.apple.Wallpaper-Settings.extension?ScreenSaver
```

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

### Selective Extension Setup for Specific Permissions

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/MODULES.md

Use this setup for specific optional permissions only, avoiding linking unnecessary modules like MusicKit or Carbon. Add the specified products to your Package.swift file.

```swift
import PermissionFlow
import PermissionFlowBluetoothStatus
import PermissionFlowScreenRecordingStatus

// Add to Package.swift:
.product(name: "PermissionFlow", package: "PermissionFlow"),
.product(name: "PermissionFlowBluetoothStatus", package: "PermissionFlow"),
.product(name: "PermissionFlowScreenRecordingStatus", package: "PermissionFlow")
```

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

### Example: Open App Settings

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings-destination.md

Demonstrates how to open the current app's Settings screen using SystemSettingsDestination.appSettings.

```swift
let destination = SystemSettingsDestination.appSettings
SystemSettings.open(destination)
```

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

### Recommended Setup: Register All Extensions

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/extension-modules.md

Registers all extension modules using PermissionFlowExtendedStatus.register() during app initialization.

```swift
@main
struct MyApp: App {
    init() {
        PermissionFlowExtendedStatus.register()
    }
    
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}
```

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

### Recommended Setup: Lazy Registration

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/extension-modules.md

Demonstrates lazy registration of a Bluetooth status provider, registering it on demand when needed.

```swift
import PermissionFlow
import PermissionFlowBluetoothStatus

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
    
    // Register on demand when needed
    func enableBluetoothSupport() {
        PermissionFlowBluetoothStatus.register()
    }
}
```

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

### Getting the Settings URL

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/permission-flow-pane.md

Demonstrates how to obtain the deep link URL for a specific permission pane in System Settings. This example retrieves the URL for the Full Disk Access pane.

```swift
let pane = PermissionFlowPane.fullDiskAccess
let url = pane.settingsURL
// url = x-apple.systempreferences:com.apple.settings.PrivacySecurity.extension?Privacy_AllFiles
```

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

### Example: Open Notification Settings

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings-destination.md

Demonstrates how to open the current app's notification settings screen using SystemSettingsDestination.notificationSettings.

```swift
let destination = SystemSettingsDestination.notificationSettings
SystemSettings.open(destination)
```

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

### App Initialization with Extended Status Registration

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/extension-modules.md

Example of registering all extended status providers during app initialization.

```swift
import PermissionFlow
import PermissionFlowExtendedStatus

@main
struct MyApp: App {
    init() {
        PermissionFlowExtendedStatus.register()
    }
    
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}
```

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

### App Initialization with Screen Recording Registration

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/extension-modules.md

Example of registering the Screen Recording status provider during app initialization.

```swift
import PermissionFlow
import PermissionFlowScreenRecordingStatus

@main
struct MyApp: App {
    init() {
        PermissionFlowScreenRecordingStatus.register()
    }
    
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}
```

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

### PermissionFlowConfiguration Initializer Example

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/permission-flow-configuration.md

Demonstrates how to create a PermissionFlowConfiguration instance with specific settings for required apps, accessibility trust, and locale.

```swift
let config = PermissionFlowConfiguration(
    requiredAppURLs: [
        URL(fileURLWithPath: "/Applications/MyApp.app")
    ],
    promptForAccessibilityTrust: true,
    localeIdentifier: "fr"
)

let controller = PermissionFlow.makeController(configuration: config)
```

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

### Return Value Handling Example

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings.md

Demonstrates how to handle the boolean return value from System Settings methods to determine if the settings app was successfully opened.

```APIDOC
## Return Value Handling

### Description
This example shows how to check the success of opening system settings.

### Code
```swift
import SystemSettingsKit

@discardableResult
func tryOpenSettings() {
    let success = SystemSettings.open(
        paneIdentifier: "com.apple.settings.PrivacySecurity.extension"
    )
    
    if !success {
        print("Failed to open System Settings")
    }
}
```
```

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

### Minimal PermissionFlow Setup

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/MODULES.md

Include the PermissionFlow product in your Package.swift for basic permission guidance features like buttons and panels.

```swift
// Add to Package.swift:
.product(name: "PermissionFlow", package: "PermissionFlow")
```

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

### localizedTitle Method Example

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/permission-flow-pane.md

Demonstrates how to get the localized permission name for a specific locale. The example shows fetching the French title for the Accessibility pane.

```swift
let pane = PermissionFlowPane.accessibility
let title = pane.localizedTitle(localeIdentifier: "fr")
print(title) // "Accessibilité"
```

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

### Codable Conformance Example

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/permission-authorization-state.md

Demonstrates encoding and decoding PermissionAuthorizationState to and from JSON. The state is represented by its raw string value.

```swift
let state = PermissionAuthorizationState.granted
let encoded = try JSONEncoder().encode(state)
// Produces: "granted"

let decoded = try JSONDecoder().decode(PermissionAuthorizationState.self, from: encoded)
```

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

### Open System Settings to Specific Page

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/README.md

Use SystemSettings.open with a SystemSettingsDestination to navigate the user to a specific page in System Settings. This example opens the Wi-Fi settings.

```swift
SystemSettings.open(destination: SystemSettingsDestination.wifi())
```

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

### PermissionFlowButton Example with Default Appearance

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/permission-flow-button.md

Demonstrates how to create a PermissionFlowButton for the accessibility pane, providing the main app's bundle URL as a suggested app URL. This example uses the default button appearance.

```swift
import SwiftUI
import PermissionFlow

struct ContentView: View {
    var body: some View {
        PermissionFlowButton(
            pane: .accessibility,
            suggestedAppURLs: [Bundle.main.bundleURL]
        )
    }
}
```

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

### Opening a Permission Pane

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/permission-flow-pane.md

Shows how to authorize a specific permission pane using PermissionFlowController. This example opens the Accessibility pane and suggests the main app bundle URL.

```swift
import PermissionFlow

let controller = PermissionFlow.makeController()

// Open Accessibility with floating panel
controller.authorize(
    pane: .accessibility,
    suggestedAppURLs: [Bundle.main.bundleURL]
)
```

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

### Navigate to System Settings Subsection

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/README.md

Construct a SystemSettingsDestination to open a specific subsection within System Settings, such as accessibility anchors like VoiceOver. This example navigates to VoiceOver settings.

```swift
let dest = SystemSettingsDestination.accessibility(anchor: .voiceOver)
SystemSettings.open(dest)
```

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

### Checking Permission Status Example

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/permission-status-registry.md

Demonstrates how to check the authorization state for a specific permission, such as accessibility. It retrieves the provider and then its authorization state to determine if the permission is granted.

```swift
import PermissionFlow

let provider = PermissionStatusRegistry.provider(for: .accessibility)
let state = provider.authorizationState()

if state == .granted {
    print("Accessibility permission granted")
} else {
    print("Permission not granted; open System Settings")
}
```

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

### Open System Settings for Privacy

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/MODULES.md

Use the SystemSettingsKit to directly open the system's privacy settings. This is useful for guiding users to grant necessary permissions.

```swift
import SystemSettingsKit

SystemSettings.open(destination: SystemSettingsDestination.privacy())
```

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

### Checking Panel Support

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/permission-flow-pane.md

Illustrates how to check if a permission pane supports the floating authorization panel. This example checks the microphone pane, which does not support it.

```swift
let pane = PermissionFlowPane.microphone

if pane.supportsFloatingAuthorizationPanel {
    print("This pane has a drag-and-drop panel")
} else {
    print("This pane uses the system prompt")
}
```

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

### Create PermissionFlowButtonState with Explicit Values

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/permission-flow-button-state.md

Example of initializing a PermissionFlowButtonState directly with provided title key, system image, and granted status.

```swift
let state = PermissionFlowButtonState(
    titleKey: "permission_flow.button.granted",
    systemImage: "checkmark.seal.fill",
    isGranted: true
)
```

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

### openAppSettings()

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings.md

Opens the main settings screen for the current application on iOS. This is a convenient shortcut for guiding users to their app's specific settings.

```APIDOC
## openAppSettings()

### Description
Opens the main settings screen for the current application on iOS.

### Method
`static func openAppSettings() -> Bool`

### Returns
- **Type:** `Bool`
- **Description:** `true` if the Settings app was successfully opened, `false` otherwise.

### Example
```swift
import SystemSettingsKit

@State private var showsSettingsPrompt = false

var body: some View {
    Button("Open Settings") {
        SystemSettings.openAppSettings()
    }
}
```
```

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

### Convert Authorization State to Button State in Usage

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/permission-flow-button-state.md

Example demonstrating how to obtain an authorization state and convert it into a PermissionFlowButtonState for use in an application. It prints the granted status and system image of the resulting button state.

```swift
let provider = PermissionStatusRegistry.provider(for: .accessibility)
let authState = provider.authorizationState()
let buttonState = PermissionFlowButtonState.make(from: authState)

print("Granted: \(buttonState.isGranted)")
print("Icon: \(buttonState.systemImage)")
```

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

### PermissionFlowConfiguration Initializer

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/permission-flow-configuration.md

Creates a new PermissionFlowConfiguration with specified options. This configuration controls initial setup for the PermissionFlowController, including default apps, accessibility access requests, and UI locale.

```APIDOC
## init(requiredAppURLs:promptForAccessibilityTrust:localeIdentifier:)

### Description
Creates a new PermissionFlowConfiguration with specified options. This configuration controls initial setup for the PermissionFlowController, including default apps, accessibility access requests, and UI locale.

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **requiredAppURLs** (`[URL]`) - Optional - Apps that should already appear in the floating panel. Defaults to `[]`.
- **promptForAccessibilityTrust** (`Bool`) - Optional - When enabled, tracking can prompt for Accessibility access so AX-based window observation becomes available immediately. Defaults to `false`.
- **localeIdentifier** (`String?`) - Optional - Optional locale identifier injected into the floating panel's SwiftUI environment to override localization. Defaults to `nil`.

### Request Example
```swift
let config = PermissionFlowConfiguration(
    requiredAppURLs: [
        URL(fileURLWithPath: "/Applications/MyApp.app")
    ],
    promptForAccessibilityTrust: true,
    localeIdentifier: "fr"
)

let controller = PermissionFlow.makeController(configuration: config)
```

### Response
#### Success Response (200)
This initializer does not return a value directly, but configures the `PermissionFlowConfiguration` struct.

#### Response Example
N/A
```

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

### Check Permission Status

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/00-START-HERE.md

Before guiding users, check the current authorization status for a given permission pane.

```swift
let status = PermissionStatusRegistry.provider(for: .accessibility).authorizationState()
```

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

### open(url:)

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings.md

Opens system settings using a fully built URL. This method is primarily for iOS and requires a URL that is supported by the iOS operating system.

```APIDOC
## open(url:)

### Description
Opens system settings from a fully built URL. The URL must be supported by iOS.

### Method
`static func open(url: URL) -> Bool`

### Parameters
#### Path Parameters
- **url** (`URL`) - Required - A Settings URL supported by iOS.

### Returns
- **Type:** `Bool`
- **Description:** `true` if the Settings app was successfully opened, `false` otherwise.

### Example
```swift
import SystemSettingsKit

if let url = URL(string: UIApplication.openSettingsURLString) {
    SystemSettings.open(url: url)
}
```
```

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

### init(configuration:)

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/permission-flow-controller.md

Initializes a new PermissionFlowController with optional configuration. It sets up the initial state, binds window-tracking callbacks, and observes frontmost app changes, preparing the controller for subsequent calls to authorize permission flows.

```APIDOC
## init(configuration:)

### Description
Initializes a new controller with the given configuration.

Sets up initial state, binds window-tracking callbacks, and observes frontmost app changes. The controller is ready to call `authorize(pane:suggestedAppURLs:sourceFrameInScreen:)` immediately after initialization.

### Parameters
- **configuration** (`PermissionFlowConfiguration`) - Optional - Initial configuration with app URLs and locale

### Example
```swift
let controller = PermissionFlowController(
    configuration: PermissionFlowConfiguration(
        requiredAppURLs: [Bundle.main.bundleURL],
        promptForAccessibilityTrust: false
    )
)
```
```

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

### Open System Settings by URL

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings.md

Opens System Settings using a fully constructed `x-apple.systempreferences:` URL. This provides maximum flexibility for deep linking into System Settings. Ensure SystemSettingsKit is imported.

```swift
import SystemSettingsKit

let url = URL(string: "x-apple.systempreferences:com.apple.settings.PrivacySecurity.extension?Privacy_AllFiles")!
SystemSettings.open(url: url)
```

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

### SystemSettings.open(_:)

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings.md

Opens a System Settings page on macOS using a structured SystemSettingsDestination object.

```APIDOC
## SystemSettings.open(_:)

### Description
Opens a System Settings page from a prebuilt deeplink destination.

### Method
`static func open(_ destination: SystemSettingsDestination) -> Bool`

### Parameters
#### Path Parameters
- **destination** (SystemSettingsDestination) - Required - A structured destination object

### Returns
- **Type:** `Bool`
- **Description:** `true` if System Settings was successfully opened, `false` otherwise

### Example
```swift
import SystemSettingsKit

let destination = SystemSettingsDestination.privacy(anchor: .privacyAccessibility)
SystemSettings.open(destination)
```
```

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

### Initialization Pattern

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/permission-status-registry.md

Illustrates the recommended initialization pattern for the PermissionFlow library, particularly when using extended status providers. It ensures all necessary providers are registered at application startup.

```APIDOC
## Initialization Pattern

This section describes the recommended way to initialize the PermissionFlow library, especially when using extended status features.

### App Startup Registration

It is recommended to register all extended status providers during your application's initialization phase.

### Example

```swift
import PermissionFlow
import PermissionFlowExtendedStatus

@main
struct MyApp: App {
    init() {
        // Register all extended status providers at app startup
        PermissionFlowExtendedStatus.register()
    }
    
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}
```
```

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

### Get Provider

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/permission-status-registry.md

Retrieves the status provider for a given permission pane. It returns the registered provider or an `UnsupportedPermissionStatusProvider` if none is found.

```APIDOC
## provider(for:)

### Description
Retrieves the status provider for a given permission pane. It returns the registered provider or an `UnsupportedPermissionStatusProvider` if none is found. This method is thread-safe.

### Method
`static func provider(for pane: PermissionFlowPane) -> any PermissionStatusProviding`

### Parameters
#### Path Parameters
- **pane** (`PermissionFlowPane`) - Required - The permission pane to look up

### Returns
- **Type:** `any PermissionStatusProviding`
- **Description:** The registered provider for the pane, or an `UnsupportedPermissionStatusProvider` if no provider exists

### Example
```swift
import PermissionFlow

let provider = PermissionStatusRegistry.provider(for: .accessibility)
let state = provider.authorizationState()

print("Accessibility permission: \(state)")
```
```

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

### SystemSettings.open(url:)

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings.md

Opens a System Settings page on macOS using a fully constructed deeplink URL.

```APIDOC
## SystemSettings.open(url:)

### Description
Opens System Settings from a fully built deeplink URL.

### Method
`static func open(url: URL) -> Bool`

### Parameters
#### Path Parameters
- **url** (URL) - Required - A complete `x-apple.systempreferences:` URL

### Returns
- **Type:** `Bool`
- **Description:** `true` if System Settings was successfully opened, `false` otherwise

### Example
```swift
import SystemSettingsKit

let url = URL(string: "x-apple.systempreferences:com.apple.settings.PrivacySecurity.extension?Privacy_AllFiles")!
SystemSettings.open(url: url)
```
```

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

### Register and Get Bluetooth Permission Provider

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/MODULES.md

Register the Bluetooth permission status provider and retrieve it from the registry to check authorization state.

```swift
import PermissionFlow
import PermissionFlowBluetoothStatus

PermissionFlowBluetoothStatus.register()

let provider = PermissionStatusRegistry.provider(for: .bluetooth)
let state = provider.authorizationState()
```

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

### Reset Dropped Apps List

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/permission-flow-controller.md

Resets the dropped apps list to its initial configuration. Useful for starting a fresh permission flow.

```swift
public func resetDroppedApps()
```

```swift
controller.resetDroppedApps()
```

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

### Handle System Settings Open Result

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings.md

Demonstrates how to check the boolean return value of SystemSettings.open to determine if the settings app was successfully opened. This is useful for error handling or user feedback.

```swift
import SystemSettingsKit

@discardableResult
func tryOpenSettings() {
    let success = SystemSettings.open(
        paneIdentifier: "com.apple.settings.PrivacySecurity.extension"
    )
    
    if !success {
        print("Failed to open System Settings")
    }
}
```

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

### Create PermissionFlowButtonState from Authorization State

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/permission-flow-button-state.md

Example of using the factory method to create a button state from a PermissionAuthorizationState. Demonstrates accessing the derived properties.

```swift
let authState = PermissionAuthorizationState.granted
let buttonState = PermissionFlowButtonState.make(from: authState)

print(buttonState.isGranted) // true
print(buttonState.systemImage) // "checkmark.seal.fill"
```

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

### SystemSettings.open(_:)

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings.md

Opens a specific Settings page on iOS using a structured SystemSettingsDestination object.

```APIDOC
## SystemSettings.open(_:)

### Description
Opens a Settings page from a prebuilt destination. iOS only exposes the destinations explicitly modeled in `SystemSettingsDestination`.

### Method
`static func open(_ destination: SystemSettingsDestination) -> Bool`

### Parameters
#### Path Parameters
- **destination** (SystemSettingsDestination) - Required - A destination object with an iOS-compatible URL

### Returns
- **Type:** `Bool`
- **Description:** `true` if the Settings app was successfully opened, `false` otherwise

### Availability
- iOS 16.0+

### Example
```swift
import SystemSettingsKit

let destination = SystemSettingsDestination.appSettings
SystemSettings.open(destination)
```
```

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

### Create SystemSettingsDestination from Raw Components

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings-destination.md

Initializes a SystemSettingsDestination using a URL, optional pane identifier, and optional anchor. Use this when you have the complete URL components.

```swift
let destination = SystemSettingsDestination(
    url: URL(string: "x-apple.systempreferences:com.apple.Accessibility-Settings.extension?display")!,
    paneIdentifier: "com.apple.Accessibility-Settings.extension",
    anchor: "display"
)
```

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

### makeController

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/permission-flow.md

Creates an object responsible for System Settings navigation, window tracking, and the lifecycle of the floating drag panel.

```APIDOC
## makeController(configuration:)

### Description
Creates the object that owns System Settings navigation, window tracking, and the floating drag panel lifecycle.

### Signature
```swift
@MainActor
public static func makeController(
    configuration: PermissionFlowConfiguration = .init()
) -> PermissionFlowController
```

### Parameters
#### Parameters
- **configuration** (`PermissionFlowConfiguration`) - Optional - Configuration object controlling initial app URLs, accessibility prompting, and locale

### Return
- **Type:** `PermissionFlowController`
- **Description:** An observable controller instance that manages the permission flow lifecycle, window tracking, and panel visibility

### Availability
- Requires `@MainActor` context

### Example
```swift
import PermissionFlow

let controller = PermissionFlow.makeController(
    configuration: PermissionFlowConfiguration(
        requiredAppURLs: [Bundle.main.bundleURL]
    )
)
```
```

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

### Link Core Products to Target

Source: https://github.com/jaywcjlove/permissionflow/blob/main/README.md

Link the main PermissionFlow and SystemSettingsKit products to your application's target.

```swift
.target(
    name: "YourApp",
    dependencies: [
        .product(name: "PermissionFlow", package: "PermissionFlow"),
        .product(name: "SystemSettingsKit", package: "PermissionFlow")
    ]
)
```

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

### Checking Provider Capability

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/permission-status-providing.md

Check if a permission provider supports preflight checks before querying its authorization state. This example demonstrates checking for Bluetooth status.

```swift
import PermissionFlow

let provider = PermissionStatusRegistry.provider(for: .bluetooth)

if provider.capability == .preflightSupported {
    let state = provider.authorizationState()
    print("Bluetooth status: \(state)")
} else {
    print("Cannot determine Bluetooth status")
}
```

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

### Querying Permission Status

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/permission-status-providing.md

Retrieve the authorization state for a specific permission pane using the PermissionStatusRegistry. This example shows how to check for Full Disk Access.

```swift
import PermissionFlow

let provider = PermissionStatusRegistry.provider(for: .fullDiskAccess)
let state = provider.authorizationState()

if state == .granted {
    print("Full Disk Access is available")
}
```

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

### SystemSettingsDestination.wallpaper

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings-destination.md

Provides a SystemSettingsDestination for the Wallpaper settings on macOS.

```APIDOC
## static let wallpaper

### Description
Wallpaper settings.

```swift
static let wallpaper: Self
```
```

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

### Register Custom Status Provider

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/README.md

Register a custom provider for checking permission status for a specific pane. This example registers 'MyProvider' for the accessibility pane.

```swift
PermissionStatusRegistry.register(provider: MyProvider(), for: .accessibility)
```

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

### PermissionFlowButton for Screen Recording

Source: https://github.com/jaywcjlove/permissionflow/blob/main/README.md

Provides examples of using PermissionFlowButton to request Screen Recording permission. It shows both a basic usage and a customized version with conditional styling.

```swift
PermissionFlowButton(
    title: "Open Screen Recording",
    pane: .screenRecording,
    suggestedAppURLs: [Bundle.main.bundleURL],
    configuration: .init()
)

PermissionFlowButton(
    pane: .screenRecording,
    suggestedAppURLs: [Bundle.main.bundleURL],
    configuration: .init()
) { buttonState in
    Label("Open Screen Recording", systemImage: buttonState.systemImage)
        .foregroundStyle(buttonState.isGranted ? .green : .primary)
}
```

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

### Open macOS System Settings by Destination

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings.md

Opens a System Settings page using a structured `SystemSettingsDestination` object. This is useful for navigating to predefined locations within System Settings. Import SystemSettingsKit before use.

```swift
import SystemSettingsKit

let destination = SystemSettingsDestination.privacy(anchor: .privacyAccessibility)
SystemSettings.open(destination)
```

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

### Opening Login Items Extension Settings

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings-destination.md

Demonstrates how to open the Login Items settings, specifically targeting extension settings like Share Menu.

```APIDOC
## Opening Extension Settings

### Description
Opens the Login Items settings pane, specifying an extension point identifier.

### Method
```swift
SystemSettings.open(destination: SystemSettingsDestination.loginItems(extensionPointIdentifier: .shareServices))
```

### Parameters
- `destination`: A `SystemSettingsDestination` object specifying the pane and extension point.
  - `loginItems`: Enum case for Login Items settings.
  - `extensionPointIdentifier`: A `LoginItemsExtensionPointIdentifier` case, e.g., `.shareServices`.
```

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

### init(title:pane:suggestedAppURLs:configuration:)

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/permission-flow-button.md

Creates a PermissionFlowButton with a localized title and default appearance. It displays a system icon and a localized title that updates automatically based on permission status.

```APIDOC
## init(title:pane:suggestedAppURLs:configuration:)

### Description
Creates a button with the default label style. The button shows a system icon (checkmark for granted, arrow for not granted, clock for checking) and a localized title. The title updates automatically when the app becomes active (to refresh permission status).

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **title** (`LocalizedStringResource?`) - Optional - Custom localized button title; if `nil`, uses the localized status-based default
- **pane** (`PermissionFlowPane`) - Required - The permission pane to open
- **suggestedAppURLs** (`[URL]`) - Optional - App bundle URLs to show in the floating panel (defaults to `[]`)
- **configuration** (`PermissionFlowConfiguration`) - Optional - Controller configuration for app list and locale (defaults to `.init()`)

### Request Example
```swift
import SwiftUI
import PermissionFlow

struct ContentView: View {
    var body: some View {
        PermissionFlowButton(
            pane: .accessibility,
            suggestedAppURLs: [Bundle.main.bundleURL]
        )
    }
}
```

### Response
None (This is a View initializer)

### Error Handling
None explicitly documented for the initializer.
```

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

### App Initialization with Extended Status Providers

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/permission-status-registry.md

Illustrates the recommended initialization pattern for an application using PermissionFlowExtendedStatus. All extended status providers are registered at app startup.

```swift
import PermissionFlow
import PermissionFlowExtendedStatus

@main
struct MyApp: App {
    init() {
        // Register all extended status providers at app startup
        PermissionFlowExtendedStatus.register()
    }
    
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}
```

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

### Register All Optional Permission Providers

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/MODULES.md

Use this convenience module to register all optional permission status providers at application startup.

```swift
import PermissionFlow
import PermissionFlowExtendedStatus

@main
struct MyApp: App {
    init() {
        PermissionFlowExtendedStatus.register()
    }
    
    var body: some Scene {
        WindowGroup { ContentView() }
    }
}
```

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

### PermissionFlowButton Usage: Simple Button

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/permission-flow-button.md

A basic example of creating a PermissionFlowButton for the accessibility pane without any custom title or suggested URLs. The button will use default localized text and behavior.

```swift
PermissionFlowButton(
    pane: .accessibility
)
```

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

### Open System Settings Destination

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/MODULES.md

Navigate to specific sections within System Settings using typed deeplinks provided by SystemSettingsKit.

```swift
import SystemSettingsKit

SystemSettings.open(
    destination: SystemSettingsDestination.privacy(anchor: .privacyAccessibility)
)
```

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

### SystemSettingsDestination Initializer

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings-destination.md

Creates a SystemSettingsDestination from raw URL components, pane identifier, and an optional anchor.

```APIDOC
## init(url:paneIdentifier:anchor:)

### Description
Creates a SystemSettingsDestination from raw components.

### Parameters
- **url** (`URL`) - Required - The deeplink URL
- **paneIdentifier** (`String?`) - Optional - Optional pane identifier
- **anchor** (`String?`) - Optional - Optional anchor within the pane

### Example
```swift
let destination = SystemSettingsDestination(
    url: URL(string: "x-apple.systempreferences:com.apple.Accessibility-Settings.extension?display")!,
    paneIdentifier: "com.apple.Accessibility-Settings.extension",
    anchor: "display"
)
```
```

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

### PermissionFlowButton Example with Custom Label

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/permission-flow-button.md

Shows how to create a PermissionFlowButton with a custom label. The label dynamically displays a system image and text based on the permission state, with different colors for granted and not granted statuses.

```swift
import SwiftUI
import PermissionFlow

struct ContentView: View {
    var body: some View {
        PermissionFlowButton(
            pane: .fullDiskAccess,
            suggestedAppURLs: [Bundle.main.bundleURL]
        ) { state in
            HStack {
                Image(systemName: state.systemImage)
                    .foregroundColor(state.isGranted ? .green : .orange)
                Text(state.titleKey)
                    .font(.headline)
            }
            .padding()
        }
    }
}
```

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

### Check Permission Status using Registry

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/INDEX.md

Retrieve the authorization status for a specific permission pane, like accessibility, by first getting the appropriate provider from the PermissionStatusRegistry. This allows checking the current state of a permission.

```swift
let provider = PermissionStatusRegistry.provider(for: .accessibility)
let state = provider.authorizationState()
```

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

### open(destination:)

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings.md

Opens a specific system settings pane and anchor on macOS using a structured destination builder. This provides a type-safe way to navigate to detailed settings.

```APIDOC
## open(destination:)

### Description
Opens a specific system settings pane and anchor on macOS using a structured destination builder.

### Method
`static func open(_ destination: SystemSettingsDestination) -> Bool`

### Parameters
#### Path Parameters
- **destination** (`SystemSettingsDestination`) - Required - A structured destination specifying the pane and anchor.

### Returns
- **Type:** `Bool`
- **Description:** `true` if the Settings app was successfully opened, `false` otherwise.

### Example
```swift
import SystemSettingsKit

let destination = SystemSettingsDestination.accessibility(anchor: .voiceOver)
SystemSettings.open(destination)
```
```

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

### open(destination:)

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings.md

Opens a specific system settings pane and anchor on macOS using a structured destination builder. This provides a type-safe way to navigate to detailed settings.

```APIDOC
## open(destination:)

### Description
Opens a specific system settings pane and anchor on macOS using a structured destination builder.

### Method
`static func open(destination: SystemSettingsDestination) -> Bool`

### Parameters
#### Path Parameters
- **destination** (`SystemSettingsDestination`) - Required - A structured destination specifying the pane and anchor.

### Returns
- **Type:** `Bool`
- **Description:** `true` if the Settings app was successfully opened, `false` otherwise.

### Example
```swift
import SystemSettingsKit

SystemSettings.open(
    destination: SystemSettingsDestination.privacy(anchor: .privacyAllFiles)
)
```
```

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

### Custom Permission Button SwiftUI View

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/permission-flow-button-state.md

Example of using PermissionFlowButtonState within a SwiftUI View to display a custom permission button. The button's appearance and text are dynamically set based on the button state.

```swift
import SwiftUI
import PermissionFlow

struct CustomPermissionButton: View {
    @State private var buttonState = PermissionFlowButtonState(
        titleKey: "permission_flow.button.grant",
        systemImage: "arrow.right.circle.fill",
        isGranted: false
    )

    var body: some View {
        Button(action: {}) {
            HStack {
                Image(systemName: buttonState.systemImage)
                    .foregroundColor(buttonState.isGranted ? .green : .blue)
                Text(buttonState.titleKey)
            }
        }
    }
}
```

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

### open(destination:)

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings.md

Opens a specific system settings pane and anchor on macOS using a structured destination builder. This provides a type-safe way to navigate to detailed settings.

```APIDOC
## open(destination:)

### Description
Opens a specific system settings pane and anchor on macOS using a structured destination builder.

### Method
`static func open(_ destination: SystemSettingsDestination) -> Bool`

### Parameters
#### Path Parameters
- **destination** (`SystemSettingsDestination`) - Required - A structured destination specifying the pane and anchor.

### Returns
- **Type:** `Bool`
- **Description:** `true` if the Settings app was successfully opened, `false` otherwise.

### Example
```swift
import SystemSettingsKit

let destination = SystemSettingsDestination.wifi(anchor: .advanced)
SystemSettings.open(destination)
```
```

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

### SystemSettingsDestination Initializer (macOS)

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings-destination.md

Creates a SystemSettingsDestination from pane and anchor identifiers, automatically constructing the macOS deeplink URL.

```APIDOC
## init(paneIdentifier:anchor:)

### Description
Creates a destination from pane and anchor identifiers. Automatically encodes the anchor as a URL query parameter and constructs the `x-apple.systempreferences:` URL.

### Parameters
- **paneIdentifier** (`String`) - Required - System Settings pane identifier
- **anchor** (`String?`) - Optional - Optional subsection anchor

### Example
```swift
let destination = SystemSettingsDestination(
    paneIdentifier: "com.apple.settings.PrivacySecurity.extension",
    anchor: "Privacy_Accessibility"
)
```
```

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

### SystemSettingsDestination.loginItems

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings-destination.md

Provides a SystemSettingsDestination for the Login Items settings on macOS.

```APIDOC
## static let loginItems

### Description
Login items settings.

```swift
static let loginItems: Self
```
```

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

### Initialize PermissionFlowConfiguration with Required App URLs

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/configuration.md

Configure the initial set of application bundle URLs to be displayed. Invalid URLs are filtered out.

```swift
let config = PermissionFlowConfiguration(
    requiredAppURLs: [
        Bundle.main.bundleURL,
        URL(fileURLWithPath: "/Applications/Helper.app")
    ]
)
```

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

### Full PermissionFlowController Initialization

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/configuration.md

Create a PermissionFlowController with all configuration options specified: initial apps, accessibility prompting, and locale override.

```swift
let config = PermissionFlowConfiguration(
    requiredAppURLs: [
        Bundle.main.bundleURL,
        URL(fileURLWithPath: "/Applications/MyHelper.app")
    ],
    promptForAccessibilityTrust: true,
    localeIdentifier: "ja"
)
let controller = PermissionFlow.makeController(configuration: config)
```

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

### SystemSettings.open(paneIdentifier:anchor:)

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings.md

Opens a System Settings page on macOS using a pane identifier and an optional anchor for a subsection.

```APIDOC
## SystemSettings.open(paneIdentifier:anchor:)

### Description
Opens a System Settings page from a pane identifier and optional anchor.

### Method
`static func open(paneIdentifier: String, anchor: String? = nil) -> Bool`

### Parameters
#### Path Parameters
- **paneIdentifier** (String) - Required - The System Settings pane identifier (e.g., `"com.apple.settings.PrivacySecurity.extension"`)
- **anchor** (String?) - Optional - Optional anchor for a subsection within the pane

### Returns
- **Type:** `Bool`
- **Description:** `true` if System Settings was successfully opened, `false` otherwise

### Example
```swift
import SystemSettingsKit

SystemSettings.open(
    paneIdentifier: "com.apple.settings.PrivacySecurity.extension",
    anchor: "Privacy_Accessibility"
)
```
```

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

### SystemSettings.openAppSettings()

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings.md

Opens the current application's settings page on iOS.

```APIDOC
## SystemSettings.openAppSettings()

### Description
Opens the current app's Settings page on iOS.

### Method
`static func openAppSettings() -> Bool`

### Returns
- **Type:** `Bool`
- **Description:** `true` if the Settings app was successfully opened, `false` otherwise

### Availability
- iOS 16.0+

### Example
```swift
import SystemSettingsKit

SystemSettings.openAppSettings()
```
```

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

### Open iOS Settings by Destination

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings.md

Opens a specific settings page on iOS using a `SystemSettingsDestination` object. This method is restricted to destinations explicitly modeled for iOS and requires iOS 16.0+. Import SystemSettingsKit.

```swift
import SystemSettingsKit

let destination = SystemSettingsDestination.appSettings
SystemSettings.open(destination)
```

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

### Open System Settings by Pane Identifier

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/README.md

Open a specific System Settings page using its identifier. This provides a direct way to navigate to system configuration areas.

```swift
SystemSettings.open(paneIdentifier: "com.apple.settings.PrivacySecurity.extension")
```

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

### SystemSettings.open

Source: https://github.com/jaywcjlove/permissionflow/blob/main/README.md

Opens a specific System Settings page directly. Can be identified by a pane identifier and an optional anchor, or by using predefined SystemSettingsDestination enums.

```APIDOC
## SystemSettings.open

Open any System Settings page directly from a pane identifier and optional anchor:

```swift
import SystemSettingsKit

SystemSettings.open(
    paneIdentifier: "com.apple.Wallpaper-Settings.extension"
)

SystemSettings.open(
    paneIdentifier: "com.apple.settings.PrivacySecurity.extension",
    anchor: "Privacy_Advertising"
)
```

You can also use `SystemSettingsDestination`:

```swift
import SystemSettingsKit

SystemSettings.open(.wallpaper)
SystemSettings.open(.privacy(anchor: .privacyAllFiles))
SystemSettings.open(.displays(anchor: .resolutionSection))
```
```

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

### Opening Accessibility Settings

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings-destination.md

Demonstrates how to open the Accessibility settings pane, specifically navigating to the VoiceOver section.

```APIDOC
## Opening Accessibility

### Description
Opens the Accessibility settings pane, navigating to a specific anchor point.

### Method
```swift
SystemSettings.open(destination: SystemSettingsDestination.accessibility(anchor: .voiceOver))
```

### Parameters
- `destination`: A `SystemSettingsDestination` object specifying the pane and anchor to open.
  - `accessibility`: Enum case for Accessibility settings.
  - `anchor`: An `AccessibilitySettingsAnchor` case, e.g., `.voiceOver`.
```

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

### Initialize PermissionFlow Controller

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/MODULES.md

Use this snippet to create a PermissionFlow controller for managing permission guidance and authorization.

```swift
import PermissionFlow

let controller = PermissionFlow.makeController()
controller.authorize(pane: .accessibility)
```

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

### Creating a Reusable PermissionFlowController

Source: https://github.com/jaywcjlove/permissionflow/blob/main/README.md

Demonstrates how to create a reusable PermissionFlowController with custom configuration, including specifying required app URLs and controlling the prompt for accessibility trust.

```swift
let controller = PermissionFlow.makeController(
    configuration: .init(
        requiredAppURLs: [Bundle.main.bundleURL],
        promptForAccessibilityTrust: false
    )
)
```

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

### SystemSettings Open Pane

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/README.md

Provides API for navigating System Settings. This method allows opening specific panes using their identifiers.

```APIDOC
## SystemSettings.open(paneIdentifier:)

### Description
Opens the specified System Settings pane using its unique identifier.

### Method
Swift Package Method

### Endpoint
N/A (Swift Package Method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **paneIdentifier** (`String`) - Required - The identifier string for the System Settings pane (e.g., `"com.apple.settings.PrivacySecurity.extension"`).

### Request Example
```swift
import SystemSettingsKit

SystemSettings.open(paneIdentifier: "com.apple.settings.PrivacySecurity.extension")
```

### Response
#### Success Response
This method does not return a value but triggers the opening of System Settings.

### Response Example
N/A
```

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

### authorize(pane:suggestedAppURLs:sourceFrameInScreen:)

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/permission-flow-controller.md

Opens the requested privacy pane in System Settings and initiates the floating guidance flow. It manages the display and animation of a floating panel, ensuring only one active panel is shown at a time.

```APIDOC
## authorize(pane:suggestedAppURLs:sourceFrameInScreen:)

### Description
Opens the requested privacy pane and starts the floating guidance flow.

Closes any other active panel, remembers the current frontmost app, and opens System Settings at the specified pane. If the pane supports a floating panel, shows it immediately or animates it from `sourceFrameInScreen`. Starts window tracking to follow System Settings. Only one active panel per app instance is allowed.

### Parameters
- **pane** (`PermissionFlowPane`) - Required - The permission pane to open inside System Settings
- **suggestedAppURLs** (`[URL]`) - Optional - Optional `.app` bundle URLs for the floating panel drag list
- **sourceFrameInScreen** (`CGRect?`) - Optional - Source rect in screen coordinates for the fly-to animation

### Example
```swift
let accessibility = PermissionFlowPane.accessibility
let sourceFrame = CGRect(x: 100, y: 100, width: 32, height: 32)

controller.authorize(
    pane: accessibility,
    suggestedAppURLs: [Bundle.main.bundleURL],
    sourceFrameInScreen: sourceFrame
)
```
```

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

### Minimal PermissionFlowController Initialization

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/configuration.md

Create a PermissionFlowController using all default configuration values.

```swift
import PermissionFlow

let controller = PermissionFlow.makeController()
```

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

### SystemSettings.activate()

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings.md

Re-activates the System Settings application if it is already running on macOS.

```APIDOC
## SystemSettings.activate()

### Description
Re-activates the running System Settings app if it already exists. Brings an already-open System Settings window to the foreground. Use this after opening a pane to ensure System Settings is visible, or to bring it to focus without opening a new pane.

### Method
`static func activate()

### Example
```swift
import SystemSettingsKit

// Open System Settings at a specific pane
SystemSettings.open(paneIdentifier: "com.apple.settings.PrivacySecurity.extension")

// Later, bring it to the foreground if user clicks something else
SystemSettings.activate()
```
```

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

### Open System Settings URL

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings.md

Opens the system settings app using a URL. This is typically used on iOS to open the main settings or specific app settings.

```swift
import SystemSettingsKit

if let url = URL(string: UIApplication.openSettingsURLString) {
    SystemSettings.open(url: url)
}
```

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

### Create SystemSettingsDestination from Pane and Anchor Identifiers

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings-destination.md

Creates a SystemSettingsDestination using pane and anchor identifiers. This initializer automatically encodes the anchor as a URL query parameter.

```swift
let destination = SystemSettingsDestination(
    paneIdentifier: "com.apple.settings.PrivacySecurity.extension",
    anchor: "Privacy_Accessibility"
)
```

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

### Manual Controller Usage with Launch Animation

Source: https://github.com/jaywcjlove/permissionflow/blob/main/README.md

Shows how to manually request accessibility permissions while preserving the launch animation by providing the click source frame. This ensures a smoother user experience.

```swift
import AppKit
import PermissionFlow

@MainActor
final class PermissionViewModel: ObservableObject {
    private let controller = PermissionFlow.makeController()

    func requestAccessibility() {
        let mouseLocation = NSEvent.mouseLocation
        let sourceFrame = CGRect(
            x: mouseLocation.x - 16,
            y: mouseLocation.y - 16,
            width: 32,
            height: 32
        )

        controller.authorize(
            pane: .accessibility,
            suggestedAppURLs: [Bundle.main.bundleURL],
            sourceFrameInScreen: sourceFrame
        )
    }
}
```

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

### Opening System Settings with SystemSettingsDestination

Source: https://github.com/jaywcjlove/permissionflow/blob/main/README.md

Illustrates using SystemSettingsDestination enum to open predefined System Settings pages and specific anchors within them, providing a more type-safe approach.

```swift
import SystemSettingsKit

SystemSettings.open(.wallpaper)
SystemSettings.open(.privacy(anchor: .privacyAllFiles))
SystemSettings.open(.displays(anchor: .resolutionSection))
```

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

### Open System Settings Pages with SystemSettingsKit

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/quick-start.md

Utilize SystemSettingsKit for typed deep links to various System Settings pages. This includes opening the main privacy page, specific privacy panes, or other settings sections, and activating the System Settings app.

```swift
import SystemSettingsKit

// Open Privacy & Security home
SystemSettings.open(
    destination: SystemSettingsDestination.privacy()
)

// Open specific privacy pane
SystemSettings.open(
    destination: SystemSettingsDestination.privacy(anchor: .privacyBluetooth)
)

// Open other settings pages
SystemSettings.open(
    destination: SystemSettingsDestination.wifi(anchor: .advanced)
)

// Bring System Settings to foreground
SystemSettings.activate()
```

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

### Opening Privacy Settings (Full Disk Access)

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/system-settings-destination.md

Shows how to open the Privacy settings, targeting the 'Full Disk Access' section.

```APIDOC
## Opening Full Disk Access

### Description
Opens the Privacy settings pane, specifically navigating to the 'All Files' (Full Disk Access) section.

### Method
```swift
SystemSettings.open(destination: SystemSettingsDestination.privacy(anchor: .privacyAllFiles))
```

### Parameters
- `destination`: A `SystemSettingsDestination` object specifying the pane and anchor to open.
  - `privacy`: Enum case for Privacy settings.
  - `anchor`: An `PrivacySettingsAnchor` case, e.g., `.privacyAllFiles`.
```

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

### Open Wi-Fi System Settings

Source: https://github.com/jaywcjlove/permissionflow/blob/main/README.md

Navigate to specific Wi-Fi settings panes using typed anchors. Options include general settings, join, details, and advanced configurations.

```swift
SystemSettings.open(.wifi)
SystemSettings.open(.wifi(anchor: .generalMain))
SystemSettings.open(.wifi(anchor: .generalJoin))
SystemSettings.open(.wifi(anchor: .generalDetails))
SystemSettings.open(.wifi(anchor: .advanced))
```

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

### Register and Use Custom Permission Provider

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/permission-status-registry.md

Shows how to define a custom provider conforming to PermissionStatusProviding and register it with the PermissionStatusRegistry. This allows for custom logic in determining authorization states.

```swift
import PermissionFlow

struct MyCustomProvider: PermissionStatusProviding {
    public var capability: PermissionStatusCapability { .preflightSupported }
    
    public func authorizationState() -> PermissionAuthorizationState {
        // Check a custom mechanism
        .granted
    }
}

// Replace the default microphone provider
PermissionStatusRegistry.register(
    provider: MyCustomProvider(),
    for: .microphone
)

let provider = PermissionStatusRegistry.provider(for: .microphone)
print(provider.authorizationState()) // Uses MyCustomProvider
```

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

### Initialize PermissionFlowConfiguration with Accessibility Trust

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/configuration.md

Enable requesting Accessibility permission for more accurate window tracking. This may trigger a system dialog.

```swift
let config = PermissionFlowConfiguration(
    promptForAccessibilityTrust: true
)
```

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

### Building Conditional UI

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/api-reference/permission-status-capability.md

Shows how to use the permission provider's capability to conditionally render UI elements based on whether the status can be checked beforehand.

```APIDOC
## Building Conditional UI

```swift
import SwiftUI
import PermissionFlow

struct PermissionStatusView: View {
    let pane: PermissionFlowPane
    
    var body: some View {
        let provider = PermissionStatusRegistry.provider(for: pane)
        
        Group {
            if provider.capability == .preflightSupported {
                let state = provider.authorizationState()
                StatusBadge(state: state)
            } else {
                Text("Status unavailable")
                    .foregroundColor(.secondary)
            }
        }
    }
}

struct StatusBadge: View {
    let state: PermissionAuthorizationState
    
    var body: some View {
        HStack {
            Image(systemName: state == .granted ? "checkmark.circle.fill" : "circle.fill")
                .foregroundColor(state == .granted ? .green : .red)
            Text(state == .granted ? "Granted" : "Not Granted")
        }
    }
}
```
```

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

### Initialize PermissionFlowConfiguration with Locale Identifier

Source: https://github.com/jaywcjlove/permissionflow/blob/main/_autodocs/configuration.md

Override the system locale for the floating panel UI. Use a valid IANA locale string.

```swift
let config = PermissionFlowConfiguration(
    localeIdentifier: "fr"
)
```