voltra 2.2.0 → 2.3.0

package/src/platforms/android/widgetSizing.ts

@@ -0,0 +1,112 @@
+/**
+ * Android widget sizing.
+ *
+ * Android 12+ (API 31+) places widgets by `targetCellWidth`/`targetCellHeight`, expressed in
+ * launcher grid cells. Android 11 and older ignore those attributes entirely and place widgets by
+ * `minWidth`/`minHeight`, expressed in dp, so a widget has to declare both sets to be placed
+ * correctly everywhere. Voltra widgets build against the host app's `minSdkVersion` — React
+ * Native's template sets 24 — so the pre-Android-12 path is not a legacy edge case.
+ * https://developer.android.com/develop/ui/compose/glance/create-app-widget
+ *
+ * Cell size varies by device, launcher and orientation, so converting cells to dp can only ever be
+ * an approximation. These are the figures Google publishes for a 5x4 handset grid, following the
+ * accompanying guidance to size widths from the portrait table and heights from the landscape
+ * table, because those are the smaller cells on each axis.
+ * https://developer.android.com/develop/ui/views/appwidgets/layouts
+ *
+ * The `voltra` CLI and the `@use-voltra/android-client` Expo plugin generate the same
+ * `appwidget-provider` XML from their own copy of this module; keep the two in sync.
+ */
+
+/** Widget fields that determine the generated `appwidget-provider` sizing attributes. */
+export interface AndroidWidgetSizingInput {
+  targetCellWidth: number
+  targetCellHeight: number
+  minWidth?: number
+  minHeight?: number
+  minCellWidth?: number
+  minCellHeight?: number
+  minResizeWidth?: number
+  minResizeHeight?: number
+  maxResizeWidth?: number
+  maxResizeHeight?: number
+}
+
+/** Resize bounds, in dp, emitted only when set. `maxResize*` is honoured from Android 12 on. */
+const RESIZE_BOUNDS = ['minResizeWidth', 'minResizeHeight', 'maxResizeWidth', 'maxResizeHeight'] as const
+
+function cellsToWidthDp(cells: number): number {
+  return cells * 73 - 16
+}
+
+function cellsToHeightDp(cells: number): number {
+  return cells * 66 - 15
+}
+
+function resolveMinimumSize(widget: AndroidWidgetSizingInput): { minWidth: number; minHeight: number } {
+  return {
+    minWidth: widget.minWidth ?? cellsToWidthDp(widget.minCellWidth ?? widget.targetCellWidth),
+    minHeight: widget.minHeight ?? cellsToHeightDp(widget.minCellHeight ?? widget.targetCellHeight),
+  }
+}
+
+/**
+ * Sizing attributes for a single widget, ordered as in Android's own reference example.
+ *
+ * `minWidth` and `minHeight` are always emitted, so a widget is placed at its intended size on
+ * Android 11 and older: an explicit dp value wins, then the deprecated cell count, then the
+ * target cell count.
+ */
+export function androidWidgetSizingAttributes(widget: AndroidWidgetSizingInput): string[] {
+  const { minWidth, minHeight } = resolveMinimumSize(widget)
+
+  const attributes = [
+    `android:minWidth="${minWidth}dp"`,
+    `android:minHeight="${minHeight}dp"`,
+    `android:targetCellWidth="${widget.targetCellWidth}"`,
+    `android:targetCellHeight="${widget.targetCellHeight}"`,
+  ]
+
+  for (const bound of RESIZE_BOUNDS) {
+    const value = widget[bound]
+    if (value !== undefined) {
+      attributes.push(`android:${bound}="${value}dp"`)
+    }
+  }
+
+  return attributes
+}
+
+/**
+ * Resize bounds Android will silently ignore, described for the developer who set them.
+ *
+ * `minResizeWidth` has no effect when it is greater than `minWidth`, and `maxResizeWidth` has no
+ * effect when it is smaller; likewise for the height pair. This reports rather than throws,
+ * because `minWidth` is usually the approximation derived from the widget's cell count.
+ * https://developer.android.com/reference/android/appwidget/AppWidgetProviderInfo
+ */
+export function androidWidgetSizingWarnings(widget: AndroidWidgetSizingInput, widgetId: string): string[] {
+  const { minWidth, minHeight } = resolveMinimumSize(widget)
+  const warnings: string[] = []
+
+  const report = (bound: string, value: number, relation: string, minimum: string, minimumValue: number): void => {
+    warnings.push(
+      `Widget '${widgetId}': ${bound} (${value}dp) is ${relation} ${minimum} (${minimumValue}dp), so Android ignores it.`
+    )
+  }
+
+  if (widget.minResizeWidth !== undefined && widget.minResizeWidth > minWidth) {
+    report('minResizeWidth', widget.minResizeWidth, 'greater than', 'minWidth', minWidth)
+  }
+  if (widget.minResizeHeight !== undefined && widget.minResizeHeight > minHeight) {
+    report('minResizeHeight', widget.minResizeHeight, 'greater than', 'minHeight', minHeight)
+  }
+  if (widget.maxResizeWidth !== undefined && widget.maxResizeWidth < minWidth) {
+    report('maxResizeWidth', widget.maxResizeWidth, 'smaller than', 'minWidth', minWidth)
+  }
+  if (widget.maxResizeHeight !== undefined && widget.maxResizeHeight < minHeight) {
+    report('maxResizeHeight', widget.maxResizeHeight, 'smaller than', 'minHeight', minHeight)
+  }
+
+  return warnings
+}

