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

package/src/live-activity/renderer.ts

@@ -0,0 +1,85 @@
+import type { ReactNode } from 'react'
+
+import { createVoltraRenderer } from '../renderer/index.js'
+import type { LiveActivityJson, LiveActivityVariants } from './types.js'
+
+/**
+ * Renders Live Activity variants to JSON.
+ * Handles non-JSX properties like keylineTint and activityBackgroundTint separately.
+ */
+export const renderLiveActivityToJson = (variants: LiveActivityVariants): LiveActivityJson => {
+  const renderer = createVoltraRenderer()
+
+  // Add lock screen variant
+  if (variants.lockScreen) {
+    const lockScreenVariant = variants.lockScreen
+    if (typeof lockScreenVariant === 'object' && lockScreenVariant !== null && 'content' in lockScreenVariant) {
+      if (lockScreenVariant.content) {
+        renderer.addRootNode('ls', lockScreenVariant.content)
+      }
+    } else {
+      renderer.addRootNode('ls', lockScreenVariant as ReactNode)
+    }
+  }
+
+  // Add island variants
+  if (variants.island) {
+    if (variants.island.expanded) {
+      if (variants.island.expanded.center) {
+        renderer.addRootNode('isl_exp_c', variants.island.expanded.center)
+      }
+      if (variants.island.expanded.leading) {
+        renderer.addRootNode('isl_exp_l', variants.island.expanded.leading)
+      }
+      if (variants.island.expanded.trailing) {
+        renderer.addRootNode('isl_exp_t', variants.island.expanded.trailing)
+      }
+      if (variants.island.expanded.bottom) {
+        renderer.addRootNode('isl_exp_b', variants.island.expanded.bottom)
+      }
+    }
+    if (variants.island.compact) {
+      if (variants.island.compact.leading) {
+        renderer.addRootNode('isl_cmp_l', variants.island.compact.leading)
+      }
+      if (variants.island.compact.trailing) {
+        renderer.addRootNode('isl_cmp_t', variants.island.compact.trailing)
+      }
+    }
+    if (variants.island.minimal) {
+      renderer.addRootNode('isl_min', variants.island.minimal)
+    }
+  }
+
+  // Add supplemental activity family variants (iOS 18+)
+  if (variants.supplementalActivityFamilies?.small) {
+    renderer.addRootNode('saf_sm', variants.supplementalActivityFamilies.small)
+  }
+
+  // Render all variants
+  const result = renderer.render() as LiveActivityJson
+
+  // Add non-JSX properties after rendering
+  if (
+    variants.lockScreen &&
+    typeof variants.lockScreen === 'object' &&
+    'activityBackgroundTint' in variants.lockScreen
+  ) {
+    if (variants.lockScreen.activityBackgroundTint) {
+      result.ls_background_tint = variants.lockScreen.activityBackgroundTint
+    }
+  }
+
+  if (variants.island?.keylineTint) {
+    result.isl_keyline_tint = variants.island.keylineTint
+  }
+
+  return result
+}
+
+/**
+ * Renders Live Activity variants to a JSON string.
+ */
+export const renderLiveActivityToString = (variants: LiveActivityVariants): string => {
+  return JSON.stringify(renderLiveActivityToJson(variants))
+}

package/src/live-activity/types.ts

@@ -0,0 +1,72 @@
+import type { ReactNode } from 'react'
+
+import type { VoltraNodeJson } from '../types.js'
+
+/**
+ * Live Activity variants - defines content for different states
+ */
+export type LiveActivityVariants = {
+  lockScreen?:
+    | ReactNode
+    | {
+        content?: ReactNode
+        activityBackgroundTint?: string
+      }
+  island?: {
+    keylineTint?: string
+    expanded?: {
+      center?: ReactNode
+      leading?: ReactNode
+      trailing?: ReactNode
+      bottom?: ReactNode
+    }
+    compact?: {
+      leading?: ReactNode
+      trailing?: ReactNode
+    }
+    minimal?: ReactNode
+  }
+  /**
+   * Supplemental activity families for iOS 18+ (watchOS Smart Stack, CarPlay)
+   * Always enabled for all Live Activities
+   */
+  supplementalActivityFamilies?: {
+    /**
+     * Small family for watchOS Smart Stack and CarPlay (iOS 18+)
+     * Should be a simplified version of the lock screen UI
+     * Falls back to compact island regions (leading + trailing) if not provided
+     */
+    small?: ReactNode
+  }
+}
+
+/**
+ * Rendered Live Activity variants to JSON.
+ */
+export type LiveActivityVariantsJson = {
+  v: number // Payload version - required for remote updates
+  s?: Record<string, unknown>[] // Shared stylesheet for all variants
+  e?: VoltraNodeJson[] // Shared elements for deduplication
+  ls?: VoltraNodeJson
+  ls_background_tint?: string
+  isl_keyline_tint?: string
+  isl_exp_c?: VoltraNodeJson
+  isl_exp_l?: VoltraNodeJson
+  isl_exp_t?: VoltraNodeJson
+  isl_exp_b?: VoltraNodeJson
+  isl_cmp_l?: VoltraNodeJson
+  isl_cmp_t?: VoltraNodeJson
+  isl_min?: VoltraNodeJson
+  // Supplemental activity families (iOS 18+)
+  saf_sm?: VoltraNodeJson // supplementalActivityFamilies.small (watchOS/CarPlay)
+}
+
+/**
+ * JSON representation of live activity variants for rendering
+ */
+export type LiveActivityJson = LiveActivityVariantsJson
+
+/**
+ * Dismissal policy for Live Activities.
+ */
+export type DismissalPolicy = 'immediate' | { after: number }

