@swiftbrowser/swift 0.1.0 → 0.3.0

package/Sources/AppIntents/Parameters.swift

@@ -0,0 +1,220 @@
+// Intent parameters, entities, enums and how they display. Shortcuts would
+// fill parameters, query entities and show the display representations; in
+// the browser the app sets parameters itself and the rest is kept as given.
+
+import Foundation
+import FoundationBridge
+import SwiftUI
+import UIKit
+import UniformTypeIdentifiers
+
+// MARK: - Parameters
+
+/// How a parameter takes the previous action's output in Shortcuts.
+public struct InputConnectionBehavior: Hashable, Sendable {
+    let name: String
+    public static let `default` = InputConnectionBehavior(name: "default")
+    public static let connectToPreviousIntentResult = InputConnectionBehavior(name: "connectToPreviousIntentResult")
+    public static let never = InputConnectionBehavior(name: "never")
+}
+
+protocol _OptionalValue { static var _none: Self { get } }
+extension Optional: _OptionalValue { static var _none: Self { nil } }
+
+/// An intent's input. It holds what the app sets (or its default). Reading
+/// an unset non-optional parameter stops the app: Shortcuts would ask the
+/// user for it, and the browser has no Shortcuts. Like Apple's, it is a
+/// class, so copies of an intent share their parameters.
+@propertyWrapper
+public final class IntentParameter<Value>: @unchecked Sendable {
+    public let title: LocalizedStringResource
+    public let description: LocalizedStringResource?
+    public let supportedContentTypes: [UTType]
+    public let requestValueDialog: IntentDialog?
+    public let inputConnectionBehavior: InputConnectionBehavior
+    private var value: Value?
+
+    public init(title: LocalizedStringResource, description: LocalizedStringResource? = nil, default defaultValue: Value? = nil,
+                supportedContentTypes: [UTType] = [], requestValueDialog: IntentDialog? = nil,
+                requestDisambiguationDialog: IntentDialog? = nil,
+                inputConnectionBehavior: InputConnectionBehavior = .default) {
+        self.title = title
+        self.description = description
+        self.value = defaultValue
+        self.supportedContentTypes = supportedContentTypes
+        self.requestValueDialog = requestValueDialog
+        self.inputConnectionBehavior = inputConnectionBehavior
+    }
+
+    /// `@Parameter(title: "Count") var count = 3`.
+    public convenience init(wrappedValue: Value, title: LocalizedStringResource, description: LocalizedStringResource? = nil,
+                            requestValueDialog: IntentDialog? = nil,
+                            inputConnectionBehavior: InputConnectionBehavior = .default) {
+        self.init(title: title, description: description, default: wrappedValue, requestValueDialog: requestValueDialog,
+                  inputConnectionBehavior: inputConnectionBehavior)
+    }
+
+    public var wrappedValue: Value {
+        get {
+            if let value { return value }
+            if let optional = Value.self as? _OptionalValue.Type { return optional._none as! Value }
+            fatalError("The intent parameter \"\(title)\" has no value: Shortcuts would ask for it, and the browser has no Shortcuts. Set it before performing the intent.")
+        }
+        set { value = newValue }
+    }
+
+    public var projectedValue: IntentParameter<Value> { self }
+}
+
+public typealias Parameter<Value> = IntentParameter<Value>
+
+/// A file passed to an intent.
+public struct IntentFile: Sendable {
+    public var data: Data
+    public var filename: String
+    public var fileURL: URL?
+    public var type: UTType?
+    public var removedOnCompletion = false
+
+    public init(data: Data, filename: String, type: UTType? = nil) {
+        self.data = data
+        self.filename = filename
+        self.type = type
+    }
+
+    /// Reads the file now.
+    public init(fileURL: URL, filename: String? = nil, type: UTType? = nil) {
+        self.data = (try? Data(contentsOf: fileURL)) ?? Data()
+        self.filename = filename ?? fileURL.lastPathComponent
+        self.fileURL = fileURL
+        self.type = type ?? UTType(filenameExtension: fileURL.pathExtension)
+    }
+}
+
+// MARK: - Display
+
+/// How Shortcuts would show a value: a title, a subtitle and an image (kept).
+public struct DisplayRepresentation: Sendable, ExpressibleByStringInterpolation {
+    public var title: LocalizedStringResource
+    public var subtitle: LocalizedStringResource?
+    public var image: Image?
+    public var synonyms: [LocalizedStringResource]
+
+    public init(title: LocalizedStringResource, subtitle: LocalizedStringResource? = nil, image: Image? = nil,
+                synonyms: [LocalizedStringResource] = []) {
+        self.title = title
+        self.subtitle = subtitle
+        self.image = image
+        self.synonyms = synonyms
+    }
+
+    public init(stringLiteral value: String) { self.init(title: LocalizedStringResource(stringLiteral: value)) }
+    public init(stringInterpolation: LocalizedStringResource.StringInterpolation) {
+        self.init(title: LocalizedStringResource(stringInterpolation: stringInterpolation))
+    }
+
+    /// A display image: a symbol, a catalog image, a URL or data, as given.
+    public struct Image: Sendable {
+        public enum DisplayStyle: Sendable { case `default`, circular }
+
+        public enum Source: Sendable {
+            case systemName(String)
+            case named(String)
+            case url(URL)
+            case data(Data)
+        }
+
+        public let source: Source
+        public let isTemplate: Bool?
+        public var displayStyle: DisplayStyle = .default
+        /// The tint of a symbol made with `init?(systemName:tintColor:symbolConfiguration:)`.
+        public private(set) var tintColor: UIColor?
+
+        public init(named name: String, isTemplate: Bool = false) { source = .named(name); self.isTemplate = isTemplate }
+        public init(systemName: String, isTemplate: Bool? = nil) { source = .systemName(systemName); self.isTemplate = isTemplate }
+        public init(url: URL, isTemplate: Bool? = nil) { source = .url(url); self.isTemplate = isTemplate }
+        public init(data: Data, isTemplate: Bool = false, displayStyle: DisplayStyle = .default) {
+            source = .data(data)
+            self.isTemplate = isTemplate
+            self.displayStyle = displayStyle
+        }
+
+        /// A tinted, configured symbol (the configuration is not used).
+        public init?(systemName: String, tintColor: UIColor?, symbolConfiguration: UIImage.SymbolConfiguration?) {
+            source = .systemName(systemName)
+            isTemplate = nil
+            self.tintColor = tintColor
+        }
+
+        /// The image as SwiftUI shows one.
+        public var swiftUIImage: SwiftUI.Image? {
+            switch source {
+            case .systemName(let name): SwiftUI.Image(systemName: name)
+            case .named(let name): SwiftUI.Image(name)
+            case .data(let data): UIImage(data: data).map(SwiftUI.Image.init(uiImage:))
+            case .url: nil
+            }
+        }
+    }
+}
+
+/// How Shortcuts would name a type ("Account").
+public struct TypeDisplayRepresentation: Sendable, ExpressibleByStringInterpolation {
+    public var name: LocalizedStringResource
+    public var numericFormat: LocalizedStringResource?
+    public var synonyms: [LocalizedStringResource]
+
+    public init(name: LocalizedStringResource, numericFormat: LocalizedStringResource? = nil, synonyms: [LocalizedStringResource] = []) {
+        self.name = name
+        self.numericFormat = numericFormat
+        self.synonyms = synonyms
+    }
+
+    public init(stringLiteral value: String) { self.init(name: LocalizedStringResource(stringLiteral: value)) }
+    public init(stringInterpolation: LocalizedStringResource.StringInterpolation) {
+        self.init(name: LocalizedStringResource(stringInterpolation: stringInterpolation))
+    }
+}
+
+// MARK: - Entities and enums
+
+/// A value of the app's that intents take, found through its `defaultQuery`.
+/// `Sendable`, as Apple's is: an entity of a main-actor module conforms
+/// without isolation.
+public protocol AppEntity: Identifiable, Sendable {
+    associatedtype DefaultQuery: EntityQuery
+    static var defaultQuery: DefaultQuery { get }
+    static var typeDisplayRepresentation: TypeDisplayRepresentation { get }
+    var displayRepresentation: DisplayRepresentation { get }
+}
+
+/// Finds entities by identifier (and suggests some). Shortcuts would call
+/// it; the app may too.
+public protocol EntityQuery: Sendable {
+    associatedtype Entity: AppEntity
+    init()
+    func entities(for identifiers: [Entity.ID]) async throws -> [Entity]
+    func suggestedEntities() async throws -> [Entity]
+    func defaultResult() async -> Entity?
+}
+
+extension EntityQuery {
+    public func suggestedEntities() async throws -> [Entity] { [] }
+    public func defaultResult() async -> Entity? { nil }
+}
+
+/// A query that also finds entities by text.
+public protocol EntityStringQuery: EntityQuery {
+    func entities(matching string: String) async throws -> [Entity]
+}
+
+/// A query whose entities can all be listed.
+public protocol EnumerableEntityQuery: EntityQuery {
+    func allEntities() async throws -> [Entity]
+}
+
+/// An enum that intents take, with how each case displays.
+public protocol AppEnum: RawRepresentable, CaseIterable, Hashable where RawValue: LosslessStringConvertible {
+    static var typeDisplayRepresentation: TypeDisplayRepresentation { get }
+    static var caseDisplayRepresentations: [Self: DisplayRepresentation] { get }
+}

