@iternio/react-native-auto-play 0.0.1

package/src/templates/MapTemplate.ts

@@ -0,0 +1,314 @@
+import React from 'react';
+import { AppRegistry, Platform } from 'react-native';
+import { NitroModules } from 'react-native-nitro-modules';
+import { type AutoText, type CleanupCallback, HybridAutoPlay } from '..';
+import { MapTemplateProvider } from '../components/MapTemplateContext';
+import { SafeAreaInsetsProvider } from '../components/SafeAreaInsetsContext';
+import type { MapTemplate as NitroMapTemplate } from '../specs/MapTemplate.nitro';
+import type { ActionButtonAndroid, MapButton, MapPanButton } from '../types/Button';
+import type { AutoManeuver } from '../types/Maneuver';
+import type { ColorScheme, RootComponentInitialProps } from '../types/RootComponent';
+import type {
+  TripConfig,
+  TripPoint,
+  TripPreviewTextConfiguration,
+  TripsConfig,
+} from '../types/Trip';
+import { type NitroAction, NitroActionUtil } from '../utils/NitroAction';
+import { type NavigationAlert, NitroAlertUtil } from '../utils/NitroAlert';
+import { NitroManeuverUtil, type NitroRoutingManeuver } from '../utils/NitroManeuver';
+import { NitroMapButton } from '../utils/NitroMapButton';
+import {
+  type HeaderActionsIos,
+  type NitroBaseMapTemplateConfig,
+  type NitroTemplateConfig,
+  Template,
+  type TemplateConfig,
+} from './Template';
+
+const HybridMapTemplate = NitroModules.createHybridObject<NitroMapTemplate>('MapTemplate');
+
+export type Point = { x: number; y: number };
+export type VisibleTravelEstimate = 'first' | 'last';
+
+export type HeaderActionsAndroidMap<T> =
+  | [ActionButtonAndroid<T>, ActionButtonAndroid<T>, ActionButtonAndroid<T>, ActionButtonAndroid<T>]
+  | [ActionButtonAndroid<T>, ActionButtonAndroid<T>, ActionButtonAndroid<T>]
+  | [ActionButtonAndroid<T>, ActionButtonAndroid<T>]
+  | [ActionButtonAndroid<T>];
+
+export interface NavigationAlertCallbacks {
+  dismiss: CleanupCallback;
+  update: (title: AutoText, subtitle?: AutoText) => void;
+}
+
+export interface NitroMapTemplateConfig extends TemplateConfig, NitroBaseMapTemplateConfig {
+  /**
+   * show either the next or final step travel estimates, defaults to final step so last
+   */
+  visibleTravelEstimate?: VisibleTravelEstimate;
+
+  /**
+   * callback for single finger pan gesture
+   * @param translation distance in pixels along the x & y axis that has been scrolled since the last touch position during the scroll event
+   * @param velocity the velocity of the pan gesture, iOS only
+   */
+  onDidUpdatePanGestureWithTranslation?: (translation: Point, velocity?: Point) => void;
+
+  /**
+   * callback for pinch to zoom gesture
+   * @param center x & y coordinate of the focal point in pixels
+   * @param scale the scaling factor
+   */
+  onDidUpdateZoomGestureWithCenter?: (center: Point, scale: number) => void;
+
+  /**
+   * single press event callback
+   * @param center coordinates of the click event in pixel
+   * @namespace Android
+   */
+  onClick?: (center: Point) => void;
+
+  /**
+   * double tap event callback
+   * @param center coordinates of the click event in pixel
+   * @namespace Android
+   */
+  onDoubleClick?: (center: Point) => void;
+
+  /**
+   * callback for color scheme changes
+   */
+  onAppearanceDidChange?: (colorScheme: ColorScheme) => void;
+
+  onStopNavigation(): void;
+  onAutoDriveEnabled?: () => void;
+
+  mapButtons?: Array<NitroMapButton>;
+  headerActions?: Array<NitroAction>;
+}
+
+export type MapButtons<T> =
+  | [MapButton<T>, MapButton<T>, MapButton<T>, MapButton<T> | MapPanButton<T>]
+  | [MapButton<T>, MapButton<T>, MapButton<T> | MapPanButton<T>]
+  | [MapButton<T>, MapButton<T> | MapPanButton<T>]
+  | [MapButton<T> | MapPanButton<T>];
+
+export type MapHeaderActions<T> = {
+  android?: HeaderActionsAndroidMap<T>;
+  ios?: HeaderActionsIos<T>;
+};
+
+export type BaseMapTemplateConfig<T> = {
+  /**
+   * buttons that represent actions on the map template, usually on the bottom right corner
+   */
+  mapButtons?: MapButtons<T>;
+
+  /**
+   * action buttons, usually at the the top right on Android and a top bar on iOS
+   */
+  headerActions?: MapHeaderActions<T>;
+};
+
+export type MapTemplateConfig = Omit<
+  NitroMapTemplateConfig,
+  'mapButtons' | 'headerActions' | 'onStopNavigation' | 'onAutoDriveEnabled'
+> &
+  BaseMapTemplateConfig<MapTemplate> & {
+    /**
+     * react component that is rendered
+     */
+    component: React.ComponentType<RootComponentInitialProps>;
+
+    /**
+     * Notification that navigation was stopped. May occur when another source such as the car head unit starts navigating.
+     * The navigation session on Android Auto/CarPlay is stopped already when this callback is triggered, make sure to stop other things like TTS too.
+     */
+    onStopNavigation(template: MapTemplate): void;
+
+    /**
+     * Notifies the app that, from this point onwards, when the user chooses to navigate to a destination, the app should start simulating a drive towards that destination.
+     * @namespace Android
+     */
+    onAutoDriveEnabled?: (template: MapTemplate) => void;
+  };
+
+export interface TripSelectorCallback {
+  setSelectedTrip: (id: string) => void;
+}
+
+export class MapTemplate extends Template<MapTemplateConfig, MapTemplateConfig['headerActions']> {
+  id = 'AutoPlayRoot';
+  private template = this;
+
+  constructor(config: MapTemplateConfig) {
+    super(config);
+
+    const {
+      component,
+      mapButtons,
+      headerActions,
+      onStopNavigation,
+      onAutoDriveEnabled,
+      ...baseConfig
+    } = config;
+
+    AppRegistry.registerComponent(
+      this.id,
+      () => (props) =>
+        React.createElement(MapTemplateProvider, {
+          mapTemplate: this.template,
+          // biome-ignore lint/correctness/noChildrenProp: there is no other way in a ts file
+          children: React.createElement(SafeAreaInsetsProvider, {
+            moduleName: this.id,
+            // biome-ignore lint/correctness/noChildrenProp: there is no other way in a ts file
+            children: React.createElement(component, props),
+          }),
+        })
+    );
+
+    const nitroConfig: NitroMapTemplateConfig & NitroTemplateConfig = {
+      ...baseConfig,
+      id: this.id,
+      headerActions: NitroActionUtil.convert(this.template, headerActions),
+      mapButtons: NitroMapButton.convert(this.template, mapButtons),
+      onStopNavigation: () => onStopNavigation(this.template),
+      onAutoDriveEnabled: onAutoDriveEnabled ? () => onAutoDriveEnabled(this.template) : undefined,
+    };
+
+    HybridMapTemplate.createMapTemplate(nitroConfig);
+  }
+
+  public setMapButtons(mapButtons: MapTemplateConfig['mapButtons']) {
+    const buttons = NitroMapButton.convert(this.template, mapButtons);
+    HybridMapTemplate.setTemplateMapButtons(this.id, buttons);
+  }
+
+  public override setHeaderActions(headerActions: MapTemplateConfig['headerActions']) {
+    const nitroActions = NitroActionUtil.convert(this.template, headerActions);
+    HybridAutoPlay.setTemplateHeaderActions(this.id, nitroActions);
+  }
+
+  /**
+   * brings up a navigation alert
+   * ⚠️ updating an existing alert is currently broken on Android Automotive, it brings up a new alert for each call
+   * @returns a callback to dismiss or update the navigation alert
+   */
+  public showAlert(alert: NavigationAlert) {
+    return HybridMapTemplate.showNavigationAlert(this.id, NitroAlertUtil.convert(alert));
+  }
+
+  /**
+   * @namespace Android brings up a custom trip selector mimicking the CarPlay trip selector as close as possible
+   * @namespace iOS brings up the stock CarPlay trip selector
+   * @returns a callback to update the shown trip
+   */
+  public showTripSelector({
+    trips,
+    selectedTripId,
+    textConfig,
+    onTripSelected,
+    onTripStarted,
+    onBackPressed,
+    mapButtons,
+  }: {
+    trips: Array<TripsConfig>;
+    selectedTripId?: string;
+    textConfig: TripPreviewTextConfiguration;
+    onTripSelected: (tripId: string, routeId: string) => void;
+    onTripStarted: (tripId: string, routeId: string) => void;
+    onBackPressed: () => void;
+    /**
+     * @namespace iOS - always shown no matter if navigation is started or not
+     * @namespace Android - these buttons will only be shown when navigation is not started, otherwise AA will not show them
+     */
+    mapButtons?: MapTemplateConfig['mapButtons'];
+  }): TripSelectorCallback {
+    if (
+      trips.length === 0 ||
+      trips.some(
+        (t) => t.routeChoices.length === 0 || t.routeChoices.some((r) => r.steps.length < 2)
+      )
+    ) {
+      throw new Error(
+        'Invalid trips passed, either no trips or some trips routeChoice or steps are empty'
+      );
+    }
+
+    if (
+      __DEV__ &&
+      Platform.OS === 'android' &&
+      new Set(trips.flatMap((t) => t.routeChoices.flatMap((r) => r.steps.at(-1)?.name))).size > 1
+    ) {
+      console.warn(
+        'found non distinct destination names, while this is possible it might lead to exceeding the step count, check https://developer.android.com/design/ui/cars/guides/ux-requirements/plan-task-flows#steps-refreshes for details'
+      );
+    }
+
+    const buttons = NitroMapButton.convert(this.template, mapButtons);
+
+    return HybridMapTemplate.showTripSelector(
+      this.id,
+      trips,
+      selectedTripId,
+      textConfig,
+      onTripSelected,
+      onTripStarted,
+      onBackPressed,
+      buttons ?? []
+    );
+  }
+
+  public hideTripSelector() {
+    HybridMapTemplate.hideTripSelector(this.id);
+  }
+
+  public updateVisibleTravelEstimate(visibleTravelEstimate: VisibleTravelEstimate) {
+    HybridMapTemplate.updateVisibleTravelEstimate(this.id, visibleTravelEstimate);
+  }
+
+  /**
+   * updates travel estimates
+   * @param steps all future steps, do not put in origin or passed steps
+   */
+  public updateTravelEstimates(steps: Array<TripPoint>) {
+    HybridMapTemplate.updateTravelEstimates(this.id, steps);
+  }
+
+  /**
+   * sets or updates maneuvers, make sure to call startNavigation first!
+   * @namespace Android sets all the supplied maneuvers whenever called
+   * @namespace iOS will update travelEstimates only when passing in maneuvers with the same id
+   */
+  public updateManeuvers(maneuvers: AutoManeuver) {
+    if (Array.isArray(maneuvers)) {
+      const nitroManeuvers = maneuvers.reduce((acc, maneuver) => {
+        if (maneuver == null) {
+          return acc;
+        }
+
+        acc.push(NitroManeuverUtil.convert(maneuver));
+        return acc;
+      }, [] as NitroRoutingManeuver[]);
+
+      HybridMapTemplate.updateManeuvers(this.id, nitroManeuvers);
+      return;
+    }
+
+    const messageManeuver = NitroManeuverUtil.convert(maneuvers);
+    HybridMapTemplate.updateManeuvers(this.id, messageManeuver);
+  }
+
+  /**
+   * either use showTripSelector to show a set of trips and let the user start the navigation session
+   * or use this to start a navigation session without asking the user
+   */
+  public startNavigation(trip: TripConfig) {
+    HybridMapTemplate.startNavigation(this.id, trip);
+  }
+
+  public stopNavigation() {
+    HybridMapTemplate.stopNavigation(this.id);
+  }
+}