package/src/payload/component-ids.ts

@@ -0,0 +1,87 @@
+/* eslint-disable */
+// 🤖 AUTO-GENERATED from data/components.json
+// DO NOT EDIT MANUALLY - Changes will be overwritten
+// Schema version: 1.0.0
+
+/**
+ * Mapping from component name to numeric ID
+ * Component IDs are assigned sequentially based on order in components.json (0-indexed)
+ */
+export const COMPONENT_NAME_TO_ID: Record<string, number> = {
+  Text: 0,
+  Button: 1,
+  Label: 2,
+  Image: 3,
+  Symbol: 4,
+  Toggle: 5,
+  LinearProgressView: 6,
+  CircularProgressView: 7,
+  Gauge: 8,
+  Timer: 9,
+  LinearGradient: 10,
+  VStack: 11,
+  HStack: 12,
+  ZStack: 13,
+  GroupBox: 14,
+  GlassContainer: 15,
+  Spacer: 16,
+  Divider: 17,
+  Mask: 18,
+  Link: 19,
+  View: 20,
+  Chart: 21,
+}
+
+/**
+ * Mapping from numeric ID to component name
+ */
+export const COMPONENT_ID_TO_NAME: Record<number, string> = {
+  0: 'Text',
+  1: 'Button',
+  2: 'Label',
+  3: 'Image',
+  4: 'Symbol',
+  5: 'Toggle',
+  6: 'LinearProgressView',
+  7: 'CircularProgressView',
+  8: 'Gauge',
+  9: 'Timer',
+  10: 'LinearGradient',
+  11: 'VStack',
+  12: 'HStack',
+  13: 'ZStack',
+  14: 'GroupBox',
+  15: 'GlassContainer',
+  16: 'Spacer',
+  17: 'Divider',
+  18: 'Mask',
+  19: 'Link',
+  20: 'View',
+  21: 'Chart',
+}
+
+/**
+ * Get component ID from name
+ * @throws Error if component name is not found
+ */
+export function getComponentId(name: string): number {
+  const id = COMPONENT_NAME_TO_ID[name]
+  if (id === undefined) {
+    throw new Error(
+      `Unknown component name: "${name}". Available components: ${Object.keys(COMPONENT_NAME_TO_ID).join(', ')}`
+    )
+  }
+  return id
+}
+
+/**
+ * Get component name from ID
+ * @throws Error if component ID is not found
+ */
+export function getComponentName(id: number): string {
+  const name = COMPONENT_ID_TO_NAME[id]
+  if (name === undefined) {
+    throw new Error(`Unknown component ID: ${id}. Valid IDs: 0-${Object.keys(COMPONENT_ID_TO_NAME).length - 1}`)
+  }
+  return name
+}

package/src/payload/short-names.ts

@@ -0,0 +1 @@
+export { expand, NAME_TO_SHORT, SHORT_TO_NAME, shorten } from '@use-voltra/core'

package/src/payload.ts

@@ -0,0 +1 @@
+export { ensurePayloadWithinBudget } from '@use-voltra/core'

package/src/renderer/index.ts

@@ -0,0 +1,6 @@
+export {
+  type ComponentRegistry,
+  createVoltraRenderer,
+  renderVoltraVariantToJson,
+  VOLTRA_PAYLOAD_VERSION,
+} from './renderer.js'

package/src/renderer/renderer.ts