package/src/platforms/ios/apply.ts

@@ -2,6 +2,7 @@ import { discoverIOSProject } from '../../discovery/ios'
 import { getMissingPlatformPackageMessage, getMissingPlatformPackages } from '../../dependencies/platformPackages'
 import { VoltraCliError } from '../../reporting/summary'
 
+import { resolveIOSBuildConfigurationValues } from './buildConfigurationValues'
 import { ensureEntitlements } from './entitlements'
 import { generateIOSFiles } from './generated'
 import { ensureInfoPlist } from './plist'
@@ -52,32 +53,36 @@ export async function applyIOSPlatform(context: PlatformApplyContext): Promise<P
   }
 
   const discovery = getIOSDiscovery(context.preflight)
+  // Values given per build configuration are collapsed once, so every mutator below sees a plain
+  // string and the project carries the per-configuration values.
+  const { ios, buildSettings } = resolveIOSBuildConfigurationValues(iosConfig, discovery)
   const generatedResult = await generateIOSFiles({
     projectRoot: context.config.projectRoot,
-    ios: iosConfig,
+    ios,
     discovery,
   })
   const entitlementsResult = await ensureEntitlements({
     projectRoot: context.config.projectRoot,
-    ios: iosConfig,
+    ios,
     discovery,
   })
   const infoPlistResult = await ensureInfoPlist({
     projectRoot: context.config.projectRoot,
-    ios: iosConfig,
+    ios,
     discovery,
   })
   const podfileResult = await ensurePodfileBlock({
     projectRoot: context.config.projectRoot,
-    ios: iosConfig,
+    ios,
     discovery,
   })
   const xcodeTargetResult = await ensureIOSWidgetTarget({
     projectRoot: context.config.projectRoot,
-    ios: iosConfig,
+    ios,
     discovery,
     generatedFiles: generatedResult.files,
     previousGeneratedFiles: context.previousState?.files,
+    buildSettings,
   })
 
   if (generatedResult.targetName !== xcodeTargetResult.targetName) {
@@ -93,11 +98,10 @@ export async function applyIOSPlatform(context: PlatformApplyContext): Promise<P
   }
 
   const changes = [
-    infoPlistResult.change,
-    entitlementsResult.change,
-    podfileResult.change,
-    xcodeTargetResult.change,
-  ].filter(isDefined)
+    ...infoPlistResult.changes,
+    ...entitlementsResult.changes,
+    ...[podfileResult.change, xcodeTargetResult.change].filter(isDefined),
+  ]
 
   return {
     platform: 'ios',
@@ -130,7 +134,13 @@ function isIOSProjectDiscovery(value: unknown): value is IOSProjectDiscovery {
       candidate.podfilePath,
       candidate.mainTargetName,
       candidate.infoPlistPath,
-    ].every((entry) => typeof entry === 'string' && entry.length > 0) && Array.isArray(candidate.mainTargetCandidates)
+    ].every((entry) => typeof entry === 'string' && entry.length > 0) &&
+    [
+      candidate.mainTargetCandidates,
+      candidate.buildConfigurationNames,
+      candidate.infoPlistPaths,
+      candidate.entitlementsPaths,
+    ].every((entry) => Array.isArray(entry))
   )
 }
 

