@use-voltra/android 2.0.0 → 2.1.1

package/src/preload-utils.ts

@@ -0,0 +1,78 @@
+import type {
+  PreloadImageFailure,
+  PreloadImageOptions,
+  PreloadImageSvgOptions,
+  PreloadImageUrlOptions,
+  PreloadImagesResult,
+} from './types.js'
+
+type NativePreloadModule = {
+  preloadUrlImages(images: PreloadImageUrlOptions[]): Promise<PreloadImagesResult>
+  preloadSvgImages(images: PreloadImageSvgOptions[]): Promise<PreloadImagesResult>
+}
+
+const emptyResult: PreloadImagesResult = {
+  succeeded: [],
+  failed: [],
+}
+
+function hasStringValue(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : 'Unknown error'
+}
+
+async function preloadGroup<T extends PreloadImageOptions>(
+  images: T[],
+  preload: (images: T[]) => Promise<PreloadImagesResult>
+): Promise<PreloadImagesResult> {
+  if (images.length === 0) {
+    return emptyResult
+  }
+
+  try {
+    return await preload(images)
+  } catch (error) {
+    return {
+      succeeded: [],
+      failed: images.map((image) => ({
+        key: image.key,
+        error: errorMessage(error),
+      })),
+    }
+  }
+}
+
+export async function dispatchPreloadImages(
+  nativeModule: NativePreloadModule,
+  images: PreloadImageOptions[]
+): Promise<PreloadImagesResult> {
+  const urlImages: PreloadImageUrlOptions[] = []
+  const svgImages: PreloadImageSvgOptions[] = []
+  const invalidImages: PreloadImageFailure[] = []
+
+  for (const image of images) {
+    if ('svg' in image && hasStringValue(image.svg)) {
+      svgImages.push(image)
+    } else if ('url' in image && hasStringValue(image.url)) {
+      urlImages.push(image)
+    } else {
+      invalidImages.push({
+        key: image.key,
+        error: `Image '${image.key}' must provide either url or svg`,
+      })
+    }
+  }
+
+  const [urlResult, svgResult] = await Promise.all([
+    preloadGroup(urlImages, (group) => nativeModule.preloadUrlImages(group)),
+    preloadGroup(svgImages, (group) => nativeModule.preloadSvgImages(group)),
+  ])
+
+  return {
+    succeeded: [...urlResult.succeeded, ...svgResult.succeeded],
+    failed: [...invalidImages, ...urlResult.failed, ...svgResult.failed],
+  }
+}

package/src/renderer/index.ts

