@javascriptcommon/react-native-carplay 2.3.11

package/src/templates/Template.ts

@@ -0,0 +1,164 @@
+import { ImageSourcePropType, Platform } from 'react-native';
+import { CarPlay } from '../CarPlay';
+import { BarButton } from '../interfaces/BarButton';
+
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const resolveAssetSource = require('react-native/Libraries/Image/resolveAssetSource');
+
+export interface BaseEvent {
+  /**
+   * Template id that fired the event
+   */
+  templateId: string;
+}
+
+export interface BarButtonEvent extends BaseEvent {
+  id: string;
+}
+
+export interface TemplateConfig {
+  /**
+   * Give the template your own ID. Must be unique.
+   */
+  id?: string;
+  /**
+   * An array of bar buttons to display on the leading side of the navigation bar.
+   *
+   * The navigation bar displays up to two buttons in the leading space. When including more than two buttons in the array, the system displays only the first two buttons.
+   * @namespace iOS
+   */
+  leadingNavigationBarButtons?: BarButton[];
+  /**
+   * An array of bar buttons to display on the trailing side of the navigation bar.
+   *
+   * The navigation bar displays up to two buttons in the trailing space. When including more than two buttons in the array, the system displays only the first two buttons.
+   * @namespace iOS
+   */
+  trailingNavigationBarButtons?: BarButton[];
+  /**
+   * UITabBarSystemItem
+   */
+  tabSystemItem?: number;
+  /**
+   * Name of system image for tab
+   */
+  tabSystemImageName?: string;
+  /**
+   * Image source for tab
+   */
+  tabImage?: ImageSourcePropType;
+  /**
+   * Set tab title
+   */
+  tabTitle?: string;
+  /**
+   * Fired before template appears
+   * @param e Event
+   */
+  onWillAppear?(e: BaseEvent): void;
+  /**
+   * Fired before template disappears
+   * @param e Event
+   */
+  onWillDisappear?(e: BaseEvent): void;
+  /**
+   * Fired after template appears
+   * @param e Event
+   */
+  onDidAppear?(e: BaseEvent): void;
+  /**
+   * Fired after template disappears
+   * @param e Event
+   */
+  onDidDisappear?(e: BaseEvent): void;
+
+  /**
+   * Fired when bar button is pressed
+   * @param e Event
+   */
+  onBarButtonPressed?(e: BarButtonEvent): void;
+}
+
+export class Template<P> {
+  public get type(): string {
+    return 'unset';
+  }
+  public id!: string;
+
+  public get eventMap() {
+    return {};
+  }
+
+  constructor(public config: TemplateConfig & P) {
+    if (config.id) {
+      this.id = config.id;
+    }
+
+    if (!this.id) {
+      this.id = `${this.type}-${Date.now()}-${Math.round(Math.random() * Number.MAX_SAFE_INTEGER)}`;
+    }
+
+    const eventMap = {
+      barButtonPressed: 'onBarButtonPressed',
+      didAppear: 'onDidAppear',
+      didDisappear: 'onDidDisappear',
+      willAppear: 'onWillAppear',
+      willDisappear: 'onWillDisappear',
+      ...(this.eventMap || {}),
+    };
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    Object.entries(eventMap).forEach(([eventName, callbackName]: [string, any]) => {
+      CarPlay.emitter.addListener(eventName, (e: { id: string; templateId: string }) => {
+        const configEventName = callbackName as keyof Pick<
+          TemplateConfig,
+          | 'onWillAppear'
+          | 'onWillDisappear'
+          | 'onDidAppear'
+          | 'onDidDisappear'
+          | 'onBarButtonPressed'
+        >;
+        if (config[configEventName] && e.templateId === this.id) {
+          config[configEventName]?.(e);
+        }
+      });
+    });
+
+    if (this.type !== 'map') {
+      const callbackFn = Platform.select({
+        android: ({ error }: { error?: string } = {}) => {
+          error && console.error(error);
+        },
+      });
+      CarPlay.bridge.createTemplate(
+        this.id,
+        this.parseConfig({ type: this.type, ...config }),
+        callbackFn,
+      );
+    }
+  }
+
+  updateTemplate = (config: P) => {
+    console.log('LETSGO!', config, this.type);
+    CarPlay.bridge.updateTemplate(this.id, this.parseConfig({ type: this.type, ...config }));
+  };
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  public parseConfig(config: any) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    function traverse(obj: any) {
+      for (const i in obj) {
+        if (obj[i] !== null && typeof obj[i] === 'object') {
+          traverse(obj[i]);
+        }
+        if (String(i).match(/[Ii]mage$/)) {
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+          obj[i] = resolveAssetSource(obj[i]);
+        }
+      }
+    }
+    const result = JSON.parse(JSON.stringify(config));
+    traverse(result);
+    return result;
+  }
+}