package/src/templates/MessageTemplate.ts

@@ -0,0 +1,109 @@
+import { Platform } from 'react-native';
+import { NitroModules } from 'react-native-nitro-modules';
+import uuid from 'react-native-uuid';
+import {
+  type AutoImage,
+  type BaseMapTemplateConfig,
+  type CustomActionButtonAndroid,
+  type HeaderActionsAndroid,
+  HybridAutoPlay,
+  type TextButton,
+} from '..';
+import type { MessageTemplate as NitroMessageTemplate } from '../specs/MessageTemplate.nitro';
+import type { AutoText } from '../types/Text';
+import { type NitroAction, NitroActionUtil } from '../utils/NitroAction';
+import { type NitroImage, NitroImageUtil } from '../utils/NitroImage';
+import { NitroMapButton } from '../utils/NitroMapButton';
+import type { NitroBaseMapTemplateConfig, NitroTemplateConfig, TemplateConfig } from './Template';
+
+const HybridMessageTemplate =
+  NitroModules.createHybridObject<NitroMessageTemplate>('MessageTemplate');
+
+export interface NitroMessageTemplateConfig extends TemplateConfig {
+  headerActions?: Array<NitroAction>;
+  /**
+   * @namespace Android title shown on header
+   */
+  title?: AutoText;
+  message: AutoText;
+  actions?: Array<NitroAction>;
+  image?: NitroImage;
+  mapConfig?: NitroBaseMapTemplateConfig;
+}
+
+export type MessageTemplateConfig = Omit<
+  NitroMessageTemplateConfig,
+  'headerActions' | 'image' | 'mapConfig' | 'actions'
+> & {
+  /**
+   * action buttons, usually at the top right on Android
+   * @namespace Android
+   */
+  headerActions?: HeaderActionsAndroid<MessageTemplate>;
+  /**
+   * image shown at the top of the message on Android
+   * @namespace Android
+   */
+  image?: AutoImage;
+  /**
+   * If mapConfig is defined, it will use a MapWithContentTemplate with the current template. This results in a MessageTemplate with a map in background. No actions need to be specified, can be empty object.
+   * @namespace Android
+   */
+  mapConfig?: BaseMapTemplateConfig<MessageTemplate>;
+
+  /**
+   * @namespace Android up to 2 buttons of type TextButton, TextAndImageButton or ImageButton
+   * @namespace iOS - up to 3 buttons of type TextButton
+   */
+  actions?: {
+    android?:
+      | [CustomActionButtonAndroid<MessageTemplate>]
+      | [CustomActionButtonAndroid<MessageTemplate>, CustomActionButtonAndroid<MessageTemplate>];
+    ios?:
+      | [TextButton<MessageTemplate>, TextButton<MessageTemplate>, TextButton<MessageTemplate>]
+      | [TextButton<MessageTemplate>, TextButton<MessageTemplate>]
+      | [TextButton<MessageTemplate>];
+  };
+};
+
+/**
+ * This template is always pushed on top and will stay on top until it is popped.
+ * Other templates being pushed will end up below this one on the stack.
+ * Pushing another MessageTemplate will pop the currently shown one.
+ */
+export class MessageTemplate {
+  private template = this;
+  public id = uuid.v4();
+
+  constructor(config: MessageTemplateConfig) {
+    const { headerActions, image, mapConfig, actions, ...rest } = config;
+
+    const platformActions =
+      Platform.OS === 'android'
+        ? NitroActionUtil.convert(this.template, actions?.android)
+        : NitroActionUtil.convert(this.template, actions?.ios);
+
+    const nitroConfig: NitroMessageTemplateConfig & NitroTemplateConfig = {
+      ...rest,
+      id: this.id,
+      headerActions: NitroActionUtil.convert(this.template, { android: headerActions }),
+      image: NitroImageUtil.convert(image),
+      actions: platformActions,
+      mapConfig: mapConfig
+        ? {
+            mapButtons: NitroMapButton.convert(this.template, mapConfig.mapButtons),
+            headerActions: NitroActionUtil.convert(this.template, mapConfig.headerActions),
+          }
+        : undefined,
+    };
+
+    HybridMessageTemplate.createMessageTemplate(nitroConfig);
+  }
+
+  /**
+   * push this template on the stack and show it to the user
+   */
+  public push() {
+    return HybridAutoPlay.pushTemplate(this.id);
+  }
+}