@@ -0,0 +1,25 @@
+import {
+  type ComponentRegistry,
+  createVoltraRenderer as createCoreVoltraRenderer,
+  renderVariantToJson,
+  VOLTRA_PAYLOAD_VERSION,
+} from '@use-voltra/core'
+import type { ReactNode } from 'react'
+
+import { getComponentId } from '../payload/component-ids.js'
+import type { VoltraNodeJson } from '../types.js'
+
+const defaultComponentRegistry: ComponentRegistry = {
+  getComponentId: (name: string) => getComponentId(name),
+}
+
+export { VOLTRA_PAYLOAD_VERSION }
+export type { ComponentRegistry }
+
+export const renderVoltraVariantToJson = (element: ReactNode): VoltraNodeJson => {
+  return renderVariantToJson(element, defaultComponentRegistry)
+}
+
+export const createVoltraRenderer = (componentRegistry: ComponentRegistry = defaultComponentRegistry) => {
+  return createCoreVoltraRenderer(componentRegistry)
+}

package/src/server.ts

@@ -0,0 +1,36 @@
+/// <reference types="node" />
+
+import { promisify } from 'node:util'
+import { brotliCompress, constants } from 'node:zlib'
+
+import { renderLiveActivityToString as render } from './live-activity/renderer.js'
+import type { LiveActivityVariants } from './live-activity/types.js'
+import { ensurePayloadWithinBudget } from './payload.js'
+import * as Voltra from './jsx/primitives.js'
+
+export { Voltra }
+export { renderWidgetToString } from './widgets/renderer.js'
+export type { WidgetVariants } from './widgets/types.js'
+
+const brotliCompressAsync = promisify(brotliCompress)
+
+const compressPayload = async (jsonString: string): Promise<string> => {
+  const jsonBuffer = Buffer.from(jsonString, 'utf8')
+
+  const compressedBuffer = await brotliCompressAsync(jsonBuffer, {
+    params: {
+      [constants.BROTLI_PARAM_QUALITY]: 2,
+      [constants.BROTLI_PARAM_SIZE_HINT]: jsonBuffer.length,
+    },
+  })
+
+  return compressedBuffer.toString('base64')
+}
+
+export const renderLiveActivityToString = async (variants: LiveActivityVariants): Promise<string> => {
+  const jsonString = render(variants)
+  const compressedBase64 = await compressPayload(jsonString)
+  ensurePayloadWithinBudget(compressedBase64)
+
+  return compressedBase64
+}

package/src/styles/index.ts

@@ -0,0 +1 @@
+export type { VoltraStyleProp, VoltraTextStyle, VoltraTextStyleProp, VoltraViewStyle } from './types.js'

package/src/styles/types.ts

@@ -0,0 +1,78 @@
+type StyleProp<T> = T | T[] | null | undefined | false
+
+type VoltraTransform =
+  | { rotate: string }
+  | { rotateX: string }
+  | { rotateY: string }
+  | { rotateZ: string }
+  | { scale: number }
+  | { scaleX: number }
+  | { scaleY: number }
+  | { translateX: number }
+  | { translateY: number }
+  | { skewX: string }
+  | { skewY: string }
+
+export type VoltraViewStyle = {
+  flex?: number
+  flexGrow?: number
+  flexShrink?: number
+  flexBasis?: number | string
+  alignItems?: 'flex-start' | 'flex-end' | 'center' | 'stretch' | 'baseline'
+  alignSelf?: 'auto' | 'flex-start' | 'flex-end' | 'center' | 'stretch' | 'baseline'
+  justifyContent?: 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly'
+  flexDirection?: 'row' | 'column' | 'row-reverse' | 'column-reverse'
+  gap?: number | string
+  minWidth?: number | string
+  maxWidth?: number | string
+  width?: number | string
+  minHeight?: number | string
+  maxHeight?: number | string
+  height?: number | string
+  padding?: number | string
+  paddingTop?: number | string
+  paddingBottom?: number | string
+  paddingLeft?: number | string
+  paddingRight?: number | string
+  paddingHorizontal?: number | string
+  paddingVertical?: number | string
+  margin?: number | string
+  marginTop?: number | string
+  marginBottom?: number | string
+  marginLeft?: number | string
+  marginRight?: number | string
+  marginHorizontal?: number | string
+  marginVertical?: number | string
+  backgroundColor?: string
+  opacity?: number
+  borderRadius?: number | string
+  borderWidth?: number
+  borderColor?: string
+  shadowColor?: string
+  shadowOffset?: { width: number; height: number }
+  shadowOpacity?: number
+  shadowRadius?: number
+  overflow?: 'visible' | 'hidden' | 'scroll'
+  aspectRatio?: number | string
+  left?: number | string
+  top?: number | string
+  position?: 'absolute' | 'relative' | 'static'
+  zIndex?: number
+  transform?: VoltraTransform[]
+  glassEffect?: 'clear' | 'identity' | 'regular' | 'none'
+}
+
+export type VoltraTextStyle = VoltraViewStyle & {
+  fontSize?: number
+  fontWeight?: 'normal' | 'bold' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900'
+  fontFamily?: string
+  color?: string
+  letterSpacing?: number
+  fontVariant?: ('small-caps' | 'tabular-nums' | 'oldstyle-nums' | 'lining-nums' | 'proportional-nums')[]
+  textDecorationLine?: 'none' | 'underline' | 'line-through' | 'underline line-through'
+  lineHeight?: number
+  textAlign?: 'auto' | 'left' | 'right' | 'center' | 'justify'
+}
+
+export type VoltraStyleProp = StyleProp<VoltraViewStyle>
+export type VoltraTextStyleProp = StyleProp<VoltraTextStyle>

