@use-voltra/expo-plugin 2.0.0 → 2.1.1

package/src/index.ts

@@ -0,0 +1,25 @@
+export { MAX_IMAGE_SIZE_BYTES, MODULE_EXTENSIONS } from './constants'
+export type {
+  DynamicWidgetEntryConfig,
+  DynamicWidgetManifest,
+  DynamicWidgetManifestWidget,
+  DynamicWidgetPlatform,
+  WidgetInitialStatePath,
+  WidgetLabel,
+  WidgetLocalizedCopy,
+} from './types'
+export {
+  assertValidLocaleKey,
+  normalizeWidgetEntryPath,
+  validateHomeScreenWidgetId,
+  validateInitialStatePath,
+  validateWidgetEntry,
+  validateWidgetLabel,
+} from './validation'
+export { addApplicationGroupsEntitlement } from './utils/entitlements'
+export { resolveFontPaths } from './utils/fonts'
+export { normalizeLocaleTag, pickLocalizedValue } from './utils/localePick'
+export { logger } from './utils/logger'
+export type { PrerenderableWidget, PrerenderedWidgetStates, WidgetRenderer } from './utils/prerender'
+export { evaluateWidgetModule, evaluateWidgetModuleExports, prerenderWidgetState } from './utils/prerender'
+export { isWidgetLocalizedMap, widgetLabelEnglish } from './utils/widgetLabel'

package/src/types.ts

@@ -0,0 +1,41 @@
+/**
+ * Types shared by iOS and Android Voltra config plugins.
+ * Platform widget config types live in each client's expo-plugin package.
+ */
+
+export type DynamicWidgetPlatform = 'ios' | 'android'
+
+/**
+ * Shared app.json entry contract for Dynamic Widgets.
+ *
+ * `entry` stays optional during rollout so platform packages can adopt the shared contract
+ * incrementally, but validation should require it for real widget declarations.
+ */
+export interface DynamicWidgetEntryConfig {
+  entry?: string
+}
+
+export interface DynamicWidgetManifestWidget {
+  id: string
+  entry: string
+}
+
+export interface DynamicWidgetManifest {
+  version: 1
+  platform: DynamicWidgetPlatform
+  widgets: DynamicWidgetManifestWidget[]
+}
+
+/**
+ * Per-locale strings for widget picker/gallery labels (`displayName`, `description`).
+ * Keys should be BCP-47-style locale tags (e.g. `en`, `pl`, `pt-BR`). Plain `string` is still allowed for a single-language setup.
+ */
+export type WidgetLocalizedCopy = Record<string, string>
+
+export type WidgetLabel = string | WidgetLocalizedCopy
+
+/**
+ * Build-time widget initial state source: a single file path, or per-locale paths (same key rules as `WidgetLocalizedCopy`).
+ * Each path must point to a module that exports the widget variants / default export for prerendering.
+ */
+export type WidgetInitialStatePath = string | WidgetLocalizedCopy

package/src/utils/entitlements.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared entitlements utilities.
+ */
+
+/**
+ * Adds application groups entitlement to an entitlements object.
+ * Ensures the group list is deduped and preserves existing order.
+ */
+export function addApplicationGroupsEntitlement(
+  entitlements: Record<string, any>,
+  groupIdentifier: string
+): Record<string, any> {
+  const existingApplicationGroups = ((entitlements['com.apple.security.application-groups'] as string[]) ?? []).filter(
+    Boolean
+  )
+
+  const deduped = Array.from(new Set(existingApplicationGroups))
+  if (deduped.includes(groupIdentifier)) {
+    entitlements['com.apple.security.application-groups'] = deduped
+    return entitlements
+  }
+
+  entitlements['com.apple.security.application-groups'] = [...deduped, groupIdentifier]
+
+  return entitlements
+}

package/src/utils/fonts.ts

