@javascriptcommon/react-native-carplay 2.3.11

package/src/templates/ListTemplate.ts

@@ -0,0 +1,167 @@
+import { CarPlay } from '../CarPlay';
+import { ListItemUpdate } from '../interfaces/ListItemUpdate';
+import { ListSection } from '../interfaces/ListSection';
+import { Template, TemplateConfig } from './Template';
+
+type CollectionType = '' | 'playlist' | 'artist' | 'groupedArtist' | 'editorial' | 'search' | 'user' | 'allTracks' | 'allRecent' | 'allFavorites'
+
+export interface ListTemplateConfig extends TemplateConfig {
+  /**
+   * The title displayed in the navigation bar while the list template is visible.
+   */
+  title?: string;
+  /**
+   * The sections displayed in the list.
+   */
+  sections: ListSection[];
+  /**
+   *  An optional array of strings, ordered from most to least preferred.
+   *  The variant strings should be provided as localized, displayable content.
+   *  The system will select the first variant that fits the available space.
+   *  If the list template does not contain any items (itemCount == 0), then
+   *  the template will display an empty view with a title and subtitle to indicate
+   *  that the template has no list items.
+   *  If the list template is updated to contain items, the empty view will be automatically
+   *  removed.
+   */
+  emptyViewTitleVariants?: string[];
+  /**
+   *  An optional array of strings, ordered from most to least preferred.
+   *  The variant strings should be provided as localized, displayable content.
+   *  The system will select the first variant that fits the available space.
+   *  If the list template does not contain any items (itemCount == 0), then
+   *  the template will display an empty view with a title and subtitle to indicate
+   *  that the template has no list items.
+   *  If the list template is updated to contain items, the empty view will be automatically
+   *  removed.
+   */
+  emptyViewSubtitleVariants?: string[];
+  /**
+   * Fired when list item is selected.
+   * Spinner shows by default.
+   * When the returned promise is resolved the spinner will hide.
+   * @param item Object with the selected index
+   */
+  onItemSelect?(item: { index: number }): Promise<void>;
+
+  /**
+   * Fired when row item is selected.
+   * Spinner shows by default.
+   * When the returned promise is resolved the spinner will hide.
+   * @param item Object with the selected index
+   */
+  onRowItemSelect?(item: { index: number }): Promise<void>;
+
+  /**
+   * Fired when the template is loaded.
+   */
+  onTemplateLoaded?(): Promise<void>;
+
+  /**
+   * Fired when the back button is pressed
+   */
+  onBackButtonPressed?(): void;
+
+  /**
+   * Option to hide back button
+   * (defaults to false)
+   */
+  backButtonHidden?: boolean;
+
+  /**
+   * Back button title
+   */
+  backButtonTitle: string;
+
+  /**
+   * Assistant Configuration
+   * @see https://developer.apple.com/documentation/carplay/cplisttemplate#3762508
+   */
+  assistant?: {
+    enabled: boolean;
+    position: 'top' | 'bottom';
+    visibility: 'off' | 'always' | 'limited';
+    action: 'playMedia' | 'startCall';
+  };
+
+  /**
+   * Set to true if you are asynchronously updating an existing template
+   */
+  updatingTemplate: boolean;
+
+  /**
+   * Set to true if you want to receive the onTemplateLoaded callback
+   */
+  needsTemplateLoadedCallback: boolean;
+}
+
+/**
+ * A hierarchical list of menu items can be displayed on the CarPlay screen using a list template.
+ *
+ * The List Template allows navigation apps to present a hierarchical list of menu items. It includes a navigation bar and a list view.
+ *
+ * The navigation bar includes a title, and up to two (2) leading buttons and two (2) trailing buttons. You can customize the appearance of these buttons with icons or text.
+ *
+ * Each item in the list view may include an icon, title, subtitle, and an optional disclosure indicator indicating the presence of a submenu. The depth of the menu hierarchy may not exceed 5 levels. Note that some cars limit the total number of items that may be shown in a list.
+ */
+export class ListTemplate extends Template<ListTemplateConfig> {
+  public get type(): string {
+    return 'list';
+  }
+
+  get eventMap() {
+    return {
+      backButtonPressed: 'onBackButtonPressed',
+    };
+  }
+
+  constructor(public config: ListTemplateConfig) {
+    super(config);
+
+    CarPlay.emitter.addListener('didSelectListItem', e => {
+      if (config.onItemSelect && e.templateId === this.id) {
+        void Promise.resolve(config.onItemSelect(e)).then(() => {
+          CarPlay.bridge.reactToSelectedResult(true);
+        });
+      }
+    });
+
+    CarPlay.emitter.addListener('didSelectRowItem', e => {
+      if (config.onRowItemSelect && e.templateId === this.id) {
+        void Promise.resolve(config.onRowItemSelect(e)).then(() => {
+          CarPlay.bridge.reactToSelectedResult(true);
+        });
+      }
+    });
+
+    CarPlay.emitter.addListener('templateLoaded', e => {
+      if (config.onTemplateLoaded && e.templateId === this.id) {
+        void Promise.resolve(config.onTemplateLoaded())
+      }
+    });
+  }
+
+  public updateSections = (sections: ListSection[]) => {
+    return CarPlay.bridge.updateListTemplateSections(this.id, this.parseConfig(sections));
+  };
+
+  public updateListTemplateItem = (config: ListItemUpdate) => {
+    return CarPlay.bridge.updateListTemplateItem(this.id, this.parseConfig(config));
+  };
+
+  public updateListTemplateRowItems = (config: ListItemUpdate) => {
+    return CarPlay.bridge.updateListTemplateRowItems(this.id, this.parseConfig(config));
+  };
+
+  public getMaximumListItemCount() {
+    return CarPlay.bridge.getMaximumListItemCount(this.id);
+  }
+
+  public getMaximumListSectionCount() {
+    return CarPlay.bridge.getMaximumListSectionCount(this.id);
+  }
+
+  public getMaximumRowItemsCount() {
+    return CarPlay.bridge.getMaximumRowItemsCount(this.id);
+  }
+}

