@use-voltra/android 2.0.0 → 2.1.0

package/src/ongoing-notification/components.tsx

@@ -0,0 +1,49 @@
+import type { ComponentType } from 'react'
+
+import type {
+  AndroidOngoingNotificationActionProps,
+  AndroidOngoingNotificationBigTextProps,
+  AndroidOngoingNotificationProgressProps,
+} from './types.js'
+
+export const ANDROID_ONGOING_NOTIFICATION_COMPONENT_TAG = Symbol.for('VOLTRA_ANDROID_ONGOING_NOTIFICATION_COMPONENT')
+
+type AndroidOngoingNotificationComponentKind = 'progress' | 'bigText' | 'action'
+
+type AndroidOngoingNotificationComponent<TProps extends Record<string, unknown>> = ComponentType<TProps> & {
+  displayName: string
+  [ANDROID_ONGOING_NOTIFICATION_COMPONENT_TAG]: AndroidOngoingNotificationComponentKind
+}
+
+const createAndroidOngoingNotificationComponent = <TProps extends Record<string, unknown>>(
+  displayName: string,
+  kind: AndroidOngoingNotificationComponentKind
+): AndroidOngoingNotificationComponent<TProps> => {
+  const Component = (_props: TProps) => null
+
+  Component.displayName = displayName
+  ;(Component as AndroidOngoingNotificationComponent<TProps>)[ANDROID_ONGOING_NOTIFICATION_COMPONENT_TAG] = kind
+
+  return Component as AndroidOngoingNotificationComponent<TProps>
+}
+
+export const Progress = createAndroidOngoingNotificationComponent<AndroidOngoingNotificationProgressProps>(
+  'AndroidOngoingNotification.Progress',
+  'progress'
+)
+
+export const BigText = createAndroidOngoingNotificationComponent<AndroidOngoingNotificationBigTextProps>(
+  'AndroidOngoingNotification.BigText',
+  'bigText'
+)
+
+export const Action = createAndroidOngoingNotificationComponent<AndroidOngoingNotificationActionProps>(
+  'AndroidOngoingNotification.Action',
+  'action'
+)
+
+export const AndroidOngoingNotification = {
+  Progress,
+  BigText,
+  Action,
+} as const

package/src/ongoing-notification/renderer.ts

