@use-voltra/ios-client 2.3.2 → 2.4.0

package/expo-plugin/build/types/types.d.ts

@@ -1,5 +1,5 @@
 import type { ConfigPlugin } from '@expo/config-plugins';
-import type { DynamicLiveActivityEntryConfig, DynamicWidgetEntryConfig, WidgetInitialStatePath, WidgetLabel } from '@use-voltra/expo-plugin';
+import type { DynamicLiveActivityEntryConfig, DynamicWidgetEntryConfig, WidgetConfigurationOption, WidgetInitialStatePath, WidgetLabel } from '@use-voltra/expo-plugin';
 /**
  * Supported iOS Home Screen widget size families.
  */
@@ -10,10 +10,19 @@ export type IOSWidgetFamily = 'systemSmall' | 'systemMedium' | 'systemLarge' | '
 export interface AppIntentParameter {
     /** Swift property name + the key under `env.configuration`. */
     name: string;
-    /** Label shown in the widget configuration sheet. */
-    title: string;
-    /** Default value used before the user configures the widget (the "from code" default). */
+    /**
+     * Label shown in the widget configuration sheet: a plain string, or a locale map
+     * (`{ "en": "Units", "pl": "Jednostki" }`) written to the extension's `Localizable.strings`.
+     */
+    title: WidgetLabel;
+    /** Default value used before the user configures the widget (the "from code" default). Must be
+     * one of `options[].value` when `options` is set. */
     default?: string;
+    /**
+     * Fixed values the user picks from. The sheet shows a picker with each option's (localisable)
+     * `title` instead of a free-text field; `env.configuration` receives the option's `value`.
+     */
+    options?: WidgetConfigurationOption[];
 }
 /**
  * AppIntent configuration for a user-configurable widget (iOS 17+).

package/expo-plugin/build/types/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/expo-plugin/build/types/utils/fileDiscovery.d.ts

@@ -1,6 +1,8 @@
 import type { IOSWidgetExtensionFiles } from '../types';
 /** Table name matches basename without extension; co-located per locale in *.lproj */
 export declare const VOLTRA_WIDGET_STRINGS_BASENAME = "VoltraWidgets.strings";