@@ -0,0 +1,44 @@
+import * as fs from 'fs/promises'
+import * as path from 'path'
+import { createRequire } from 'module'
+
+import { logger } from './logger'
+
+const FONT_EXTENSIONS = ['.ttf', '.otf', '.woff', '.woff2']
+
+async function resolveFontInput(input: string, projectRoot: string): Promise<string | null> {
+  const resolvedPath = path.resolve(projectRoot, input)
+
+  try {
+    await fs.stat(resolvedPath)
+    return resolvedPath
+  } catch {
+    try {
+      const projectRequire = createRequire(path.join(projectRoot, 'package.json'))
+      return projectRequire.resolve(input)
+    } catch {
+      logger.warn(`Could not resolve font path: ${input}`)
+      return null
+    }
+  }
+}
+
+export async function resolveFontPaths(fonts: string[], projectRoot: string): Promise<string[]> {
+  const promises = fonts.map(async (input) => {
+    const resolvedInput = await resolveFontInput(input, projectRoot)
+    if (!resolvedInput) {
+      return []
+    }
+
+    const stat = await fs.stat(resolvedInput)
+    if (stat.isDirectory()) {
+      const dir = await fs.readdir(resolvedInput)
+      return dir.map((file) => path.join(resolvedInput, file))
+    }
+
+    return [resolvedInput]
+  })
+
+  const results = await Promise.all(promises)
+  return results.flat().filter((filePath) => FONT_EXTENSIONS.some((ext) => filePath.endsWith(ext)))
+}

package/src/utils/localePick.node.test.ts

@@ -0,0 +1,24 @@
+import { pickLocalizedValue } from './localePick'
+
+describe('pickLocalizedValue', () => {
+  it('prefers exact locale tag match', () => {
+    const out = pickLocalizedValue({ en: '{"a":1}', pl: '{"a":2}', 'pt-BR': '{"a":3}' }, ['pt-BR', 'en'])
+    expect(out).toBe('{"a":3}')
+  })
+
+  it('falls back to language-only match', () => {
+    const out = pickLocalizedValue({ en: 'en', pl: 'pl' }, ['pl-PL'])
+    expect(out).toBe('pl')
+  })
+
+  it('uses en then __default then first sorted key', () => {
+    expect(pickLocalizedValue({ de: 'de', en: 'en' }, ['fr'])).toBe('en')
+    expect(pickLocalizedValue({ __default: 'd', pl: 'pl' }, ['fr'])).toBe('d')
+    expect(pickLocalizedValue({ zz: 'z', aa: 'a' }, ['fr'])).toBe('a')
+  })
+
+  it('prefers english-family locales when plain en is absent', () => {
+    expect(pickLocalizedValue({ 'en-US': 'us', pl: 'pl' }, ['en'])).toBe('us')
+    expect(pickLocalizedValue({ de: 'de', en_GB: 'gb' }, ['en'])).toBe('gb')
+  })
+})

package/src/utils/localePick.ts

@@ -0,0 +1,53 @@
+/**
+ * Picks a localized string value from a locale-keyed map using the same fallback rules as iOS/Android runtimes:
+ * preferred language tags (full match, then language-only), then `en`, then `__default`, then first value.
+ */
+export function normalizeLocaleTag(tag: string): string {
+  return tag.trim().toLowerCase().replace(/_/g, '-')
+}
+
+export function pickLocalizedValue(
+  perLocale: Record<string, string>,
+  preferredLanguages: string[]
+): string | undefined {
+  const entries = Object.entries(perLocale).filter(([, v]) => typeof v === 'string' && v.length > 0)
+  if (entries.length === 0) {
+    return undefined
+  }
+
+  const byNorm = new Map<string, string>()
+  for (const [k, v] of entries) {
+    byNorm.set(normalizeLocaleTag(k), v)
+  }
+
+  const DEFAULT_KEY = '__default'
+
+  for (const pref of preferredLanguages) {
+    const n = normalizeLocaleTag(pref)
+    const direct = byNorm.get(n)
+    if (direct !== undefined) {
+      return direct
+    }
+    const lang = n.split('-')[0] ?? n
+    for (const [key, val] of entries) {
+      const kn = normalizeLocaleTag(key)
+      const keyLang = kn.split('-')[0] ?? kn
+      if (keyLang === lang) {
+        return val
+      }
+    }
+  }
+
+  const en = byNorm.get('en') ?? entries.find(([k]) => normalizeLocaleTag(k) === 'en')?.[1]
+  if (en !== undefined) {
+    return en
+  }
+
+  const defaultVal = byNorm.get(DEFAULT_KEY) ?? entries.find(([k]) => k === DEFAULT_KEY)?.[1]
+  if (defaultVal !== undefined) {
+    return defaultVal
+  }
+
+  const sorted = [...entries].sort(([a], [b]) => a.localeCompare(b))
+  return sorted[0]?.[1]
+}

package/src/utils/logger.ts