package/Sources/AppIntents/Shortcuts.swift

@@ -0,0 +1,159 @@
+// App Shortcuts, and SwiftUI's controls that perform an intent.
+
+import Foundation
+import FoundationBridge
+import SwiftUI
+
+// MARK: - App Shortcuts
+
+/// The app's App Shortcuts. Nothing reads them in the browser: there is no
+/// Shortcuts app, Siri or Spotlight.
+public protocol AppShortcutsProvider {
+    @AppShortcutsBuilder static var appShortcuts: [AppShortcut] { get }
+    static var shortcutTileColor: ShortcutTileColor { get }
+}
+
+extension AppShortcutsProvider {
+    public static var shortcutTileColor: ShortcutTileColor { .automatic }
+    /// Does nothing: no system index to update.
+    public static func updateAppShortcutParameters() {}
+}
+
+public enum ShortcutTileColor: Sendable {
+    case automatic, red, tangerine, orange, yellow, lime, grayGreen, teal, lightBlue, blue, navy, purple, pink, grayBlue, grayBrown
+}
+
+@resultBuilder
+public enum AppShortcutsBuilder {
+    public static func buildExpression(_ shortcut: AppShortcut) -> [AppShortcut] { [shortcut] }
+    public static func buildBlock(_ components: [AppShortcut]...) -> [AppShortcut] { components.flatMap { $0 } }
+    public static func buildOptional(_ component: [AppShortcut]?) -> [AppShortcut] { component ?? [] }
+    public static func buildEither(first component: [AppShortcut]) -> [AppShortcut] { component }
+    public static func buildEither(second component: [AppShortcut]) -> [AppShortcut] { component }
+    public static func buildArray(_ components: [[AppShortcut]]) -> [AppShortcut] { components.flatMap { $0 } }
+    public static func buildLimitedAvailability(_ component: [AppShortcut]) -> [AppShortcut] { component }
+}
+
+/// An intent with the phrases that would run it, kept.
+public struct AppShortcut: Sendable {
+    public let intent: any AppIntent
+    public let phrases: [String]
+    public let shortTitle: LocalizedStringResource?
+    public let systemImageName: String?
+
+    public init<Intent: AppIntent>(intent: Intent, phrases: [AppShortcutPhrase<Intent>],
+                                   shortTitle: LocalizedStringResource, systemImageName: String) {
+        self.intent = intent
+        self.phrases = phrases.map(\.text)
+        self.shortTitle = shortTitle
+        self.systemImageName = systemImageName
+    }
+
+    public init<Intent: AppIntent>(intent: Intent, phrases: [AppShortcutPhrase<Intent>]) {
+        self.intent = intent
+        self.phrases = phrases.map(\.text)
+        self.shortTitle = nil
+        self.systemImageName = nil
+    }
+}
+
+/// A phrase that would run an intent: "Post in \(.applicationName)".
+public struct AppShortcutPhrase<Intent: AppIntent>: Sendable, ExpressibleByStringInterpolation {
+    /// The phrase, with `${applicationName}` and `${parameter}` placeholders as Apple writes them.
+    public let text: String
+
+    public init(stringLiteral value: String) { text = value }
+    public init(stringInterpolation: StringInterpolation) { text = stringInterpolation.text }
+
+    public struct StringInterpolation: StringInterpolationProtocol {
+        var text = ""
+        public init(literalCapacity: Int, interpolationCount: Int) {}
+        public mutating func appendLiteral(_ literal: String) { text += literal }
+        public mutating func appendInterpolation(_ token: AppShortcutPhraseToken) { text += "${\(token.name)}" }
+        public mutating func appendInterpolation<Value>(_ parameter: KeyPath<Intent, IntentParameter<Value>>) { text += "${parameter}" }
+    }
+}
+
+public struct AppShortcutPhraseToken: Sendable {
+    let name: String
+    public static let applicationName = AppShortcutPhraseToken(name: "applicationName")
+}
+
+// MARK: - Controls that perform an intent
+
+extension Button {
+    /// A button that performs `intent` when tapped (in a task on the main
+    /// actor; a thrown error is dropped, as SwiftUI only logs it).
+    public init(role: ButtonRole? = nil, intent: some AppIntent, @ViewBuilder label: () -> Label) {
+        self.init(role: role, action: _perform(intent), label: label)
+    }
+}
+
+extension Button where Label == Text {
+    public init(_ titleKey: LocalizedStringKey, role: ButtonRole? = nil, intent: some AppIntent) {
+        self.init(titleKey, role: role, action: _perform(intent))
+    }
+
+    @_disfavoredOverload
+    public init<S: StringProtocol>(_ title: S, role: ButtonRole? = nil, intent: some AppIntent) {
+        self.init(title, role: role, action: _perform(intent))
+    }
+}
+
+extension Button where Label == SwiftUI.Label<Text, Image> {
+    public init(_ titleKey: LocalizedStringKey, systemImage: String, role: ButtonRole? = nil, intent: some AppIntent) {
+        self.init(titleKey, systemImage: systemImage, role: role, action: _perform(intent))
+    }
+
+    @_disfavoredOverload
+    public init<S: StringProtocol>(_ title: S, systemImage: String, role: ButtonRole? = nil, intent: some AppIntent) {
+        self.init(title, systemImage: systemImage, role: role, action: _perform(intent))
+    }
+}
+
+extension Toggle {
+    /// A toggle that performs `intent` when switched (the intent sets the state the binding reads).
+    public init(isOn: Bool, intent: some AppIntent, @ViewBuilder label: () -> Label) {
+        let action = _perform(intent)
+        self.init(isOn: Binding(get: { isOn }, set: { _ in MainActor.assumeIsolated { action() } }), label: label)
+    }
+}
+
+/// The action that performs `intent`.
+func _perform<Intent: AppIntent>(_ intent: Intent) -> @MainActor () -> Void {
+    { Task { @MainActor in _ = try? await intent.perform() } }
+}
+
+// MARK: - Siri tips and Shortcuts links
+
+/// A tip suggesting the phrase that runs an intent with Siri. There is no
+/// Siri in the browser, so it draws nothing, as when iOS has nothing to suggest.
+public struct SiriTipView: View {
+    public init(intent: some AppIntent, isVisible: Binding<Bool> = .constant(true)) {}
+    public var body: some View { EmptyView() }
+}
+
+/// How a `SiriTipView` is drawn; kept.
+public enum SiriTipViewStyle: Sendable {
+    case automatic, light, dark, black
+}
+
+extension View {
+    public func siriTipViewStyle(_ style: SiriTipViewStyle) -> some View { self }
+}
+
+/// A button that opens the app's page in the Shortcuts app. There is no
+/// Shortcuts app in the browser, so it draws nothing.
+public struct ShortcutsLink: View {
+    public init(action: (() -> Void)? = nil) {}
+    public var body: some View { EmptyView() }
+}
+
+/// How a `ShortcutsLink` is drawn; kept.
+public enum ShortcutsLinkStyle: Sendable {
+    case automatic, automaticOutline, light, lightOutline, dark, darkOutline
+}
+
+extension View {
+    public func shortcutsLinkStyle(_ style: ShortcutsLinkStyle) -> some View { self }
+}