package/src/platforms/ios/buildConfigurationValues.ts

@@ -0,0 +1,105 @@
+import { getValuesByBuildConfiguration, isPerConfigurationMap } from '../../config/perConfiguration'
+import { VoltraCliError } from '../../reporting/summary'
+
+import type { PerConfiguration } from '../../config/perConfiguration'
+import type { NormalizedVoltraIOSConfig, ResolvedVoltraIOSConfig } from '../../config/types'
+import type { IOSProjectDiscovery } from '../../discovery/ios'
+
+/**
+ * Prefix of the user-defined build settings Voltra writes. Settings under it are Voltra's to add
+ * and remove, so a value that stops being per build configuration leaves nothing behind.
+ */
+export const VOLTRA_BUILD_SETTING_PREFIX = 'VOLTRA_'
+
+const APP_GROUP_IDENTIFIER_SETTING = `${VOLTRA_BUILD_SETTING_PREFIX}APP_GROUP_IDENTIFIER`
+const KEYCHAIN_GROUP_SETTING = `${VOLTRA_BUILD_SETTING_PREFIX}KEYCHAIN_GROUP`
+
+/**
+ * The settings Voltra writes and is therefore allowed to remove. Anything else a project happens to
+ * name `VOLTRA_*` belongs to the user and is left alone.
+ */
+export const VOLTRA_OWNED_BUILD_SETTINGS: readonly string[] = [APP_GROUP_IDENTIFIER_SETTING, KEYCHAIN_GROUP_SETTING]
+
+export interface IOSBuildConfigurationValues {
+  /** iOS config with every per-build-configuration value collapsed to a single string. */
+  ios: ResolvedVoltraIOSConfig
+  /** User-defined build settings to write, keyed by build configuration name. */
+  buildSettings: Map<string, Record<string, string>>
+}
+
+export class IOSBuildConfigurationValueError extends VoltraCliError {
+  constructor(message: string) {
+    super(message, 'VOLTRA_IOS_BUILD_CONFIGURATION_VALUE_FAILED')
+    this.name = 'IOSBuildConfigurationValueError'
+  }
+}
+
+/**
+ * Collapses per-build-configuration values into the single strings the platform mutators consume.
+ *
+ * A plain string resolves to itself and writes no build settings. A value given per build
+ * configuration becomes a user-defined build setting holding one value per configuration, and
+ * resolves to a reference to that setting, which Xcode expands per build into the entitlements and
+ * Info.plist files. The app and the generated widget extension both read the value that way, so
+ * nothing downstream has to know which environment is being built.
+ */
+export function resolveIOSBuildConfigurationValues(
+  ios: NormalizedVoltraIOSConfig,
+  discovery: IOSProjectDiscovery
+): IOSBuildConfigurationValues {
+  const buildSettings = new Map<string, Record<string, string>>()
+
+  const resolve = (
+    settingName: string,
+    value: PerConfiguration<string> | undefined,
+    context: string
+  ): string | undefined => {
+    if (!isPerConfigurationMap(value)) {
+      return value
+    }
+
+    const valuesByBuildConfiguration = getValuesByBuildConfiguration(
+      value,
+      discovery.buildConfigurationNames,
+      context,
+      (message) => new IOSBuildConfigurationValueError(message)
+    )
+
+    for (const [buildConfigurationName, configurationValue] of valuesByBuildConfiguration) {
+      const configurationSettings = buildSettings.get(buildConfigurationName) ?? {}
+      configurationSettings[settingName] = configurationValue
+      buildSettings.set(buildConfigurationName, configurationSettings)
+    }
+
+    return `$(${settingName})`
+  }
+
+  return {
+    ios: {
+      ...ios,
+      groupIdentifier: resolve(APP_GROUP_IDENTIFIER_SETTING, ios.groupIdentifier, 'ios.groupIdentifier'),
+      keychainGroup: resolve(KEYCHAIN_GROUP_SETTING, ios.keychainGroup, 'ios.keychainGroup'),
+      project: {
+        ...ios.project,
+        entitlementsPath: resolveEntitlementsPath(ios.project.entitlementsPath, discovery),
+      },
+    },
+    buildSettings,
+  }
+}
+
+/**
+ * The entitlements file of the default build configuration. Unlike a value written into a file, a
+ * per-configuration entitlements path is a build setting of its own, so it is applied to the Xcode
+ * project directly rather than through a reference.
+ */
+function resolveEntitlementsPath(
+  entitlementsPath: PerConfiguration<string> | undefined,
+  discovery: IOSProjectDiscovery
+): string | undefined {
+  if (!isPerConfigurationMap(entitlementsPath)) {
+    return entitlementsPath
+  }
+
+  return discovery.entitlementsPathByConfiguration?.get(discovery.buildConfigurationNames[0])
+}