package/src/templates/SearchTemplate.ts

@@ -0,0 +1,98 @@
+import { NitroModules } from 'react-native-nitro-modules';
+import type { DefaultRow, SingleSection } from '..';
+import type { SearchTemplate as NitroSearchTemplate } from '../specs/SearchTemplate.nitro';
+import type { AutoText } from '../types/Text';
+import { type NitroAction, NitroActionUtil } from '../utils/NitroAction';
+import { type NitroSection, NitroSectionUtil } from '../utils/NitroSection';
+import {
+  type HeaderActions,
+  type NitroTemplateConfig,
+  Template,
+  type TemplateConfig,
+} from './Template';
+
+const HybridSearchTemplate = NitroModules.createHybridObject<NitroSearchTemplate>('SearchTemplate');
+
+export type SearchSection<T> = {
+  type: 'default';
+  items: Array<DefaultRow<T>>;
+};
+
+export interface NitroSearchTemplateConfig extends TemplateConfig {
+  headerActions?: Array<NitroAction>;
+  title: AutoText;
+  results: NitroSection;
+  /**
+   * Text that is put into the searchbar as initial value
+   * @namespace Android
+   */
+  initialSearchText?: string;
+  /**
+   * Placeholder value in the search bar until text is entered
+   * @namespace Android
+   */
+  searchHint?: string;
+  /**
+   * Called when the user types on the keyboard. Should be debounced to avoid excessive calls to backend.
+   * @param searchText the text that the user has entered into the search bar
+   */
+  onSearchTextChanged: (searchText: string) => void;
+  /**
+   * Called when the user presses enter or search button to confirm search explicitly.
+   * Can be used to trigger a backend call immediately, but might never be called if the user selects a search result item from autocomplete results instead.
+   * @param searchText the text that the user has entered into the search bar
+   */
+  onSearchTextSubmitted: (searchText: string) => void;
+}
+
+export type SearchTemplateConfig = Omit<
+  NitroSearchTemplateConfig,
+  'headerActions' | 'results' | 'onPopped'
+> & {
+  /**
+   * action buttons, usually at the the top right on Android and a top bar on iOS
+   * @namespace Android
+   */
+  headerActions?: HeaderActions<SearchTemplate>;
+  /**
+   * List of search results to show in the search results screen
+   */
+  results?: SearchSection<SearchTemplate>;
+
+  /**
+   * @namespace Android
+   */
+  onPopped?: TemplateConfig['onPopped'];
+};
+
+export class SearchTemplate extends Template<SearchTemplateConfig, HeaderActions<SearchTemplate>> {
+  private template = this;
+
+  constructor(config: SearchTemplateConfig) {
+    super(config);
+
+    const { headerActions, results, ...rest } = config;
+
+    const nitroConfig: NitroSearchTemplateConfig & NitroTemplateConfig = {
+      ...rest,
+      id: this.id,
+      headerActions: NitroActionUtil.convert(this.template, headerActions),
+      results: NitroSectionUtil.convert(this.template, results)?.at(0) ?? {
+        items: [],
+        type: 'default',
+      },
+    };
+
+    HybridSearchTemplate.createSearchTemplate(nitroConfig);
+  }
+
+  public updateSearchResults(results?: SingleSection<SearchTemplate>) {
+    HybridSearchTemplate.updateSearchResults(
+      this.id,
+      NitroSectionUtil.convert(this.template, results)?.at(0) ?? {
+        items: [],
+        type: 'default',
+      }
+    );
+  }
+}