@@ -0,0 +1,6 @@
+export {
+  type ComponentRegistry,
+  createVoltraRenderer,
+  renderAndroidVariantToJson,
+  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 { getAndroidComponentId } from '../payload/component-ids.js'
+import type { VoltraNodeJson } from '../types.js'
+
+export const androidComponentRegistry: ComponentRegistry = {
+  getComponentId: (name: string) => getAndroidComponentId(name),
+}
+
+export { VOLTRA_PAYLOAD_VERSION }
+export type { ComponentRegistry }
+
+export const renderAndroidVariantToJson = (element: ReactNode): VoltraNodeJson => {
+  return renderVariantToJson(element, androidComponentRegistry)
+}
+
+export const createVoltraRenderer = (componentRegistry: ComponentRegistry = androidComponentRegistry) => {
+  return createCoreVoltraRenderer(componentRegistry)
+}

package/src/server.ts

@@ -0,0 +1,19 @@
+export { AndroidOngoingNotification } from './ongoing-notification/components.js'
+export {
+  renderAndroidOngoingNotificationPayload,
+  renderAndroidOngoingNotificationPayloadToJson,
+} from './ongoing-notification/renderer.js'
+export type {
+  AndroidOngoingNotificationActionPayload,
+  AndroidOngoingNotificationActionProps,
+  AndroidOngoingNotificationBigTextPayload,
+  AndroidOngoingNotificationBigTextProps,
+  AndroidOngoingNotificationContent,
+  AndroidOngoingNotificationPayload,
+  AndroidOngoingNotificationProgressPayload,
+  AndroidOngoingNotificationProgressPoint,
+  AndroidOngoingNotificationProgressProps,
+  AndroidOngoingNotificationProgressSegment,
+} from './ongoing-notification/types.js'
+export { renderAndroidWidgetToString } from './widgets/renderer.js'
+export type { AndroidColorValue, AndroidDynamicColorRole, AndroidDynamicColorToken } from './dynamic-colors.js'

package/src/styles/types.ts

@@ -0,0 +1,114 @@
+/**
+ * Android-specific style types for Voltra components.
+ * These types mirror the supported properties in the Android implementation (Glance).
+ */
+
+import type { AndroidColorValue } from '../dynamic-colors.js'
+
+export type StyleProp<T> = T | T[] | null | undefined | false
+
+export type VoltraAndroidViewStyle = {
+  /** Width of the component. Supports fixed numbers (dp) or "100%" to fill. */
+  width?: number | string
+  /** Height of the component. Supports fixed numbers (dp) or "100%" to fill. */
+  height?: number | string
+  /** Minimum width (Note: Limited support in Glance) */
+  minWidth?: number
+  /** Maximum width (Note: Limited support in Glance) */
+  maxWidth?: number
+  /** Minimum height (Note: Limited support in Glance) */
+  minHeight?: number
+  /** Maximum height (Note: Limited support in Glance) */
+  maxHeight?: number
+
+  /** Flex weight for the component (maps to .defaultWeight() in Glance) */
+  flex?: number
+  /** Flex grow weight for the component (maps to .defaultWeight() in Glance) */
+  flexGrow?: number
+
+  /** Aspect ratio of the component (Note: Not supported in Glance) */
+  aspectRatio?: number
+
+  /** Inner padding for the component */
+  padding?: number
+  paddingTop?: number
+  paddingBottom?: number
+  paddingLeft?: number
+  paddingRight?: number
+  paddingVertical?: number
+  paddingHorizontal?: number
+
+  /** Gap between children (Note: Supported by specific layouts like LazyColumn/Row) */
+  gap?: number
+
+  /** Alignment of children along the cross axis */
+  alignItems?: 'flex-start' | 'flex-end' | 'center' | 'stretch' | 'baseline'
+  /** Alignment of children along the main axis */
+  justifyContent?: 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly'
+
+  /** Absolute positioning from the left (maps to Offset in Glance) */
+  left?: number
+  /** Absolute positioning from the top (maps to Offset in Glance) */
+  top?: number
+  /** Z-index for layering (Note: Limited support in Glance) */
+  zIndex?: number
+
+  /** Background color of the component */
+  backgroundColor?: AndroidColorValue
+  /** CSS gradient background image, e.g. linear-gradient(to right, red, blue) */
+  backgroundImage?: string
+  /** Corner radius for the component (requires Android 12+) */
+  borderRadius?: number
+  /** Border width (Note: Not yet implemented in Glance) */
+  borderWidth?: number
+  /** Border color (Note: Not yet implemented in Glance) */
+  borderColor?: AndroidColorValue
+
+  /** Opacity of the component (Note: Not supported in Glance - apply alpha to colors instead) */
+  opacity?: number
+  /** Controls if content is clipped to the border (maps to clipToOutline) */
+  overflow?: 'visible' | 'hidden'
+
+  /** Controls layout display mode */
+  display?: 'none' | 'flex'
+  /** Controls component visibility */
+  visibility?: 'visible' | 'hidden' | 'invisible'
+
+  /** Transform effects (Note: Not supported in Glance) */
+  transform?: ({ rotate: string } | { rotateZ: string } | { scale: number } | { scaleX: number } | { scaleY: number })[]
+
+  /** Shadow properties (Note: Not supported in Glance) */
+  shadowColor?: AndroidColorValue
+  shadowOffset?: { width: number; height: number }
+  shadowOpacity?: number
+  shadowRadius?: number
+
+  /** Glass effect (iOS-specific, included for API compatibility) */
+  glassEffect?: 'clear' | 'identity' | 'regular' | 'none'
+}
+
+export type VoltraAndroidTextStyle = VoltraAndroidViewStyle & {
+  /** Text color */
+  color?: AndroidColorValue
+  /** Font size in sp */
+  fontSize?: number
+  /** Font weight */
+  fontWeight?: 'normal' | 'bold' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900' | number
+  /** Font family name. When used with `renderAsBitmap`, loads custom .ttf/.otf from `assets/fonts/` */
+  fontFamily?: string
+  /** Text alignment */
+  textAlign?: 'auto' | 'left' | 'right' | 'center' | 'justify' | 'start' | 'end'
+  /** Text decoration line */
+  textDecorationLine?: 'none' | 'underline' | 'line-through' | 'underline line-through'
+  /** Line height (maps to line spacing in Glance) */
+  lineHeight?: number
+  /** Letter spacing (Note: Not supported in Glance) */
+  letterSpacing?: number
+  /** Font variants (Note: Not supported in Glance) */
+  fontVariant?: ('small-caps' | 'tabular-nums')[]
+  /** Maximum number of lines to display (maps to lineLimit) */
+  numberOfLines?: number
+}
+
+export type VoltraAndroidStyleProp = StyleProp<VoltraAndroidViewStyle>
+export type VoltraAndroidTextStyleProp = StyleProp<VoltraAndroidTextStyle>

package/src/types.ts

@@ -0,0 +1,38 @@
+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 WidgetServerCredentials = {
+  token: string
+  headers?: Record<string, string>
+}

package/src/widgets/renderer.ts

@@ -0,0 +1,90 @@
+import { createElement, Fragment as ReactFragment, type ReactNode } from 'react'
+
+import { getAndroidComponentId } from '../payload/component-ids.js'
+import { ComponentRegistry, createVoltraRenderer } from '../renderer/renderer.js'
+import type { AndroidWidgetVariants } from './types.js'
+
+/**
+ * Android component registry that uses Android component ID mappings
+ */
+const androidComponentRegistry: ComponentRegistry = {
+  getComponentId: (name: string) => getAndroidComponentId(name),
+}
+
+export type AndroidWidgetRenderOptions = Record<string, never>
+
+/**
+ * Renders Android widget variants to JSON with size breakpoints.
+ *
+ * Output format:
+ * {
+ *   "v": 1,
+ *   "variants": {
+ *     "150x100": { ... node tree ... },
+ *     "150x200": { ... node tree ... },
+ *     "215x100": { ... node tree ... }
+ *   },
+ *   "s": [...shared styles...],
+ *   "e": [...shared elements...]
+ * }
+ */
+export const renderAndroidWidgetToJson = (
+  variants: AndroidWidgetVariants,
+  _options?: AndroidWidgetRenderOptions
+): Record<string, any> => {
+  const renderer = createVoltraRenderer(androidComponentRegistry)
+
+  // Add each size variant with key format "WIDTHxHEIGHT"
+  for (const { size, content } of variants) {
+    const key = `${size.width}x${size.height}`
+    renderer.addRootNode(key, createElement(ReactFragment, null, content))
+  }
+
+  const rendered = renderer.render()
+
+  // Extract variant keys (everything except v, s, e which are metadata)
+  const variantsMap: Record<string, any> = {}
+  const metadataKeys = ['v', 's', 'e']
+
+  for (const key of Object.keys(rendered)) {
+    if (!metadataKeys.includes(key)) {
+      variantsMap[key] = rendered[key]
+      delete rendered[key]
+    }
+  }
+
+  // Add variants as a nested object (expected by Kotlin parser)
+  rendered.variants = variantsMap
+
+  return rendered
+}
+
+/**
+ * Renders Android widget variants to a JSON string.
+ */
+export const renderAndroidWidgetToString = (
+  variants: AndroidWidgetVariants,
+  options?: AndroidWidgetRenderOptions
+): string => {
+  return JSON.stringify(renderAndroidWidgetToJson(variants, options))
+}
+
+/**
+ * Renders Android JSX to JSON for VoltraView component.
+ */
+export const renderAndroidViewToJson = (
+  children: ReactNode,
+  _options?: AndroidWidgetRenderOptions
+): Record<string, any> => {
+  const renderer = createVoltraRenderer(androidComponentRegistry)
+
+  renderer.addRootNode('content', createElement(ReactFragment, null, children))
+
+  const rendered = renderer.render()
+  const node = rendered.content
+
+  delete rendered.content
+  rendered.variants = { content: node }
+
+  return rendered
+}

package/src/widgets/types.ts

@@ -0,0 +1,62 @@
+import type { ReactNode } from 'react'
+
+/**
+ * Size breakpoint for Android widgets.
+ * Represents width x height in dp.
+ */
+export type AndroidWidgetSize = {
+  width: number
+  height: number
+}
+
+/**
+ * A single size variant with its breakpoint and content.
+ */
+export type AndroidWidgetSizeVariant = {
+  size: AndroidWidgetSize
+  content: ReactNode
+}
+
+/**
+ * Information about an active widget instance on Android
+ */
+export type WidgetInfo = {
+  /** The name (ID) of the widget as defined in the config plugin */
+  name: string
+  /** The unique ID for this widget instance (required for updates) */
+  widgetId: number
+  /** The class name of the provider (e.g., ".WeatherWidget") */
+  providerClassName: string
+  /** Current labeling associated with the widget */
+  label: string
+  /** Dimensions in dp as reported by the system */
+  width: number
+  height: number
+}
+
+/**
+ * Widget variants using size-based breakpoints.
+ * Android picks the best matching variant based on widget dimensions.
+ *
+ * @example
+ * ```tsx
+ * const variants: AndroidWidgetVariants = [
+ *   { size: { width: 150, height: 100 }, content: <SmallWidget /> },
+ *   { size: { width: 150, height: 200 }, content: <TallWidget /> },
+ *   { size: { width: 215, height: 100 }, content: <WideWidget /> },
+ * ]
+ * ```
+ */
+export type AndroidWidgetVariants = AndroidWidgetSizeVariant[]
+
+/**
+ * Options for updating an Android widget
+ */
+export type UpdateAndroidWidgetOptions = {
+  /**
+   * URL to open when the widget is tapped.
+   * Can be a full URL (e.g., "myapp://screen/details")
+   * or a path that will be prefixed with your app's URL scheme.
+   */
+  deepLinkUrl?: string
+}