@@ -0,0 +1,55 @@
+/**
+ * Structured logging utility for the Voltra plugin
+ */
+
+const PREFIX = '[Voltra]'
+
+// ANSI color codes
+const RED = '\x1b[31m'
+const RESET = '\x1b[0m'
+
+export const logger = {
+  /**
+   * Log an informational message
+   */
+  info: (message: string): void => {
+    console.log(`${PREFIX} ${message}`)
+  },
+
+  /**
+   * Log a warning message
+   */
+  warn: (message: string): void => {
+    console.warn(`${PREFIX} ⚠️  ${message}`)
+  },
+
+  /**
+   * Log a warning message in red (for critical warnings)
+   */
+  warnRed: (message: string): void => {
+    console.warn(`${RED}${PREFIX} ⚠️  ${message}${RESET}`)
+  },
+
+  /**
+   * Log an error message
+   */
+  error: (message: string): void => {
+    console.error(`${PREFIX} ❌ ${message}`)
+  },
+
+  /**
+   * Log a success message
+   */
+  success: (message: string): void => {
+    console.log(`${PREFIX} ✅ ${message}`)
+  },
+
+  /**
+   * Log a debug message (only when VOLTRA_DEBUG env var is set)
+   */
+  debug: (message: string): void => {
+    if (process.env.VOLTRA_DEBUG) {
+      console.log(`${PREFIX} 🔍 ${message}`)
+    }
+  },
+}

package/src/utils/prerender.node.test.ts

@@ -0,0 +1,69 @@
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+
+import { logger } from './logger'
+import { prerenderWidgetState } from './prerender'
+
+async function writePackage(root: string, packageName: string, source: string): Promise<void> {
+  const packageDir = path.join(root, 'node_modules', ...packageName.split('/'))
+  await fs.mkdir(packageDir, { recursive: true })
+  await fs.writeFile(
+    path.join(packageDir, 'package.json'),
+    JSON.stringify(
+      {
+        name: packageName,
+        main: 'index.js',
+      },
+      null,
+      2
+    )
+  )
+  await fs.writeFile(path.join(packageDir, 'index.js'), source)
+}
+
+describe('prerenderWidgetState', () => {
+  it.each([
+    ['@use-voltra/ios-client', '@use-voltra/ios', 'ios'],
+    ['@use-voltra/android-client', '@use-voltra/android', 'android'],
+  ] as const)('redirects %s to %s and warns once', async (clientPackage, targetPackage, targetLabel) => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'voltra-prerender-'))
+    const warnSpy = jest.spyOn(logger, 'warn').mockImplementation(() => undefined)
+
+    try {
+      await fs.writeFile(
+        path.join(tempRoot, 'package.json'),
+        JSON.stringify(
+          {
+            name: 'fixture-project',
+          },
+          null,
+          2
+        )
+      )
+
+      await fs.mkdir(path.join(tempRoot, 'widgets'), { recursive: true })
+      await writePackage(tempRoot, targetPackage, `exports.label = ${JSON.stringify(targetLabel)}\n`)
+      await writePackage(tempRoot, clientPackage, `throw new Error('client package should not load')\n`)
+
+      await fs.writeFile(
+        path.join(tempRoot, 'widgets', 'state.ts'),
+        [`import { label } from '${clientPackage}'`, 'export default { label }', ''].join('\n')
+      )
+
+      const states = await prerenderWidgetState(
+        [{ id: 'demo', initialStatePath: './widgets/state.ts' }],
+        tempRoot,
+        (variants) => JSON.stringify(variants)
+      )
+
+      expect(states.get('demo')?.get('__default')).toBe(JSON.stringify({ label: targetLabel }))
+      expect(warnSpy).toHaveBeenCalledTimes(1)
+      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining(clientPackage))
+      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining(targetPackage))
+    } finally {
+      warnSpy.mockRestore()
+      await fs.rm(tempRoot, { recursive: true, force: true })
+    }
+  })
+})

package/src/utils/prerender.ts