@@ -0,0 +1,360 @@
+import { Children, Fragment, isValidElement, type ReactElement, type ReactNode } from 'react'
+
+import type { ImageSource } from '../jsx/Image.js'
+import { getAndroidComponentId } from '../payload/component-ids.js'
+import { ANDROID_ONGOING_NOTIFICATION_COMPONENT_TAG } from './components.js'
+import type {
+  AndroidOngoingNotificationActionPayload,
+  AndroidOngoingNotificationActionProps,
+  AndroidOngoingNotificationBigTextPayload,
+  AndroidOngoingNotificationBigTextProps,
+  AndroidOngoingNotificationContent,
+  AndroidOngoingNotificationPayload,
+  AndroidOngoingNotificationProgressPayload,
+  AndroidOngoingNotificationProgressPoint,
+  AndroidOngoingNotificationProgressProps,
+  AndroidOngoingNotificationProgressSegment,
+} from './types.js'
+
+void getAndroidComponentId
+
+const PAYLOAD_VERSION = 1 as const
+
+const flattenChildren = (node: ReactNode): ReactNode[] => {
+  if (node === null || node === undefined || typeof node === 'boolean') {
+    return []
+  }
+
+  if (Array.isArray(node)) {
+    return node.flatMap((child) => flattenChildren(child))
+  }
+
+  return [node]
+}
+
+const getSingleRootElement = (content: ReactNode): ReactElement<Record<string, unknown>> => {
+  const children = flattenChildren(content)
+
+  if (children.length !== 1) {
+    throw new Error('[Voltra] [Android] Ongoing notification content must contain exactly one root element.')
+  }
+
+  const [root] = children
+
+  if (!isValidElement(root)) {
+    throw new Error(
+      '[Voltra] [Android] Ongoing notification content must be a valid AndroidOngoingNotification element.'
+    )
+  }
+
+  if (root.type === Fragment) {
+    return getSingleRootElement((root.props as { children?: ReactNode }).children)
+  }
+
+  return root as ReactElement<Record<string, unknown>>
+}
+
+const assertString = (value: unknown, propName: string): string => {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`[Voltra] [Android] Ongoing notification prop "${propName}" must be a non-empty string.`)
+  }
+
+  return value
+}
+
+const assertOptionalNonEmptyString = (value: unknown, propName: string): string | undefined => {
+  if (value === undefined) {
+    return undefined
+  }
+
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(
+      `[Voltra] [Android] Ongoing notification prop "${propName}" must be a non-empty string when provided.`
+    )
+  }
+
+  return value
+}
+
+const assertOptionalString = (value: unknown, propName: string): string | undefined => {
+  if (value === undefined) {
+    return undefined
+  }
+
+  if (typeof value !== 'string') {
+    throw new Error(`[Voltra] [Android] Ongoing notification prop "${propName}" must be a string.`)
+  }
+
+  return value
+}
+
+const isImageSource = (value: unknown): value is ImageSource => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return false
+  }
+
+  const keys = Object.keys(value)
+  if (keys.length !== 1) {
+    return false
+  }
+
+  if ('assetName' in value) {
+    return typeof value.assetName === 'string' && value.assetName.length > 0
+  }
+
+  if ('base64' in value) {
+    return typeof value.base64 === 'string' && value.base64.length > 0
+  }
+
+  return false
+}
+
+const assertOptionalImageSource = (value: unknown, propName: string): ImageSource | undefined => {
+  if (value === undefined) {
+    return undefined
+  }
+
+  if (!isImageSource(value)) {
+    throw new Error(
+      `[Voltra] [Android] Ongoing notification prop "${propName}" must be an image source with either assetName or base64.`
+    )
+  }
+
+  return value
+}
+
+const assertBoolean = (value: unknown, propName: string): boolean | undefined => {
+  if (value === undefined) {
+    return undefined
+  }
+
+  if (typeof value !== 'boolean') {
+    throw new Error(`[Voltra] [Android] Ongoing notification prop "${propName}" must be a boolean.`)
+  }
+
+  return value
+}
+
+const assertFiniteNumber = (value: unknown, propName: string): number => {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new Error(`[Voltra] [Android] Ongoing notification prop "${propName}" must be a finite number.`)
+  }
+
+  return value
+}
+
+const assertOptionalColorString = (value: unknown, propName: string): string | undefined => {
+  if (value === undefined) {
+    return undefined
+  }
+
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new Error(`[Voltra] [Android] Ongoing notification prop "${propName}" must be a non-empty color string.`)
+  }
+
+  return value
+}
+
+const normalizeProgressSegments = (value: unknown): AndroidOngoingNotificationProgressSegment[] | undefined => {
+  if (value === undefined) {
+    return undefined
+  }
+
+  if (!Array.isArray(value)) {
+    throw new Error('[Voltra] [Android] Ongoing notification prop "segments" must be an array.')
+  }
+
+  return value.map((segment, index) => {
+    if (!segment || typeof segment !== 'object' || Array.isArray(segment)) {
+      throw new Error(`[Voltra] [Android] Ongoing notification prop "segments[${index}]" must be an object.`)
+    }
+
+    const length = assertFiniteNumber((segment as { length?: unknown }).length, `segments[${index}].length`)
+    if (length <= 0) {
+      throw new Error(
+        `[Voltra] [Android] Ongoing notification prop "segments[${index}].length" must be greater than 0.`
+      )
+    }
+
+    return {
+      length,
+      color: assertOptionalColorString((segment as { color?: unknown }).color, `segments[${index}].color`),
+    }
+  })
+}
+
+const normalizeProgressPoints = (value: unknown): AndroidOngoingNotificationProgressPoint[] | undefined => {
+  if (value === undefined) {
+    return undefined
+  }
+
+  if (!Array.isArray(value)) {
+    throw new Error('[Voltra] [Android] Ongoing notification prop "points" must be an array.')
+  }
+
+  return value.map((point, index) => {
+    if (!point || typeof point !== 'object' || Array.isArray(point)) {
+      throw new Error(`[Voltra] [Android] Ongoing notification prop "points[${index}]" must be an object.`)
+    }
+
+    const position = assertFiniteNumber((point as { position?: unknown }).position, `points[${index}].position`)
+    if (position < 0) {
+      throw new Error(
+        `[Voltra] [Android] Ongoing notification prop "points[${index}].position" must be greater than or equal to 0.`
+      )
+    }
+
+    return {
+      position,
+      color: assertOptionalColorString((point as { color?: unknown }).color, `points[${index}].color`),
+    }
+  })
+}
+
+const normalizeWhen = (value: unknown): number | undefined => {
+  if (value === undefined) {
+    return undefined
+  }
+
+  if (value instanceof Date) {
+    const timestamp = value.getTime()
+    if (!Number.isFinite(timestamp)) {
+      throw new Error('[Voltra] [Android] Ongoing notification prop "when" must be a valid Date or timestamp.')
+    }
+
+    return timestamp
+  }
+
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return value
+  }
+
+  throw new Error('[Voltra] [Android] Ongoing notification prop "when" must be a valid Date or timestamp.')
+}
+
+const getElementKind = (element: ReactElement<Record<string, unknown>>) => {
+  const elementType = element.type as unknown
+
+  return typeof elementType === 'function' || (typeof elementType === 'object' && elementType !== null)
+    ? (elementType as Record<PropertyKey, unknown>)[ANDROID_ONGOING_NOTIFICATION_COMPONENT_TAG]
+    : undefined
+}
+
+const normalizeActionPayload = (
+  props: AndroidOngoingNotificationActionProps
+): AndroidOngoingNotificationActionPayload => {
+  return {
+    title: assertString(props.title, 'title'),
+    deepLinkUrl: assertString(props.deepLinkUrl, 'deepLinkUrl'),
+    icon: assertOptionalImageSource(props.icon, 'icon'),
+  }
+}
+
+const normalizeActions = (value: ReactNode): AndroidOngoingNotificationActionPayload[] | undefined => {
+  const actions: AndroidOngoingNotificationActionPayload[] = []
+
+  Children.forEach(value, (child) => {
+    if (!isValidElement(child)) {
+      return
+    }
+
+    if (child.type === Fragment) {
+      const fragmentChildren = normalizeActions((child.props as { children?: ReactNode }).children)
+      if (fragmentChildren) {
+        actions.push(...fragmentChildren)
+      }
+      return
+    }
+
+    if (getElementKind(child as ReactElement<Record<string, unknown>>) !== 'action') {
+      return
+    }
+
+    actions.push(normalizeActionPayload(child.props as AndroidOngoingNotificationActionProps))
+  })
+
+  return actions.length > 0 ? actions : undefined
+}
+
+const normalizeProgressPayload = (
+  props: AndroidOngoingNotificationProgressProps
+): AndroidOngoingNotificationProgressPayload => {
+  const value = assertFiniteNumber(props.value, 'value')
+  const max = assertFiniteNumber(props.max, 'max')
+
+  if (max <= 0) {
+    throw new Error('[Voltra] [Android] Ongoing notification prop "max" must be greater than 0.')
+  }
+
+  if (value < 0 || value > max) {
+    throw new Error('[Voltra] [Android] Ongoing notification prop "value" must be between 0 and max.')
+  }
+
+  return {
+    v: PAYLOAD_VERSION,
+    kind: 'progress',
+    title: assertOptionalNonEmptyString(props.title, 'title'),
+    subText: assertOptionalString(props.subText, 'subText'),
+    text: assertOptionalString(props.text, 'text'),
+    value,
+    max,
+    indeterminate: assertBoolean(props.indeterminate, 'indeterminate'),
+    shortCriticalText: assertOptionalString(props.shortCriticalText, 'shortCriticalText'),
+    when: normalizeWhen(props.when),
+    chronometer: assertBoolean(props.chronometer, 'chronometer'),
+    largeIcon: assertOptionalImageSource(props.largeIcon, 'largeIcon'),
+    progressTrackerIcon: assertOptionalImageSource(props.progressTrackerIcon, 'progressTrackerIcon'),
+    progressStartIcon: assertOptionalImageSource(props.progressStartIcon, 'progressStartIcon'),
+    progressEndIcon: assertOptionalImageSource(props.progressEndIcon, 'progressEndIcon'),
+    segments: normalizeProgressSegments(props.segments),
+    points: normalizeProgressPoints(props.points),
+    actions: normalizeActions(props.children),
+  }
+}
+
+const normalizeBigTextPayload = (
+  props: AndroidOngoingNotificationBigTextProps
+): AndroidOngoingNotificationBigTextPayload => {
+  const text = assertString(props.text, 'text')
+
+  return {
+    v: PAYLOAD_VERSION,
+    kind: 'bigText',
+    title: assertOptionalNonEmptyString(props.title, 'title'),
+    subText: assertOptionalString(props.subText, 'subText'),
+    text,
+    bigText: assertOptionalString(props.bigText, 'bigText') ?? text,
+    shortCriticalText: assertOptionalString(props.shortCriticalText, 'shortCriticalText'),
+    when: normalizeWhen(props.when),
+    chronometer: assertBoolean(props.chronometer, 'chronometer'),
+    largeIcon: assertOptionalImageSource(props.largeIcon, 'largeIcon'),
+    actions: normalizeActions(props.children),
+  }
+}
+
+export const renderAndroidOngoingNotificationPayloadToJson = (
+  content: ReactNode
+): AndroidOngoingNotificationPayload => {
+  const element = getSingleRootElement(content)
+  const kind = getElementKind(element)
+
+  if (kind === 'progress') {
+    return normalizeProgressPayload(element.props as AndroidOngoingNotificationProgressProps)
+  }
+
+  if (kind === 'bigText') {
+    return normalizeBigTextPayload(element.props as AndroidOngoingNotificationBigTextProps)
+  }
+
+  throw new Error(
+    '[Voltra] [Android] Ongoing notification content must use AndroidOngoingNotification.Progress or AndroidOngoingNotification.BigText.'
+  )
+}
+
+export const renderAndroidOngoingNotificationPayload = (content: ReactNode): string => {
+  return JSON.stringify(renderAndroidOngoingNotificationPayloadToJson(content))
+}
+
+export const renderAndroidOngoingNotificationContent = (content: AndroidOngoingNotificationContent): string => {
+  return renderAndroidOngoingNotificationPayload(content)
+}