package/src/templates/MapTemplate.ts

@@ -0,0 +1,231 @@
+import { AppRegistry, Platform } from 'react-native';
+import { CarPlay } from '../CarPlay';
+import { MapButton } from '../interfaces/MapButton';
+import { NavigationAlert } from '../interfaces/NavigationAlert';
+import { TextConfiguration } from '../interfaces/TextConfiguration';
+import { TimeRemainingColor } from '../interfaces/TimeRemainingColor';
+import { TravelEstimates } from '../interfaces/TravelEstimates';
+import { NavigationSession } from '../navigation/NavigationSession';
+import { Trip } from '../navigation/Trip';
+import { Template, TemplateConfig } from './Template';
+import { ListItem } from '../interfaces/ListItem';
+import { Action } from '../interfaces/Action';
+import { Header } from '../interfaces/Header';
+import { Pane } from '../interfaces/Pane';
+
+export interface MapTemplateConfig extends TemplateConfig {
+  /**
+   * The background color the map template uses when displaying guidance.
+   * @namespace iOS
+   */
+  guidanceBackgroundColor?: string;
+  /**
+   * The style that the map template uses when displaying trip estimates during active nagivation.
+   * @default dark
+   * @namespace iOS
+   */
+  tripEstimateStyle?: 'dark' | 'light';
+  /**
+   * Your component to render inside CarPlay/Android Auto
+   * Example `component: MyComponent`
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  component: React.ComponentType<any>;
+  /**
+   * An array of map buttons displayed on the trailing bottom corner of the map template.
+   * If the array contains more than three buttons, the map template displays only the first three buttons, ignoring the remaining buttons.
+   * @namespace iOS
+   * @namespace Android
+   */
+  mapButtons?: MapButton[];
+  /**
+   * A Boolean value that indicates whether the navigation bar hides automatically.
+   * @namespace iOS
+   */
+  automaticallyHidesNavigationBar?: boolean;
+  /**
+   * A Boolean value that tells the system to hide the map buttons when hiding the navigation bar.
+   * @namespace iOS
+   */
+  hidesButtonsWithNavigationBar?: boolean;
+  /**
+   * A component that holds onto data associated with a template's header.
+   * @namespace Android
+   */
+  header?: Header;
+  /**
+   * Sets an ItemList to show in a list view along with the map.
+   * - 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.
+   * - Images of type IMAGE_TYPE_LARGE are not allowed in this template.
+   * - Rows are not allowed to have both an image and a place marker.
+   * @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.
+   * @namespace Android
+   */
+  items?: ListItem[];
+  /**
+   * Sets the ActionStrip for this template.
+   * Unless set with this method, the template will not have an action strip.
+   * 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.
+   * @namespace Android
+   */
+  actions?: Action[];
+  /**
+   * Sets the Pane for this template. getImage for pane will not be shown in MapTemplate.
+   * Unless set with this method, the template will not show a pane.
+   * @limit The number of items in the Pane should be smaller or equal than the limit provided by CONTENT_LIMIT_TYPE_PANE. The host via addText and cannot contain either a Toggle or a OnClickListener.
+   * Up to 2 Actions are allowed in the Pane. Each action's title color can be customized with ForegroundCarColorSpan instances. Any other span is not supported.
+   * If none of the header Action, the header title or the action strip have been set on the template, the header is hidden.
+   */
+  pane?: Pane;
+  /**
+   * Fired when Alert Action button is pressed
+   * @param e Event
+   */
+  onAlertActionPressed?(e: { secondary?: boolean; primary?: boolean }): void;
+  onMapButtonPressed?(e: { id: string; template: string }): void;
+  onPanWithDirection?(e: { direction: string }): void;
+  onPanBeganWithDirection?(e: { direction: string }): void;
+  onPanEndedWithDirection?(e: { direction: string }): void;
+  onSelectedPreviewForTrip?(e: { tripId: string; routeIndex: number }): void;
+  onDidCancelNavigation?(): void;
+  onStartedTrip?(e: { tripId: string; routeIndex: number }): void;
+}
+
+/**
+ * The Map Template is a control layer that appears as an overlay over the base view and allows you to present user controls.
+ *
+ * The control layer consists of a navigation bar and map buttons. By default, the navigation bar appears when the user interacts with the app, and disappears after a period of inactivity.
+ *
+ * The navigation bar includes up to two leading buttons and two trailing buttons. You can customize the appearance of these buttons with icons or text.
+ *
+ * The control layer may also include up to four map buttons. The map buttons are always shown as icons.
+ *
+ * Navigation apps enter panning mode, zoom in or out, and perform other functions by responding to user actions on these buttons.
+ */
+export class MapTemplate extends Template<MapTemplateConfig> {
+  public get type(): string {
+    return 'map';
+  }
+
+  get eventMap() {
+    return {
+      alertActionPressed: 'onAlertActionPressed',
+      mapButtonPressed: 'onMapButtonPressed',
+      panWithDirection: 'onPanWithDirection',
+      panBeganWithDirection: 'onPanBeganWithDirection',
+      panEndedWithDirection: 'onPanEndedWithDirection',
+      selectedPreviewForTrip: 'onSelectedPreviewForTrip',
+      didCancelNavigation: 'onDidCancelNavigation',
+      startedTrip: 'onStartedTrip',
+    };
+  }
+
+  constructor(public config: MapTemplateConfig) {
+    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,
+    );
+  }
+
+  /**
+   * Begins guidance for a trip.
+   *
+   * Keep a reference to the navigation session to perform guidance updates.
+   * @param trip Trip class instance
+   */
+  public async startNavigationSession(trip: Trip): Promise<NavigationSession> {
+    const res = await CarPlay.bridge.startNavigationSession(this.id, trip.id);
+    return new NavigationSession(res.navigationSessionId, trip, this);
+  }
+
+  public updateTravelEstimates(
+    trip: Trip,
+    travelEstimates: TravelEstimates,
+    timeRemainingColor: TimeRemainingColor = 0,
+  ) {
+    if (!travelEstimates.distanceUnits) {
+      travelEstimates.distanceUnits = 'kilometers';
+    }
+    CarPlay.bridge.updateTravelEstimatesForTrip(
+      this.id,
+      trip.id,
+      travelEstimates,
+      timeRemainingColor,
+    );
+  }
+  /**
+   * Update MapTemplate configuration
+   */
+  public updateConfig(config: MapTemplateConfig) {
+    this.config = config;
+    CarPlay.bridge.updateMapTemplateConfig(this.id, this.parseConfig(config));
+  }
+
+  public updateMapButtons(mapButtons: MapButton[]) {
+    this.config.mapButtons = mapButtons;
+    CarPlay.bridge.updateMapTemplateMapButtons(this.id, this.parseConfig(mapButtons));
+  }
+
+  /**
+   * Hides the display of trip previews.
+   */
+  public hideTripPreviews() {
+    CarPlay.bridge.hideTripPreviews(this.id);
+  }
+
+  public showTripPreviews(tripPreviews: Trip[], textConfiguration: TextConfiguration = {}) {
+    CarPlay.bridge.showTripPreviews(
+      this.id,
+      tripPreviews.map(trip => trip.id),
+      textConfiguration,
+    );
+  }
+
+  public showRouteChoicesPreviewForTrip(trip: Trip, textConfiguration: TextConfiguration = {}) {
+    CarPlay.bridge.showRouteChoicesPreviewForTrip(this.id, trip.id, textConfiguration);
+  }
+
+  public presentNavigationAlert(config: NavigationAlert, animated = true) {
+    CarPlay.bridge.presentNavigationAlert(this.id, config, animated);
+  }
+
+  public dismissNavigationAlert(animated = true) {
+    CarPlay.bridge.dismissNavigationAlert(this.id, animated);
+  }
+
+  /**
+   * Shows the panning interface over the map.
+   *
+   * Calling this method while displaying the panning interface has no effect.
+   *
+   * While showing the panning interface, the system hides all map buttons. The system doesn't provide a button to dismiss the panning interface. Instead, you must provide a map button in the navigation bar that the user taps to dismiss the panning interface.
+   * @param animated A Boolean value that determines whether to animate the panning interface.
+   */
+  public showPanningInterface(animated = false) {
+    CarPlay.bridge.showPanningInterface(this.id, animated);
+  }
+
+  /**
+   * Dismisses the panning interface.
+   *
+   * When dismissing the panning interface, the system shows the previously hidden map buttons.
+   * @param animated A Boolean value that determines whether to animate the dismissal of the panning interface.
+   */
+  public dismissPanningInterface(animated = false) {
+    CarPlay.bridge.dismissPanningInterface(this.id, animated);
+  }
+}

