@iternio/react-native-auto-play 0.6.0 → 0.7.0

package/src/index.web.ts

@@ -0,0 +1,166 @@
+// Web/Jest stub for the native CarPlay/Android Auto surface. Nothing here talks to a real native
+// module — every function call resolves to `undefined` (or an already-resolved promise, which is
+// indistinguishable from `undefined` to an `await`er) rather than throwing. Types are preserved by
+// casting against the real exports, so callers still get full type-checking/autocomplete.
+//
+// Anything below that's already safe as-is (pure types, plain enums, or modules that neither
+// create native objects nor import anything that does) is re-exported directly instead of stubbed.
+
+import { createElement } from 'react';
+import { View, type ViewProps } from 'react-native';
+import type { AndroidAutomotive } from './specs/AndroidAutomotive.nitro';
+import type { AutoPlay } from './specs/AutoPlay.nitro';
+import type { Voice } from './specs/Voice.nitro';
+import type { GridTemplate as RealGridTemplate } from './templates/GridTemplate';
+import type { InformationTemplate as RealInformationTemplate } from './templates/InformationTemplate';
+import type { ListTemplate as RealListTemplate } from './templates/ListTemplate';
+import type { MapTemplate as RealMapTemplate } from './templates/MapTemplate';
+import type { MessageTemplate as RealMessageTemplate } from './templates/MessageTemplate';
+import type { SearchTemplate as RealSearchTemplate } from './templates/SearchTemplate';
+import type { SignInTemplate as RealSignInTemplate } from './templates/SignInTemplate';
+import type { Template as RealTemplate } from './templates/Template';
+import type { SafeAreaInsets } from './types/Event';
+import type { Telemetry } from './types/Telemetry';
+
+function noop() {
+  return undefined;
+}
+
+/** Any property access returns a no-op function, so any method call is safe regardless of name. */
+function createNoopObject<T>(): T {
+  return new Proxy(
+    {},
+    {
+      get: (_target, prop) => (prop === 'then' || prop === 'toJSON' ? undefined : noop),
+    }
+  ) as T;
+}
+
+function createNoopClass<T>(): new (...args: never[]) => T {
+  function NoopInstance() {
+    return createNoopObject<T>();
+  }
+  return NoopInstance as unknown as new (
+    ...args: never[]
+  ) => T;
+}
+
+export * from './Constants';
+export * from './hooks/useMapTemplate';
+export type {
+  ActiveCarUxRestrictions,
+  AppFocusState,
+} from './specs/AndroidAutomotive.nitro';
+export { CarUxRestrictions } from './specs/AndroidAutomotive.nitro';
+export type { GridImageSize, GridTemplateConfig } from './templates/GridTemplate';
+export type { InformationItems, InformationTemplateConfig } from './templates/InformationTemplate';
+export type {
+  DefaultRow,
+  ListImageType,
+  ListTemplateConfig,
+  MultiSection,
+  RadioRow,
+  Section,
+  SingleSection,
+  TextRow,
+  ToggleRow,
+  WaypointCoordinate,
+  WaypointRow,
+} from './templates/ListTemplate';
+export type {
+  BaseMapTemplateConfig,
+  ChargerLocation,
+  ChargerOutlet,
+  ChargingConnector,
+  HeaderActionsAndroidMap,
+  MapButtons,
+  MapHeaderActions,
+  MapTemplateConfig,
+  OptionsPanelChargerSection,
+  OptionsPanelConfig,
+  OptionsPanelGridSection,
+  OptionsPanelListSection,
+  OptionsPanelSection,
+  PanelActionsIos,
+  PanelHeaderActions,
+  Point,
+  TripSelectorCallback,
+  VisibleTravelEstimate,
+} from './templates/MapTemplate';
+export type { MessageTemplateConfig } from './templates/MessageTemplate';
+export type { SearchSection, SearchTemplateConfig } from './templates/SearchTemplate';
+export type { SignInTemplateConfig } from './templates/SignInTemplate';
+export type {
+  ActionButton,
+  HeaderActions,
+  HeaderActionsAndroid,
+  HeaderActionsIos,
+  NitroBaseMapTemplateConfig,
+  NitroTemplateConfig,
+  TemplateConfig,
+} from './templates/Template';
+export * from './types/Button';
+export * from './types/Event';
+export * from './types/Image';
+export * from './types/Maneuver';
+export * from './types/RootComponent';
+export * from './types/SignInMethod';
+export * from './types/Telemetry';
+export * from './types/Text';
+export * from './types/Trip';
+export type { VoiceInputChunk, VoiceInputOptions, VoiceInputResult } from './types/Voice';
+export * from './utils/ErrorUtil';
+export type {
+  AlertPriority,
+  NavigationAlert as Alert,
+  NavigationAlertAction as AlertAction,
+} from './utils/NitroAlert';
+export type { ThemedColor } from './utils/NitroColor';
+export type { GridButton } from './utils/NitroGrid';
+
+export enum AutoPlayModules {
+  App = 'main',
+  AutoPlayRoot = 'AutoPlayRoot',
+  CarPlayDashboard = 'CarPlayDashboard',
+}
+
+const NO_INSETS: SafeAreaInsets = { top: 0, bottom: 0, left: 0, right: 0 };
+export const useSafeAreaInsets = () => NO_INSETS;
+export const SafeAreaView = (props: ViewProps) => createElement(View, props);
+
+export function setIconFont(_name: string, _glyphMap?: Record<string, number>): void {}
+
+export const useFocusedEffect = () => {};
+
+export const useVoiceInput = () => ({
+  voiceInputResult: undefined,
+  resetVoiceInputResult: () => {},
+});
+
+export const useAndroidAutoTelemetry = (): {
+  permissionsGranted: boolean | null;
+  telemetry: Telemetry | undefined;
+  error: string | undefined;
+} => ({
+  permissionsGranted: null,
+  telemetry: undefined,
+  error: undefined,
+});
+
+export const AutoPlayCluster = createNoopObject<Record<string, unknown>>();
+export const CarPlayDashboard = createNoopObject<Record<string, unknown>>();
+
+export const HybridAndroidAutomotive: AndroidAutomotive | null = null;
+export { HybridAndroidAutoTelemetry } from './hybrid/HybridAndroidAutoTelemetry';
+export { HybridAndroidWindowInformation } from './hybrid/HybridAndroidWindowInformation';
+export const HybridAutoPlay = createNoopObject<AutoPlay>();
+export const HybridVoice = createNoopObject<Voice>();
+
+export const Template = createNoopClass<InstanceType<typeof RealTemplate>>();
+export const ListTemplate = createNoopClass<RealListTemplate>();
+export const GridTemplate = createNoopClass<RealGridTemplate>();
+export const InformationTemplate = createNoopClass<RealInformationTemplate>();
+export const MessageTemplate = createNoopClass<RealMessageTemplate>();
+export const MapTemplate = createNoopClass<RealMapTemplate>();
+export const SearchTemplate = createNoopClass<RealSearchTemplate>();
+export const SignInTemplate = createNoopClass<RealSignInTemplate>();

