@iternio/react-native-auto-play 0.3.11 → 0.4.0

package/src/types/Image.ts

@@ -1,32 +1,81 @@
 import type { ImageSourcePropType } from 'react-native';
 import type { ThemedColor } from '../utils/NitroColor';
-import type { GlyphName } from './Glyphmap';
+
+/**
+ * Augment this interface in your app to get type-safe glyph name autocompletion.
+ *
+ * @example
+ * ```ts
+ * // autoplay-glyphs.d.ts
+ * import type { GlyphName } from './assets/symbolFont/Glyphmap';
+ * declare module '@iternio/react-native-auto-play' {
+ *   interface AutoPlayGlyphMap extends Record<GlyphName, number> {}
+ * }
+ * ```
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: must be an interface for declaration merging
+export interface AutoPlayGlyphMap {}
+
+/** Resolves to the augmented glyph name union, or falls back to `string` when not augmented. */
+export type GlyphMapKey = keyof AutoPlayGlyphMap extends never
+  ? string
+  : Extract<keyof AutoPlayGlyphMap, string>;
+
+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.
+   * Might not get applied everywhere like MapTemplate buttons on Android.
+   */
+  color?: ThemedColor | string;
+
+  /**
+   * Sets the background color for dark and light mode or a single color for both
+   * Defaults to transparent if not specified.
+   */
+  backgroundColor?: ThemedColor | string;
+  fontScale?: number;
+};
+
+/** Glyph by name — looked up in the glyph map registered via {@link setIconFont}. */
+export type AutoGlyphByName = GlyphStyleFields & {
+  type: 'glyph';
+  /** Key in the glyph map passed to `setIconFont`. */
+  name: GlyphMapKey;
+  /** Optional override — if set, used instead of the map lookup. */
+  codepoint?: number;
+};
+
+/** Glyph by raw Unicode code point. */
+export type AutoGlyphByCodepoint = GlyphStyleFields & {
+  type: 'glyph';
+  codepoint: number;
+};
+
+export type AutoGlyph = AutoGlyphByName | AutoGlyphByCodepoint;
 
 export type AutoImage =
+  | AutoGlyph
   | {
-      name: GlyphName;
-
+      image: ImageSourcePropType;
       /**
-       * 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.
+       * 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.
        */
       color?: ThemedColor | string;
-
-      /**
-       * Sets the background color for dark and light mode or a single color for both
-       * Defaults to transparent if not specified.
-       */
-      backgroundColor?: ThemedColor | string;
-      fontScale?: number;
-      type: 'glyph';
+      type: 'asset';
     }
   | {
-      image: ImageSourcePropType;
+      /** HTTPS URL to a remote image. HTTP is not supported (blocked by App Transport Security). */
+      uri: string;
       /**
        * 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.
        */
       color?: ThemedColor | string;
-      type: 'asset';
+      /**
+       * Network timeout in milliseconds before the remote fetch is abandoned and `null` is returned.
+       * Defaults to 500ms when not specified.
+       */
+      timeoutMs?: number;
+      type: 'remote';
     };

package/src/types/Maneuver.ts

@@ -1,6 +1,6 @@
 import type { ImageSourcePropType } from 'react-native';
 import type { ThemedColor } from '../utils/NitroColor';
