@use-voltra/ios-client 2.3.1 → 2.4.0

package/expo-plugin/src/utils/fileDiscovery.ts

@@ -7,6 +7,9 @@ import { logger } from '@use-voltra/expo-plugin'
 /** Table name matches basename without extension; co-located per locale in *.lproj */
 export const VOLTRA_WIDGET_STRINGS_BASENAME = 'VoltraWidgets.strings'
 
+/** Default table: Edit Widget sheet strings, and the file that makes each `.lproj` a real resource. */
+export const VOLTRA_LOCALIZABLE_STRINGS_BASENAME = 'Localizable.strings'
+
 /**
  * Scans the widget extension target directory and returns categorized file lists.
  *
@@ -43,9 +46,10 @@ export function getIOSWidgetExtensionFiles(targetPath: string, targetName: strin
     if (!entry.endsWith('.lproj')) {
       continue
     }
-    const stringsPath = path.join(targetPath, entry, VOLTRA_WIDGET_STRINGS_BASENAME)
-    if (fs.existsSync(stringsPath)) {
-      widgetFiles.localizedStringResources.push(`${entry}/${VOLTRA_WIDGET_STRINGS_BASENAME}`)
+    for (const basename of [VOLTRA_WIDGET_STRINGS_BASENAME, VOLTRA_LOCALIZABLE_STRINGS_BASENAME]) {
+      if (fs.existsSync(path.join(targetPath, entry, basename))) {
+        widgetFiles.localizedStringResources.push(`${entry}/${basename}`)
+      }
     }
   }
 

package/expo-plugin/src/validation.ts

@@ -1,6 +1,7 @@
 import {
   validateHomeScreenWidgetId,
   validateInitialStatePath,
+  validateWidgetConfigurationCopy,
   validateWidgetEntry,
   validateWidgetLabel,
   validateWidgetServerUpdate,
@@ -55,6 +56,7 @@ export function validateIOSWidgetConfig(widget: IOSWidgetConfig, projectRoot?: s
   }
 
   validateWidgetServerUpdate(widget.serverUpdate, widget.id, iosServerUpdateRules(widget))
+  validateWidgetConfigurationCopy(widget, { requireParameterTitle: true })
 
   if (widget.supportedFamilies) {
     if (!Array.isArray(widget.supportedFamilies)) {

package/ios/Package.swift

@@ -68,6 +68,7 @@ let package = Package(
         "JSONValue.swift",
         "VoltraConfig.swift",
         "VoltraConstants.swift",
+        "VoltraLocaleEnvironment.swift",
         "VoltraWidgetKind.swift",
         "VoltraPayloadMigrator.swift",
         "VoltraRegion.swift",
@@ -76,6 +77,7 @@ let package = Package(
         // by `ui/VoltraNode+View.swift`, which the podspecs compile alongside them.
         "ShortNames.swift",
         "VoltraElement.swift",
+        "VoltraModifierDescriptor.swift",
         "VoltraNode.swift",
       ]
     ),
@@ -86,18 +88,23 @@ let package = Package(
     ),
     .target(
       name: "VoltraStyleCore",
+      dependencies: ["VoltraSharedCore"],
       path: "ui",
       sources: [
         "Style/BackgroundValue.swift",
         "Style/JSColorParser.swift",
         "Style/JSGradientParser.swift",
+        "Modifiers/VoltraModifierRegistry.swift",
+        "Modifiers/BuiltInModifiers.swift",
+        "Modifiers/VoltraElement+nativeModifiers.swift",
+        "Helpers/VoltraDeepLinkResolver+URL.swift",
       ]
     ),
     .testTarget(
       name: "VoltraStyleTests",
       dependencies: ["VoltraStyleCore"],
       path: "tests",
-      sources: ["JSGradientParserTests.swift"]
+      sources: ["JSGradientParserTests.swift", "NativeModifierTests.swift"]
     ),
   ]
 )

package/ios/VoltraWidget.podspec

@@ -14,7 +14,7 @@ Pod::Spec.new do |s|
     :ios => '16.4',
   }
   s.swift_version  = '5.9'
-  s.module_name    = 'VoltraRuntime'
+  s.module_name    = 'VoltraWidgetRuntime'
   s.source         = { git: 'https://github.com/callstackincubator/voltra' }
   s.static_framework = true
 

package/ios/app/NativeVoltra.mm

@@ -1,8 +1,8 @@
 #import "NativeVoltra.h"
 #import <UIKit/UIKit.h>
 
-#if __has_include("Voltra/VoltraRuntime-Swift.h")
-#import "Voltra/VoltraRuntime-Swift.h"
+#if __has_include("VoltraRuntime/VoltraRuntime-Swift.h")
+#import "VoltraRuntime/VoltraRuntime-Swift.h"
 #else
 #import "VoltraRuntime-Swift.h"
 #endif
@@ -375,6 +375,19 @@ static void VoltraRejectPromise(RCTPromiseRejectBlock reject, NSString *fallback
   }];
 }
 
+- (void)setDynamicWidgetLocale:(NSString *)tag
+                       resolve:(RCTPromiseResolveBlock)resolve
+                        reject:(RCTPromiseRejectBlock)reject
+{
+  [self.module setDynamicWidgetLocale:tag completion:^(NSError *error) {
+    if (error) {
+      reject(@"setDynamicWidgetLocale", error.localizedDescription, error);
+    } else {
+      resolve(nil);
+    }
+  }];
+}
+
 - (void)scheduleWidget:(NSString *)widgetId
           timelineJson:(NSString *)timelineJson
                resolve:(RCTPromiseResolveBlock)resolve

package/ios/app/VoltraModule.swift

@@ -245,6 +245,17 @@ public enum VoltraErrors: Error, CustomNSError {
     }
   }
 
+  @objc public func setDynamicWidgetLocale(_ tag: String?, completion: @escaping (Error?) -> Void) {
+    Task {
+      do {
+        try await impl.setDynamicWidgetLocale(tag: tag)
+        completion(nil)
+      } catch {
+        completion(error)
+      }
+    }
+  }
+
   @objc public func updateWidget(
     _ widgetId: String,
     jsonString: String,

package/ios/app/VoltraModuleImpl.swift

@@ -342,6 +342,20 @@ public class VoltraModuleImpl {
     )
   }
 
+  /// Stores the app's language override in the App Group, where the widget extension reads it as
+  /// `env.appLocale` (ADR 0009 §3), then reloads every widget and re-renders running Dynamic Live
+  /// Activities so it takes effect at once. Throws `WidgetError.appGroupNotConfigured` without a
+  /// `groupIdentifier`, since the extension could never see the value.
+  func setDynamicWidgetLocale(tag: String?) async throws {
+    try VoltraWidgetDefaults.setDynamicWidgetLocale(tag)
+    VoltraWidgetService.reloadAllTimelines()
+    // Re-send each running Dynamic Live Activity its current content so WidgetKit renders it again
+    // with the new env.appLocale (the render cache is keyed on the locale environment). This is the
+    // release-safe half of `reloadDynamicLiveActivities`, which is DEBUG-only because it also
+    // refetches bundles from Metro.
+    await VoltraDynamicLiveActivityRegistry.shared.reload(definitionIds: nil)
+  }
+
   func updateWidget(widgetId: String, jsonString: String, options: UpdateWidgetOptions?) async throws {
     try VoltraWidgetService.setWidgetData(widgetId: widgetId, jsonString: jsonString, deepLinkUrl: options?.deepLinkUrl)
 

package/ios/app/VoltraViewComponentView.mm

@@ -1,7 +1,7 @@
 #import "VoltraViewComponentView.h"
 
-#if __has_include("Voltra/VoltraRuntime-Swift.h")
-#import "Voltra/VoltraRuntime-Swift.h"
+#if __has_include("VoltraRuntime/VoltraRuntime-Swift.h")
+#import "VoltraRuntime/VoltraRuntime-Swift.h"
 #else
 #import "VoltraRuntime-Swift.h"
 #endif

package/ios/app/VoltraViewRoot.swift

@@ -3,7 +3,7 @@ import SwiftUI
 import UIKit
 
 @objc public class VoltraViewRoot: UIView {
-  private var hostingController: UIHostingController<AnyView>?
+  private var hostingController: UIHostingController<Voltra>?
   private var root: VoltraNode = .empty
   private var viewId: String = UUID().uuidString
 
@@ -20,8 +20,7 @@ import UIKit
   }
 
   private func setupHostingController() {
-    let view = Voltra(root: .empty, activityId: viewId)
-    let hostingController = UIHostingController(rootView: AnyView(view))
+    let hostingController = UIHostingController(rootView: Voltra(root: .empty, activityId: viewId))
     hostingController.view.backgroundColor = .clear
     addSubview(hostingController.view)
     self.hostingController = hostingController
@@ -49,15 +48,10 @@ import UIKit
     updateView()
   }
 
+  /// Updates the existing hosting controller in place. SwiftUI then diffs the new tree against the
+  /// previous one, so `animation`, `transition` and `contentTransition` modifiers animate between
+  /// payloads and view state survives updates, as it does in widgets and Live Activities.
   private func updateView() {
-    hostingController?.view.removeFromSuperview()
-
-    let newView = Voltra(root: root, activityId: viewId)
-    let newHostingController = UIHostingController(rootView: AnyView(newView))
-    newHostingController.view.backgroundColor = .clear
-    newHostingController.view.frame = bounds
-    addSubview(newHostingController.view)
-
-    hostingController = newHostingController
+    hostingController?.rootView = Voltra(root: root, activityId: viewId)
   }
 }

package/ios/shared/ShortNames.swift

@@ -117,6 +117,7 @@ public enum ShortNames {
     "minvl": "minimumValueLabel",
     "minl": "minLength",
     "minw": "minWidth",
+    "mods": "modifiers",
     "md": "monospacedDigit",
     "mta": "multilineTextAlignment",
     "n": "name",

package/ios/shared/VoltraConstants.swift

@@ -52,6 +52,10 @@ public enum VoltraStorageKeys {
   /// React-free, so it can't resolve the URL itself; the app writes it via RCTBundleURLProvider.
   public static let devServerURL = "Voltra_DevServerURL"
 
+  /// BCP-47 tag the app chose with `setDynamicWidgetLocale`, surfaced to widgets as
+  /// `env.appLocale` (ADR 0009 §3). Absent when the app has not set one.
+  public static let dynamicWidgetLocale = "Voltra_DynamicWidgetLocale"
+
   // MARK: - Info.plist keys
 
   public static let widgetIds = "Voltra_WidgetIds"

package/ios/shared/VoltraElement.swift

@@ -20,11 +20,20 @@ public struct VoltraElement: Hashable {
   /// Style dictionary with expanded keys, resolved once while parsing.
   private let _style: [String: JSONValue]?
 
+  /// The `modifiers` prop, decoded once while parsing because renderers read it on every body
+  /// evaluation. Derived from `_props`, so identity leaves it out like `_style`.
+  public let nativeModifiers: [VoltraModifierDescriptor]
+
+  /// Element-shaped props, such as a Gauge label, parsed once while parsing and keyed by their
+  /// expanded name. `componentProp(_:)` reads them, and so do the hosts that look for native
+  /// modifiers anywhere in the rendered tree. Derived from `_props`, like `_style`.
+  public let propNodes: [String: VoltraNode]
+
   // MARK: - Hashable
 
   /// `_props` carries fully resolved values, so it alone distinguishes elements that render
-  /// differently. Identity deliberately omits `_style`, which is derived from `_props` and would
-  /// only restate it.
+  /// differently. Identity deliberately omits `_style`, `nativeModifiers` and `propNodes`, which are derived from `_props`
+  /// and would only restate it.
   public func hash(into hasher: inout Hasher) {
     hasher.combine(type)
     hasher.combine(id)
@@ -106,15 +115,47 @@ public struct VoltraElement: Hashable {
 
     _props = resolvedProps
     _style = Self.expandedStyle(from: resolvedProps)
+    nativeModifiers = VoltraModifierDescriptor.parseList((resolvedProps?["mods"] ?? resolvedProps?["modifiers"])?.stringValue)
+    propNodes = Self.elementNodes(in: resolvedProps)
   }
 
   /// Get component prop by name - handles both single component and array
   public func componentProp(_ propName: String) -> VoltraNode {
+    if let node = propNodes[propName] {
+      return node
+    }
     guard let propValue = props?[propName] else { return .empty }
 
     return VoltraNode(from: propValue)
   }
 
+  /// Parses the props whose values are serialized elements, or arrays of them. Other values, such
+  /// as a string label, are left to `componentProp(_:)`.
+  private static func elementNodes(in props: [String: JSONValue]?) -> [String: VoltraNode] {
+    guard let props else { return [:] }
+    var nodes: [String: VoltraNode] = [:]
+    for (key, value) in props where isElementShaped(value) {
+      let name = ShortNames.expand(key)
+      guard name != "style", name != "modifiers" else { continue }
+      let node = VoltraNode(from: value)
+      if !node.isEmpty {
+        nodes[name] = node
+      }
+    }
+    return nodes
+  }
+
+  private static func isElementShaped(_ value: JSONValue) -> Bool {
+    switch value {
+    case let .object(dict):
+      return dict["t"]?.intValue != nil
+    case let .array(items):
+      return !items.isEmpty && items.allSatisfy(isElementShaped)
+    default:
+      return false
+    }
+  }
+
   /// Decode parameters from props
   public func parameters<T: Decodable>(_: T.Type) -> T {
     guard let props = props else {

package/ios/shared/VoltraLocaleEnvironment.swift

@@ -0,0 +1,185 @@
+import Foundation
+
+/// The locale and formatting fields of `WidgetEnvironment` (ADR 0009 §1), captured once per render
+/// and shared by the Dynamic Widget and Dynamic Live Activity env builders so both hand JS the same
+/// shape.
+///
+/// Foundation-only on purpose: the SwiftUI views pass `\.layoutDirection` in as a plain `Bool`, so
+/// the mapping stays testable without a simulator.
+public struct VoltraLocaleEnvironment: Hashable {
+  /// BCP-47 tag with Unicode extensions (`pl-PL`, `en-US-u-hc-h23`). Never the ICU `pl_PL` form,
+  /// which `Intl` rejects with a `RangeError`.
+  public let locale: String
+  /// `Locale.preferredLanguages`: the user's list, independent of the extension bundle.
+  public let preferredLanguages: [String]
+  /// The tag the app stored with `setDynamicWidgetLocale`, if any.
+  public let appLocale: String?
+  /// `"ltr"` or `"rtl"`.
+  public let layoutDirection: String
+  /// `"h12"` or `"h23"`.
+  public let hourCycle: String
+  public let timeZone: String
+  /// `"metric"`, `"us"` or `"uk"`.
+  public let measurementSystem: String?
+  /// Unicode calendar identifier as `Intl` spells it (`gregory`, not `gregorian`).
+  public let calendar: String?
+  /// 1 = Sunday … 7 = Saturday.
+  public let firstDayOfWeek: Int?
+
+  public init(
+    locale: String,
+    preferredLanguages: [String],
+    appLocale: String?,
+    layoutDirection: String,
+    hourCycle: String,
+    timeZone: String,
+    measurementSystem: String?,
+    calendar: String?,
+    firstDayOfWeek: Int?
+  ) {
+    self.locale = locale
+    self.preferredLanguages = preferredLanguages
+    self.appLocale = appLocale
+    self.layoutDirection = layoutDirection
+    self.hourCycle = hourCycle
+    self.timeZone = timeZone
+    self.measurementSystem = measurementSystem
+    self.calendar = calendar
+    self.firstDayOfWeek = firstDayOfWeek
+  }
+
+  /// Captures the environment for `locale`, the SwiftUI `\.locale` of the view being drawn.
+  ///
+  /// - Parameters:
+  ///   - isRightToLeft: SwiftUI's `\.layoutDirection == .rightToLeft`; `nil` outside a view body
+  ///     (the server-update trial render), in which case the locale's script direction is used.
+  ///   - appLocale: the app's override from the App Group, read by the caller.
+  public static func capture(
+    locale: Locale,
+    isRightToLeft: Bool? = nil,
+    appLocale: String? = nil,
+    preferredLanguages: [String] = Locale.preferredLanguages,
+    timeZone: TimeZone = .current
+  ) -> VoltraLocaleEnvironment {
+    let rtl = isRightToLeft ?? (locale.language.characterDirection == .rightToLeft)
+    return VoltraLocaleEnvironment(
+      locale: bcp47(locale),
+      preferredLanguages: preferredLanguages,
+      appLocale: appLocale.flatMap { $0.isEmpty ? nil : $0 },
+      layoutDirection: rtl ? "rtl" : "ltr",
+      hourCycle: hourCycle(locale.hourCycle),
+      timeZone: timeZone.identifier,
+      measurementSystem: measurementSystem(locale.measurementSystem),
+      calendar: calendarIdentifier((locale as NSLocale).calendarIdentifier),
+      firstDayOfWeek: firstDayOfWeek(locale)
+    )
+  }
+
+  // MARK: - Mapping
+
+  public static func bcp47(_ locale: Locale) -> String {
+    locale.identifier(.bcp47)
+  }
+
+  /// `Locale.hourCycle` already reflects the user's 24-Hour Time override on the current locale.
+  static func hourCycle(_ cycle: Locale.HourCycle) -> String {
+    switch cycle {
+    case .zeroToEleven, .oneToTwelve:
+      return "h12"
+    default:
+      return "h23"
+    }
+  }
+
+  static func measurementSystem(_ system: Locale.MeasurementSystem) -> String {
+    if system == .us {
+      return "us"
+    }
+    if system == .uk {
+      return "uk"
+    }
+    return "metric"
+  }
+
+  /// Foundation spells CLDR calendar types the long way; `Intl` and BCP-47 use the short keys.
+  static func calendarIdentifier(_ foundationIdentifier: String) -> String? {
+    if foundationIdentifier.isEmpty {
+      return nil
+    }
+    switch foundationIdentifier {
+    case "gregorian":
+      return "gregory"
+    case "ethiopic-amete-alem":
+      return "ethioaa"
+    default:
+      return foundationIdentifier
+    }
+  }
+
+  static func firstDayOfWeek(_ locale: Locale) -> Int? {
+    var calendar = Calendar(identifier: .gregorian)
+    calendar.locale = locale
+    let weekday = calendar.firstWeekday
+    return (1 ... 7).contains(weekday) ? weekday : nil
+  }
+
+  // MARK: - JSON
+
+  /// The fields as `"key": value` pairs, one per line, for splicing into a hand-rolled env JSON
+  /// object. Absent optionals are left out so they read as `undefined` in JS.
+  public var jsonFields: String {
+    var fields: [String] = [
+      "\"locale\": \(Self.jsonString(locale))",
+      "\"preferredLanguages\": [\(preferredLanguages.map(Self.jsonString).joined(separator: ", "))]",
+    ]
+    if let appLocale {
+      fields.append("\"appLocale\": \(Self.jsonString(appLocale))")
+    }
+    fields.append("\"layoutDirection\": \(Self.jsonString(layoutDirection))")
+    fields.append("\"hourCycle\": \(Self.jsonString(hourCycle))")
+    fields.append("\"timeZone\": \(Self.jsonString(timeZone))")
+    if let measurementSystem {
+      fields.append("\"measurementSystem\": \(Self.jsonString(measurementSystem))")
+    }
+    if let calendar {
+      fields.append("\"calendar\": \(Self.jsonString(calendar))")
+    }
+    if let firstDayOfWeek {
+      fields.append("\"firstDayOfWeek\": \(firstDayOfWeek)")
+    }
+    return fields.joined(separator: ",\n  ")
+  }
+
+  /// The same fields for `JSONSerialization`-based builders.
+  public var dictionary: [String: Any] {
+    var values: [String: Any] = [
+      "locale": locale,
+      "preferredLanguages": preferredLanguages,
+      "layoutDirection": layoutDirection,
+      "hourCycle": hourCycle,
+      "timeZone": timeZone,
+    ]
+    if let appLocale {
+      values["appLocale"] = appLocale
+    }
+    if let measurementSystem {
+      values["measurementSystem"] = measurementSystem
+    }
+    if let calendar {
+      values["calendar"] = calendar
+    }
+    if let firstDayOfWeek {
+      values["firstDayOfWeek"] = firstDayOfWeek
+    }
+    return values
+  }
+
+  static func jsonString(_ value: String) -> String {
+    let escaped = value
+      .replacingOccurrences(of: "\\", with: "\\\\")
+      .replacingOccurrences(of: "\"", with: "\\\"")
+      .replacingOccurrences(of: "\n", with: "\\n")
+      .replacingOccurrences(of: "\r", with: "\\r")
+    return "\"\(escaped)\""
+  }
+}

package/ios/shared/VoltraModifierDescriptor.swift

@@ -0,0 +1,33 @@
+import Foundation
+import os
+
+/// One entry of a component's `modifiers` prop: `{ "$type": "<name>", ...params }` (ADR 0005).
+///
+/// Decoding lives next to `VoltraElement`, which decodes the prop once while parsing; building
+/// the SwiftUI modifier is the job of `VoltraModifierRegistry` in `ui/Modifiers`.
+public struct VoltraModifierDescriptor {
+  public let type: String
+  public let params: [String: Any]
+
+  public init(type: String, params: [String: Any]) {
+    self.type = type
+    self.params = params
+  }
+
+  private static let logger = Logger(subsystem: "com.voltra", category: "modifier")
+
+  /// Decodes the JSON-encoded `modifiers` prop. Entries without a string `$type` are dropped.
+  public static func parseList(_ json: String?) -> [VoltraModifierDescriptor] {
+    guard let json, let data = json.data(using: .utf8) else { return [] }
+    guard let entries = (try? JSONSerialization.jsonObject(with: data)) as? [[String: Any]] else {
+      logger.warning("Ignoring modifiers that are not a JSON array of objects")
+      return []
+    }
+    return entries.compactMap { entry in
+      guard let type = entry["$type"] as? String else { return nil }
+      var params = entry
+      params.removeValue(forKey: "$type")
+      return VoltraModifierDescriptor(type: type, params: params)
+    }
+  }
+}

package/ios/shared/VoltraWidgetDefaults.swift

@@ -43,6 +43,17 @@ public enum VoltraWidgetDefaults {
     try? resolvedDefaults().string(forKey: VoltraStorageKeys.devServerURL)
   }
 
+  /// The app's language override for Dynamic Widgets and Dynamic Live Activities
+  /// (`env.appLocale`). nil when none is set or the app group is not configured.
+  public static func dynamicWidgetLocale() -> String? {
+    guard let tag = try? resolvedDefaults().string(forKey: VoltraStorageKeys.dynamicWidgetLocale),
+          !tag.isEmpty
+    else {
+      return nil
+    }
+    return tag
+  }
+
   // MARK: - Write
 
   public static func setWidgetJson(_ json: String, for widgetId: String, deepLinkUrl: String?) throws {
@@ -84,6 +95,19 @@ public enum VoltraWidgetDefaults {
     defaults.synchronize()
   }
 
+  /// Stores (or, with nil, clears) the app's language override for Dynamic Widgets. Throws
+  /// `WidgetError.appGroupNotConfigured` without a `groupIdentifier`, since the extension could
+  /// never read the value.
+  public static func setDynamicWidgetLocale(_ tag: String?) throws {
+    let defaults = try resolvedDefaults()
+    if let tag, !tag.isEmpty {
+      defaults.set(tag, forKey: VoltraStorageKeys.dynamicWidgetLocale)
+    } else {
+      defaults.removeObject(forKey: VoltraStorageKeys.dynamicWidgetLocale)
+    }
+    defaults.synchronize()
+  }
+
   // MARK: - Remove
 
   /// Removes all persisted data (json, deepLinkUrl, timeline, Dynamic Widget props) for a single widget.