+/** Default table: Edit Widget sheet strings, and the file that makes each `.lproj` a real resource. */
+export declare const VOLTRA_LOCALIZABLE_STRINGS_BASENAME = "Localizable.strings";
 /**
  * Scans the widget extension target directory and returns categorized file lists.
  *

package/expo-plugin/build/types/utils/fileDiscovery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fileDiscovery.d.ts","sourceRoot":"","sources":["../../../src/utils/fileDiscovery.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAA;AAGvD,sFAAsF;AACtF,eAAO,MAAM,8BAA8B,0BAA0B,CAAA;AAErE;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,uBAAuB,CA4E1G"}
+{"version":3,"file":"fileDiscovery.d.ts","sourceRoot":"","sources":["../../../src/utils/fileDiscovery.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAA;AAGvD,sFAAsF;AACtF,eAAO,MAAM,8BAA8B,0BAA0B,CAAA;AAErE,uGAAuG;AACvG,eAAO,MAAM,mCAAmC,wBAAwB,CAAA;AAExE;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,uBAAuB,CA6E1G"}

package/expo-plugin/build/types/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/validation.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,oBAAoB,EAAE,4BAA4B,EAAE,eAAe,EAAmB,MAAM,SAAS,CAAA;AAanH,wBAAgB,oCAAoC,CAClD,YAAY,EAAE,4BAA4B,EAC1C,WAAW,CAAC,EAAE,MAAM,GACnB,IAAI,CAaN;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,eAAe,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CA6B3F;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,oBAAoB,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAwEpG"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/validation.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,oBAAoB,EAAE,4BAA4B,EAAE,eAAe,EAAmB,MAAM,SAAS,CAAA;AAanH,wBAAgB,oCAAoC,CAClD,YAAY,EAAE,4BAA4B,EAC1C,WAAW,CAAC,EAAE,MAAM,GACnB,IAAI,CAaN;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,eAAe,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CA8B3F;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,oBAAoB,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAwEpG"}

package/expo-plugin/src/ios-widget/clientRenderedPrerender.ts

@@ -42,6 +42,10 @@ function buildPlaceholderEnv(voltraVersion: string): Record<string, unknown> {
     widgetFamily: 'systemMedium',
     colorScheme: 'light',
     locale: 'en-US',
+    preferredLanguages: ['en-US'],
+    layoutDirection: 'ltr',
+    hourCycle: 'h12',
+    timeZone: 'UTC',
     widgetRenderingMode: 'fullColor',
     showsWidgetContainerBackground: true,
     configuration: undefined,

package/expo-plugin/src/ios-widget/dynamic-live-activity/swift.ts

@@ -26,7 +26,15 @@ export function generateDynamicLiveActivityTypesSwift(liveActivities: IOSDynamic
     import ActivityKit
     import Foundation
 
+    // This file compiles in both the app target (pod Voltra, module
+    // VoltraRuntime) and the widget extension target (pod VoltraWidget,
+    // module VoltraWidgetRuntime). The two pods must keep distinct module
+    // names so their build products never collide.
+    #if canImport(VoltraWidgetRuntime)
+    import VoltraWidgetRuntime
+    #else
     import VoltraRuntime
+    #endif
 
     @objc(VoltraGeneratedDynamicLiveActivityRegistration)
     public final class VoltraGeneratedDynamicLiveActivityRegistration: NSObject {
@@ -97,7 +105,7 @@ export function generateDynamicLiveActivitiesSwift(liveActivities: IOSDynamicLiv
     import ActivityKit
     import SwiftUI
     import WidgetKit
-    import VoltraRuntime
+    import VoltraWidgetRuntime
 
   `
   return [header.trim(), configurations.trim()].filter(Boolean).join('\n\n')

package/expo-plugin/src/ios-widget/files/index.ts

@@ -6,6 +6,11 @@ import type { IOSDynamicLiveActivityConfig, IOSWidgetConfig } from '../../types'
 import { generateAssets } from './assets'
 import { generateEntitlements } from './entitlements'
 import { generateInfoPlist } from './infoPlist'
+import {
+  resolveDevelopmentRegion,
+  resolveExtensionLocalizations,
+  syncExtensionLocalizableStrings,
+} from './localization'
 import { generateIOSDynamicLiveActivitiesManifest, generateIOSDynamicWidgetsManifest } from './manifest'
 import { generateSwiftFiles } from './swift'
 
@@ -29,6 +34,7 @@ export interface GenerateWidgetExtensionFilesProps {
  * - VoltraWidgetBundle.swift (widget bundle definition)
  * - VoltraWidgetInitialStates.swift (pre-rendered widget states)
  * - {targetName}.entitlements (entitlements file)
+ * - <locale>.lproj/Localizable.strings (declared languages and Edit Widget sheet strings)
  *
  * This should run before configureXcodeProject so the files exist when Xcode project is configured.
  */
@@ -51,8 +57,11 @@ export const generateWidgetExtensionFiles: ConfigPlugin<GenerateWidgetExtensionF
         fs.mkdirSync(targetPath, { recursive: true })
       }
 
+      // Languages the extension declares, mirrored from the app (ADR 0009 §4)
+      const localizations = resolveExtensionLocalizations(config, widgets)
+
       // Generate Info.plist
-      generateInfoPlist(targetPath, targetName, version, buildNumber, voltraVersion)
+      generateInfoPlist(targetPath, targetName, version, buildNumber, voltraVersion, localizations)
 
       // Generate Assets.xcassets and copy user images
       generateAssets({ targetPath })
@@ -65,6 +74,10 @@ export const generateWidgetExtensionFiles: ConfigPlugin<GenerateWidgetExtensionF
         liveActivities,
       })
 