package/src/templates/NowPlayingTemplate.ts

@@ -0,0 +1,31 @@
+import { Template, TemplateConfig } from './Template';
+
+export type NowPlayingButton = {
+  id: string;
+  imageName: string;
+  selected: boolean;
+};
+
+export interface NowPlayingTemplateConfig extends TemplateConfig {
+  albumArtistButtonEnabled?: boolean;
+  upNextButtonTitle?: string;
+  upNextButtonEnabled?: boolean;
+  onAlbumArtistButtonPressed?(): void;
+  onUpNextButtonPressed?(): void;
+  onButtonPressed?(e: { id: string; templateId: string }): void;
+  buttons?: NowPlayingButton[];
+}
+
+export class NowPlayingTemplate extends Template<NowPlayingTemplateConfig> {
+  public get type(): string {
+    return 'nowplaying';
+  }
+
+  get eventMap() {
+    return {
+      albumArtistButtonPressed: 'onAlbumArtistButtonPressed',
+      upNextButtonPressed: 'onUpNextButtonPressed',
+      buttonPressed: 'onButtonPressed',
+    };
+  }
+}

package/src/templates/PointOfInterestTemplate.ts

@@ -0,0 +1,40 @@
+import { Template, TemplateConfig } from './Template';
+
+export interface PointOfInterestItem {
+  id: string;
+  location: {
+    latitude: number;
+    longitude: number;
+  };
+  title: string;
+  subtitle?: string;
+  summary?: string;
+  detailTitle?: string;
+  detailSubtitle?: string;
+  detailSummary?: string;
+}
+
+export interface PointOfInterestTemplateConfig extends TemplateConfig {
+  title: string;
+  items: PointOfInterestItem[];
+  onPointOfInterestSelect?(e: PointOfInterestItem): void;
+  onChangeMapRegion(e: {
+    latitude: number;
+    longitude: number;
+    latitudeDelta: number;
+    longitudeDelta: number;
+  }): void;
+}
+
+export class PointOfInterestTemplate extends Template<PointOfInterestTemplateConfig> {
+  public get type(): string {
+    return 'poi';
+  }
+
+  get eventMap() {
+    return {
+      didSelectPointOfInterest: 'onPointOfInterestSelect',
+      didChangeMapRegion: 'onChangeMapRegion',
+    };
+  }
+}

