feat: add supplemental activity families support for iOS 18+

example/app.json

@@ -24,6 +24,9 @@
         {
           "groupIdentifier": "group.callstackincubator.voltraexample",
           "enablePushNotifications": true,
+          "liveActivity": {
+            "supplementalActivityFamilies": ["small"]
+          },
           "widgets": [
             {
               "id": "weather",

example/components/live-activities/WatchLiveActivityUI.tsx

@@ -0,0 +1,59 @@
+import React from 'react'
+import { Voltra } from 'voltra'
+
+export function WatchLiveActivityLockScreen() {
+  return (
+    <Voltra.VStack id="watch-lock-screen" spacing={12} style={{ padding: 16 }}>
+      <Voltra.HStack spacing={12} alignment="center">
+        <Voltra.Image
+          source={{ assetName: 'voltra-icon' }}
+          style={{ width: 48, height: 48, borderRadius: 10 }}
+          resizeMode="stretch"
+        />
+        <Voltra.VStack spacing={4} alignment="leading">
+          <Voltra.Text
+            style={{
+              color: '#F0F9FF',
+              fontSize: 20,
+              fontWeight: '700',
+            }}
+          >
+            Workout Active
+          </Voltra.Text>
+          <Voltra.Text
+            style={{
+              color: '#94A3B8',
+              fontSize: 14,
+            }}
+          >
+            Running · 3.2 km
+          </Voltra.Text>
+        </Voltra.VStack>
+      </Voltra.HStack>
+
+      <Voltra.HStack distribution="equalSpacing">
+        <Voltra.VStack alignment="center">
+          <Voltra.Text style={{ color: '#10B981', fontSize: 24, fontWeight: '700' }}>25:42</Voltra.Text>
+          <Voltra.Text style={{ color: '#64748B', fontSize: 12 }}>Duration</Voltra.Text>
+        </Voltra.VStack>
+        <Voltra.VStack alignment="center">
+          <Voltra.Text style={{ color: '#F59E0B', fontSize: 24, fontWeight: '700' }}>142</Voltra.Text>
+          <Voltra.Text style={{ color: '#64748B', fontSize: 12 }}>BPM</Voltra.Text>
+        </Voltra.VStack>
+        <Voltra.VStack alignment="center">
+          <Voltra.Text style={{ color: '#8B5CF6', fontSize: 24, fontWeight: '700' }}>312</Voltra.Text>
+          <Voltra.Text style={{ color: '#64748B', fontSize: 12 }}>Calories</Voltra.Text>
+        </Voltra.VStack>
+      </Voltra.HStack>
+    </Voltra.VStack>
+  )
+}
+
+export function WatchLiveActivitySmall() {
+  return (
+    <Voltra.VStack id="watch-small" spacing={4} alignment="center" style={{ padding: 8 }}>
+      <Voltra.Text style={{ color: '#10B981', fontSize: 18, fontWeight: '700' }}>25:42</Voltra.Text>
+      <Voltra.Text style={{ color: '#F59E0B', fontSize: 14, fontWeight: '600' }}>142 BPM</Voltra.Text>
+    </Voltra.VStack>
+  )
+}

example/screens/live-activities/LiveActivitiesScreen.tsx

@@ -12,11 +12,12 @@ import CompassLiveActivity from '~/screens/live-activities/CompassLiveActivity'
 import FlightLiveActivity from '~/screens/live-activities/FlightLiveActivity'
 import LiquidGlassLiveActivity from '~/screens/live-activities/LiquidGlassLiveActivity'
 import MusicPlayerLiveActivity from '~/screens/live-activities/MusicPlayerLiveActivity'
+import WatchLiveActivity from '~/screens/live-activities/WatchLiveActivity'
 import WorkoutLiveActivity from '~/screens/live-activities/WorkoutLiveActivity'
 
 import { LiveActivityExampleComponentRef } from './types'
 
-type ActivityKey = 'basic' | 'stylesheet' | 'glass' | 'flight' | 'workout' | 'compass'
+type ActivityKey = 'basic' | 'stylesheet' | 'glass' | 'flight' | 'workout' | 'compass' | 'watch'
 
 const ACTIVITY_METADATA: Record<ActivityKey, { title: string; description: string }> = {
   basic: {
@@ -43,9 +44,13 @@ const ACTIVITY_METADATA: Record<ActivityKey, { title: string; description: strin
     title: 'Compass',
     description: 'Real-time compass using magnetometer with rotating arrow indicator.',
   },
+  watch: {
+    title: 'Watch Demo (iOS 18+)',
+    description: 'Demonstrates supplementalActivityFamilies.small for watchOS Smart Stack appearance.',
+  },
 }
 
-const CARD_ORDER: ActivityKey[] = ['basic', 'stylesheet', 'glass', 'flight', 'workout', 'compass']
+const CARD_ORDER: ActivityKey[] = ['basic', 'stylesheet', 'glass', 'flight', 'workout', 'compass', 'watch']
 
 export default function LiveActivitiesScreen() {
   const insets = useSafeAreaInsets()
@@ -57,6 +62,7 @@ export default function LiveActivitiesScreen() {
     flight: false,
     workout: false,
     compass: false,
+    watch: false,
   })
 
   const basicRef = useRef<LiveActivityExampleComponentRef>(null)
@@ -65,6 +71,7 @@ export default function LiveActivitiesScreen() {
   const flightRef = useRef<LiveActivityExampleComponentRef>(null)
   const workoutRef = useRef<LiveActivityExampleComponentRef>(null)
   const compassRef = useRef<LiveActivityExampleComponentRef>(null)
+  const watchRef = useRef<LiveActivityExampleComponentRef>(null)
 
   const activityRefs = useMemo(
     () => ({
@@ -74,6 +81,7 @@ export default function LiveActivitiesScreen() {
       flight: flightRef,
       workout: workoutRef,
       compass: compassRef,
+      watch: watchRef,
     }),
     []
   )
@@ -109,6 +117,10 @@ export default function LiveActivitiesScreen() {
     (isActive: boolean) => handleStatusChange('compass', isActive),
     [handleStatusChange]
   )
+  const handleWatchStatusChange = useCallback(
+    (isActive: boolean) => handleStatusChange('watch', isActive),
+    [handleStatusChange]
+  )
 
   const handleStart = async (key: ActivityKey) => {
     await activityRefs[key].current?.start?.().catch(console.error)
@@ -187,6 +199,7 @@ export default function LiveActivitiesScreen() {
         <FlightLiveActivity ref={flightRef} onIsActiveChange={handleFlightStatusChange} />
         <WorkoutLiveActivity ref={workoutRef} onIsActiveChange={handleWorkoutStatusChange} />
         <CompassLiveActivity ref={compassRef} onIsActiveChange={handleCompassStatusChange} />
+        <WatchLiveActivity ref={watchRef} onIsActiveChange={handleWatchStatusChange} />
       </ScrollView>
     </View>
   )

example/screens/live-activities/WatchLiveActivity.tsx

@@ -0,0 +1,48 @@
+import React, { forwardRef, useEffect, useImperativeHandle } from 'react'
+import { useLiveActivity } from 'voltra/client'
+
+import {
+  WatchLiveActivityLockScreen,
+  WatchLiveActivitySmall,
+} from '../../components/live-activities/WatchLiveActivityUI'
+import { LiveActivityExampleComponent } from './types'
+
+const WatchLiveActivity: LiveActivityExampleComponent = forwardRef(
+  ({ autoUpdate = true, autoStart = false, onIsActiveChange }, ref) => {
+    const { start, update, end, isActive } = useLiveActivity(
+      {
+        lockScreen: {
+          content: <WatchLiveActivityLockScreen />,
+        },
+        supplementalActivityFamilies: {
+          small: <WatchLiveActivitySmall />,
+        },
+        island: {
+          keylineTint: '#10B981',
+        },
+      },
+      {
+        activityName: 'watch-demo',
+        autoUpdate,
+        autoStart,
+        deepLinkUrl: '/voltraui/watch-demo',
+      }
+    )
+
+    useEffect(() => {
+      onIsActiveChange?.(isActive)
+    }, [isActive, onIsActiveChange])
+
+    useImperativeHandle(ref, () => ({
+      start,
+      update,
+      end,
+    }))
+
+    return null
+  }
+)
+
+WatchLiveActivity.displayName = 'WatchLiveActivity'
+
+export default WatchLiveActivity

ios/shared/VoltraRegion.swift

@@ -9,6 +9,7 @@ public enum VoltraRegion: String, Codable, Hashable, CaseIterable {
   case islandCompactLeading
   case islandCompactTrailing
   case islandMinimal
+  case supplementalActivityFamiliesSmall
 
   /// The JSON key for this region in the payload
   public var jsonKey: String {
@@ -29,6 +30,8 @@ public enum VoltraRegion: String, Codable, Hashable, CaseIterable {
       return "isl_cmp_t"
     case .islandMinimal:
       return "isl_min"
+    case .supplementalActivityFamiliesSmall:
+      return "saf_sm"
     }
   }
 }

ios/target/VoltraWidget.swift

@@ -14,6 +14,37 @@ public struct VoltraWidget: Widget {
   }
 
   public var body: some WidgetConfiguration {
+    if #available(iOS 18.0, *) {
+      return withAdaptiveViewConfig()
+    } else {
+      return defaultViewConfig()
+    }
+  }
+
+  // MARK: - iOS 18+ Configuration (with adaptive view for supplemental activity families)
+
+  @available(iOS 18.0, *)
+  private func withAdaptiveViewConfig() -> some WidgetConfiguration {
+    ActivityConfiguration(for: VoltraAttributes.self) { context in
+      VoltraAdaptiveLockScreenView(
+        context: context,
+        rootNodeProvider: rootNode
+      )
+      .widgetURL(VoltraDeepLinkResolver.resolve(context.attributes))
+      .voltraIfLet(context.state.activityBackgroundTint) { view, tint in
+        let color = JSColorParser.parse(tint)
+        view.activityBackgroundTint(color)
+      }
+    } dynamicIsland: { context in
+      dynamicIslandContent(context: context)
+    }
+    // NOTE: .supplementalActivityFamilies() is applied by VoltraWidgetWithSupplementalActivityFamilies
+    // wrapper when configured via plugin (see VoltraWidgetBundle.swift)
+  }
+
+  // MARK: - Default Configuration (iOS 16.2 - 17.x)
+
+  private func defaultViewConfig() -> some WidgetConfiguration {
     ActivityConfiguration(for: VoltraAttributes.self) { context in
       Voltra(root: rootNode(for: .lockScreen, from: context.state), activityId: context.activityID)
         .widgetURL(VoltraDeepLinkResolver.resolve(context.attributes))
@@ -22,42 +53,77 @@ public struct VoltraWidget: Widget {
           view.activityBackgroundTint(color)
         }
     } dynamicIsland: { context in
-      let dynamicIsland = DynamicIsland {
-        DynamicIslandExpandedRegion(.leading) {
-          Voltra(root: rootNode(for: .islandExpandedLeading, from: context.state), activityId: context.activityID)
-            .widgetURL(VoltraDeepLinkResolver.resolve(context.attributes))
-        }
-        DynamicIslandExpandedRegion(.trailing) {
-          Voltra(root: rootNode(for: .islandExpandedTrailing, from: context.state), activityId: context.activityID)
-            .widgetURL(VoltraDeepLinkResolver.resolve(context.attributes))
-        }
-        DynamicIslandExpandedRegion(.center) {
-          Voltra(root: rootNode(for: .islandExpandedCenter, from: context.state), activityId: context.activityID)
-            .widgetURL(VoltraDeepLinkResolver.resolve(context.attributes))
-        }
-        DynamicIslandExpandedRegion(.bottom) {
-          Voltra(root: rootNode(for: .islandExpandedBottom, from: context.state), activityId: context.activityID)
-            .widgetURL(VoltraDeepLinkResolver.resolve(context.attributes))
-        }
-      } compactLeading: {
-        Voltra(root: rootNode(for: .islandCompactLeading, from: context.state), activityId: context.activityID)
+      dynamicIslandContent(context: context)
+    }
+  }
+
+  // MARK: - Dynamic Island (shared between iOS versions)
+
+  private func dynamicIslandContent(context: ActivityViewContext<VoltraAttributes>) -> DynamicIsland {
+    let dynamicIsland = DynamicIsland {
+      DynamicIslandExpandedRegion(.leading) {
+        Voltra(root: rootNode(for: .islandExpandedLeading, from: context.state), activityId: context.activityID)
           .widgetURL(VoltraDeepLinkResolver.resolve(context.attributes))
-      } compactTrailing: {
-        Voltra(root: rootNode(for: .islandCompactTrailing, from: context.state), activityId: context.activityID)
+      }
+      DynamicIslandExpandedRegion(.trailing) {
+        Voltra(root: rootNode(for: .islandExpandedTrailing, from: context.state), activityId: context.activityID)
           .widgetURL(VoltraDeepLinkResolver.resolve(context.attributes))
-      } minimal: {
-        Voltra(root: rootNode(for: .islandMinimal, from: context.state), activityId: context.activityID)
+      }
+      DynamicIslandExpandedRegion(.center) {
+        Voltra(root: rootNode(for: .islandExpandedCenter, from: context.state), activityId: context.activityID)
           .widgetURL(VoltraDeepLinkResolver.resolve(context.attributes))
       }
-
-      // Apply keylineTint if specified
-      if let keylineTint = context.state.keylineTint,
-         let color = JSColorParser.parse(keylineTint)
-      {
-        return dynamicIsland.keylineTint(color)
-      } else {
-        return dynamicIsland
+      DynamicIslandExpandedRegion(.bottom) {
+        Voltra(root: rootNode(for: .islandExpandedBottom, from: context.state), activityId: context.activityID)
+          .widgetURL(VoltraDeepLinkResolver.resolve(context.attributes))
       }
+    } compactLeading: {
+      Voltra(root: rootNode(for: .islandCompactLeading, from: context.state), activityId: context.activityID)
+        .widgetURL(VoltraDeepLinkResolver.resolve(context.attributes))
+    } compactTrailing: {
+      Voltra(root: rootNode(for: .islandCompactTrailing, from: context.state), activityId: context.activityID)
+        .widgetURL(VoltraDeepLinkResolver.resolve(context.attributes))
+    } minimal: {
+      Voltra(root: rootNode(for: .islandMinimal, from: context.state), activityId: context.activityID)
+        .widgetURL(VoltraDeepLinkResolver.resolve(context.attributes))
+    }
+
+    // Apply keylineTint if specified
+    if let keylineTint = context.state.keylineTint,
+       let color = JSColorParser.parse(keylineTint)
+    {
+      return dynamicIsland.keylineTint(color)
+    } else {
+      return dynamicIsland
+    }
+  }
+}
+
+// MARK: - Adaptive Lock Screen View (iOS 18+)
+
+/// A view that adapts its content based on the activity family environment
+/// - For .small (watchOS/CarPlay): Uses supplementalActivityFamiliesSmall content if available, falls back to lockScreen
+/// - For .medium (iPhone lock screen) and unknown: Always uses lockScreen
+@available(iOS 18.0, *)
+struct VoltraAdaptiveLockScreenView: View {
+  let context: ActivityViewContext<VoltraAttributes>
+  let rootNodeProvider: (VoltraRegion, VoltraAttributes.ContentState) -> VoltraNode
+
+  @Environment(\.activityFamily) private var activityFamily
+
+  var body: some View {
+    switch activityFamily {
+    case .small:
+      let region: VoltraRegion = context.state.regions[.supplementalActivityFamiliesSmall] != nil
+        ? .supplementalActivityFamiliesSmall
+        : .lockScreen
+      Voltra(root: rootNodeProvider(region, context.state), activityId: context.activityID)
+
+    case .medium:
+      Voltra(root: rootNodeProvider(.lockScreen, context.state), activityId: context.activityID)
+
+    @unknown default:
+      Voltra(root: rootNodeProvider(.lockScreen, context.state), activityId: context.activityID)
     }
   }
 }

plugin/src/constants/activities.ts

@@ -0,0 +1,13 @@
+import type { ActivityFamily } from '../types'
+
+/**
+ * Activity-related constants for the Voltra plugin
+ */
+
+/** Default supplemental activity families when not specified */
+export const DEFAULT_ACTIVITY_FAMILIES: ActivityFamily[] = ['small']
+
+/** Maps JS activity family names to SwiftUI ActivityFamily enum cases */
+export const ACTIVITY_FAMILY_MAP: Record<ActivityFamily, string> = {
+  small: '.small',
+}

plugin/src/constants/index.ts

@@ -2,6 +2,7 @@
  * Re-exports all constants
  */
 
+export { DEFAULT_ACTIVITY_FAMILIES, ACTIVITY_FAMILY_MAP } from './activities'
 export { IOS } from './ios'
 export { DEFAULT_USER_IMAGES_PATH } from './paths'
 export {