@use-voltra/ios-client 2.3.1 → 2.4.0

package/ios/ui/Modifiers/VoltraModifierRegistry.swift

@@ -0,0 +1,181 @@
+import Foundation
+import os
+import SwiftUI
+#if canImport(VoltraSharedCore)
+  // The Swift package splits the SwiftUI-free parsing layer into its own module; the podspec
+  // compiles both folders into one.
+  import VoltraSharedCore
+#endif
+
+enum VoltraModifierError: Error, Equatable {
+  case missingParameter(String)
+  case invalidParameter(String)
+  case unexpectedParameter(String)
+}
+
+/// A native modifier: the parameter names its TypeScript factory may send, and how to build it.
+/// Declaring the names makes a renamed parameter fail the parity test instead of silently
+/// falling back to a default.
+struct VoltraModifierDefinition {
+  let parameters: Set<String>
+  let make: ([String: Any]) throws -> any ViewModifier
+}
+
+/// String-keyed table of native modifiers. Unknown types and parameters that do not decode are
+/// logged and skipped, so a bad descriptor never breaks the widget.
+enum VoltraModifierRegistry {
+  private static let logger = Logger(subsystem: "com.voltra", category: "modifier")
+
+  private(set) static var definitions: [String: VoltraModifierDefinition] = builtInModifierDefinitions
+
+  static var registeredTypes: Set<String> {
+    Set(definitions.keys)
+  }
+
+  /// Not public yet: user-registered modifiers are future work (ADR 0005).
+  static func register(_ type: String, definition: VoltraModifierDefinition) {
+    definitions[type] = definition
+  }
+
+  /// Decodes the JSON-encoded `modifiers` prop. Entries without a string `$type` are dropped.
+  static func parseDescriptors(_ json: String?) -> [VoltraModifierDescriptor] {
+    VoltraModifierDescriptor.parseList(json)
+  }
+
+  /// Builds the modifier for a descriptor, or `nil` when the type is unknown.
+  static func makeModifier(_ descriptor: VoltraModifierDescriptor) throws -> (any ViewModifier)? {
+    guard let definition = definitions[descriptor.type] else { return nil }
+    if let unexpected = descriptor.params.keys.sorted().first(where: { !definition.parameters.contains($0) }) {
+      throw VoltraModifierError.unexpectedParameter(unexpected)
+    }
+    return try definition.make(descriptor.params)
+  }
+
+  /// Whether the descriptor names a known modifier whose parameters decode, so applying it
+  /// changes the view. Hosts use it before dropping a default the modifier would replace.
+  static func canApply(_ descriptor: VoltraModifierDescriptor) -> Bool {
+    (try? makeModifier(descriptor)) != nil
+  }
+
+  static func apply<Content: View>(_ descriptor: VoltraModifierDescriptor, to content: Content) -> AnyView {
+    do {
+      guard let modifier = try makeModifier(descriptor) else {
+        logger.warning("Ignoring unknown modifier \(descriptor.type, privacy: .public)")
+        return AnyView(content)
+      }
+      return erase(content, modifier)
+    } catch {
+      logger.warning("Ignoring modifier \(descriptor.type, privacy: .public): \(String(describing: error), privacy: .public)")
+      return AnyView(content)
+    }
+  }
+
+  private static func erase<Content: View, Modifier: ViewModifier>(_ content: Content, _ modifier: Modifier) -> AnyView {
+    AnyView(content.modifier(modifier))
+  }
+}
+
+/// Every link of a native modifier chain has this one type, so the outer shape of the view
+/// depends only on the length of the list. Inside a link, the erased type is the concrete
+/// modifier: value changes of the same modifier diff and animate, while a different `$type` at a
+/// position (or an entry that stops decoding) rebuilds the wrapped component.
+struct VoltraStableModifier: ViewModifier {
+  let descriptor: VoltraModifierDescriptor
+
+  @Environment(\.voltraHostAppliedModifierTypes) private var hostAppliedModifierTypes
+
+  func body(content: Content) -> some View {
+    // The widget host applies this modifier itself with a configured value that takes
+    // precedence; applying the tree's as well would leave SwiftUI two of them.
+    hostAppliedModifierTypes.contains(descriptor.type)
+      ? AnyView(content)
+      : VoltraModifierRegistry.apply(descriptor, to: content)
+  }
+}
+
+private struct VoltraHostAppliedModifierTypesKey: EnvironmentKey {
+  static let defaultValue: Set<String> = []
+}
+
+extension EnvironmentValues {
+  /// Native modifier types that a widget or Live Activity host applies outside the rendered tree,
+  /// so the tree's own descriptors of these types are skipped.
+  var voltraHostAppliedModifierTypes: Set<String> {
+    get { self[VoltraHostAppliedModifierTypesKey.self] }
+    set { self[VoltraHostAppliedModifierTypesKey.self] = newValue }
+  }
+}
+
+extension View {
+  /// Applies native modifiers in array order: the first descriptor is innermost.
+  @ViewBuilder
+  func applyNativeModifiers(_ descriptors: [VoltraModifierDescriptor]) -> some View {
+    if descriptors.isEmpty {
+      self
+    } else {
+      descriptors.reduce(AnyView(self)) { view, descriptor in
+        AnyView(view.modifier(VoltraStableModifier(descriptor: descriptor)))
+      }
+    }
+  }
+}
+
+// MARK: - Parameter decoding
+
+extension [String: Any] {
+  func requiredString(_ key: String) throws -> String {
+    guard let string = try optionalString(key) else { throw VoltraModifierError.missingParameter(key) }
+    return string
+  }
+
+  func optionalString(_ key: String) throws -> String? {
+    guard let value = self[key], !(value is NSNull) else { return nil }
+    guard let string = value as? String else { throw VoltraModifierError.invalidParameter(key) }
+    return string
+  }
+
+  func requiredNumber(_ key: String) throws -> CGFloat {
+    guard let number = try optionalNumber(key) else { throw VoltraModifierError.missingParameter(key) }
+    return number
+  }
+
+  /// A color string in any form `style` accepts; JSON `null` means "system default".
+  func optionalColor(_ key: String) throws -> Color? {
+    guard let string = try optionalString(key) else { return nil }
+    guard let color = JSColorParser.parse(string) else { throw VoltraModifierError.invalidParameter(key) }
+    return color
+  }
+
+  func requiredColor(_ key: String) throws -> Color {
+    guard let color = try optionalColor(key) else { throw VoltraModifierError.missingParameter(key) }
+    return color
+  }
+
+  func requiredEnum<Option: RawRepresentable>(_ key: String, as _: Option.Type = Option.self) throws -> Option where Option.RawValue == String {
+    guard let option = try Option(rawValue: requiredString(key)) else { throw VoltraModifierError.invalidParameter(key) }
+    return option
+  }
+
+  func optionalEnum<Option: RawRepresentable>(_ key: String, as _: Option.Type = Option.self) throws -> Option? where Option.RawValue == String {
+    guard let string = try optionalString(key) else { return nil }
+    guard let option = Option(rawValue: string) else { throw VoltraModifierError.invalidParameter(key) }
+    return option
+  }
+
+  func optionalBool(_ key: String) throws -> Bool? {
+    guard let value = self[key], !(value is NSNull) else { return nil }
+    // JSONSerialization bridges JSON booleans to NSNumber; reject plain numbers.
+    guard let number = value as? NSNumber, CFGetTypeID(number) == CFBooleanGetTypeID() else {
+      throw VoltraModifierError.invalidParameter(key)
+    }
+    return number.boolValue
+  }
+
+  func optionalNumber(_ key: String) throws -> CGFloat? {
+    guard let value = self[key], !(value is NSNull) else { return nil }
+    guard let number = value as? NSNumber, CFGetTypeID(number) != CFBooleanGetTypeID() else {
+      throw VoltraModifierError.invalidParameter(key)
+    }
+    return CGFloat(number.doubleValue)
+  }
+}