package/src/templates/VoiceControlTemplate.ts

@@ -0,0 +1,25 @@
+import { CarPlay } from '../CarPlay';
+import { VoiceControlState } from '../interfaces/VoiceControlState';
+import { Template } from './Template';
+
+export interface VoiceControlTemplateConfig {
+  /**
+   * The array of voice control states that can be used by your voice control template.
+   */
+  voiceControlStates: VoiceControlState[];
+}
+
+/**
+ * Displays a voice control indicator on the CarPlay screen.
+ *
+ * CarPlay navigation apps must show the voice control template during audio input.
+ */
+export class VoiceControlTemplate extends Template<VoiceControlTemplateConfig> {
+  public get type(): string {
+    return 'voicecontrol';
+  }
+
+  public activateVoiceControlState(identifier: string) {
+    CarPlay.bridge.activateVoiceControlState(this.id, identifier);
+  }
+}

package/src/templates/android/AndroidNavigationBaseTemplate.ts

@@ -0,0 +1,46 @@
+import { AppRegistry, Platform } from 'react-native';
+import { Template, TemplateConfig } from '../Template';
+import { CarPlay } from '../../CarPlay';
+
+export interface AndroidNavigationBaseTemplateConfig extends TemplateConfig {
+  /**
+   * Your component to render inside Android Auto Map view
+   * Example `component: MyComponent`
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  component: React.ComponentType<any>;
+
+  onDidShowPanningInterface?(): void;
+  onDidDismissPanningInterface?(): void;
+}
+
+export class AndroidNavigationBaseTemplate<
+  T extends AndroidNavigationBaseTemplateConfig,
+> extends Template<T> {
+  get eventMap() {
+    return {
+      didShowPanningInterface: 'onDidShowPanningInterface',
+      didDismissPanningInterface: 'onDidDismissPanningInterface',
+    };
+  }
+
+  constructor(public config: T) {
+    super(config);
+
+    if (config.component) {
+      AppRegistry.registerComponent(this.id, () => config.component);
+    }
+
+    const callbackFn = Platform.select({
+      android: ({ error }: { error?: string } = {}) => {
+        error && console.error(error);
+      },
+    });
+
+    CarPlay.bridge.createTemplate(
+      this.id,
+      this.parseConfig({ type: this.type, ...config, render: true }),
+      callbackFn,
+    );
+  }
+}

package/src/templates/android/MessageTemplate.ts

@@ -0,0 +1,19 @@
+import { Action, HeaderAction } from '../../interfaces/Action';
+import { Template, TemplateConfig } from '../Template';
+import { ImageSourcePropType } from 'react-native';
+
+export interface MessageTemplateConfig extends TemplateConfig {
+  message?: string;
+  loading?: boolean;
+  headerAction?: HeaderAction;
+  actions?: Action[];
+  icon?: ImageSourcePropType;
+  title?: string;
+  debugMessage?: string;
+}
+
+export class MessageTemplate extends Template<MessageTemplateConfig> {
+  public get type(): string {
+    return 'message';
+  }
+}

package/src/templates/android/NavigationTemplate.ts

@@ -0,0 +1,50 @@
+import { Action } from '../../interfaces/Action';
+import { CarColor } from '../../interfaces/CarColor';
+import { NavigationInfo } from '../../interfaces/NavigationInfo';
+import { TravelEstimates } from '../../interfaces/TravelEstimates';
+import {
+  AndroidNavigationBaseTemplate,
+  AndroidNavigationBaseTemplateConfig,
+} from './AndroidNavigationBaseTemplate';
+
+export interface NavigationTemplateConfig extends AndroidNavigationBaseTemplateConfig {
+  /**
+   * Sets an ActionStrip with a list of template-scoped actions for this template.
+   * The Action buttons in Map Based Template are automatically adjusted based on the screen size. On narrow width screen, icon Actions show by default. If no icon specify, showing title Actions instead. On wider width screen, title Actions show by default. If no title specify, showing icon Actions instead.
+   * Requirements This template allows up to 4 Actions in its ActionStrip. Of the 4 allowed Actions, it can either be a title Action as set via setTitle, or a icon Action as set via setIcon.
+   */
+  actions: Action[];
+  /**
+   * Sets the background color to use for the navigation information.
+   * Depending on contrast requirements, capabilities of the vehicle screens, or other factors, the color may be ignored by the host or overridden by the vehicle system.
+   */
+  backgroundColor?: CarColor;
+  /**
+   * Sets the TravelEstimate to the final destination.
+   */
+  travelEstimate?: TravelEstimates;
+  /**
+   * Sets an ActionStrip with a list of map-control related actions for this template, such as pan or zoom.
+   * The host will draw the buttons in an area that is associated with map controls.
+   * If the app does not include the PAN button in this ActionStrip, the app will not receive the user input for panning gestures from SurfaceCallback methods, and the host will exit any previously activated pan mode.
+   * Requirements This template allows up to 4 Actions in its map ActionStrip. Only Actions with icons set via setIcon are allowed.
+   */
+  mapButtons?: Action[];
+  /**
+   * Sets the navigation information to display on the template.
+   * Unless set with this method, navigation info won't be displayed on the template.
+   */
+  navigationInfo?: NavigationInfo;
+}
+
+/**
+ * A template for showing navigation information.
+ * This template has two independent sections which can be updated:
+ * - Navigation information such as routing instructions or navigation-related messages.
+ * - Travel estimates to the destination.
+ */
+export class NavigationTemplate extends AndroidNavigationBaseTemplate<NavigationTemplateConfig> {
+  public get type(): string {
+    return 'navigation';
+  }
+}