-import type { GlyphName } from './Glyphmap';
+import type { AutoGlyphByCodepoint, AutoGlyphByName } from './Image';
 import type { TravelEstimates } from './Trip';
 
 export enum ManeuverType {
@@ -174,15 +174,8 @@ export interface PreferredLane extends Lane {
 }
 
 export type ManeuverImage =
-  | {
-      name: GlyphName;
-      /**
-       * make sure to specify a color with a proper contrast ratio to cardBackgroundColor otherwise it might not get applied
-       * defaults to white/black for dark/light mode
-       */
-      color?: ThemedColor | string;
-      type: 'glyph';
-    }
+  | Pick<AutoGlyphByName, 'type' | 'name' | 'codepoint' | 'color'>
+  | Pick<AutoGlyphByCodepoint, 'type' | 'codepoint' | 'color'>
   | {
       image: ImageSourcePropType;
       /**

package/src/utils/NitroImage.ts

@@ -1,8 +1,69 @@
 import { Image, type ImageResolvedAssetSource } from 'react-native';
-import { glyphMap } from '../types/Glyphmap';
 import type { AutoImage } from '../types/Image';
 import { type NitroColor, NitroColorUtil } from './NitroColor';
 
+let _iconFont: string | undefined;
+let _glyphMap: Record<string, number> | undefined;
+
+/**
+ * Register the icon font and (optionally) a glyph map for name-based lookups.
+ * Must be called **once** before creating any templates. Subsequent calls are ignored.
+ *
+ * The font name maps directly to a native font asset:
+ * - **Android** — `res/font/<name>.ttf` (must be lowercase)
+ * - **iOS** — `<name>.ttf` in the app bundle (registered via CoreText automatically)
+ *
+ * For cross-platform compatibility use lowercase with underscores only.
+ *
+ * @param name  Native font asset name (without extension).
+ * @param glyphMap  Optional map of glyph names to Unicode code points.
+ *                  When provided, glyphs can use `{ type: 'glyph', name: 'icon_name' }`.
+ *
+ * @example
+ * ```ts
+ * import { glyphMap } from './assets/Glyphmap';
+ * setIconFont('material_symbols', glyphMap);
+ * ```
+ */
+export function setIconFont(name: string, glyphMap?: Record<string, number>): void {
+  if (_iconFont != null) {
+    return;
+  }
+  _iconFont = name;
+  _glyphMap = glyphMap;
+}
+
+function getIconFont(): string {
+  if (_iconFont == null) {
+    throw new Error(
+      'No icon font configured. Call setIconFont("your_font_name") before using glyph images.'
+    );
+  }
+  return _iconFont;
+}
+
+function resolveGlyph(image: Extract<AutoImage, { type: 'glyph' }>): number {
+  if ('name' in image && image.name !== undefined) {
+    if (image.codepoint !== undefined) {
+      return image.codepoint;
+    }
+    if (_glyphMap == null) {
+      throw new Error(
+        `Glyph name "${image.name}" used but no glyph map was provided to setIconFont().`
+      );
+    }
+    const cp = _glyphMap[image.name];
+    if (cp === undefined) {
+      throw new Error(`Glyph name "${image.name}" not found in the glyph map.`);
+    }
+    return cp;
+  }
+  if (image.codepoint !== undefined) {
+    return image.codepoint;
+  }
+  throw new Error('Glyph image must provide either `name` or `codepoint`.');
+}
+
 interface AssetImage extends ImageResolvedAssetSource {
   color?: NitroColor;
   packager_asset: boolean;
@@ -10,16 +71,22 @@ interface AssetImage extends ImageResolvedAssetSource {
 
 interface GlyphImage {
   glyph: number;
+  fontName: string;
   color: NitroColor;
   backgroundColor: NitroColor;
   fontScale?: number;
 }
 
+interface RemoteImage {
+  uri: string;
+  color?: NitroColor;
+  timeoutMs?: number;
+}
+
 /**
- * we need to map the ButtonImage.name from GlyphName to
- * the actual numeric value so we need a nitro specific type
+ * NitroModules-compatible image types passed to native.
  */
-export type NitroImage = GlyphImage | AssetImage;
+export type NitroImage = GlyphImage | AssetImage | RemoteImage;
 
 function convert(image: AutoImage): NitroImage;
 function convert(image?: AutoImage): NitroImage | undefined;
@@ -32,18 +99,26 @@ function convert(image?: AutoImage): NitroImage | undefined {
     const {
       color = { darkColor: 'white', lightColor: 'black' },
       fontScale,
-      name,
       backgroundColor = 'transparent',
     } = image;
 
     return {
-      glyph: glyphMap[name],
+      glyph: resolveGlyph(image),
+      fontName: getIconFont(),
       color: NitroColorUtil.convert(color),
       backgroundColor: NitroColorUtil.convert(backgroundColor),
       fontScale,
     };
   }
 
+  if (image.type === 'remote') {
+    return {
+      uri: image.uri,
+      color: NitroColorUtil.convert(image.color),
+      timeoutMs: image.timeoutMs,
+    };
+  }
+
   // Image.resolveAssetSource is pretty terrible, it will simply return whatever object you pass it is not a number [require(...)]
   // so the input allows all optional parameters which are returned as is even though
   // the return type claims to not have any optional parameters...