package/ios/ui/Modifiers/VoltraRootDefaults.swift

@@ -0,0 +1,100 @@
+import os
+import SwiftUI
+import WidgetKit
+#if canImport(VoltraSharedCore)
+  import VoltraSharedCore
+#endif
+
+/// The native modifiers in a rendered tree that replace a host default, found in one walk so a
+/// host that checks both pays for a single pass.
+struct VoltraRootModifiers {
+  let setsWidgetURL: Bool
+  let setsContainerBackground: Bool
+
+  init(root: VoltraNode?) {
+    let found = root?.nativeModifierTypes(among: ["widgetURL", "containerBackground"]) ?? []
+    setsWidgetURL = found.contains("widgetURL")
+    setsContainerBackground = found.contains("containerBackground")
+  }
+
+  private static let logger = Logger(subsystem: "com.voltra", category: "modifier")
+
+  /// A tap on the compact or minimal Dynamic Island opens only `DynamicIsland.widgetURL`, which
+  /// hosts set from the configured deep link; a `widgetURL` inside these regions is not used.
+  static let islandTapRegions: Set<VoltraRegion> = [.islandCompactLeading, .islandCompactTrailing, .islandMinimal]
+
+  /// Warns when a compact or minimal Dynamic Island region sets `widgetURL` with no deep link
+  /// configured, because tapping the island then opens the app without a URL.
+  static func warnIfIslandIgnoresWidgetURL(in region: VoltraRegion, root: VoltraNode?, configured: URL?) {
+    guard configured == nil, islandTapRegions.contains(region), VoltraRootModifiers(root: root).setsWidgetURL else {
+      return
+    }
+    logger.warning(
+      "widgetURL in the Dynamic Island region \(region.rawValue, privacy: .public) does not set where a tap opens; pass deepLinkUrl when starting the Live Activity"
+    )
+  }
+}
+
+/// Defaults that widget and Live Activity hosts apply outside the rendered tree (ADR 0005). Host
+/// code calls these instead of naming modifiers.
+extension View {
+  /// Sets the tap URL of a view hierarchy that carries at most one `widgetURL`; Apple leaves several
+  /// undefined. A configured deep link takes precedence and the tree's `widgetURL` modifiers are
+  /// skipped. Otherwise a `widgetURL` modifier in the tree wins over the synthetic fallback.
+  @ViewBuilder
+  func voltraWidgetURL(configured: URL?, tree: VoltraRootModifiers? = nil, fallback: () -> URL? = { nil }) -> some View {
+    if let configured {
+      voltraHostApplies("widgetURL")
+        .widgetURL(configured)
+    } else if tree?.setsWidgetURL == true {
+      self
+    } else if let url = fallback() {
+      widgetURL(url)
+    } else {
+      self
+    }
+  }
+
+  /// For a Dynamic Island region: a configured deep link is set once on the `DynamicIsland`, which
+  /// makes it the default for every region, so the region only drops the tree's `widgetURL`
+  /// modifiers that would override it.
+  @ViewBuilder
+  func voltraDeferringWidgetURL(to configured: URL?) -> some View {
+    if configured != nil {
+      voltraHostApplies("widgetURL")
+    } else {
+      self
+    }
+  }
+
+  /// Tints a Live Activity's Lock Screen background with the tint passed when starting or updating
+  /// it, which takes precedence over an `activityBackgroundTint` modifier in the tree.
+  @ViewBuilder
+  func voltraActivityBackgroundTint(configured: Color?) -> some View {
+    if let configured {
+      voltraHostApplies("activityBackgroundTint")
+        .activityBackgroundTint(configured)
+    } else {
+      self
+    }
+  }
+
+  /// Clears the widget's container background, unless the tree sets its own with a
+  /// `containerBackground` modifier.
+  @ViewBuilder
+  func voltraDefaultContainerBackground(tree: VoltraRootModifiers) -> some View {
+    if tree.setsContainerBackground {
+      self
+    } else if #available(iOS 17.0, *) {
+      containerBackground(.clear, for: .widget)
+    } else {
+      self
+    }
+  }
+
+  /// Marks a native modifier type as applied by the host, so the tree's descriptors of that type
+  /// are skipped. Adds to the set, so several host defaults compose.
+  private func voltraHostApplies(_ type: String) -> some View {
+    transformEnvironment(\.voltraHostAppliedModifierTypes) { $0.insert(type) }
+  }
+}

