@iternio/react-native-auto-play 0.5.14-beta.1 → 0.6.0

package/src/templates/MessageTemplate.ts

@@ -5,7 +5,7 @@ import type {
   AutoImage,
   BaseMapTemplateConfig,
   CustomActionButtonAndroid,
-  HeaderActionsAndroid,
+  HeaderActions,
   TextButton,
 } from '..';
 import { HybridAutoPlay } from '../hybrid/HybridAutoPlay';
@@ -14,6 +14,7 @@ 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 { PanelActionsIos, PanelHeaderActions } from './MapTemplate';
 import type { NitroBaseMapTemplateConfig, NitroTemplateConfig, TemplateConfig } from './Template';
 
 const HybridMessageTemplate =
@@ -23,6 +24,7 @@ export interface NitroMessageTemplateConfig extends TemplateConfig {
   headerActions?: Array<NitroAction>;
   /**
    * @namespace Android title shown on header
+   * @namespace iOS title shown when mapConfig is set, otherwise it isn't supported
    */
   title?: AutoText;
   message: AutoText;
@@ -31,41 +33,86 @@ export interface NitroMessageTemplateConfig extends TemplateConfig {
   mapConfig?: NitroBaseMapTemplateConfig;
 }
 
-export type MessageTemplateConfig = Omit<
+type MessageActionsAndroid<T> =
+  | [CustomActionButtonAndroid<T>]
+  | [CustomActionButtonAndroid<T>, CustomActionButtonAndroid<T>];
+
+type MessageTemplateBaseConfig = Omit<
   NitroMessageTemplateConfig,
   'headerActions' | 'image' | 'mapConfig' | 'actions'
 > & {
   /**
    * action buttons, usually at the top right on Android
-   * @namespace Android
+   * @namespace iOS `ios` only takes effect once this renders as a CPMapPanel (`mapConfig` set,
+   * iOS 27+) and is applied to the root map template's nav bar — without `mapConfig` (or below
+   * iOS 27, where `mapConfig` is a no-op) this template is a full-screen `CPAlertTemplate`, which
+   * has no nav bar at all, so `ios` is silently unused there.
    */
-  headerActions?: HeaderActionsAndroid<MessageTemplate>;
+  headerActions?: HeaderActions<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>];
-  };
 };
 