package/src/templates/android/PaneTemplate.ts

@@ -0,0 +1,16 @@
+import { Action, HeaderAction } from '../../interfaces/Action';
+import { Template, TemplateConfig } from '../Template';
+import { Pane } from '../../interfaces/Pane';
+
+export interface PaneTemplateConfig extends TemplateConfig {
+  pane: Pane;
+  headerAction?: HeaderAction;
+  actions?: Action[];
+  title?: string;
+}
+
+export class PaneTemplate extends Template<PaneTemplateConfig> {
+  public get type(): string {
+    return 'pane';
+  }
+}

package/src/templates/android/PlaceListMapTemplate.ts

@@ -0,0 +1,64 @@
+import { Action, HeaderAction } from '../../interfaces/Action';
+import {
+  AndroidNavigationBaseTemplate,
+  AndroidNavigationBaseTemplateConfig,
+} from './AndroidNavigationBaseTemplate';
+import { Place } from '../../interfaces/Place';
+import { ListItem } from '../../interfaces/ListItem';
+
+export interface PlaceListMapTemplateConfig extends AndroidNavigationBaseTemplateConfig {
+  /**
+   * Sets an ActionStrip with a list of template-scoped actions for this template.
+   * The Action buttons in Map Based Template are automatically adjusted based on the screen size. On narrow width screen, icon Actions show by default. If no icon specify, showing title Actions instead. On wider width screen, title Actions show by default. If no title specify, showing icon Actions instead.
+   * @limit This template allows up to 4 Actions in its ActionStrip. Of the 4 allowed Actions, it can either be a title Action as set via setTitle, or a icon Action as set via setIcon.
+   */
+  actions?: Action[];
+  /**
+   * Sets the anchor maker on the map.
+   * An anchor marker will not be displayed unless set with this method.
+   * The anchor marker is displayed differently from other markers by the host.
+   * If not null, an anchor marker will be shown at the specified CarLocation on the map. The camera will adapt to always have the anchor marker visible within its viewport, along with other places' markers from Row that are currently visible in the Pane. This can be used to provide a reference point on the map (e.g. the center of a search region) as the user pages through the Pane's markers, for example.
+   */
+  anchor?: Place;
+  /**
+   * Sets whether to show the current location in the map.
+   * The map template will show the user's current location on the map.
+   * This functionality requires the app to have either the ACCESS_FINE_LOCATION or ACCESS_COARSE_LOCATION permission. When isEnabled is true, the host may receive location updates from the app in order to show the user's current location.
+   */
+  currentLocationEnabled?: boolean;
+  /**
+   * Sets the Action that will be displayed in the header of the template.
+   * Unless set with this method, the template will not have a header action.
+   * @limit This template only supports either one of APP_ICON and BACK as a header Action.
+   */
+  headerAction?: HeaderAction;
+  /**
+   * Sets an ItemList to show in a list view along with the map.
+   * Unless set with this method, the template will not show an item list.
+   * To show a marker corresponding to a point of interest represented by a row, set the Place instance via setMetadata. The host will display the PlaceMarker in both the map and the list view as the row becomes visible.
+   * @limit The number of items in the ItemList should be smaller or equal than the limit provided by CONTENT_LIMIT_TYPE_PLACE_LIST. The host will ignore any items over that limit. The list itself cannot be selectable as set via setOnSelectedListener. Each Row can add up to 2 lines of texts via addText and cannot contain a Toggle.
+   */
+  itemList?: ListItem[];
+  /**
+   * Sets whether the template is in a loading state.
+   */
+  loading?: boolean;
+  /**
+   * Title for the map
+   */
+  title?: string;
+}
+
+/**
+ * A template that displays a map along with a list of places.
+ * The map can display markers corresponding to the places in the list. See setItemList for details.
+ * Template Restrictions In regards to template refreshes, as described in onGetTemplate, this template is considered a refresh of a previous one if:
+ * - The previous template is in a loading state (see setLoading, or
+ * - The template title has not changed, and the number of rows and the title (not counting spans) of each row between the previous and new ItemLists have not changed.
+ * - The template is sent in response to a user-initiated content refresh request. (see setOnContentRefreshListener.
+ */
+export class PlaceListMapTemplate extends AndroidNavigationBaseTemplate<PlaceListMapTemplateConfig> {
+  public get type(): string {
+    return 'place-list-map';
+  }
+}