package/src/templates/SearchTemplate.ts

@@ -0,0 +1,70 @@
+import { CarPlay } from '../CarPlay';
+import { ListItem } from '../interfaces/ListItem';
+import { BaseEvent, Template, TemplateConfig } from './Template';
+import { Image, Platform } from 'react-native';
+
+export interface SearchTemplateConfig extends TemplateConfig {
+  /**
+   * Fired when search input is changed.
+   * Must return list of items to show.
+   * @param query Search query
+   */
+  onSearch?(query: string): Promise<ListItem[]>;
+  /**
+   * Fired when result item is selected.
+   * Spinner shows by default.
+   * When the returned promise is resolved the spinner will hide.
+   * @param item Object with the selected index
+   */
+  onItemSelect?(item: { index: number }): Promise<void>;
+  /**
+   * Fired when search button is pressed
+   */
+  onSearchButtonPressed?(e: BaseEvent): void;
+}
+
+export class SearchTemplate extends Template<SearchTemplateConfig> {
+  public get type(): string {
+    return 'search';
+  }
+
+  get eventMap() {
+    return {
+      searchButtonPressed: 'onSearchButtonPressed',
+    };
+  }
+
+  constructor(public config: SearchTemplateConfig) {
+    // parse out any images in the results
+
+    super(config);
+
+    CarPlay.emitter.addListener(
+      'updatedSearchText',
+      (e: { searchText: string; templateId: string }) => {
+        if (config.onSearch && e.templateId === this.id) {
+          void Promise.resolve(config.onSearch(e.searchText)).then((result = []) => {
+            if (Platform.OS === 'ios') {
+              const parsedResults = result.map(item => ({
+                ...item,
+                image: item.image ? Image.resolveAssetSource(item.image) : undefined,
+              }));
+              CarPlay.bridge.reactToUpdatedSearchText(parsedResults);
+            }
+          });
+        }
+      },
+    );
+
+    CarPlay.emitter.addListener(
+      'selectedResult',
+      (e: { templateId: string; index: number; id?: string }) => {
+        if (config.onItemSelect && e.templateId === this.id) {
+          void Promise.resolve(config.onItemSelect(e)).then(
+            () => Platform.OS === 'ios' && CarPlay.bridge.reactToSelectedResult(true),
+          );
+        }
+      },
+    );
+  }
+}