package/ios/ui/Style/TextStyle.swift

@@ -6,7 +6,9 @@ struct TextStyle {
   var fontSize: CGFloat = 17
   var fontWeight: Font.Weight = .regular
   var fontFamily: String?
-  var alignment: TextAlignment = .leading
+  /// Only set when `textAlign` is given, so an unset alignment leaves the inherited value, such
+  /// as a `multilineTextAlignment` native modifier, in effect.
+  var alignment: TextAlignment?
   var lineLimit: Int?
   var lineSpacing: CGFloat = 0 // Extra space between lines
   var decoration: TextDecoration = .none
@@ -43,7 +45,7 @@ struct TextStyleModifier: ViewModifier {
       // 2. Color
       .foregroundColor(resolvedColor)
       // 3. Layout / Spacing
-      .multilineTextAlignment(style.alignment)
+      .voltraIfLet(style.alignment) { view, alignment in view.multilineTextAlignment(alignment) }
       .lineLimit(style.lineLimit)
       .lineSpacing(style.lineSpacing)
   }

package/ios/ui/Style/View+applyStyle.swift

@@ -25,7 +25,7 @@ extension View {
 
   func applyStyle(_ style: (LayoutStyle, DecorationStyle, RenderingStyle, TextStyle), contentAlignment: Alignment? = nil) -> some View {
     let (layout, decoration, rendering, text) = style
-    let frameAlignment = contentAlignment ?? Alignment(horizontal: text.alignment.horizontalAlignment, vertical: .top)
+    let frameAlignment = contentAlignment ?? Alignment(horizontal: (text.alignment ?? .leading).horizontalAlignment, vertical: .top)
     return self
       // 1. Text Properties (Propagate font size for measurement)
       .modifier(TextStyleModifier(style: text))

package/ios/ui/Views/VoltraText.swift

@@ -51,13 +51,9 @@ public struct VoltraText: VoltraView {
       return baseFont
     }
 
-    let alignment: TextAlignment = {
-      // Parameter takes precedence over style
-      if let mta = params.multilineTextAlignment {
-        return JSStyleParser.textAlignment(mta)
-      }
-      return textStyle.alignment
-    }()
+    // Parameter takes precedence over style. Without either, the inherited alignment applies, so a
+    // `multilineTextAlignment` native modifier on this Text or a container is not overridden.
+    let alignment: TextAlignment? = params.multilineTextAlignment.map { JSStyleParser.textAlignment($0) } ?? textStyle.alignment
 
     let resolvedColor: Color = {
       if let widget = voltraEnvironment.widget,
@@ -77,7 +73,7 @@ public struct VoltraText: VoltraView {
       // These technically work on View, but good to keep close
       .font(font)
       .foregroundColor(resolvedColor)
-      .multilineTextAlignment(alignment)
+      .voltraIfLet(alignment) { view, alignment in view.multilineTextAlignment(alignment) }
       .lineSpacing(textStyle.lineSpacing)
       .voltraIfLet(params.numberOfLines) { view, numberOfLines in
         view.lineLimit(Int(numberOfLines))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@use-voltra/ios-client",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "description": "Client-only Voltra APIs for iOS",
   "main": "./build/commonjs/index.js",
   "module": "./build/module/index.js",
@@ -39,9 +39,9 @@
     "@expo/plist": "^0.3.5",
     "dedent": "^1.7.1",
     "xcode": "^3.0.1",
-    "@use-voltra/compiler": "^2.3.1",
-    "@use-voltra/expo-plugin": "^2.3.1",
-    "@use-voltra/ios": "^2.3.1"
+    "@use-voltra/compiler": "^2.4.0",
+    "@use-voltra/expo-plugin": "^2.4.0",
+    "@use-voltra/ios": "^2.4.0"
   },
   "peerDependencies": {
     "expo": "*",

package/src/dynamic-widget/api.ts

@@ -23,3 +23,31 @@ export const updateDynamicWidget = async (
 
   return getNativeVoltra().updateDynamicWidget(dynamicWidgetId, dynamicWidgetPropsJson)
 }
+
+/**
+ * Render Dynamic Widgets and Dynamic Live Activities in a language the app chooses.
+ *
+ * iOS 17 and 18 do not pass a per-app language chosen in Settings to widget extensions, and apps
+ * with their own language setting have no other way to reach them. The tag (BCP-47, for example
+ * `"pl"` or `"pt-BR"`) is stored in the App Group and reaches every render as `env.appLocale`;
+ * `resolveLocale` gives it precedence over the user's system languages. Pass `null` to clear it.
+ *
+ * Widgets reload and running Dynamic Live Activities re-render once the value is stored.
+ * Requires `groupIdentifier` in the Voltra config plugin, and rejects without one.
+ */
+export const setDynamicWidgetLocale = async (tag: string | null): Promise<void> => {
+  if (!assertRunningOnApple()) return Promise.resolve()
+
+  return getNativeVoltra().setDynamicWidgetLocale(normalizeDynamicWidgetLocale(tag))
+}
+
+function normalizeDynamicWidgetLocale(tag: string | null): string | null {
+  if (tag === null) {
+    return null
+  }
+  if (typeof tag !== 'string') {
+    throw new TypeError('setDynamicWidgetLocale expects a BCP-47 language tag or null.')
+  }
+  const trimmed = tag.trim().replace(/_/g, '-')
+  return trimmed.length === 0 ? null : trimmed
+}

package/src/index.ts

@@ -5,7 +5,12 @@ export {
 } from './components/VoltraLiveActivityPreview.js'
 export { VoltraView, type VoltraViewProps } from './components/VoltraView.js'
 export { VoltraWidgetPreview, type VoltraWidgetPreviewProps } from './components/VoltraWidgetPreview.js'
-export { type DynamicWidgetProps, type DynamicWidgetPropsValue, updateDynamicWidget } from './dynamic-widget/api.js'
+export {
+  type DynamicWidgetProps,
+  type DynamicWidgetPropsValue,
+  setDynamicWidgetLocale,
+  updateDynamicWidget,
+} from './dynamic-widget/api.js'
 export * from './events.js'
 export { isGlassSupported, isHeadless, useIsHeadless } from './helpers.js'
 export { logger, type VoltraLogLevel } from './logger.js'
@@ -47,7 +52,6 @@ export { assertRunningOnApple } from './utils/assertRunningOnApple.js'
 export { enableWidgetHotReload } from './utils/enableWidgetHotReload.js'
 export { enableDynamicLiveActivityHotReload } from './utils/enableDynamicLiveActivityHotReload.js'
 export { useUpdateOnHMR } from './utils/useUpdateOnHMR.js'
-export * from './utils/helpers.js'
 export type { VoltraElementJson, VoltraNodeJson } from './types.js'
 export {
   clearWidgetServerUpdate,

package/src/native/NativeVoltra.ts

@@ -117,6 +117,8 @@ export interface Spec extends TurboModule {
   reloadDynamicLiveActivities(definitionIds?: string[] | null): Promise<void>
   clearPreloadedImages(keys?: string[] | null): Promise<void>
   updateDynamicWidget(dynamicWidgetId: string, dynamicWidgetPropsJson: string): Promise<void>
+  /** Language override for Dynamic Widgets and Live Activities (`env.appLocale`); null clears it. */
+  setDynamicWidgetLocale(tag: string | null): Promise<void>
   updateWidget(widgetId: string, jsonString: string, options: UpdateWidgetOptions): Promise<void>
   scheduleWidget(widgetId: string, timelineJson: string): Promise<void>
   reloadWidgets(widgetIds?: string[] | null): Promise<void>

package/src/utils/useUpdateOnHMR.ts

@@ -1,16 +1 @@
-import { getFastRefreshHub } from '@use-voltra/ios'
-import { useEffect, useState } from 'react'
-
-export const useUpdateOnHMR = () => {
-  const [, forceUpdate] = useState(0)
-
-  useEffect(() => {
-    if (!__DEV__) {
-      return
-    }
-
-    return getFastRefreshHub().onPatch(() => {
-      forceUpdate((prev) => prev + 1)
-    })
-  }, [])
-}
+export { useUpdateOnHMR } from '@use-voltra/ios'

package/build/commonjs/utils/helpers.js

@@ -1,25 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-Object.defineProperty(exports, "isGlassSupported", {
-  enumerable: true,
-  get: function () {
-    return _helpers.isGlassSupported;
-  }
-});
-Object.defineProperty(exports, "isHeadless", {
-  enumerable: true,
-  get: function () {
-    return _helpers.isHeadless;
-  }
-});
-Object.defineProperty(exports, "useIsHeadless", {
-  enumerable: true,
-  get: function () {
-    return _helpers.useIsHeadless;
-  }
-});
-var _helpers = require("../helpers.js");
-//# sourceMappingURL=helpers.js.map

package/build/commonjs/utils/helpers.js.map

@@ -1 +0,0 @@
-{"version":3,"names":["_helpers","require"],"sourceRoot":"../../../src","sources":["utils/helpers.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAAA,IAAAA,QAAA,GAAAC,OAAA","ignoreList":[]}

package/build/module/utils/helpers.js

@@ -1,4 +0,0 @@
-"use strict";
-
-export { isGlassSupported, isHeadless, useIsHeadless } from '../helpers.js';
-//# sourceMappingURL=helpers.js.map

package/build/module/utils/helpers.js.map

@@ -1 +0,0 @@
-{"version":3,"names":["isGlassSupported","isHeadless","useIsHeadless"],"sourceRoot":"../../../src","sources":["utils/helpers.ts"],"mappings":";;AAAA,SAASA,gBAAgB,EAAEC,UAAU,EAAEC,aAAa,QAAQ,eAAe","ignoreList":[]}

package/build/typescript/commonjs/utils/helpers.d.ts

@@ -1,2 +0,0 @@
-export { isGlassSupported, isHeadless, useIsHeadless } from '../helpers.js';
-//# sourceMappingURL=helpers.d.ts.map

package/build/typescript/commonjs/utils/helpers.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../../src/utils/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA"}

package/build/typescript/module/utils/helpers.d.ts

@@ -1,2 +0,0 @@
-export { isGlassSupported, isHeadless, useIsHeadless } from '../helpers.js';
-//# sourceMappingURL=helpers.d.ts.map

package/build/typescript/module/utils/helpers.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../../src/utils/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA"}

package/src/utils/helpers.ts

@@ -1 +0,0 @@
-export { isGlassSupported, isHeadless, useIsHeadless } from '../helpers.js'