package/src/installTimers.ts

@@ -0,0 +1,9 @@
+// Side-effect-only entry point, re-exported at the package root as `installTimers` (see
+// ../installTimers.ts) for `import '@iternio/react-native-auto-play/installTimers';` as the
+// app's first import. installAutoPlayTimers() itself isn't part of the public API -- funneling
+// installation through this one module is what actually guarantees "runs before anything else
+// captures the original globals" (see the README) instead of just documenting it as a rule
+// callers have to get right.
+import { installAutoPlayTimers } from './utils/AutoPlayTimers';
+
+installAutoPlayTimers();

package/src/installTimers.web.ts

@@ -0,0 +1,2 @@
+// Web/Jest stub -- nothing to install there. See installTimers.ts.
+export {};

package/src/specs/AutoPlayTiming.nitro.ts

@@ -0,0 +1,25 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+
+/**
+ * Backs setTimeout/setInterval with a scheduler that never pauses -- unlike RN's own JS
+ * timers, which RN throttles or pauses whenever the app backgrounds, regardless of whether
+ * the process is actually still running.
+ *
+ * iOS: CarPlay keeps this app's process alive and driving the external screen even when the
+ * phone's own screen is off, but RN's own RCTTiming still pauses in that state regardless.
+ *
+ * Android: JavaTimerManager only keeps ticking while the host is resumed *or* a headless JS
+ * task is running -- previously satisfied by registering a permanent no-op headless task
+ * (see AutoPlayHeadlessJsTask), which this replaces.
+ *
+ * All due-time bookkeeping lives here natively (mirroring RCTTiming's/JavaTimerManager's own
+ * architecture) so JS only crosses the bridge when a timer actually fires, not on every tick.
+ */
+export interface AutoPlayTiming extends HybridObject<{ ios: 'swift'; android: 'kotlin' }> {
+  /**
+   * Schedules `callback` to run after `durationMs`, repeating every `durationMs` if `repeats`
+   * is true. Returns an id to pass to `deleteTimer`.
+   */
+  createTimer(callback: () => void, durationMs: number, repeats: boolean): number;
+  deleteTimer(id: number): void;
+}