package/src/templates/TabBarTemplate.ts

@@ -0,0 +1,56 @@
+import { CarPlay } from '../CarPlay';
+import { GridTemplate } from './GridTemplate';
+import { InformationTemplate } from './InformationTemplate';
+import { ListTemplate } from './ListTemplate';
+import { PointOfInterestTemplate } from './PointOfInterestTemplate';
+import { Template, TemplateConfig } from './Template';
+
+export type TabBarTemplates =
+  | ListTemplate
+  | GridTemplate
+  | InformationTemplate
+  | PointOfInterestTemplate;
+
+export interface TabBarTemplateConfig extends TemplateConfig {
+  /**
+   * The title displayed in the navigation bar while the tab bar template is visible.
+   */
+  title?: string;
+  /**
+   * The templates to show as tabs.
+   */
+  templates: TabBarTemplates[];
+
+  onTemplateSelect(
+    template: TabBarTemplates | undefined,
+    e: { templateId: string; selectedTemplateId: string },
+  ): void;
+}
+
+/**/
+export class TabBarTemplate extends Template<TabBarTemplateConfig> {
+  public get type(): string {
+    return 'tabbar';
+  }
+
+  constructor(public config: TabBarTemplateConfig) {
+    super(config);
+
+    CarPlay.emitter.addListener(
+      'didSelectTemplate',
+      (e: { templateId: string; selectedTemplateId: string }) => {
+        if (config.onTemplateSelect && e.templateId === this.id) {
+          config.onTemplateSelect(
+            config.templates.find(tpl => tpl.id === e.selectedTemplateId),
+            e,
+          );
+        }
+      },
+    );
+  }
+
+  public updateTemplates = (config: TabBarTemplateConfig) => {
+    this.config = config;
+    return CarPlay.bridge.updateTabBarTemplates(this.id, this.parseConfig(config));
+  };
+}