+/**
+ * `actions`/`mapConfig` are a discriminated union — `mapConfig` restricts `actions.ios` to at
+ * most one `TextButton` plus one icon-only `ImageButton` (a `CPMapPanel` can't show more), vs. up
+ * to three `TextButton`s otherwise. If your `mapConfig` value comes from a variable/prop rather
+ * than an inline literal, TS can't narrow which branch applies — assign it to a local `const` and
+ * branch with `if (mapConfig) { ... } else { ... }` into two separate constructor calls instead
+ * of passing it straight through to one.
+ */
+export type MessageTemplateConfig = MessageTemplateBaseConfig &
+  (
+    | {
+        mapConfig?: undefined;
+
+        /**
+         * @namespace Android up to 2 buttons of type TextButton, TextAndImageButton or ImageButton
+         * @namespace iOS - up to 3 buttons of type TextButton
+         */
+        actions?: {
+          android?: MessageActionsAndroid<MessageTemplate>;
+          ios?:
+            | [
+                TextButton<MessageTemplate>,
+                TextButton<MessageTemplate>,
+                TextButton<MessageTemplate>,
+              ]
+            | [TextButton<MessageTemplate>, TextButton<MessageTemplate>]
+            | [TextButton<MessageTemplate>];
+        };
+      }
+    | {
+        /**
+         * 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 - uses MapWithContentTemplate
+         * @namespace iOS - renders as a CPMapPanel on the current root map template (iOS 27+),
+         * trading the usual full-screen modal alert presentation for panel content;
+         * `headerActions` here is Android-only — on iOS this template's own `headerActions` are
+         * applied to the root map template's nav bar instead, since CarPlay has no separate
+         * header for the map behind a panel.
+         */
+        mapConfig: Omit<BaseMapTemplateConfig<MessageTemplate>, 'headerActions'> & {
+          headerActions?: PanelHeaderActions<MessageTemplate>;
+        };
+
+        /**
+         * @namespace Android up to 2 buttons of type TextButton, TextAndImageButton or ImageButton
+         * @namespace iOS - the panel can only show one TextButton plus one optional icon-only
+         * ImageButton, see PanelActionsIos
+         */
+        actions?: {
+          android?: MessageActionsAndroid<MessageTemplate>;
+          ios?: PanelActionsIos<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.
@@ -86,7 +133,7 @@ export class MessageTemplate {
     const nitroConfig: NitroMessageTemplateConfig & NitroTemplateConfig = {
       ...rest,
       id: this.id,
-      headerActions: NitroActionUtil.convert(this.template, { android: headerActions }),
+      headerActions: NitroActionUtil.convert(this.template, headerActions),
       image: NitroImageUtil.convert(image),
       actions: platformActions,
       mapConfig: mapConfig

package/src/utils/NitroOptionsPanel.ts

@@ -0,0 +1,218 @@
+import type { ImageButton, TextButton } from '../types/Button';
+import type { AutoImage } from '../types/Image';
+import type { AutoText, Distance } from '../types/Text';
+import type { DurationWithTimeZone } from '../types/Trip';
+import { type NitroAction, NitroActionUtil } from './NitroAction';
+import { type GridButton, type NitroGridButton, NitroGridUtil } from './NitroGrid';
+import { type NitroImage, NitroImageUtil } from './NitroImage';
+import {
+  type DefaultRow,
+  type MultiSection,
+  type NitroSection,
+  NitroSectionUtil,
+  type RadioRow,
+  type TextRow,
+  type ToggleRow,
+  type WaypointCoordinate,
+  type WaypointRow,
+} from './NitroSection';
+
+export type OptionsPanelGridSection<T> = {
+  type: 'grid';
+  title?: string;
+  buttons: Array<GridButton<T>>;
+};
+
+export type ChargingConnector =
+  | 'ccs1'
+  | 'ccs2'
+  | 'j1772'
+  | 'chaDeMo'
+  | 'mennekes'
+  | 'gbtDC'
+  | 'gbtAC'
+  | 'nacsDC'
+  | 'nacsAC';
+
+/**
+ * one outlet (`CPChargingStationConnection`) on a charging station.
+ */
+export type ChargerOutlet<T> = {
+  connector: ChargingConnector;
+  voltage: number;
+  /** converted to megawatts on the native side above 1000 kW */
+  powerKw: number;
+  onPress?: (template: T) => void;
+};
+
+/**
+ * the charging station's own location, shown as an additional `CPMapTemplateWaypoint` item in
+ * the charger section, alongside its outlets.
+ */
+export type ChargerLocation<T> = {
+  /**
+   * the item's own label — distinct from the section's `title`, which is already shown as the
+   * section header, so this defaults to blank rather than repeating it.
+   */
+  name?: string;
+  /** newline-separated address lines, most-preferred first */
+  address?: string;
+  coordinate: WaypointCoordinate;
+  travelEstimates: {
+    distance: Distance;
+    duration: DurationWithTimeZone;
+    /**
+     * by default travel estimates are not shown
+     * setting this to true add another row showing CPTravelEstimates
+     */
+    visible?: boolean;
+  };
+  image?: AutoImage;
+  onPress?: (template: T) => void;
+};
+
+/**
+ * charger section having n-ChargerOutlet
+ */
+export type OptionsPanelChargerSection<T> = {
+  type: 'charger';
+  title?: string;
+  outlets: Array<ChargerOutlet<T>>;
+  location?: ChargerLocation<T>;
+};
+
+export type OptionsPanelListSection<T> = {
+  type: 'list';
+  title?: string;
+  items: Array<DefaultRow<T> | ToggleRow<T> | TextRow | WaypointRow<T>> | Array<RadioRow<T>>;
+};
+
+export type OptionsPanelSection<T> =
+  | OptionsPanelListSection<T>
+  | OptionsPanelGridSection<T>
+  | OptionsPanelChargerSection<T>;
+
+export type OptionsPanelConfig<T> = {
+  title?: AutoText;
+  sections: Array<OptionsPanelSection<T>>;
+  actions?: [TextButton<T>] | [TextButton<T>, ImageButton<T>];
+};
+
+export type NitroOptionsPanelGridSection = {
+  title?: string;
+  buttons: Array<NitroGridButton>;
+};
+
+export type NitroChargerOutlet = {
+  connector: ChargingConnector;
+  voltage: number;
+  powerKw: number;
+  onPress?: () => void;
+};
+
+export type NitroChargerLocation = {
+  name?: string;
+  address?: string;
+  coordinate: WaypointCoordinate;
+  distance: Distance;
+  duration: DurationWithTimeZone;
+  visible?: boolean;
+  image?: NitroImage;
+  onPress?: () => void;
+};
+
+export type NitroOptionsPanelChargerSection = {
+  title?: string;
+  outlets: Array<NitroChargerOutlet>;
+  location?: NitroChargerLocation;
+};
+
+export type NitroOptionsPanelSection =
+  | NitroSection
+  | NitroOptionsPanelGridSection
+  | NitroOptionsPanelChargerSection;
+
+export type NitroOptionsPanelConfig = {
+  title?: AutoText;
+  sections: Array<NitroOptionsPanelSection>;
+  actions?: Array<NitroAction>;
+};
+
+const isRadioSection = <T>(
+  items: OptionsPanelListSection<T>['items']
+): items is Array<RadioRow<T>> => {
+  return items.length > 0 && items.every((item) => item.type === 'radio');
+};
+
+const convertSection = <T>(
+  template: T,
+  section: OptionsPanelSection<T>
+): NitroOptionsPanelSection => {
+  if (section.type === 'grid') {
+    return {
+      title: section.title,
+      buttons: NitroGridUtil.convert(template, section.buttons),
+    };
+  }
+
+  if (section.type === 'charger') {
+    const { location } = section;
+
+    return {
+      title: section.title,
+      outlets: section.outlets.map((outlet) => ({
+        connector: outlet.connector,
+        voltage: outlet.voltage,
+        powerKw: outlet.powerKw,
+        onPress: outlet.onPress ? () => outlet.onPress?.(template) : undefined,
+      })),
+      location: location
+        ? {
+            name: location.name,
+            address: location.address,
+            coordinate: location.coordinate,
+            distance: location.travelEstimates.distance,
+            duration: location.travelEstimates.duration,
+            visible: location.travelEstimates.visible,
+            image: NitroImageUtil.convert(location.image),
+            onPress: location.onPress ? () => location.onPress?.(template) : undefined,
+          }
+        : undefined,
+    };
+  }
+
+  const { items, title = '' } = section;
+
+  const multiSection: MultiSection<T> = isRadioSection(items)
+    ? { type: 'radio', title, items }
+    : {
+        type: 'default',
+        title,
+        items,
+      };
+
+  const [nitroSection] = NitroSectionUtil.convert(template, [multiSection]) ?? [];
+
+  if (nitroSection == null) {
+    throw new Error('converting sections failed');
+  }
+
+  return nitroSection;
+};
+
+const convert = <T>(
+  template: T,
+  config?: OptionsPanelConfig<T>
+): NitroOptionsPanelConfig | undefined => {
+  if (config == null) {
+    return undefined;
+  }
+
+  return {
+    title: config.title,
+    sections: config.sections.map((section) => convertSection(template, section)),
+    actions: NitroActionUtil.convert(template, config.actions),
+  };
+};
+
+export const NitroOptionsPanelUtil = { convert };

package/src/utils/NitroSection.ts

@@ -1,7 +1,95 @@
-import type { DefaultRow, RadioRow, Section, TextRow, ToggleRow } from '../templates/ListTemplate';
-import type { AutoText } from '../types/Text';
+import type { ListImageType } from '../templates/ListTemplate';
+import type { AutoImage } from '../types/Image';
+import { type AutoText, type Distance, TextPlaceholders } from '../types/Text';
+import type { DurationWithTimeZone } from '../types/Trip';
 import { type NitroImage, NitroImageUtil } from './NitroImage';
 
+type BaseRow = {
+  title: AutoText;
+  enabled?: boolean;
+  image?: AutoImage;
+  /** @namespace Android */
+  imageType?: ListImageType;
+};
+
+export type DefaultRow<T> = BaseRow & {
+  type: 'default';
+  /**
+   * adds a chevron at the end of the row
+   */
+  browsable?: boolean;
+  onPress: (template: T) => void;
+  detailedText?: AutoText;
+};
+
+export type ToggleRow<T> = BaseRow & {
+  type: 'toggle';
+  checked: boolean;
+  onPress: (template: T, checked: boolean) => void;
+};
+
+export type RadioRow<T> = BaseRow & {
+  type: 'radio';
+  onPress: (template: T) => void;
+  selected?: boolean;
+};
+
+export type TextRow = BaseRow & {
+  type: 'text';
+  detailedText?: AutoText;
+};
+
+export type WaypointCoordinate = {
+  latitude: number;
+  longitude: number;
+  altitude?: number;
+};
+
+/**
+ * a point of interest, e.g. a charger's location. Renders as a `CPMapTemplateWaypoint` item
+ * (showing `title` as the name, `address` as the address, and the travel estimate for reaching
+ * it) when part of a `CPMapPanel` (iOS 27+); falls back to a plain row using `title`/`address`
+ * as the detail line everywhere else (including Android, which has no equivalent concept).
+ */
+export type WaypointRow<T> = BaseRow & {
+  type: 'waypoint';
+  /**
+   * add one of {@link TextPlaceholders} to add travelEstimates
+   * prefer travelEstimates.visible over that on iOS 27+
+   */
+  address?: string;
+  coordinate: WaypointCoordinate;
+  travelEstimates: {
+    distance: Distance;
+    duration: DurationWithTimeZone;
+    /**
+     * by default travel estimates are not shown
+     * setting this to true adds another row showing CPTravelEstimates
+     * @namespace iOS 27+
+     */
+    visible?: boolean;
+  };
+  onPress?: (template: T) => void;
+};
+
+export type MultiSection<T> =
+  | {
+      type: 'default';
+      title: string;
+      items: Array<DefaultRow<T> | ToggleRow<T> | TextRow | WaypointRow<T>>;
+    }
+  | {
+      type: 'radio';
+      title: string;
+      items: Array<RadioRow<T>>;
+    };
+
+export type SingleSection<T> = {
+  [K in MultiSection<T> as K['type']]: Omit<K, 'title' | 'detailedText'>;
+}[MultiSection<T>['type']];
+
+export type Section<T> = Array<MultiSection<T>> | SingleSection<T>;
+
 type NitroSectionType = 'default' | 'radio';
 
 export type NitroRow = {
@@ -10,9 +98,20 @@ export type NitroRow = {
   browsable?: boolean;
   enabled: boolean;
   image?: NitroImage;
+  imageType?: ListImageType;
   checked?: boolean;
   onPress?: (checked?: boolean) => void;
   selected?: boolean;
+  coordinate?: WaypointCoordinate;
+  distance?: Distance;
+  duration?: DurationWithTimeZone;
+  /**
+   * only meaningful in panel context (iOS 27+, `mapConfig` set) — adds a sibling `CPMapPanelItem`
+   * showing `distance`/`duration` as a native `CPTravelEstimates` row. Non-panel/Android rendering
+   * relies purely on `title`/`detailedText` opting in via `TextPlaceholders` instead.
+   */
+  travelEstimatesVisible?: boolean;
+  address?: string;
 };
 
 export type NitroSection = {
@@ -63,13 +162,63 @@ const convert = <T>(template: T, sections?: Section<T>): Array<NitroSection> | u
   ];
 };
 
+/**
+ * `AutoText.distance`/`.duration` only take effect if `text` actually uses the matching
+ * `TextPlaceholders` marker — populate whichever of those the text references, leaving the rest
+ * of `text` untouched, so a title/address that doesn't opt in via a placeholder is unaffected.
+ */
+const withTravelEstimates = (
+  text: AutoText,
+  distance: Distance,
+  durationSeconds: number
+): AutoText => {
+  const hasDistance = text.text.includes(TextPlaceholders.Distance);
+  const hasDuration = text.text.includes(TextPlaceholders.Duration);
+
+  if (!hasDistance && !hasDuration) {
+    return text;
+  }
+
+  return {
+    ...text,
+    distance: hasDistance ? distance : text.distance,
+    duration: hasDuration ? durationSeconds : text.duration,
+  };
+};
+
 const convertRow = <T>(
   template: T,
-  item: DefaultRow<T> | RadioRow<T> | ToggleRow<T> | TextRow
+  item: DefaultRow<T> | RadioRow<T> | ToggleRow<T> | TextRow | WaypointRow<T>
 ): NitroRow => {
-  const { title, type, enabled = true, image } = item;
+  const { type, enabled = true, image, imageType } = item;
+
+  // `WaypointRow` has no `detailedText` of its own — `address` doubles as the detail line
+  // whenever this falls back to a plain row (non-panel context, Android).
+  let title = item.title;
+  let detailedText =
+    item.type === 'waypoint'
+      ? item.address != null
+        ? { text: item.address }
+        : undefined
+      : 'detailedText' in item
+        ? item.detailedText
+        : undefined;
+
+  // Opt-in only: a title/address using `{distance}`/`{duration}` gets those values filled in,
+  // via the same substitution `AutoText` already does everywhere else — no separate "estimate"
+  // UI element needed for a row embedded in a list alongside other rows. Deliberately NOT gated
+  // on `travelEstimates.visible` — that flag only controls the panel-only sibling
+  // `CPTravelEstimates` item (see `Parser.swift`'s `travelEstimatesVisible` check), which has no
+  // bearing on the non-panel/Android fallback text this feeds; a placeholder in the text is
+  // already its own explicit opt-in regardless of `visible`.
+  if (item.type === 'waypoint') {
+    const { distance, duration } = item.travelEstimates;
+    title = withTravelEstimates(title, distance, duration.seconds);
+    if (detailedText != null) {
+      detailedText = withTravelEstimates(detailedText, distance, duration.seconds);
+    }
+  }
 
-  const detailedText = 'detailedText' in item ? item.detailedText : undefined;
   const selected = type === 'radio' ? (item.selected ?? false) : undefined;
 
   const onTogglePress = item.type === 'toggle' ? item.onPress : undefined;
@@ -93,10 +242,16 @@ const convertRow = <T>(
     detailedText,
     enabled,
     image: NitroImageUtil.convert(image),
+    imageType,
     title,
     checked: type === 'toggle' ? item.checked : undefined,
     onPress,
     selected,
+    coordinate: item.type === 'waypoint' ? item.coordinate : undefined,
+    distance: item.type === 'waypoint' ? item.travelEstimates.distance : undefined,
+    duration: item.type === 'waypoint' ? item.travelEstimates.duration : undefined,
+    travelEstimatesVisible: item.type === 'waypoint' ? item.travelEstimates.visible : undefined,
+    address: item.type === 'waypoint' ? item.address : undefined,
   };
 };