package/Sources/AudioToolbox/AudioToolbox.swift

@@ -0,0 +1,55 @@
+// `import AudioToolbox` for the browser: System Sound Services, which apps
+// use for short sound effects and the vibration "sound". The page has no
+// audio player for the app yet (AVFoundation is empty for the same reason),
+// so a registered sound gets an ID and playing it is silent; vibration is
+// silent too. Ice Cubes registers its effects (`pull`, `refresh`, …) this way.
+
+import Foundation
+// `OSStatus`, `CFURL`
+@_exported import CoreFoundationTypes
+
+public typealias SystemSoundID = UInt32
+
+public let kAudioServicesNoError: OSStatus = 0
+public let kAudioServicesBadSpecifierSizeError: OSStatus = 0x7E73697A  // '!siz'
+public let kAudioServicesSystemSoundUnspecifiedError: OSStatus = -1500
+public let kAudioServicesSystemSoundClientTimedOutError: OSStatus = -1501
+
+/// The "sound" that vibrates an iPhone.
+public let kSystemSoundID_Vibrate: SystemSoundID = 0x00000FFF
+
+nonisolated(unsafe) private var registered: [SystemSoundID: URL] = [:]
+nonisolated(unsafe) private var nextID: SystemSoundID = 4096 + 1
+
+/// Registers the sound file at `inFileURL` and writes its ID. The file must
+/// exist; it is never played.
+@discardableResult
+public func AudioServicesCreateSystemSoundID(_ inFileURL: CFURL, _ outSystemSoundID: UnsafeMutablePointer<SystemSoundID>) -> OSStatus {
+    guard FileManager.default.fileExists(atPath: inFileURL.path) else { return kAudioServicesSystemSoundUnspecifiedError }
+    let id = nextID
+    nextID += 1
+    registered[id] = inFileURL
+    outSystemSoundID.pointee = id
+    return kAudioServicesNoError
+}
+
+@discardableResult
+public func AudioServicesDisposeSystemSoundID(_ inSystemSoundID: SystemSoundID) -> OSStatus {
+    registered[inSystemSoundID] = nil
+    return kAudioServicesNoError
+}
+
+/// Silent: the page has no audio player for the app.
+public func AudioServicesPlaySystemSound(_ inSystemSoundID: SystemSoundID) {}
+
+/// Silent; calls `inCompletionBlock` at once.
+public func AudioServicesPlaySystemSoundWithCompletion(_ inSystemSoundID: SystemSoundID, _ inCompletionBlock: (@Sendable () -> Void)?) {
+    inCompletionBlock?()
+}
+
+/// Silent: the browser has no haptics.
+public func AudioServicesPlayAlertSound(_ inSystemSoundID: SystemSoundID) {}
+
+public func AudioServicesPlayAlertSoundWithCompletion(_ inSystemSoundID: SystemSoundID, _ inCompletionBlock: (@Sendable () -> Void)?) {
+    inCompletionBlock?()
+}