package/src/ongoing-notification/types.ts

@@ -0,0 +1,199 @@
+import type { ReactNode } from 'react'
+
+import type { ImageSource } from '../jsx/Image.js'
+
+export type AndroidOngoingNotificationFallbackBehavior = 'standard' | 'error'
+
+export type AndroidOngoingNotificationCommonDisplayProps = {
+  title?: string
+  subText?: string
+  shortCriticalText?: string
+  when?: Date | number
+  chronometer?: boolean
+}
+
+export type AndroidOngoingNotificationProgressSegment = {
+  length: number
+  color?: string
+}
+
+export type AndroidOngoingNotificationProgressPoint = {
+  position: number
+  color?: string
+}
+
+export type AndroidOngoingNotificationActionProps = {
+  title: string
+  deepLinkUrl: string
+  icon?: ImageSource
+}
+
+export type AndroidOngoingNotificationActionPayload = {
+  title: string
+  deepLinkUrl: string
+  icon?: ImageSource
+}
+
+export type AndroidOngoingNotificationProgressProps = AndroidOngoingNotificationCommonDisplayProps & {
+  text?: string
+  value: number
+  max: number
+  indeterminate?: boolean
+  largeIcon?: ImageSource
+  progressTrackerIcon?: ImageSource
+  progressStartIcon?: ImageSource
+  progressEndIcon?: ImageSource
+  segments?: AndroidOngoingNotificationProgressSegment[]
+  points?: AndroidOngoingNotificationProgressPoint[]
+  children?: ReactNode
+}
+
+export type AndroidOngoingNotificationBigTextProps = AndroidOngoingNotificationCommonDisplayProps & {
+  text: string
+  bigText?: string
+  largeIcon?: ImageSource
+  children?: ReactNode
+}
+
+export type AndroidOngoingNotificationProgressPayload = {
+  v: 1
+  kind: 'progress'
+  title?: string
+  subText?: string
+  text?: string
+  value: number
+  max: number
+  indeterminate?: boolean
+  shortCriticalText?: string
+  when?: number
+  chronometer?: boolean
+  largeIcon?: ImageSource
+  progressTrackerIcon?: ImageSource
+  progressStartIcon?: ImageSource
+  progressEndIcon?: ImageSource
+  segments?: AndroidOngoingNotificationProgressSegment[]
+  points?: AndroidOngoingNotificationProgressPoint[]
+  actions?: AndroidOngoingNotificationActionPayload[]
+}
+
+export type AndroidOngoingNotificationBigTextPayload = {
+  v: 1
+  kind: 'bigText'
+  title?: string
+  subText?: string
+  text: string
+  bigText?: string
+  shortCriticalText?: string
+  when?: number
+  chronometer?: boolean
+  largeIcon?: ImageSource
+  actions?: AndroidOngoingNotificationActionPayload[]
+}
+
+export type AndroidOngoingNotificationPayload =
+  | AndroidOngoingNotificationProgressPayload
+  | AndroidOngoingNotificationBigTextPayload
+
+export type AndroidOngoingNotificationContent = ReactNode
+
+export type AndroidOngoingNotificationInput =
+  | AndroidOngoingNotificationContent
+  | AndroidOngoingNotificationPayload
+  | string
+
+export type StartAndroidOngoingNotificationOptions = {
+  notificationId?: string
+  channelId: string
+  smallIcon?: string
+  deepLinkUrl?: string
+  requestPromotedOngoing?: boolean
+  fallbackBehavior?: AndroidOngoingNotificationFallbackBehavior
+}
+
+export type UpdateAndroidOngoingNotificationOptions = Omit<
+  Partial<StartAndroidOngoingNotificationOptions>,
+  'notificationId'
+>
+
+export type UseAndroidOngoingNotificationOptions = StartAndroidOngoingNotificationOptions & {
+  autoStart?: boolean
+  autoUpdate?: boolean
+}
+
+export type AndroidOngoingNotificationCapabilities = {
+  apiLevel: number
+  notificationsEnabled: boolean
+  supportsPromotedNotifications: boolean
+  canPostPromotedNotifications: boolean
+  canRequestPromotedOngoing: boolean
+}
+
+export type AndroidOngoingNotificationStatus = {
+  isActive: boolean
+  isDismissed: boolean
+  isPromoted?: boolean
+  hasPromotableCharacteristics?: boolean
+}
+
+export type AndroidOngoingNotificationStartResult =
+  | {
+      ok: true
+      notificationId: string
+      action: 'started'
+      reason?: undefined
+    }
+  | {
+      ok: false
+      notificationId: string
+      action?: undefined
+      reason: 'already_exists'
+    }
+
+export type AndroidOngoingNotificationUpdateResult =
+  | {
+      ok: true
+      notificationId: string
+      action: 'updated'
+      reason?: undefined
+    }
+  | {
+      ok: false
+      notificationId: string
+      action?: undefined
+      reason: 'not_found' | 'dismissed'
+    }
+
+export type AndroidOngoingNotificationUpsertResult =
+  | {
+      ok: true
+      notificationId: string
+      action: 'started' | 'updated'
+      reason?: undefined
+    }
+  | {
+      ok: false
+      notificationId: string
+      action?: undefined
+      reason: 'already_exists' | 'dismissed'
+    }
+
+export type AndroidOngoingNotificationStopResult =
+  | {
+      ok: true
+      notificationId: string
+      action: 'stopped'
+      reason?: undefined
+    }
+  | {
+      ok: false
+      notificationId: string
+      action?: undefined
+      reason: 'not_found'
+    }
+
+export type UseAndroidOngoingNotificationResult = {
+  start: (options?: Partial<StartAndroidOngoingNotificationOptions>) => Promise<AndroidOngoingNotificationStartResult>
+  update: (options?: UpdateAndroidOngoingNotificationOptions) => Promise<AndroidOngoingNotificationUpdateResult>
+  end: () => Promise<AndroidOngoingNotificationStopResult>
+  isActive: boolean
+}