package/src/types.ts

@@ -0,0 +1,42 @@
+export type { VoltraElementJson, VoltraElementRef, VoltraNodeJson, VoltraPropValue } from '@use-voltra/core'
+
+export type EventSubscription = {
+  remove: () => void
+}
+
+type PreloadImageBaseOptions = {
+  key: string
+  width?: number
+  height?: number
+}
+
+export type PreloadImageUrlOptions = PreloadImageBaseOptions & {
+  url: string
+  method?: 'GET' | 'POST' | 'PUT'
+  headers?: Record<string, string>
+}
+
+export type PreloadImageSvgOptions = PreloadImageBaseOptions & {
+  svg: string
+}
+
+export type PreloadImageOptions = PreloadImageUrlOptions | PreloadImageSvgOptions
+
+export type PreloadImageFailure = {
+  key: string
+  error: string
+}
+
+export type PreloadImagesResult = {
+  succeeded: string[]
+  failed: PreloadImageFailure[]
+}
+
+export type UpdateWidgetOptions = {
+  deepLinkUrl?: string
+}
+
+export type WidgetServerCredentials = {
+  token: string
+  headers?: Record<string, string>
+}

package/src/widgets/renderer.ts

@@ -0,0 +1,26 @@
+import { createVoltraRenderer } from '../renderer/renderer.js'
+import type { WidgetVariants } from './types.js'
+
+/**
+ * Renders widget variants to JSON.
+ */
+export const renderWidgetToJson = (variants: WidgetVariants): Record<string, any> => {
+  const renderer = createVoltraRenderer()
+
+  // Add all widget family variants
+  for (const [family, content] of Object.entries(variants)) {
+    if (content !== undefined && content !== null) {
+      renderer.addRootNode(family, content)
+    }
+  }
+
+  // Render and return result
+  return renderer.render()
+}
+
+/**
+ * Renders widget variants to a JSON string.
+ */
+export const renderWidgetToString = (variants: WidgetVariants): string => {
+  return JSON.stringify(renderWidgetToJson(variants))
+}

package/src/widgets/types.ts

@@ -0,0 +1,49 @@
+import type { ReactNode } from 'react'
+
+/**
+ * Widget size families supported by iOS
+ */
+export type WidgetFamily =
+  | 'systemSmall'
+  | 'systemMedium'
+  | 'systemLarge'
+  | 'systemExtraLarge'
+  | 'accessoryCircular'
+  | 'accessoryRectangular'
+  | 'accessoryInline'
+
+/**
+ * Widget variants following the same pattern as LiveActivityVariants.
+ * Each key corresponds to a widget family.
+ */
+export type WidgetVariants = Partial<Record<WidgetFamily, ReactNode>>
+
+/**
+ * Information about an active widget configuration on iOS
+ */
+export interface WidgetInfo {
+  /** The name (ID) of the widget as defined in the config plugin */
+  name: string
+  /** The 'kind' string defined in your WidgetExtension */
+  kind: string
+  /** The visual size of the widget */
+  family: WidgetFamily
+}
+
+/**
+ * A single entry in a widget timeline with scheduled display time and content
+ */
+export type ScheduledWidgetEntry = {
+  /**
+   * When this content should be displayed
+   */
+  date: Date
+  /**
+   * Widget content for different size families
+   */
+  variants: WidgetVariants
+  /**
+   * Optional deep link URL for this specific entry
+   */
+  deepLinkUrl?: string
+}