@use-voltra/core 2.0.0-rc.4 → 2.1.0

package/src/renderer/renderer.ts

@@ -0,0 +1,491 @@
+import {
+  ComponentType,
+  ConsumerProps,
+  Context,
+  ForwardRefExoticComponent,
+  FunctionComponent,
+  LazyExoticComponent,
+  MemoExoticComponent,
+  ProviderProps,
+  ReactElement,
+  ReactNode,
+} from 'react'
+import {
+  isContextConsumer,
+  isContextProvider,
+  isForwardRef,
+  isFragment,
+  isLazy,
+  isMemo,
+  isPortal,
+  isProfiler,
+  isStrictMode,
+  isSuspense,
+} from 'react-is'
+
+import { isVoltraComponent } from '../jsx/createVoltraComponent.js'
+import { shorten } from '../payload/short-names.js'
+import { VoltraElementRef, VoltraNodeJson, VoltraPropValue } from '../types.js'
+import { ContextRegistry, getContextRegistry } from './context-registry.js'
+import { getHooksDispatcher, getReactCurrentDispatcher } from './dispatcher.js'
+import { createElementRegistry, type ElementRegistry, preScanForDuplicates } from './element-registry.js'
+import { flattenStyle } from './flatten-styles.js'
+import { getRenderCache, type RenderCache } from './render-cache.js'
+import { createStylesheetRegistry, type StylesheetRegistry } from './stylesheet-registry.js'
+
+export type ComponentRegistry = {
+  getComponentId: (name: string) => number
+}
+
+type VoltraRenderingContext = {
+  registry: ContextRegistry
+  stylesheetRegistry?: StylesheetRegistry
+  elementRegistry?: ElementRegistry
+  duplicates?: Set<ReactNode>
+  inStringOnlyContext?: boolean
+  componentRegistry: ComponentRegistry
+}
+
+function renderNode(element: ReactNode, context: VoltraRenderingContext): VoltraNodeJson {
+  if (element === null || element === undefined) {
+    return []
+  }
+
+  if (typeof element === 'boolean') {
+    if (context.inStringOnlyContext) {
+      return ''
+    }
+    return []
+  }
+
+  if (typeof element === 'string') {
+    if (context.inStringOnlyContext) {
+      return element
+    }
+    throw new Error(
+      'Expected a React element, but got "string". Strings are only allowed as children of Text components.'
+    )
+  }
+
+  if (typeof element === 'number' || typeof element === 'bigint') {
+    if (context.inStringOnlyContext) {
+      return String(element)
+    }
+    throw new Error(`Expected a React element, but got "${typeof element}".`)
+  }
+
+  if (Array.isArray(element)) {
+    if (context.inStringOnlyContext) {
+      if (element.length === 0) {
+        throw new Error('Text component must have at least one child that resolves to a string.')
+      }
+      const results: string[] = []
+      for (const child of element) {
+        const result = renderNode(child, context)
+        if (Array.isArray(result) && result.length === 0) {
+          continue
+        }
+        if (typeof result !== 'string') {
+          throw new Error('Text component children must resolve to strings.')
+        }
+        results.push(result)
+      }
+      return results.join('')
+    }
+    return element.map((child) => renderNode(child, context)).flat() as VoltraNodeJson
+  }
+
+  if (context.duplicates?.has(element) && context.elementRegistry) {
+    const existingIndex = context.elementRegistry.isRegistered(element)
+    if (existingIndex !== undefined) {
+      return { $r: existingIndex } as VoltraElementRef
+    }
+
+    const rendered = renderNodeInternal(element, context)
+    const index = context.elementRegistry.register(element, rendered)
+    return { $r: index } as VoltraElementRef
+  }
+
+  return renderNodeInternal(element, context)
+}
+
+function renderNodeInternal(element: ReactNode, context: VoltraRenderingContext): VoltraNodeJson {
+  if (typeof element !== 'object' || element === null) {
+    throw new Error(`Expected element-like object with type and props, got ${typeof element}`)
+  }
+
+  if (!('type' in element) || !('props' in element)) {
+    throw new Error(`Expected element-like object with type and props, got ${typeof element}`)
+  }
+
+  if (typeof element.type === 'string') {
+    throw new Error(`Host component "${element.type}" is not supported in Voltra.`)
+  }
+
+  if (isStrictMode(element)) {
+    throw new Error('Strict mode is not supported in Voltra.')
+  }
+  if (isProfiler(element)) {
+    throw new Error('Profiler is not supported in Voltra.')
+  }
+  if (isSuspense(element)) {
+    throw new Error('Suspense is not supported in Voltra.')
+  }
+  if (isPortal(element) || (element as { type?: unknown }).type === Symbol.for('react.portal')) {
+    throw new Error('Portal is not supported in Voltra.')
+  }
+
+  if (isFragment(element) || (element as { type?: unknown }).type === Symbol.for('react.fragment')) {
+    const fragmentElement = element as ReactElement<{ children?: ReactNode }>
+    return renderNode(fragmentElement.props.children, context)
+  }
+
+  if (isMemo(element)) {
+    const memoElement = element as ReactElement<unknown, MemoExoticComponent<ComponentType<unknown>>>
+    const { type: memoizedComponent } = memoElement.type
+    return renderNode({ ...memoElement, type: memoizedComponent }, context)
+  }
+
+  if (isForwardRef(element)) {
+    const forwardRefElement = element as ReactElement<unknown, ForwardRefExoticComponent<ComponentType<unknown>>>
+    const { render } = forwardRefElement.type as unknown as { render: (props: unknown) => ReactNode }
+    return renderFunctionalComponent(render, forwardRefElement.props, context)
+  }
+
+  if (isLazy(element)) {
+    const lazyElement = element as ReactElement<unknown, LazyExoticComponent<ComponentType<unknown>>>
+    const lazyType = lazyElement.type as unknown as {
+      _init?: (payload: unknown) => ComponentType<unknown>
+      _payload?: unknown
+    }
+
+    if (typeof lazyType._init !== 'function') {
+      throw new Error('Lazy component could not be resolved by the Voltra renderer.')
+    }
+
+    try {
+      const resolvedType = lazyType._init(lazyType._payload)
+      return renderNode({ ...lazyElement, type: resolvedType }, context)
+    } catch (error) {
+      if (error instanceof Promise) {
+        throw new Error('Lazy component suspended! Voltra does not support Suspense/Promises.')
+      }
+
+      throw error
+    }
+  }
+
+  if (isContextProvider(element)) {
+    const contextProviderElement = element as ReactElement<ProviderProps<unknown>>
+    const reactContext = contextProviderElement.type as Context<unknown>
+    const { value, children } = contextProviderElement.props
+    context.registry.pushProvider(reactContext, value)
+    const result = renderNode(children, context)
+    context.registry.popProvider(reactContext)
+    return result
+  }
+
+  if (isContextConsumer(element)) {
+    const contextConsumerElement = element as ReactElement<ConsumerProps<unknown>>
+    const reactContext = (contextConsumerElement.type as unknown as { _context: Context<unknown> })._context
+    const value = context.registry.readContext(reactContext)
+    const children = contextConsumerElement.props.children
+
+    if (typeof children === 'function') {
+      return renderNode(children(value), context)
+    }
+
+    throw new Error(`Expected a function as children of a context consumer, but got "${typeof children}".`)
+  }
+
+  if (
+    element != null &&
+    typeof element === 'object' &&
+    'type' in element &&
+    'props' in element &&
+    typeof (element as { type: unknown }).type === 'function'
+  ) {
+    const reactElement = element as ReactElement
+    const componentType = reactElement.type as FunctionComponent<unknown>
+
+    if (componentType.prototype && 'render' in componentType.prototype) {
+      throw new Error('Class components are not supported in Voltra.')
+    }
+
+    if (isVoltraComponent(componentType)) {
+      const child = componentType(reactElement.props)
+
+      if (typeof child !== 'object' || child === null || !('type' in child) || !('props' in child)) {
+        throw new Error(`Expected a React element, but got "${typeof child}".`)
+      }
+
+      if (typeof child.type !== 'string') {
+        throw new Error(`Expected a string as the type of a React element, but got "${typeof child.type}".`)
+      }
+
+      const { children, ...parameters } = child.props as { children?: ReactNode; [key: string]: unknown }
+      const isTextComponent = child.type === 'Text' || child.type === 'AndroidText'
+      const childContext: VoltraRenderingContext = {
+        ...context,
+        inStringOnlyContext: isTextComponent,
+      }
+      const renderedChildren =
+        children !== null && children !== undefined ? renderNode(children, childContext) : isTextComponent ? '' : []
+
+      const id = typeof parameters.id === 'string' ? parameters.id : undefined
+      const { id: _id, ...cleanParameters } = parameters
+
+      if (isTextComponent) {
+        if (typeof renderedChildren !== 'string') {
+          throw new Error(
+            'Text component children must resolve to a string. Nested components are allowed, but they must eventually resolve to a string.'
+          )
+        }
+
+        const transformedProps = transformProps(cleanParameters, context)
+        const hasProps = Object.keys(transformedProps).length > 0
+
+        return {
+          t: context.componentRegistry.getComponentId(child.type),
+          ...(id ? { i: id } : {}),
+          c: renderedChildren,
+          ...(hasProps ? { p: transformedProps } : {}),
+        }
+      }
+
+      if (typeof renderedChildren === 'string') {
+        throw new Error('Unexpected string in non-Text component children.')
+      }
+
+      const transformedProps = transformProps(cleanParameters, context)
+      const hasProps = Object.keys(transformedProps).length > 0
+      const hasChildren = Array.isArray(renderedChildren) ? renderedChildren.length > 0 : true
+
+      return {
+        t: context.componentRegistry.getComponentId(child.type),
+        ...(id ? { i: id } : {}),
+        ...(hasChildren ? { c: renderedChildren } : {}),
+        ...(hasProps ? { p: transformedProps } : {}),
+      }
+    }
+
+    return renderFunctionalComponent(componentType, reactElement.props, context)
+  }
+
+  throw new Error(
+    `Unsupported element type "${String(
+      (element as { type?: unknown }).type
+    )}". Report this as a bug in the Voltra project.`
+  )
+}
+
+export const renderFunctionalComponent = <TProps>(
+  Component: FunctionComponent<TProps>,
+  props: TProps,
+  context: VoltraRenderingContext
+): VoltraNodeJson => {
+  const reactDispatcher = getReactCurrentDispatcher()
+  const prevHooksDispatcher = reactDispatcher.H
+
+  try {
+    reactDispatcher.H = getHooksDispatcher(context.registry)
+    const result = Component(props)
+
+    if (result instanceof Promise) {
+      throw new Error(
+        `Component "${
+          Component.name || 'Anonymous'
+        }" tried to suspend (returned a Promise). Async components are not supported in this synchronous renderer.`
+      )
+    }
+
+    return renderNode(result, context)
+  } catch (error) {
+    if (error instanceof Promise) {
+      throw new Error(
+        `Component "${Component.name || 'Anonymous'}" suspended! Voltra does not support Suspense/Promises.`
+      )
+    }
+
+    throw error
+  } finally {
+    reactDispatcher.H = prevHooksDispatcher
+  }
+}
+
+export const renderVariantToJson = (element: ReactNode, componentRegistry: ComponentRegistry): VoltraNodeJson => {
+  const registry = getContextRegistry()
+  const context: VoltraRenderingContext = {
+    registry,
+    componentRegistry,
+  }
+
+  return renderNode(element, context)
+}
+
+function compressStyleObject(style: any): any {
+  if (style === null || style === undefined) {
+    return style
+  }
+
+  const flattened = flattenStyle(style)
+  const compressed: Record<string, any> = {}
+
+  for (const [key, value] of Object.entries(flattened)) {
+    const shortKey = shorten(key)
+
+    if (value === null || value === undefined) {
+      continue
+    }
+
+    if (typeof value === 'object' && !Array.isArray(value) && value.constructor === Object) {
+      const compressedNested: Record<string, any> = {}
+      for (const [nestedKey, nestedValue] of Object.entries(value)) {
+        compressedNested[nestedKey] = nestedValue
+      }
+      compressed[shortKey] = compressedNested
+    } else {
+      compressed[shortKey] = value
+    }
+  }
+
+  return compressed
+}
+
+function isReactNode(value: unknown): value is ReactNode {
+  if (value === null || value === undefined || value === false || value === true) {
+    return false
+  }
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'bigint') {
+    return false
+  }
+  if (Array.isArray(value)) {
+    return true
+  }
+  if (typeof value === 'object' && value !== null && 'type' in value && 'props' in value) {
+    return true
+  }
+  return false
+}
+
+export function transformProps(
+  props: Record<string, unknown>,
+  context: VoltraRenderingContext
+): Record<string, VoltraPropValue> {
+  const transformed: Record<string, VoltraPropValue> = {}
+
+  for (const [key, value] of Object.entries(props)) {
+    if (key === 'style') {
+      const shortKey = shorten(key)
+      if (context.stylesheetRegistry) {
+        const index = context.stylesheetRegistry.registerStyle(value as object)
+        transformed[shortKey] = index
+      } else {
+        transformed[shortKey] = compressStyleObject(value)
+      }
+    } else if (isReactNode(value)) {
+      const serializedComponent = renderNode(value, {
+        registry: getContextRegistry(),
+        stylesheetRegistry: context.stylesheetRegistry,
+        elementRegistry: context.elementRegistry,
+        duplicates: context.duplicates,
+        inStringOnlyContext: false,
+        componentRegistry: context.componentRegistry,
+      })
+      const shortKey = shorten(key)
+      transformed[shortKey] = serializedComponent
+    } else {
+      const shortKey = shorten(key)
+      transformed[shortKey] = value as VoltraPropValue
+    }
+  }
+
+  return transformed
+}
+
+export const VOLTRA_PAYLOAD_VERSION = 1
+
+export const createVoltraRenderer = (componentRegistry: ComponentRegistry) => {
+  const rootNodes: { name: string; node: ReactNode }[] = []
+
+  let duplicates: Set<ReactNode> | undefined
+  let stylesheetRegistry: StylesheetRegistry | undefined
+  let elementRegistry: ElementRegistry | undefined
+  let renderCache: RenderCache | undefined
+
+  const addRootNode = (name: string, node: ReactNode): void => {
+    if (node === null || node === undefined) {
+      return
+    }
+    rootNodes.push({ name, node })
+  }
+
+  const preScanAllNodes = (): Set<ReactNode> => {
+    const seen = new Set<ReactNode>()
+    const duplicatesSet = new Set<ReactNode>()
+
+    for (const { node } of rootNodes) {
+      if (node && typeof node === 'object') {
+        if (seen.has(node)) {
+          duplicatesSet.add(node)
+        } else {
+          seen.add(node)
+        }
+      }
+
+      const nodeDuplicates = preScanForDuplicates(node)
+      for (const dup of nodeDuplicates) {
+        duplicatesSet.add(dup)
+      }
+    }
+
+    return duplicatesSet
+  }
+
+  const render = (): Record<string, any> => {
+    stylesheetRegistry = createStylesheetRegistry()
+    elementRegistry = createElementRegistry()
+    duplicates = preScanAllNodes()
+
+    const renderVariantToJson = (element: ReactNode): VoltraNodeJson => {
+      const registry = getContextRegistry()
+      const context: VoltraRenderingContext = {
+        registry,
+        stylesheetRegistry,
+        elementRegistry,
+        duplicates,
+        componentRegistry,
+      }
+      return renderNode(element, context)
+    }
+
+    renderCache = getRenderCache(renderVariantToJson)
+
+    const result: Record<string, any> = {
+      v: VOLTRA_PAYLOAD_VERSION,
+    }
+
+    for (const { name, node } of rootNodes) {
+      if (node !== null && node !== undefined) {
+        result[name] = renderCache.getOrRender(node)
+      }
+    }
+
+    const sharedElements = elementRegistry.getElements()
+    if (sharedElements.length > 0) {
+      result.e = sharedElements
+    }
+
+    const styles = stylesheetRegistry.getStyles()
+    if (styles.length > 0) {
+      result.s = styles
+    }
+
+    return result
+  }
+
+  return {
+    addRootNode,
+    render,
+  }
+}