package/src/platforms/ios/entitlements.ts

@@ -6,7 +6,7 @@ import { buildPlistXml, parsePlistFile } from './plist'
 import { resolveMainAppEntitlementsPath } from './mainAppEntitlements'
 
 import type { IOSProjectDiscovery } from '../../discovery/ios'
-import type { NormalizedVoltraIOSConfig } from '../../config/types'
+import type { ResolvedVoltraIOSConfig } from '../../config/types'
 import type { ReportedChange } from '../../reporting/summary'
 
 interface PreviousVoltraEntitlementValues {
@@ -17,12 +17,12 @@ interface PreviousVoltraEntitlementValues {
 
 export interface EnsureEntitlementsOptions {
   projectRoot: string
-  ios: NormalizedVoltraIOSConfig
+  ios: ResolvedVoltraIOSConfig
   discovery: IOSProjectDiscovery
 }
 
 export interface EnsureEntitlementsResult {
-  change?: ReportedChange
+  changes: ReportedChange[]
 }
 
 export class IOSEntitlementsMutationError extends VoltraCliError {
@@ -34,44 +34,68 @@ export class IOSEntitlementsMutationError extends VoltraCliError {
 
 export async function ensureEntitlements(options: EnsureEntitlementsOptions): Promise<EnsureEntitlementsResult> {
   const { projectRoot, ios, discovery } = options
-  const entitlementsPath = resolveMainAppEntitlementsPath(discovery)
+  const entitlementsPaths = resolveEntitlementsPathsToMutate(ios, discovery)
 
-  if (!discovery.entitlementsPath) {
-    if (!needsEntitlementsMutation(ios)) {
-      return {}
-    }
+  if (entitlementsPaths.length === 0) {
+    return { changes: [] }
   }
 
-  const entitlements: Record<string, unknown> = (await pathExists(entitlementsPath))
-    ? await parsePlistFile(entitlementsPath, 'main app entitlements', createEntitlementsError)
-    : {}
   const previousVoltraValues = await readPreviousVoltraEntitlementValues(discovery.infoPlistPath)
+  const changes: ReportedChange[] = []
+
+  for (const entitlementsPath of entitlementsPaths) {
+    const entitlements: Record<string, unknown> = (await pathExists(entitlementsPath))
+      ? await parsePlistFile(entitlementsPath, 'main app entitlements', createEntitlementsError)
+      : {}
+
+    ensureStringArrayValue(
+      entitlements,
+      'com.apple.security.application-groups',
+      ios.groupIdentifier,
+      previousVoltraValues.appGroupIdentifier
+    )
+    ensureStringArrayValue(
+      entitlements,
+      'keychain-access-groups',
+      ios.keychainGroup,
+      previousVoltraValues.keychainGroup
+    )
+
+    if (ios.enablePushNotifications && entitlements['aps-environment'] === undefined) {
+      entitlements['aps-environment'] = 'development'
+    } else if (
+      !ios.enablePushNotifications &&
+      previousVoltraValues.pushNotificationsEnabled &&
+      entitlements['aps-environment'] === 'development'
+    ) {
+      delete entitlements['aps-environment']
+    }
 
-  ensureStringArrayValue(
-    entitlements,
-    'com.apple.security.application-groups',
-    ios.groupIdentifier,
-    previousVoltraValues.appGroupIdentifier
-  )
-  ensureStringArrayValue(entitlements, 'keychain-access-groups', ios.keychainGroup, previousVoltraValues.keychainGroup)
-
-  if (ios.enablePushNotifications && entitlements['aps-environment'] === undefined) {
-    entitlements['aps-environment'] = 'development'
-  } else if (
-    !ios.enablePushNotifications &&
-    previousVoltraValues.pushNotificationsEnabled &&
-    entitlements['aps-environment'] === 'development'
-  ) {
-    delete entitlements['aps-environment']
+    const nextContent = buildPlistXml(entitlements, createEntitlementsError)
+    const change = await writeEntitlementsIfChanged(projectRoot, entitlementsPath, nextContent)
+
+    if (change) {
+      changes.push(change)
+    }
   }
 
-  const nextContent = buildPlistXml(entitlements, createEntitlementsError)
-  const change = await writeEntitlementsIfChanged(projectRoot, entitlementsPath, nextContent)
+  return { changes }
+}
+
+/**
+ * Every entitlements file the app target references, so each build configuration of a
+ * multi-environment app keeps its own file. Falls back to the standard path when the project
+ * references none and Voltra has values to write.
+ */
+function resolveEntitlementsPathsToMutate(ios: ResolvedVoltraIOSConfig, discovery: IOSProjectDiscovery): string[] {
+  if (discovery.entitlementsPaths.length > 0) {
+    return discovery.entitlementsPaths
+  }
 
-  return { change }
+  return needsEntitlementsMutation(ios) ? [resolveMainAppEntitlementsPath(discovery)] : []
 }
 
-export function needsEntitlementsMutation(ios: NormalizedVoltraIOSConfig): boolean {
+export function needsEntitlementsMutation(ios: ResolvedVoltraIOSConfig): boolean {
   return ios.enablePushNotifications || ios.groupIdentifier !== undefined || ios.keychainGroup !== undefined
 }
 

package/src/platforms/ios/generated.node.test.ts

@@ -0,0 +1,61 @@
+import assert from 'node:assert/strict'
+import { describe, test } from 'node:test'
+
+import { __test__ } from './generated.ts'
+
+import type { DetectedIOSWidget } from './generated.ts'
+
+describe('generateWidgetBundleSwift', () => {
+  test('imports the compiled VoltraRuntime module, not the VoltraWidget pod name', () => {
+    const swift = __test__.generateWidgetBundleSwift([])
+
+    assert.ok(swift.includes('import VoltraRuntime'))
+    assert.ok(!swift.includes('import VoltraWidget'))
+  })
+
+  test('imports VoltraRuntime when widgets are configured too', () => {
+    const widget: DetectedIOSWidget = {
+      id: 'weather',
+      displayName: 'Weather',
+      description: 'Shows weather',
+      supportedFamilies: ['systemSmall'],
+      clientRendered: false,
+    }
+
+    const swift = __test__.generateWidgetBundleSwift([widget])
+
+    assert.ok(swift.includes('import VoltraRuntime'))
+    assert.ok(!swift.includes('import VoltraWidget'))
+  })
+
+  test('defaults the WidgetKit kind to the prefixed widget id', () => {
+    const widget: DetectedIOSWidget = {
+      id: 'weather',
+      displayName: 'Weather',
+      description: 'Shows weather',
+      supportedFamilies: ['systemSmall'],
+      clientRendered: false,
+    }
+
+    const swift = __test__.generateWidgetBundleSwift([widget])
+
+    assert.ok(swift.includes('kind: "Voltra_Widget_weather"'))
+  })
+
+  test('uses the `kind` option as the WidgetKit kind when set', () => {
+    // A widget migrated from a hand-written extension keeps the kind its placed instances use.
+    const widget: DetectedIOSWidget = {
+      id: 'streak',
+      kind: 'StreakWidget',
+      displayName: 'Streak',
+      description: 'Your daily streak',
+      supportedFamilies: ['systemSmall'],
+      clientRendered: false,
+    }
+
+    const swift = __test__.generateWidgetBundleSwift([widget])
+
+    assert.ok(swift.includes('kind: "StreakWidget"'))
+    assert.ok(!swift.includes('Voltra_Widget_streak'))
+  })
+})