package/src/templates/Template.ts

@@ -0,0 +1,108 @@
+import uuid from 'react-native-uuid';
+import { HybridAutoPlay } from '..';
+import type { ActionButtonAndroid, ActionButtonIos, AppButton, BackButton } from '../types/Button';
+import { type NitroAction, NitroActionUtil } from '../utils/NitroAction';
+import type { NitroMapButton } from '../utils/NitroMapButton';
+
+export type ActionButton<T> = ActionButtonAndroid<T> | ActionButtonIos<T>;
+
+export type HeaderActionsIos<T> = {
+  /**
+   * @platform iOS - the back button can not be hidden or disabled, if you don't define it iOS will provide a default back button popping the template
+   */
+  backButton?: BackButton<T>;
+  leadingNavigationBarButtons?: [ActionButtonIos<T>, ActionButtonIos<T>] | [ActionButtonIos<T>];
+  trailingNavigationBarButtons?: [ActionButtonIos<T>, ActionButtonIos<T>] | [ActionButtonIos<T>];
+};
+
+export type HeaderActionsAndroid<T> = {
+  startHeaderAction?: AppButton | BackButton<T>;
+  endHeaderActions?: [ActionButtonAndroid<T>, ActionButtonAndroid<T>] | [ActionButtonAndroid<T>];
+};
+
+export type HeaderActions<T> = {
+  android?: HeaderActionsAndroid<T>;
+  ios?: HeaderActionsIos<T>;
+};
+export interface NitroTemplateConfig {
+  id: string;
+}
+
+export interface TemplateConfig {
+  /**
+   * Fired before template appears
+   */
+  onWillAppear?(animated?: boolean): void;
+
+  /**
+   * Fired before template disappears
+   */
+  onWillDisappear?(animated?: boolean): void;
+
+  /**
+   * Fired after template appears
+   */
+  onDidAppear?(animated?: boolean): void;
+
+  /**
+   * Fired after template disappears
+   */
+  onDidDisappear?(animated?: boolean): void;
+
+  /**
+   * Fired when the template was removed from the stack
+   * on all other states the template is still on the stack and might appear again
+   * this callback lets you know the template is gone forever
+   * @namespace Android - works fine on all templates
+   * @namespace iOS - does not work on all templates like SearchTemplate
+   */
+  onPopped?(): void;
+
+  /**
+   * if specified the template will be popped after the specified timeout once it has been pushed
+   * will be ignored if setRootTemplate is called
+   * template will be popped only if it is still visible to the user aka the topmost template
+   */
+  autoDismissMs?: number;
+}
+
+export interface NitroBaseMapTemplateConfig extends TemplateConfig {
+  mapButtons?: Array<NitroMapButton>;
+  headerActions?: Array<NitroAction>;
+}
+
+export class Template<TemplateConfigType, ActionsType> {
+  public id!: string;
+
+  constructor(config: TemplateConfig & TemplateConfigType) {
+    // templates that render on a surface provide their own id, others use a auto generated one
+    this.id =
+      'id' in config && config.id != null && typeof config.id === 'string' ? config.id : uuid.v4();
+  }
+
+  /**
+   * set as root template on the stack
+   */
+  public setRootTemplate() {
+    return HybridAutoPlay.setRootTemplate(this.id);
+  }
+
+  /**
+   * push this template on the stack and show it to the user
+   */
+  public push() {
+    return HybridAutoPlay.pushTemplate(this.id);
+  }
+
+  /**
+   * remove all templates above this one from the stack
+   */
+  public popTo() {
+    return HybridAutoPlay.popToTemplate(this.id);
+  }
+
+  public setHeaderActions<T>(headerActions?: ActionsType) {
+    const nitroActions = NitroActionUtil.convert(headerActions as HeaderActions<T>);
+    HybridAutoPlay.setTemplateHeaderActions(this.id, nitroActions);
+  }
+}