package/src/renderer/stylesheet-registry.ts

@@ -0,0 +1,54 @@
+import { shorten } from '../payload/short-names.js'
+import { flattenStyle } from './flatten-styles.js'
+
+function compressStyleObject(style: any): any {
+  if (style === null || style === undefined) {
+    return style
+  }
+
+  const flattened = flattenStyle(style)
+  const compressed: Record<string, any> = {}
+
+  for (const [key, value] of Object.entries(flattened)) {
+    const shortKey = shorten(key)
+
+    if (value === null || value === undefined) {
+      continue
+    }
+
+    if (typeof value === 'object' && !Array.isArray(value) && value.constructor === Object) {
+      const compressedNested: Record<string, any> = {}
+      for (const [nestedKey, nestedValue] of Object.entries(value)) {
+        compressedNested[nestedKey] = nestedValue
+      }
+      compressed[shortKey] = compressedNested
+    } else {
+      compressed[shortKey] = value
+    }
+  }
+
+  return compressed
+}
+
+export type StylesheetRegistry = {
+  registerStyle: (styleObject: object) => number
+  getStyles: () => Record<string, unknown>[]
+}
+
+export const createStylesheetRegistry = (): StylesheetRegistry => {
+  const styleToIndex = new Map<object, number>()
+  const styles: Record<string, unknown>[] = []
+
+  return {
+    registerStyle: (styleObject: object): number => {
+      const existing = styleToIndex.get(styleObject)
+      if (existing !== undefined) return existing
+
+      const index = styles.length
+      styleToIndex.set(styleObject, index)
+      styles.push(compressStyleObject(styleObject))
+      return index
+    },
+    getStyles: () => styles,
+  }
+}