+      // <locale>.lproj/Localizable.strings: Edit Widget sheet strings, and one real resource per
+      // declared language. Runs after the gallery strings, which share the .lproj folders.
+      syncExtensionLocalizableStrings(targetPath, localizations, widgets, resolveDevelopmentRegion(config))
+
       // Write the iOS-owned Dynamic Widgets manifest for Metro to consume later.
       generateIOSDynamicWidgetsManifest({
         projectRoot,

package/expo-plugin/src/ios-widget/files/infoPlist.ts

@@ -3,6 +3,10 @@ import * as path from 'path'
 
 import { logger } from '@use-voltra/expo-plugin'
 
+function escapeXml(value: string): string {
+  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
 /**
  * Generates the Info.plist content for a WidgetKit extension.
  *
@@ -13,8 +17,17 @@ function generateInfoPlistContent(
   targetName: string,
   version: string,
   buildNumber: string,
-  voltraVersion: string
+  voltraVersion: string,
+  localizations: string[]
 ): string {
+  // CFBundleLocalizations mirrors the app's languages into the extension (ADR 0009 §4), so
+  // Locale.current and SwiftUI's \.locale there resolve the way they do in the app.
+  const localizationsEntry =
+    localizations.length > 0
+      ? `\t<key>CFBundleLocalizations</key>\n\t<array>\n${localizations
+          .map((locale) => `\t\t<string>${escapeXml(locale)}</string>\n`)
+          .join('')}\t</array>\n`
+      : ''
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -27,7 +40,7 @@ function generateInfoPlistContent(
 	<string>$(EXECUTABLE_NAME)</string>
 	<key>CFBundleIdentifier</key>
 	<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
-	<key>CFBundleInfoDictionaryVersion</key>
+${localizationsEntry}	<key>CFBundleInfoDictionaryVersion</key>
 	<string>6.0</string>
 	<key>CFBundleName</key>
 	<string>$(PRODUCT_NAME)</string>
@@ -57,15 +70,21 @@ function generateInfoPlistContent(
  * @param version - The app version (CFBundleShortVersionString)
  * @param buildNumber - The build number (CFBundleVersion)
  * @param voltraVersion - The installed @use-voltra/ios-client package version
+ * @param localizations - Languages the extension declares (`CFBundleLocalizations`); see
+ *   `resolveExtensionLocalizations`
  */
 export function generateInfoPlist(
   targetPath: string,
   targetName: string,
   version: string,
   buildNumber: string,
-  voltraVersion: string
+  voltraVersion: string,
+  localizations: string[] = []
 ): void {
   const infoPlistPath = path.join(targetPath, 'Info.plist')
-  fs.writeFileSync(infoPlistPath, generateInfoPlistContent(targetName, version, buildNumber, voltraVersion))
+  fs.writeFileSync(
+    infoPlistPath,
+    generateInfoPlistContent(targetName, version, buildNumber, voltraVersion, localizations)
+  )
   logger.info('Generated Info.plist')
 }

package/expo-plugin/src/ios-widget/files/localization.ts

@@ -0,0 +1,176 @@
+import * as fs from 'fs'
+import * as path from 'path'
+
+import {
+  collectLabelLocaleKeys,
+  collectWidgetConfigurationStrings,
+  isWidgetLocalizedMap,
+  normalizeLocaleTag,
+  pickLocalizedValue,
+  widgetLabelEnglish,
+  type WidgetLabel,
+} from '@use-voltra/expo-plugin'
+
+import type { IOSWidgetConfig } from '../../types'
+import { VOLTRA_LOCALIZABLE_STRINGS_BASENAME } from '../../utils/fileDiscovery'
+import { escapeForSwiftStringLiteral } from './swift-utils'
+
+/**
+ * The parts of the Expo config that say which languages the app supports: the `locales` map
+ * (`{ "pl": "./languages/pl.json" }`) and an explicit `ios.infoPlist.CFBundleLocalizations`.
+ */
+export interface AppLocalizationSource {
+  locales?: Record<string, unknown> | null
+  ios?: { infoPlist?: Record<string, unknown> | null } | null
+}
+
+function widgetLabels(widget: IOSWidgetConfig): Array<WidgetLabel | undefined> {
+  return [
+    widget.displayName,
+    widget.description,
+    ...(widget.appIntent?.parameters ?? []).flatMap((parameter) => [
+      parameter.title,
+      ...(parameter.options ?? []).map((option) => option.title),
+    ]),
+  ]
+}
+
+const LOCALE_TAG_PATTERN = /^[a-zA-Z][a-zA-Z0-9]*([_-][a-zA-Z0-9]+)*$/
+
+/**
+ * The app's development language: `ios.infoPlist.CFBundleDevelopmentRegion` when it is a literal
+ * locale tag, otherwise `en` (Expo's default, and what `$(DEVELOPMENT_LANGUAGE)` is in practice).
+ */
+export function resolveDevelopmentRegion(config: AppLocalizationSource | undefined): string {
+  const region = config?.ios?.infoPlist?.CFBundleDevelopmentRegion
+  return typeof region === 'string' && LOCALE_TAG_PATTERN.test(region.trim()) ? region.trim() : 'en'
+}
+
+/**
+ * The languages the widget extension declares (ADR 0009 §4).
+ *
+ * iOS resolves `Locale.current` and SwiftUI's `\.locale` in the extension against the extension
+ * bundle's own localisations, so an extension that declares none reports `en_PL` to a Polish user
+ * of a Polish app. Mirroring the app's languages makes the extension resolve the way the app does.
+ *
+ * Sources: the Expo `locales` keys, `ios.infoPlist.CFBundleLocalizations`, and every locale used
+ * by a widget's locale maps. The app's development language (see `resolveDevelopmentRegion`) is
+ * added whenever anything is declared: it is the language iOS falls back to when none of the user's
+ * languages match, so its `.lproj` must exist and carry every string.
+ */
+export function resolveExtensionLocalizations(
+  config: AppLocalizationSource | undefined,
+  widgets: IOSWidgetConfig[] | undefined
+): string[] {
+  const candidates: string[] = []
+
+  for (const locale of Object.keys(config?.locales ?? {})) {
+    candidates.push(locale)
+  }
+
+  const infoPlistLocalizations = config?.ios?.infoPlist?.CFBundleLocalizations
+  if (Array.isArray(infoPlistLocalizations)) {
+    for (const locale of infoPlistLocalizations) {
+      if (typeof locale === 'string') {
+        candidates.push(locale)
+      }
+    }
+  }
+
+  candidates.push(...collectLabelLocaleKeys((widgets ?? []).flatMap(widgetLabels)))
+
+  const byNormalized = new Map<string, string>()
+  for (const candidate of candidates) {
+    const trimmed = candidate.trim()
+    if (!trimmed || trimmed === '__default' || !LOCALE_TAG_PATTERN.test(trimmed)) {
+      continue
+    }
+    const normalized = normalizeLocaleTag(trimmed)
+    if (!byNormalized.has(normalized)) {
+      byNormalized.set(normalized, trimmed)
+    }
+  }
+
+  const developmentRegion = resolveDevelopmentRegion(config)
+  const developmentLanguage = normalizeLocaleTag(developmentRegion).split('-')[0]
+  if (byNormalized.size > 0 && ![...byNormalized.keys()].some((key) => key.split('-')[0] === developmentLanguage)) {
+    byNormalized.set(normalizeLocaleTag(developmentRegion), developmentRegion)
+  }
+
+  return [...byNormalized.values()].sort((a, b) => a.localeCompare(b))
+}
+
+/**
+ * The Edit Widget sheet strings for one locale: every locale-mapped title, resolved for `locale`,
+ * then the development language, then the usual fallback (English, `__default`, first), so every
+ * key resolves in every `.lproj` and none shows verbatim. Plain-string titles are compiled into the
+ * Swift source as literals and need no entry.
+ */
+export function collectSheetStringsForLocale(
+  widgets: IOSWidgetConfig[] | undefined,
+  locale: string,
+  developmentRegion = 'en'
+): Record<string, string> {
+  const entries: Record<string, string> = {}
+  for (const widget of widgets ?? []) {
+    for (const { key, label } of collectWidgetConfigurationStrings(widget)) {
+      if (!isWidgetLocalizedMap(label)) {
+        continue
+      }
+      entries[key] = pickLocalizedValue(label, [locale, developmentRegion]) ?? widgetLabelEnglish(label)
+    }
+  }
+  return entries
+}
+
+function formatLocalizableStrings(entries: Record<string, string>): string {
+  const lines = Object.keys(entries)
+    .sort()
+    .map((key) => `"${escapeForSwiftStringLiteral(key)}" = "${escapeForSwiftStringLiteral(entries[key]!)}";`)
+  return `/* Voltra widget extension strings (auto-generated) */\n${lines.join('\n')}${lines.length > 0 ? '\n' : ''}`
+}
+
+/**
+ * Writes `<locale>.lproj/Localizable.strings` for every declared language. The file carries the
+ * Edit Widget sheet strings (ADR 0009 §6) and, even when empty, makes the `.lproj` folder a real
+ * resource of the extension target so iOS sees the language as supported.
+ *
+ * The extension is generated and owned by Voltra, so every `Localizable.strings` in it is ours to
+ * rewrite; stale ones from a removed language are deleted.
+ */
+export function syncExtensionLocalizableStrings(
+  targetPath: string,
+  locales: string[],
+  widgets: IOSWidgetConfig[] | undefined,
+  developmentRegion = 'en'
+): void {
+  if (fs.existsSync(targetPath)) {
+    for (const entry of fs.readdirSync(targetPath)) {
+      if (!entry.endsWith('.lproj')) {
+        continue
+      }
+      const dirPath = path.join(targetPath, entry)
+      const stringsPath = path.join(dirPath, VOLTRA_LOCALIZABLE_STRINGS_BASENAME)
+      if (fs.existsSync(stringsPath)) {
+        fs.unlinkSync(stringsPath)
+      }
+      try {
+        if (fs.readdirSync(dirPath).length === 0) {
+          fs.rmdirSync(dirPath)
+        }
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+
+  for (const locale of locales) {
+    const lproj = path.join(targetPath, `${locale}.lproj`)
+    fs.mkdirSync(lproj, { recursive: true })
+    fs.writeFileSync(
+      path.join(lproj, VOLTRA_LOCALIZABLE_STRINGS_BASENAME),
+      formatLocalizableStrings(collectSheetStringsForLocale(widgets, locale, developmentRegion)),
+      'utf8'
+    )
+  }
+}

package/expo-plugin/src/ios-widget/files/swift.ts

@@ -7,12 +7,14 @@ import {
   logger,
   prerenderWidgetState,
   widgetLabelEnglish,
+  widgetParameterOptionKey,
+  widgetParameterTitleKey,
   type PrerenderedWidgetStates,
   type WidgetLabel,
 } from '@use-voltra/expo-plugin'
 
 import { DEFAULT_WIDGET_FAMILIES, WIDGET_FAMILY_MAP, widgetKind } from '../../constants'
-import type { IOSDynamicLiveActivityConfig, IOSWidgetConfig } from '../../types'
+import type { AppIntentParameter, IOSDynamicLiveActivityConfig, IOSWidgetConfig } from '../../types'
 import { VOLTRA_WIDGET_STRINGS_BASENAME } from '../../utils/fileDiscovery'
 import { detectClientRenderedWidgets, type DetectedIOSWidget } from '../clientRendered'
 import { prerenderClientRenderedWidgets } from '../clientRenderedPrerender'
@@ -372,6 +374,67 @@ function generateWidgetStruct(widget: DetectedIOSWidget): string {
   `
 }
 
+/**
+ * Generates a Dynamic Widget backed by AppIntentConfiguration (iOS 17+): a
+ * WidgetConfigurationIntent (params + code defaults), an AppIntentTimelineProvider that loads the
+ * bundle via the shared client runtime, and an AppIntentConfiguration widget. The configured
+ * params are passed into the render as env.configuration; the native "Edit Widget" sheet edits them.
+ */
+/**
+ * A string literal for a title on the Edit Widget sheet (ADR 0009 §6). A plain string is compiled in
+ * as-is. A locale map becomes a bare string-literal key into the extension's default `Localizable`
+ * table, which `syncExtensionLocalizableStrings` fills for every declared language: the one form
+ * the App Intents metadata processor is documented to accept without question.
+ */
+function sheetStringLiteral(label: WidgetLabel, key: string): string {
+  return `"${escapeForSwiftStringLiteral(isWidgetLocalizedMap(label) ? key : label)}"`
+}
+
+function parameterOptionEnumName(widgetId: string, parameterName: string): string {
+  return `VoltraWidget_${widgetId}_${parameterName}_Option`
+}
+
+/**
+ * Static `options` become an `AppEnum`, so the sheet shows a picker of localised labels instead of
+ * a free-text field. Cases are positional (`option0`…) because option values are free-form; the raw
+ * value is the option's `value`, which is what `env.configuration` receives.
+ */
+function generateParameterOptionEnum(widgetId: string, parameter: AppIntentParameter): string {
+  const options = parameter.options ?? []
+  const enumName = parameterOptionEnumName(widgetId, parameter.name)
+  const cases = options
+    .map((option, index) => `  case option${index} = "${escapeForSwiftStringLiteral(option.value)}"`)
+    .join('\n')
+  const representations = options
+    .map(
+      (option, index) =>
+        `    .option${index}: ${sheetStringLiteral(
+          option.title,
+          widgetParameterOptionKey(widgetId, parameter.name, option.value)
+        )},`
+    )
+    .join('\n')
+  const typeTitle = sheetStringLiteral(parameter.title, widgetParameterTitleKey(widgetId, parameter.name))
+
+  return [
+    '@available(iOS 17.0, *)',
+    `enum ${enumName}: String, AppEnum {`,
+    cases,
+    '',
+    `  static var typeDisplayRepresentation: TypeDisplayRepresentation = ${typeTitle}`,
+    `  static var caseDisplayRepresentations: [${enumName}: DisplayRepresentation] = [`,
+    representations,
+    '  ]',
+    '}',
+  ].join('\n')
+}
+
+/** Index of the option `parameter.default` names, or the first option. */
+function defaultOptionIndex(parameter: AppIntentParameter): number {
+  const index = (parameter.options ?? []).findIndex((option) => option.value === parameter.default)
+  return index >= 0 ? index : 0
+}
+
 /**
  * Generates a Dynamic Widget backed by AppIntentConfiguration (iOS 17+): a
  * WidgetConfigurationIntent (params + code defaults), an AppIntentTimelineProvider that loads the
@@ -388,20 +451,35 @@ function generateClientAppIntentWidgetCode(widget: DetectedIOSWidget): string {
   const displayNameExpr = iosWidgetGalleryLabelSwiftExpr(widget.id, 'displayName', widget.displayName)
   const descriptionExpr = iosWidgetGalleryLabelSwiftExpr(widget.id, 'description', widget.description)
 
-  const swiftDefault = (p: { default?: string }) => `"${escapeForSwiftStringLiteral(p.default ?? '')}"`
+  const hasOptions = (p: AppIntentParameter) => (p.options?.length ?? 0) > 0
+  // The raw default, as env.configuration sees it before the user configures anything.
+  const swiftDefault = (p: AppIntentParameter) =>
+    hasOptions(p)
+      ? `"${escapeForSwiftStringLiteral(p.options![defaultOptionIndex(p)]!.value)}"`
+      : `"${escapeForSwiftStringLiteral(p.default ?? '')}"`
+  const swiftType = (p: AppIntentParameter) => (hasOptions(p) ? parameterOptionEnumName(widget.id, p.name) : 'String')
+  const parameterDefault = (p: AppIntentParameter) =>
+    hasOptions(p) ? `.option${defaultOptionIndex(p)}` : swiftDefault(p)
+  const configuredValue = (p: AppIntentParameter) =>
+    hasOptions(p) ? `configuration.${p.name}.rawValue` : `configuration.${p.name}`
   const dictLiteral = (entries: string[]) => (entries.length > 0 ? `[${entries.join(', ')}]` : '[:]')
 
+  const optionEnums = params
+    .filter(hasOptions)
+    .map((p) => generateParameterOptionEnum(widget.id, p))
+    .join('\n\n')
   const paramDecls = params
     .map(
       (p) =>
-        `  @Parameter(title: "${escapeForSwiftStringLiteral(p.title)}", default: ${swiftDefault(p)})\n  var ${
-          p.name
-        }: String`
+        `  @Parameter(title: ${sheetStringLiteral(
+          p.title,
+          widgetParameterTitleKey(widget.id, p.name)
+        )}, default: ${parameterDefault(p)})\n  var ${p.name}: ${swiftType(p)}`
     )
     .join('\n\n')
-  const initParams = params.map((p) => `${p.name}: String`).join(', ')
+  const initParams = params.map((p) => `${p.name}: ${swiftType(p)}`).join(', ')
   const initBody = params.map((p) => `    self.${p.name} = ${p.name}`).join('\n')
-  const configuredDict = dictLiteral(params.map((p) => `"${p.name}": configuration.${p.name}`))
+  const configuredDict = dictLiteral(params.map((p) => `"${p.name}": ${configuredValue(p)}`))
   const defaultDict = dictLiteral(params.map((p) => `"${p.name}": ${swiftDefault(p)}`))
   // A server-driven Dynamic Widget fetches on every timeline request and schedules the next one
   // from its resolved interval; a plain one has nothing to ask again for, so its policy is .never.
@@ -418,7 +496,7 @@ function generateClientAppIntentWidgetCode(widget: DetectedIOSWidget): string {
 
   return dedent`
     // MARK: - Client-rendered AppIntent widget: ${widget.id}
-
+    ${optionEnums ? `\n${optionEnums}\n` : ''}
     @available(iOS 17.0, *)
     struct ${intentName}: WidgetConfigurationIntent {
       static var title: LocalizedStringResource = "${intentTitle}"
@@ -518,7 +596,7 @@ function generateWidgetBundleSwift(
 
     ${foundationImport}${appIntentsImport}import SwiftUI
     import WidgetKit
-    import VoltraRuntime
+    import VoltraWidgetRuntime
 
     @main
     struct VoltraWidgetBundle: WidgetBundle {
@@ -552,7 +630,7 @@ function generateDefaultWidgetBundleSwift(): string {
 
     import SwiftUI
     import WidgetKit
-    import VoltraRuntime  // Import Voltra widgets
+    import VoltraWidgetRuntime  // Import Voltra widgets
 
     @main
     struct VoltraWidgetBundle: WidgetBundle {

package/expo-plugin/src/ios-widget/xcode/groups.ts

@@ -1,7 +1,7 @@
 import { XcodeProject } from '@expo/config-plugins'
 
 import type { IOSWidgetExtensionFiles } from '../../types'
-import { ensureWidgetFileReference } from './fileReferences'
+import { ensureWidgetFileReference, normalizeRef } from './fileReferences'
 
 const pbxFile = require('xcode/lib/pbxFile')
 
@@ -89,8 +89,11 @@ export function ensurePbxGroup(xcodeProject: XcodeProject, options: AddPbxGroupO
   for (const filePath of allFiles) {
     const file = new pbxFile(filePath)
     const fileRef = ensureWidgetFileReference(xcodeProject, filePath, targetName)
+    // Localized files share a basename across `.lproj` folders (`pl.lproj/Localizable.strings`,
+    // `de.lproj/Localizable.strings`), so for them only the file reference itself identifies the child.
+    const isLocalized = filePath.includes('.lproj/')
     const alreadyInGroup = existingGroup.children.some(
-      (child: any) => child.value === fileRef || child.comment === file.basename
+      (child: any) => normalizeRef(child.value) === fileRef || (!isLocalized && child.comment === file.basename)
     )
     if (!alreadyInGroup) {
       existingGroup.children.push({ value: fileRef, comment: file.basename })

package/expo-plugin/src/types.ts

@@ -3,6 +3,7 @@ import type { ConfigPlugin } from '@expo/config-plugins'
 import type {
   DynamicLiveActivityEntryConfig,
   DynamicWidgetEntryConfig,
+  WidgetConfigurationOption,
   WidgetInitialStatePath,
   WidgetLabel,
 } from '@use-voltra/expo-plugin'
@@ -25,10 +26,19 @@ export type IOSWidgetFamily =
 export interface AppIntentParameter {
   /** Swift property name + the key under `env.configuration`. */
   name: string
-  /** Label shown in the widget configuration sheet. */
-  title: string
-  /** Default value used before the user configures the widget (the "from code" default). */
+  /**
+   * Label shown in the widget configuration sheet: a plain string, or a locale map
+   * (`{ "en": "Units", "pl": "Jednostki" }`) written to the extension's `Localizable.strings`.
+   */
+  title: WidgetLabel
+  /** Default value used before the user configures the widget (the "from code" default). Must be
+   * one of `options[].value` when `options` is set. */
   default?: string
+  /**
+   * Fixed values the user picks from. The sheet shows a picker with each option's (localisable)
+   * `title` instead of a free-text field; `env.configuration` receives the option's `value`.
+   */
+  options?: WidgetConfigurationOption[]
 }
 
 /**

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)) {