package/src/payload/component-ids.ts

@@ -0,0 +1,89 @@
+/* eslint-disable */
+// 🤖 AUTO-GENERATED from data/components.json
+// DO NOT EDIT MANUALLY - Changes will be overwritten
+// Schema version: 1.0.0
+
+/**
+ * Mapping from Android component name to numeric ID
+ * Component IDs are assigned sequentially based on order in components.json (0-indexed)
+ */
+export const ANDROID_COMPONENT_NAME_TO_ID: Record<string, number> = {
+  AndroidFilledButton: 0,
+  AndroidImage: 1,
+  AndroidSwitch: 2,
+  AndroidCheckBox: 3,
+  AndroidRadioButton: 4,
+  AndroidBox: 5,
+  AndroidButton: 6,
+  AndroidCircleIconButton: 7,
+  AndroidCircularProgressIndicator: 8,
+  AndroidColumn: 9,
+  AndroidLazyColumn: 10,
+  AndroidLazyVerticalGrid: 11,
+  AndroidLinearProgressIndicator: 12,
+  AndroidOutlineButton: 13,
+  AndroidRow: 14,
+  AndroidScaffold: 15,
+  AndroidSpacer: 16,
+  AndroidSquareIconButton: 17,
+  AndroidText: 18,
+  AndroidTitleBar: 19,
+  AndroidChart: 20,
+}
+
+/**
+ * Mapping from numeric ID to Android component name
+ */
+export const ANDROID_COMPONENT_ID_TO_NAME: Record<number, string> = {
+  0: 'AndroidFilledButton',
+  1: 'AndroidImage',
+  2: 'AndroidSwitch',
+  3: 'AndroidCheckBox',
+  4: 'AndroidRadioButton',
+  5: 'AndroidBox',
+  6: 'AndroidButton',
+  7: 'AndroidCircleIconButton',
+  8: 'AndroidCircularProgressIndicator',
+  9: 'AndroidColumn',
+  10: 'AndroidLazyColumn',
+  11: 'AndroidLazyVerticalGrid',
+  12: 'AndroidLinearProgressIndicator',
+  13: 'AndroidOutlineButton',
+  14: 'AndroidRow',
+  15: 'AndroidScaffold',
+  16: 'AndroidSpacer',
+  17: 'AndroidSquareIconButton',
+  18: 'AndroidText',
+  19: 'AndroidTitleBar',
+  20: 'AndroidChart',
+}
+
+/**
+ * Get Android component ID from name
+ * @throws Error if component name is not found
+ */
+export function getAndroidComponentId(name: string): number {
+  const id = ANDROID_COMPONENT_NAME_TO_ID[name]
+  if (id === undefined) {
+    throw new Error(
+      `Unknown Android component name: "${name}". Available components: ${Object.keys(
+        ANDROID_COMPONENT_NAME_TO_ID
+      ).join(', ')}`
+    )
+  }
+  return id
+}
+
+/**
+ * Get Android component name from ID
+ * @throws Error if component ID is not found
+ */
+export function getAndroidComponentName(id: number): string {
+  const name = ANDROID_COMPONENT_ID_TO_NAME[id]
+  if (name === undefined) {
+    throw new Error(
+      `Unknown Android component ID: ${id}. Valid IDs: 0-${Object.keys(ANDROID_COMPONENT_ID_TO_NAME).length - 1}`
+    )
+  }
+  return name
+}