package/src/renderer/types.ts

@@ -0,0 +1,5 @@
+import { ReactNode } from 'react'
+
+import { VoltraNodeJson } from '../types.js'
+
+export type VoltraVariantRenderer = (node: ReactNode) => VoltraNodeJson

package/src/types.ts

@@ -0,0 +1,14 @@
+export type VoltraPropValue = string | number | boolean | null | VoltraNodeJson
+
+export type VoltraElementJson = {
+  t: number
+  i?: string
+  c?: VoltraNodeJson
+  p?: Record<string, VoltraPropValue>
+}
+
+export type VoltraElementRef = {
+  $r: number
+}
+
+export type VoltraNodeJson = VoltraElementJson | VoltraElementJson[] | VoltraElementRef | string

package/src/widget-environment.ts

@@ -0,0 +1,114 @@
+/**
+ * Env shape consumed by Dynamic Widgets.
+ *
+ * Dynamic Widgets are functions of `(props, env) => JSX`, evaluated inside the
+ * Voltra JS runtime (JSC on iOS, Hermes on Android) at every render. The `env` second
+ * argument is populated by the native runtime at draw time and carries:
+ *
+ * - **Runtime device state** (`colorScheme`, `widgetFamily`, etc.) captured per render
+ * - **Platform-specific runtime state** (`widgetRenderingMode` on iOS), present only on the
+ *   platform that has the concept
+ * - **AppIntent / user-configured params** under `env.configuration` (TypeScript-typed per
+ *   widget via the generic parameter)
+ * - **Build env** under `env.build.*` — values that don't change between renders inside a
+ *   process (isDev, Metro URL, app version, Voltra version)
+ *
+ * The shape mirrors expo-widgets' `WidgetEnvironment` for the runtime device fields, with
+ * a Voltra-specific `env.build.*` namespace added for dev-mode tooling.
+ *
+ * @typeParam TConfig - Shape of `env.configuration` (AppIntent / user-configured params).
+ *   Defaults to `undefined` for widgets that don't accept user configuration. Widget authors
+ *   can supply a more specific type per widget for typed access.
+ */
+export type WidgetEnvironment<TConfig extends Record<string, unknown> | undefined = undefined> = {
+  /** Date the widget is being rendered for. Transported as epoch ms over the JS boundary
+   * and reconstructed as `Date` by the runtime entry. */
+  date: Date
+
+  /** Widget size family. iOS values: `systemSmall`, `systemMedium`, `systemLarge`, etc.
+   * Android values: synthesized from Glance `LocalSize` (e.g. `"200x200"`). */
+  widgetFamily: string
+
+  /** Current color scheme of the widget's environment. May be `undefined` if the platform
+   * doesn't expose it (rare). */
+  colorScheme?: 'light' | 'dark'
+
+  /** BCP-47 locale tag — for example `"en-US"` or `"pl-PL"`. */
+  locale?: string
+
+  // ---------------------------------------------------------------------------
+  // iOS-only runtime values
+  // Present only when rendering on iOS; `undefined` on Android.
+  // ---------------------------------------------------------------------------
+
+  /** iOS — rendering mode the widget is being drawn in. `fullColor` on home screen,
+   * `accented` on tinted/Liquid Glass widgets (iOS 18+) and watchOS, `vibrant` on lock
+   * screen. Maps to SwiftUI `@Environment(\.widgetRenderingMode)`. */
+  widgetRenderingMode?: 'fullColor' | 'accented' | 'vibrant'
+
+  /** iOS — whether the system is drawing a container background behind the widget.
+   * Maps to SwiftUI `@Environment(\.showsWidgetContainerBackground)`. iOS 17+. */
+  showsWidgetContainerBackground?: boolean
+
+  // ---------------------------------------------------------------------------
+  // System-managed configuration
+  // ---------------------------------------------------------------------------
+
+  /** AppIntent / user-configured parameters for this widget. `undefined` for widgets that
+   * don't accept user configuration. Typed per widget via the [TConfig] generic. */
+  configuration: TConfig
+
+  // ---------------------------------------------------------------------------
+  // Build env — static for the process lifetime, supplied by the runtime
+  // ---------------------------------------------------------------------------
+
+  /** Build / process-level metadata, populated by the runtime once per process. Static for
+   * the JS runtime's lifetime; does not change between renders. */
+  build: WidgetBuildEnvironment
+}
+
+/**
+ * Build / process metadata available inside the widget render function. Populated by the
+ * native runtime; identical across every render in a process.
+ */
+export type WidgetBuildEnvironment = {
+  /** True when running against a development build (DEBUG / `__DEV__`). Used to gate
+   * dev-mode behaviour like fetching bundles from Metro. */
+  isDev: boolean
+
+  /** URL of the Metro dev server when `isDev` is true. Used by the runtime to fetch widget
+   * bundles for hot-reload. `undefined` in release builds. */
+  metroUrl?: string
+
+  /** App version string (`CFBundleShortVersionString` on iOS, `versionName` on Android). */
+  appVersion: string
+
+  /** Voltra package version (`@use-voltra/core`). Surfaces in error reports and lets
+   * widgets gate behaviour by compatibility level if needed. */
+  voltraVersion: string
+}
+
+/**
+ * Type guard — returns true when the runtime env is an iOS-platform env.
+ *
+ * @example
+ *   if (isIosEnv(env)) {
+ *     // env.widgetRenderingMode is narrowed to the concrete value (not undefined)
+ *   }
+ */
+export function isIosEnv(
+  env: WidgetEnvironment
+): env is WidgetEnvironment & { widgetRenderingMode: NonNullable<WidgetEnvironment['widgetRenderingMode']> } {
+  return env.widgetRenderingMode !== undefined
+}
+
+/**
+ * Type guard — returns true when the runtime env is an Android-platform env.
+ *
+ * Android carries no platform-only runtime field (Material You colors are consumed via
+ * `AndroidDynamicColors` tokens resolved by the native renderer, not through `env`), so this is
+ * the complement of {@link isIosEnv}.
+ */
+export function isAndroidEnv(env: WidgetEnvironment): boolean {
+  return !isIosEnv(env)
+}