@@ -0,0 +1,249 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { createRequire } from 'node:module'
+import vm from 'node:vm'
+
+import * as babel from '@babel/core'
+
+import { MODULE_EXTENSIONS } from '../constants'
+import type { WidgetInitialStatePath, WidgetLabel } from '../types'
+import { logger } from './logger'
+import { isWidgetLocalizedMap } from './widgetLabel'
+
+/**
+ * Type for the widget renderer function
+ */
+export type WidgetRenderer = (variants: any) => string
+
+/**
+ * Minimal interface for widget configuration needed for prerendering
+ */
+export interface PrerenderableWidget {
+  id: string
+  initialStatePath?: WidgetInitialStatePath
+}
+
+/** widgetId -> locale key -> prerendered JSON string (single-file widgets use `__default`) */
+export type PrerenderedWidgetStates = Map<string, Map<string, string>>
+
+const PRERENDER_PACKAGE_REDIRECTS: Record<string, string> = {
+  '@use-voltra/ios-client': '@use-voltra/ios',
+  '@use-voltra/android-client': '@use-voltra/android',
+}
+
+/**
+ * Check if a module specifier is a relative or absolute path (local file)
+ */
+function isLocalModule(moduleSpecifier: string): boolean {
+  return moduleSpecifier.startsWith('.') || moduleSpecifier.startsWith('/')
+}
+
+/**
+ * Resolve a module path, trying different extensions
+ */
+function resolveModulePath(moduleSpecifier: string, fromDir: string): string | null {
+  const basePath = path.resolve(fromDir, moduleSpecifier)
+
+  for (const ext of MODULE_EXTENSIONS) {
+    const fullPath = basePath + ext
+    if (fs.existsSync(fullPath) && fs.statSync(fullPath).isFile()) {
+      return fullPath
+    }
+  }
+
+  // Try index files if it's a directory
+  if (fs.existsSync(basePath) && fs.statSync(basePath).isDirectory()) {
+    for (const ext of MODULE_EXTENSIONS) {
+      const indexPath = path.join(basePath, 'index' + ext)
+      if (fs.existsSync(indexPath)) {
+        return indexPath
+      }
+    }
+  }
+
+  return null
+}
+
+function getProjectBabelConfigPath(projectRoot: string): string | null {
+  const configPath = path.join(projectRoot, 'babel.config.js')
+  return fs.existsSync(configPath) ? configPath : null
+}
+
+function getFallbackExpoPreset(projectRoot: string): string {
+  return require.resolve('babel-preset-expo', { paths: [projectRoot] })
+}
+
+/**
+ * Transpile a file with Babel
+ */
+function transpileFile(filePath: string, projectRoot: string): string {
+  const code = fs.readFileSync(filePath, 'utf8')
+  const projectBabelConfigPath = getProjectBabelConfigPath(projectRoot)
+
+  const result = babel.transformSync(code, {
+    cwd: projectRoot,
+    filename: filePath,
+    ...(projectBabelConfigPath
+      ? { configFile: projectBabelConfigPath }
+      : {
+          babelrc: false,
+          configFile: false,
+          presets: [getFallbackExpoPreset(projectRoot)],
+        }),
+  })
+
+  if (!result || !result.code) {
+    throw new Error(`Babel transpilation failed for ${filePath}`)
+  }
+
+  return result.code
+}
+
+/**
+ * Evaluate a widget module using Babel transpilation and Node.js VM.
+ * This allows executing widget code that uses JSX and React components.
+ * Local module dependencies are also transpiled with the same Babel settings.
+ *
+ * Exported so platform-specific prerender flows can reuse the same module loader rather
+ * than duplicating the Babel + VM scaffolding. The returned value is the module's exports
+ * object — callers decide whether to read `.default`, a named export, etc.
+ */
+export function evaluateWidgetModuleExports(
+  projectRoot: string,
+  filePath: string,
+  warnedRedirects = new Set<string>()
+): any {
+  // Cache for already-evaluated modules to handle circular dependencies
+  const moduleCache = new Map<string, any>()
+  const projectRequire = createRequire(path.join(projectRoot, 'package.json'))
+
+  /**
+   * Custom require that transpiles local modules with Babel
+   */
+  function customRequire(moduleSpecifier: string, currentDir: string): any {
+    // For non-local modules (npm packages), use native require
+    if (!isLocalModule(moduleSpecifier)) {
+      const redirectedSpecifier = PRERENDER_PACKAGE_REDIRECTS[moduleSpecifier]
+
+      if (redirectedSpecifier) {
+        if (!warnedRedirects.has(moduleSpecifier)) {
+          warnedRedirects.add(moduleSpecifier)
+          logger.warn(
+            `Prerendering initial state imported '${moduleSpecifier}'. Using '${redirectedSpecifier}' instead.`
+          )
+        }
+
+        return projectRequire(redirectedSpecifier)
+      }
+
+      return projectRequire(moduleSpecifier)
+    }
+
+    // Resolve the local module path
+    const resolvedPath = resolveModulePath(moduleSpecifier, currentDir)
+    if (!resolvedPath) {
+      throw new Error(`Cannot resolve module '${moduleSpecifier}' from '${currentDir}'`)
+    }
+
+    // Return cached module if already evaluated
+    if (moduleCache.has(resolvedPath)) {
+      return moduleCache.get(resolvedPath)
+    }
+
+    // Transpile and evaluate the module
+    const transpiledCode = transpileFile(resolvedPath, projectRoot)
+    const moduleDir = path.dirname(resolvedPath)
+
+    const mockModule = { exports: {} as any }
+
+    // Create require function bound to the module's directory
+    const boundRequire = (spec: string) => customRequire(spec, moduleDir)
+
+    const context = vm.createContext({
+      exports: mockModule.exports,
+      module: mockModule,
+      require: boundRequire,
+      __filename: resolvedPath,
+      __dirname: moduleDir,
+      console: console,
+      process: process,
+    })
+
+    // Cache before evaluation to handle circular dependencies
+    moduleCache.set(resolvedPath, mockModule.exports)
+
+    const script = new vm.Script(transpiledCode, { filename: resolvedPath })
+    script.runInContext(context)
+
+    // Update cache with final exports (in case module.exports was reassigned)
+    moduleCache.set(resolvedPath, mockModule.exports)
+
+    return mockModule.exports
+  }
+
+  return customRequire(filePath, path.dirname(filePath))
+}
+
+/**
+ * Evaluate a widget file as a server-style WidgetVariants module and return its object export.
+ */
+export function evaluateWidgetModule(projectRoot: string, filePath: string, warnedRedirects = new Set<string>()): any {
+  const exports = evaluateWidgetModuleExports(projectRoot, filePath, warnedRedirects)
+  const widgetVariants: any = exports.default || exports
+
+  if (!widgetVariants || typeof widgetVariants !== 'object') {
+    throw new Error('Widget file must export a WidgetVariants object or have a default export of WidgetVariants')
+  }
+
+  return widgetVariants
+}
+
+/**
+ * Prerender widget initial states for build-time inclusion.
+ *
+ * Widget code is transpiled with Babel and executed in a Node.js VM sandbox.
+ * This function loads widget files that export WidgetVariants for widgets with initialStatePath configured,
+ * renders them to JSON, and returns a map of prerendered states that can be bundled into the app.
+ *
+ * @param widgets - Array of widget configurations
+ * @param projectRoot - Root directory of the Expo project
+ * @param renderer - The renderer function to use (voltra/server or voltra/android/server)
+ * @returns Map of widgetId -> (locale key -> prerendered JSON string)
+ */
+export async function prerenderWidgetState(
+  widgets: PrerenderableWidget[],
+  projectRoot: string,
+  renderer: WidgetRenderer
+): Promise<PrerenderedWidgetStates> {
+  const prerenderedStates: PrerenderedWidgetStates = new Map()
+  const warnedRedirects = new Set<string>()
+
+  for (const widget of widgets) {
+    if (!widget.initialStatePath) {
+      continue
+    }
+
+    const pathSpec = widget.initialStatePath
+    const perLocalePaths: Record<string, string> = isWidgetLocalizedMap(pathSpec as WidgetLabel)
+      ? (pathSpec as Record<string, string>)
+      : { __default: pathSpec as string }
+
+    const inner = new Map<string, string>()
+
+    try {
+      for (const [localeKey, relativePath] of Object.entries(perLocalePaths)) {
+        const absoluteWidgetPath = path.resolve(projectRoot, relativePath)
+        const widgetVariants = evaluateWidgetModule(projectRoot, absoluteWidgetPath, warnedRedirects)
+        const prerenderedState = renderer(widgetVariants)
+        inner.set(localeKey, prerenderedState)
+      }
+      prerenderedStates.set(widget.id, inner)
+    } catch (error) {
+      throw new Error(
+        `Failed to prerender widget state for ${widget.id}: ${error instanceof Error ? error.message : String(error)}`
+      )
+    }
+  }
+
+  return prerenderedStates
+}

package/src/utils/widgetLabel.ts

@@ -0,0 +1,19 @@
+import type { WidgetLabel, WidgetLocalizedCopy } from '../types'
+
+import { pickLocalizedValue } from './localePick'
+
+export function isWidgetLocalizedMap(label: WidgetLabel): label is WidgetLocalizedCopy {
+  return typeof label === 'object' && label !== null && !Array.isArray(label)
+}
+
+/**
+ * Development / fallback English copy for LocalizedStringResource.defaultValue.
+ * Prefers `en`, then `en-*`, then default fallback order from locale picking.
+ */
+export function widgetLabelEnglish(label: WidgetLabel): string {
+  if (!isWidgetLocalizedMap(label)) {
+    return label
+  }
+
+  return pickLocalizedValue(label, ['en']) ?? ''
+}