package/src/templates/android/PlaceListNavigationTemplate.ts

@@ -0,0 +1,57 @@
+import { Action } from '../../interfaces/Action';
+import { Header } from '../../interfaces/Header';
+import { ListItem } from '../../interfaces/ListItem';
+import {
+  AndroidNavigationBaseTemplate,
+  AndroidNavigationBaseTemplateConfig,
+} from './AndroidNavigationBaseTemplate';
+
+export interface PlaceListNavigationTemplateConfig extends AndroidNavigationBaseTemplateConfig {
+  /**
+   * Sets an ActionStrip with a list of template-scoped actions for this template.
+   * The Action buttons in Map Based Template are automatically adjusted based on the screen size. On narrow width screen, icon Actions show by default. If no icon specify, showing title Actions instead. On wider width screen, title Actions show by default. If no title specify, showing icon Actions instead.
+   * @limit This template allows up to 4 Actions in its ActionStrip. Of the 4 allowed Actions, it can either be a title Action as set via setTitle, or a icon Action as set via setIcon.
+   */
+  actions?: Action[];
+  /**
+   * Sets the Header for this template.
+   */
+  header?: Header;
+  /**
+   * Sets an ItemList to show in a list view along with the map.
+   * Unless set with this method, the template will not show an item list.
+   * To show a marker corresponding to a point of interest represented by a row, set the Place instance via setMetadata. The host will display the PlaceMarker in both the map and the list view as the row becomes visible.
+   * @limit The number of items in the ItemList should be smaller or equal than the limit provided by CONTENT_LIMIT_TYPE_PLACE_LIST. The host will ignore any items over that limit. The list itself cannot be selectable as set via setOnSelectedListener. Each Row can add up to 2 lines of texts via addText and cannot contain a Toggle.
+   */
+  itemList?: ListItem[];
+  /**
+   * Sets whether the template is in a loading state.
+   */
+  loading?: boolean;
+  /**
+   * Sets an ActionStrip with a list of map-control related actions for this template, such as pan or zoom.
+   * The host will draw the buttons in an area that is associated with map controls.
+   * If the app does not include the PAN button in this ActionStrip, the app will not receive the user input for panning gestures from SurfaceCallback methods, and the host will exit any previously activated pan mode.
+   * @limit This template allows up to 4 Actions in its map ActionStrip. Only Actions with icons set via setIcon are allowed.
+   */
+  mapButtons?: Action[];
+  /**
+   * Title for the map
+   */
+  title?: string;
+}
+
+/**
+ * A template that supports showing a list of places alongside a custom drawn map.
+ * The template itself does not expose a drawing surface. In order to draw on the canvas, use setSurfaceCallback.
+ * Template Restrictions In regards to template refreshes, as described in onGetTemplate, this template is considered a refresh of a previous one if:
+ * - The previous template is in a loading state (see setLoading, or
+ * - The template title has not changed, and the number of rows and the title (not counting spans) of each row between the previous and new ItemLists have not changed.
+ * - The template is sent in response to a user-initiated content refresh request. (see setOnContentRefreshListener.
+ * In order to use this template your car app MUST declare that it uses the **androidx.car.app.NAVIGATION_TEMPLATES** permission in the manifest.
+ */
+export class PlaceListNavigationTemplate extends AndroidNavigationBaseTemplate<PlaceListNavigationTemplateConfig> {
+  public get type(): string {
+    return 'place-navigation-map';
+  }
+}

