Add action widgets, open page widgets, and gauges on the Lock Screen (#…

…2830)

<!-- Thank you for submitting a Pull Request and helping to improve Home
Assistant. Please complete the following sections to help the processing
and review of your changes. Please do not delete anything from this
template. -->

## Summary
Allow action widget, open page widget, and watchOS style complications
to be available on the iOS Lock Screen.

## Screenshots
<img width="1163" alt="Screenshot 2024-06-30 at 9 28 19 AM"
src="https://github.com/home-assistant/iOS/assets/62899372/be0fd76e-ae4a-494d-b564-9e467533087e">
<img width="722" alt="Screenshot 2024-06-30 at 11 17 13 AM"
src="https://github.com/home-assistant/iOS/assets/62899372/d9ac98c8-acf4-4001-9a0c-461ba794c0ee">
<img width="677" alt="Screenshot 2024-06-30 at 9 29 26 AM"
src="https://github.com/home-assistant/iOS/assets/62899372/6c2be522-dd78-4325-93e5-29e75ec20576">


## Link to pull request in Documentation repository
<!-- Pull requests that add, change or remove functionality must have a
corresponding pull request in the Companion App Documentation repository
(https://github.com/home-assistant/companion.home-assistant). Please add
the number of this pull request after the "#" -->
Documentation: home-assistant/companion.home-assistant#

## Any other notes
<!-- If there is any other information of note, like if this Pull
Request is part of a bigger change, please include it here. -->

---------

Co-authored-by: Bruno Pantaleão Gonçalves <bruno.ing879@gmail.com>

Sources/App/Resources/en.lproj/Localizable.strings

@@ -844,6 +844,7 @@ Home Assistant is free and open source home automation software with a focus on
 "watch.labels.complication_text_areas.trailing.label" = "Trailing";
 "watch.labels.no_action" = "No actions configured. Configure actions on your phone to dismiss this message.";
 "watch.placeholder_complication_name" = "Placeholder";
+"widgets.actions.parameters.action" = "Action";
 "widgets.actions.description" = "Perform Home Assistant actions.";
 "widgets.actions.not_configured" = "No Actions Configured";
 "widgets.actions.title" = "Actions";
@@ -855,4 +856,24 @@ Home Assistant is free and open source home automation software with a focus on
 "widgets.open_page.description" = "Open a frontend page in Home Assistant.";
 "widgets.open_page.not_configured" = "No Pages Available";
 "widgets.open_page.title" = "Open Page";
+"widgets.gauge.parameters.gauge_type" = "Gauge Type";
+"widgets.gauge.parameters.gauge_type.normal" = "Normal";
+"widgets.gauge.parameters.gauge_type.capacity" = "Capacity";
+"widgets.gauge.parameters.server" = "Server";
+"widgets.gauge.parameters.value_template" = "Value Template (0-1)";
+"widgets.gauge.parameters.value_label_template" = "Value Label Template";
+"widgets.gauge.parameters.min_label_template" = "Min Label Template";
+"widgets.gauge.parameters.max_label_template" = "Max Label Template";
+"widgets.gauge.parameters.run_action" = "Run Action";
+"widgets.gauge.parameters.action" = "Action";
+"widgets.gauge.description" = "Display numeric states from Home Assistant in a gauge";
+"widgets.gauge.title" = "Gauge";
+"widgets.details.parameters.server" = "Server";
+"widgets.details.parameters.upper_template" = "Upper Text Template";
+"widgets.details.parameters.lower_template" = "Lower Text Template";
+"widgets.details.parameters.details_template" = "Details Text Template (only in rectangular family)";
+"widgets.details.parameters.run_action" = "Run Action (only in rectangular family)";
+"widgets.details.parameters.action" = "Action";
+"widgets.details.description" = "Display states using from Home Assistant in text";
+"widgets.details.title" = "Details";
 "yes_label" = "Yes";

Sources/Extensions/AppIntents/IntentServerAppEntitiy.swift

@@ -0,0 +1,60 @@
+import AppIntents
+import Foundation
+import Shared
+
+@available(iOS 16.0, macOS 13.0, watchOS 9.0, tvOS 16.0, *)
+struct IntentServerAppEntity: AppEntity, Sendable {
+ static let typeDisplayRepresentation = TypeDisplayRepresentation(name: "MaterialDesignIcons")
+
+ struct IntentServerAppEntityQuery: EntityQuery, EntityStringQuery {
+ func entities(for identifiers: [IntentServerAppEntity.ID]) async throws -> [IntentServerAppEntity] {
+ getServerEntities().filter { identifiers.contains($0.id) }
+ }
+
+ func entities(matching string: String) async throws -> [IntentServerAppEntity] {
+ getServerEntities().filter { $0.getInfo()?.remoteName.contains(string) ?? false }
+ }
+
+ func suggestedEntities() async throws -> [IntentServerAppEntity] {
+ getServerEntities()
+ }
+
+ private func getServerEntities() -> [IntentServerAppEntity] {
+ Current.servers.all.map { IntentServerAppEntity(from: $0) }
+ }
+
+ func defaultResult() async -> IntentServerAppEntity? {
+ let server = Current.servers.all.first
+ if server == nil {
+ return nil
+ } else {
+ return IntentServerAppEntity(from: server!)
+ }
+ }
+ }
+
+ static let defaultQuery = IntentServerAppEntityQuery()
+
+ var id: String
+ var displayRepresentation: DisplayRepresentation {
+ DisplayRepresentation(
+ title: .init(stringLiteral: getInfo()?.name ?? "Unknown")
+ )
+ }
+
+ init(identifier: Identifier<Server>) {
+ self.id = identifier.rawValue
+ }
+
+ init(from server: Server) {
+ self.init(identifier: server.identifier)
+ }
+
+ func getServer() -> Server? {
+ Current.servers.server(for: .init(rawValue: id))
+ }
+
+ func getInfo() -> ServerInfo? {
+ getServer()?.info
+ }
+}

Sources/Extensions/AppIntents/Widget/Details/WidgetDetailsAppIntent.swift

@@ -0,0 +1,92 @@
+import AppIntents
+import AudioToolbox
+import Foundation
+import Shared
+
+@available(iOS 17.0, macOS 14.0, watchOS 10.0, *)
+struct WidgetDetailsAppIntent: WidgetConfigurationIntent {
+ static let title: LocalizedStringResource = .init("widgets.details.title", defaultValue: "Details")
+ static let description = IntentDescription(
+ .init("widgets.details.description", defaultValue: "Display states using from Home Assistant in text")
+ )
+
+ @Parameter(title: .init("widgets.details.parameters.server", defaultValue: "Server"), default: nil)
+ var server: IntentServerAppEntity
+
+ @Parameter(
+ title: .init("widgets.details.parameters.upper_template", defaultValue: "Upper Text Template"),
+ default: "",
+ inputOptions: .init(
+ capitalizationType: .none,
+ multiline: true,
+ autocorrect: false,
+ smartQuotes: false,
+ smartDashes: false
+ )
+ )
+ var upperTemplate: String
+
+ @Parameter(
+ title: .init("widgets.details.parameters.lower_template", defaultValue: "Lower Text Template"),
+ default: "",
+ inputOptions: .init(
+ capitalizationType: .none,
+ multiline: true,
+ autocorrect: false,
+ smartQuotes: false,
+ smartDashes: false
+ )
+ )
+ var lowerTemplate: String
+
+ @Parameter(
+ title: .init(
+ "widgets.details.parameters.details_template",
+ defaultValue: "Details Text Template (only in rectangular family)"
+ ),
+ default: "",
+ inputOptions: .init(
+ capitalizationType: .none,
+ multiline: true,
+ autocorrect: false,
+ smartQuotes: false,
+ smartDashes: false
+ )
+ )
+ var detailsTemplate: String
+
+ @Parameter(
+ title: .init("widgets.details.parameters.run_action", defaultValue: "Run Action (only in rectangular family)"),
+ default: false
+ )
+ var runAction: Bool
+
+ @Parameter(
+ title: .init("widgets.details.parameters.action", defaultValue: "Action"),
+ default: nil
+ )
+ var action: IntentActionAppEntity?
+
+ static var parameterSummary: some ParameterSummary {
+ When(\WidgetDetailsAppIntent.$runAction, .equalTo, true) {
+ Summary {
+ \.$server
+ \.$upperTemplate
+ \.$lowerTemplate
+ \.$detailsTemplate
+
+ \.$runAction
+ \.$action
+ }
+ } otherwise: {
+ Summary {
+ \.$server
+ \.$upperTemplate
+ \.$lowerTemplate
+ \.$detailsTemplate
+
+ \.$runAction
+ }
+ }
+ }
+}

Sources/Extensions/AppIntents/Widget/Details/WidgetDetailsAppIntentTimelineProvider.swift

@@ -0,0 +1,134 @@
+import AppIntents
+import HAKit
+import RealmSwift
+import Shared
+import WidgetKit
+
+@available(iOS 17, *)
+struct WidgetDetailsAppIntentTimelineProvider: AppIntentTimelineProvider {
+ typealias Entry = WidgetDetailsEntry
+ typealias Intent = WidgetDetailsAppIntent
+
+ func snapshot(for configuration: WidgetDetailsAppIntent, in context: Context) async -> WidgetDetailsEntry {
+ do {
+ return try await entry(for: configuration, in: context)
+ } catch {
+ Current.Log.debug("Using placeholder for gauge widget snapshot")
+ return placeholder(in: context)
+ }
+ }
+
+ func timeline(for configuration: WidgetDetailsAppIntent, in context: Context) async -> Timeline<Entry> {
+ do {
+ let snapshot = try await entry(for: configuration, in: context)
+ return .init(
+ entries: [snapshot],
+ policy: .after(
+ Current.date()
+ .addingTimeInterval(WidgetDetailsDataSource.expiration.converted(to: .seconds).value)
+ )
+ )
+ } catch {
+ Current.Log.debug("Using placeholder for gauge widget")
+ return .init(
+ entries: [placeholder(in: context)],
+ policy: .after(
+ Current.date()
+ .addingTimeInterval(WidgetDetailsDataSource.expiration.converted(to: .seconds).value)
+ )
+ )
+ }
+ }
+
+ func placeholder(in context: Context) -> WidgetDetailsEntry {
+ .init(
+ upperText: nil, lowerText: nil, detailsText: nil,
+ runAction: false, action: nil
+ )
+ }
+
+ private func entry(for configuration: WidgetDetailsAppIntent, in context: Context) async throws -> Entry {
+ guard Current.servers.all.count > 0 else {
+ Current.Log.error("Failed to fetch data for details widget: No servers exist")
+ throw WidgetDetailsDataError.noServers
+ }
+
+ let server = configuration.server.getServer() ?? Current.servers.all.first!
+ let api = Current.api(for: server)
+
+ let upperTemplate = !configuration.upperTemplate.isEmpty ? configuration.upperTemplate : "?"
+ let lowerTemplate = !configuration.lowerTemplate.isEmpty ? configuration.lowerTemplate : "?"
+ let detailsTemplate = !configuration.detailsTemplate.isEmpty ? configuration.detailsTemplate : "?"
+ let template = "\(upperTemplate)|\(lowerTemplate)|\(detailsTemplate)"
+
+ let result = await withCheckedContinuation { continuation in
+ api.connection.send(.init(
+ type: .rest(.post, "template"),
+ data: ["template": template],
+ shouldRetry: true
+ )) { result in
+ continuation.resume(returning: result)
+ }
+ }
+
+ var data: HAData?
+ switch result {
+ case let .success(resultData):
+ data = resultData
+ case let .failure(error):
+ Current.Log.error("Failed to render template for details widget: \(error)")
+ throw WidgetDetailsDataError.apiError
+ }
+
+ var renderedTemplate: String?
+ switch data! {
+ case let .primitive(response):
+ renderedTemplate = response as? String
+ default:
+ Current.Log.error("Failed to render template for details widget: Bad response data")
+ throw WidgetDetailsDataError.badResponse
+ }
+
+ let params = renderedTemplate!.split(separator: "|")
+ guard params.count == 3 else {
+ Current.Log.error("Failed to render template for details widget: Wrong length response")
+ throw WidgetDetailsDataError.badResponse
+ }
+
+ let upperText = String(params[0])
+ let lowerText = String(params[1])
+ let detailsText = String(params[2])
+ return .init(
+ upperText: upperText != "?" ? upperText : nil,
+ lowerText: lowerText != "?" ? lowerText : nil,
+ detailsText: detailsText != "?" ? detailsText : nil,
+
+ runAction: configuration.runAction,
+ action: configuration.action?.asAction()
+ )
+ }
+}
+
+enum WidgetDetailsDataSource {
+ static var expiration: Measurement<UnitDuration> {
+ .init(value: 15, unit: .minutes)
+ }
+}
+
+@available(iOS 17, *)
+struct WidgetDetailsEntry: TimelineEntry {
+ var date = Date()
+
+ var upperText: String?
+ var lowerText: String?
+ var detailsText: String?
+
+ var runAction: Bool
+ var action: Action?
+}
+
+enum WidgetDetailsDataError: Error {
+ case noServers
+ case apiError
+ case badResponse
+}