package/src/types/Image.ts

@@ -24,7 +24,8 @@ export type GlyphMapKey = keyof AutoPlayGlyphMap extends never
 type GlyphStyleFields = {
   /**
    * Sets the icon dark and light mode color or a single color for both.
-   * Defaults to white for dark mode and black for light mode if not specified.
+   * Defaults to `'default'` if not specified, which is white for dark mode and black for light mode.
+   * On Android Auto the host tint that follows the template is not applied when `backgroundColor` is not transparent.
    * Might not get applied everywhere like MapTemplate buttons on Android.
    */
   color?: ThemedColor | string;
@@ -61,6 +62,8 @@ export type AutoImage =
       /**
        * if specified the image gets tinted, if not it will just use the original image
        * Might not get applied everywhere like MapTemplate buttons on Android.
+       * Use `'default'` for monochrome icons that must stay readable on both dark and light
+       * Android Auto templates (17.8+), see README.
        */
       color?: ThemedColor | string;
       type: 'asset';
@@ -70,6 +73,8 @@ export type AutoImage =
       uri: string;
       /**
        * if specified the image gets tinted, if not it will just use the original image
+       * Use `'default'` for monochrome icons that must stay readable on both dark and light
+       * Android Auto templates (17.8+), see README.
        */
       color?: ThemedColor | string;
       /**

package/src/types/Telemetry.ts

@@ -1,4 +1,4 @@
-import type { Permission } from 'react-native/types';
+import type { Permission } from 'react-native';
 
 export type AndroidAutoPermissions =
   | Permission

package/src/utils/AutoPlayTimers.ts

@@ -0,0 +1,60 @@
+import { HybridAutoPlayTiming } from '../hybrid/HybridAutoPlayTiming';
+
+type TimerCallback = (...args: unknown[]) => void;
+
+let installed = false;
+
+/**
+ * Replaces the global `setTimeout`/`setInterval`/`clearTimeout`/`clearInterval` and
+ * `requestAnimationFrame`/`cancelAnimationFrame` with implementations backed by the native
+ * `AutoPlayTiming` module, so they keep running while the app is actively driving a car
+ * surface even though the phone itself is backgrounded or its screen is locked. React
+ * Native's own timers throttle or pause in that state regardless of whether the process is
+ * actually still alive, which would otherwise stall ETA updates and telemetry polling.
+ *
+ * `requestIdleCallback`/`cancelIdleCallback` are deliberately not covered: bridgeless RN
+ * backs those with a separate native module unrelated to `setTimeout`/`requestAnimationFrame`
+ * (and its own callback delivery path is an unimplemented stub on iOS), so there is nothing
+ * for this library to intercept there.
+ *
+ * All due-time bookkeeping happens natively -- this is a thin pass-through, so JS only
+ * crosses the bridge when a timer actually fires, not on some fixed interval.
+ *
+ * Call this **once**, as early as possible in your app -- ideally the first line of your
+ * entry file, before any other import -- so nothing else has already captured a reference to
+ * the original globals. Safe to call more than once; only the first call has any effect.
+ */
+export function installAutoPlayTimers(): void {
+  if (installed || HybridAutoPlayTiming == null) {
+    return;
+  }
+  installed = true;
+
+  const timing = HybridAutoPlayTiming;
+
+  const schedule =
+    (repeats: boolean) =>
+    (callback: TimerCallback, delay?: number, ...args: unknown[]): number =>
+      timing.createTimer(() => callback(...args), delay ?? 0, repeats);
+
+  const clear = (id: unknown): void => {
+    if (typeof id === 'number') {
+      timing.deleteTimer(id);
+    }
+  };
+
+  globalThis.setTimeout = schedule(false) as unknown as typeof setTimeout;
+  globalThis.setInterval = schedule(true) as unknown as typeof setInterval;
+  globalThis.clearTimeout = clear as unknown as typeof clearTimeout;
+  globalThis.clearInterval = clear as unknown as typeof clearInterval;
+
+  // Mirrors bridgeless RN's own implementation: requestAnimationFrame is setTimeout(0) with
+  // a performance.now() timestamp handed to the callback, and cancelAnimationFrame deletes
+  // the same underlying timer clearTimeout would.
+  const now = () =>
+    (globalThis as { performance?: { now(): number } }).performance?.now() ?? Date.now();
+
+  globalThis.requestAnimationFrame = ((callback: (timestamp: number) => void): number =>
+    timing.createTimer(() => callback(now()), 0, false)) as unknown as typeof requestAnimationFrame;
+  globalThis.cancelAnimationFrame = clear as unknown as typeof cancelAnimationFrame;
+}

package/src/utils/NitroColor.ts

@@ -1,8 +1,14 @@
 import { processColor } from 'react-native';
 
-export type NitroColor = { lightColor: number; darkColor: number };
+export type NitroColor = { lightColor: number; darkColor: number; isDefault?: boolean };
 export type ThemedColor = { lightColor: string; darkColor: string };
 
+const DefaultNitroColor = {
+  darkColor: convertColor('white'),
+  lightColor: convertColor('black'),
+  isDefault: true,
+};
+
 function convertColor(color: string): number;
 function convertColor(color?: string): number | undefined;
 function convertColor(color?: string): number | undefined {
@@ -18,6 +24,9 @@ function convert(color?: ThemedColor | string): NitroColor | undefined {
   }
 
   if (typeof color === 'string') {
+    if (color === 'default') {
+      return DefaultNitroColor;
+    }
     const convertedColor = convertColor(color);
     return { darkColor: convertedColor, lightColor: convertedColor };
   }

package/src/utils/NitroImage.ts

@@ -1,4 +1,4 @@
-import { Image, type ImageResolvedAssetSource } from 'react-native';
+import { Image } from 'react-native';
 import type { AutoImage } from '../types/Image';
 import { type NitroColor, NitroColorUtil } from './NitroColor';
 
@@ -64,7 +64,11 @@ function resolveGlyph(image: Extract<AutoImage, { type: 'glyph' }>): number {
   throw new Error('Glyph image must provide either `name` or `codepoint`.');
 }
 
-interface AssetImage extends ImageResolvedAssetSource {
+interface AssetImage {
+  uri: string;
+  width: number;
+  height: number;
+  scale: number;
   color?: NitroColor;
   packager_asset: boolean;
 }
@@ -96,11 +100,7 @@ function convert(image?: AutoImage): NitroImage | undefined {
   }
 
   if (image.type === 'glyph') {
-    const {
-      color = { darkColor: 'white', lightColor: 'black' },
-      fontScale,
-      backgroundColor = 'transparent',
-    } = image;
+    const { color = 'default', fontScale, backgroundColor = 'transparent' } = image;
 
     return {
       glyph: resolveGlyph(image),
@@ -123,7 +123,13 @@ function convert(image?: AutoImage): NitroImage | undefined {
   // so the input allows all optional parameters which are returned as is even though
   // the return type claims to not have any optional parameters...
   // we specify some default values to not crash because of proper typing required by nitro-modules
-  const { height = 0, scale = 0, uri, width = 0, ...rest } = Image.resolveAssetSource(image.image);
+  const {
+    height = 0,
+    scale = 0,
+    uri = '',
+    width = 0,
+    ...rest
+  } = Image.resolveAssetSource(image.image) ?? {};
 
   const assetImage: AssetImage = {
     height,

package/src/utils/NitroManeuver.ts

@@ -71,10 +71,7 @@ function convertManeuverImage(image?: ManeuverImage): NitroImage | undefined {
   }
 
   if (image.type === 'glyph') {
-    const color =
-      typeof image.color === 'string'
-        ? image.color
-        : (image.color ?? { darkColor: 'white', lightColor: 'black' });
+    const color = typeof image.color === 'string' ? image.color : (image.color ?? 'default');
     return NitroImageUtil.convert({
       ...image,
       color: color,

package/android/src/main/java/com/margelo/nitro/swe/iternio/reactnativeautoplay/HeadlessTaskService.kt

@@ -1,36 +0,0 @@
-package com.margelo.nitro.swe.iternio.reactnativeautoplay
-
-import android.content.Intent
-import android.os.Binder
-import android.os.IBinder
-import com.facebook.react.HeadlessJsTaskService
-import com.facebook.react.bridge.Arguments
-import com.facebook.react.bridge.UiThreadUtil
-import com.facebook.react.jstasks.HeadlessJsTaskConfig
-
-class HeadlessTaskService : HeadlessJsTaskService() {
-    // we use a bound service so it will never be killed when Android Auto is active
-    inner class LocalBinder : Binder() {
-        fun getService() = this@HeadlessTaskService
-    }
-
-    private val mBinder = LocalBinder()
-
-    override fun getTaskConfig(intent: Intent?): HeadlessJsTaskConfig {
-        val data = intent?.extras?.let {
-            Arguments.fromBundle(it)
-        } ?: Arguments.createMap()
-
-        return HeadlessJsTaskConfig(
-            taskKey = "AndroidAutoHeadlessJsTask", data = data, isAllowedInForeground = true
-        )
-    }
-
-    override fun onBind(intent: Intent): IBinder? {
-        // Start the headless task when bound
-        UiThreadUtil.runOnUiThread {
-            startTask(getTaskConfig(intent))
-        }
-        return mBinder
-    }
-}

package/lib/AutoPlayHeadlessJsTask.d.ts

@@ -1,5 +0,0 @@
-import type { AutoPlay as NitroAutoPlay } from './specs/AutoPlay.nitro';
-declare const _default: {
-    registerHeadlessTask: (hybridAutoPlay: NitroAutoPlay) => void;
-};
-export default _default;

package/lib/AutoPlayHeadlessJsTask.js

@@ -1,14 +0,0 @@
-import { AppRegistry, Platform } from 'react-native';
-const createTaskProvider = (hybridAutoPlay) => () => () => new Promise((resolve) => {
-    const remove = hybridAutoPlay.addListener('didDisconnect', () => {
-        resolve();
-        remove();
-    });
-});
-const registerHeadlessTask = (hybridAutoPlay) => {
-    if (Platform.OS !== 'android') {
-        return;
-    }
-    AppRegistry.registerHeadlessTask('AndroidAutoHeadlessJsTask', createTaskProvider(hybridAutoPlay));
-};
-export default { registerHeadlessTask };

package/src/AutoPlayHeadlessJsTask.ts

@@ -1,22 +0,0 @@
-import { AppRegistry, Platform, type Task, type TaskProvider } from 'react-native';
-import type { AutoPlay as NitroAutoPlay } from './specs/AutoPlay.nitro';
-
-const createTaskProvider =
-  (hybridAutoPlay: NitroAutoPlay): TaskProvider =>
-  (): Task =>
-  () =>
-    new Promise((resolve) => {
-      const remove = hybridAutoPlay.addListener('didDisconnect', () => {
-        resolve();
-        remove();
-      });
-    });
-
-const registerHeadlessTask = (hybridAutoPlay: NitroAutoPlay) => {
-  if (Platform.OS !== 'android') {
-    return;
-  }
-  AppRegistry.registerHeadlessTask('AndroidAutoHeadlessJsTask', createTaskProvider(hybridAutoPlay));
-};
-
-export default { registerHeadlessTask };