package/src/templates/android/RoutePreviewNavigationTemplate.ts

@@ -0,0 +1,66 @@
+import { Action } from '../../interfaces/Action';
+import { Header } from '../../interfaces/Header';
+import { ListItem } from '../../interfaces/ListItem';
+import {
+  AndroidNavigationBaseTemplate,
+  AndroidNavigationBaseTemplateConfig,
+} from './AndroidNavigationBaseTemplate';
+
+export interface RoutePreviewNavigationTemplateConfig extends AndroidNavigationBaseTemplateConfig {
+  /**
+   * Sets an ActionStrip with a list of template-scoped actions for this template.
+   * The Action buttons in Map Based Template are automatically adjusted based on the screen size. On narrow width screen, icon Actions show by default. If no icon specify, showing title Actions instead. On wider width screen, title Actions show by default. If no title specify, showing icon Actions instead.
+   * @limit This template allows up to 4 Actions in its ActionStrip. Of the 4 allowed Actions, it can either be a title Action as set via setTitle, or a icon Action as set via setIcon.
+   */
+  actions?: Action[];
+  /**
+   * Sets the Header for this template.
+   */
+  header?: Header;
+  /**
+   * Sets an ItemList to show in a list view along with the map.
+   * Unless set with this method, the template will not show an item list.
+   * To show a marker corresponding to a point of interest represented by a row, set the Place instance via setMetadata. The host will display the PlaceMarker in both the map and the list view as the row becomes visible.
+   * @limit The number of items in the ItemList should be smaller or equal than the limit provided by CONTENT_LIMIT_TYPE_PLACE_LIST. The host will ignore any items over that limit. The list itself cannot be selectable as set via setOnSelectedListener. Each Row can add up to 2 lines of texts via addText and cannot contain a Toggle.
+   */
+  itemList?: ListItem[];
+  /**
+   * Sets whether the template is in a loading state.
+   */
+  loading?: boolean;
+  /**
+   * Sets an ActionStrip with a list of map-control related actions for this template, such as pan or zoom.
+   * The host will draw the buttons in an area that is associated with map controls.
+   * If the app does not include the PAN button in this ActionStrip, the app will not receive the user input for panning gestures from SurfaceCallback methods, and the host will exit any previously activated pan mode.
+   * @limit This template allows up to 4 Actions in its map ActionStrip. Only Actions with icons set via setIcon are allowed.
+   */
+  mapButtons?: Action[];
+  /**
+   * Sets the Action to allow users to request navigation using the currently selected route.
+   * This should not be null if the template is not in a loading state (see #setIsLoading}), and the Action's title must be set.
+   * Spans are not supported in the navigate action and will be ignored.
+   */
+  navigateAction?: Action;
+  /**
+   * Title for the map
+   */
+  title?: string;
+}
+
+/**
+ * A template that supports showing a list of routes alongside a custom drawn map.
+ * The list must have its ItemList.OnSelectedListener set, and the template must have its navigate action set (see setNavigateAction). These are used in conjunction to inform the app that:
+ * - A route has been selected. The app should also highlight the route on the map surface.
+ * - A navigate action has been triggered. The app should begin navigation using the selected route.
+ * The template itself does not expose a drawing surface. In order to draw on the canvas, use setSurfaceCallback.
+ * Template Restrictions In regards to template refreshes, as described in onGetTemplate, this template is considered a refresh of a previous one if:
+ * - The previous template is in a loading state (see setLoading, or
+ * - The template title has not changed, and the number of rows and the title (not counting spans) of each row between the previous and new ItemLists have not changed.
+ * Note that specifically, this means the app should not use this template to continuously refresh the routes as the car moves.
+ * In order to use this template your car app MUST declare that it uses the **androidx.car.app.NAVIGATION_TEMPLATES** permission in the manifest.
+ */
+export class RoutePreviewNavigationTemplate extends AndroidNavigationBaseTemplate<RoutePreviewNavigationTemplateConfig> {
+  public get type(): string {
+    return 'route-preview-navigation';
+  }
+}