react-native-icon-switcher 0.0.0-stage → 0.1.0

package/src/NativeIconSwitcher.ts

@@ -0,0 +1,17 @@
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+export interface IconSwitcherConstants {
+  isSupported: boolean;
+  iconNames: string[];
+}
+
+export interface Spec extends TurboModule {
+  getConstants(): IconSwitcherConstants;
+  getCurrent(): Promise<string>;
+  // Plain `string` status keeps codegen parsers happy on older RN versions.
+  set(name: string): Promise<{ status: string }>;
+  applyPending(): Promise<{ status: string }>;
+}
+
+export default TurboModuleRegistry.get<Spec>('IconSwitcher');

package/src/config.ts

@@ -0,0 +1,15 @@
+import type { IconSwitcherConfig } from './types';
+
+export type {
+  AndroidAdaptiveIcon,
+  HexColor,
+  IconSource,
+  IconSpec,
+  IconSwitcherConfig,
+  ImagePath,
+  IosIconVariants,
+} from './types';
+
+export function defineIcons(cfg: IconSwitcherConfig): IconSwitcherConfig {
+  return cfg;
+}

package/src/errors.ts

@@ -0,0 +1,38 @@
+export type IconSwitcherErrorCode =
+  'unsupported' | 'unknown_icon' | 'os_rejected' | 'foreground';
+
+export class IconSwitcherError extends Error {
+  readonly code: IconSwitcherErrorCode;
+
+  constructor(code: IconSwitcherErrorCode, message?: string) {
+    super(message ?? code);
+    this.name = 'IconSwitcherError';
+    this.code = code;
+  }
+}
+
+const _NATIVE_TO_JS: Record<string, IconSwitcherErrorCode> = {
+  ERR_UNSUPPORTED: 'unsupported',
+  ERR_UNKNOWN_ICON: 'unknown_icon',
+  ERR_OS_REJECTED: 'os_rejected',
+  ERR_FOREGROUND: 'foreground',
+};
+
+export function mapNativeError(error: unknown): IconSwitcherError {
+  if (error instanceof IconSwitcherError) {
+    return error;
+  }
+  const code =
+    typeof error === 'object' && error !== null && 'code' in error
+      ? String((error as { code: unknown }).code)
+      : undefined;
+  const mapped = code ? _NATIVE_TO_JS[code] : undefined;
+  if (mapped) {
+    const message = error instanceof Error ? error.message : undefined;
+    return new IconSwitcherError(mapped, message);
+  }
+  return new IconSwitcherError(
+    'os_rejected',
+    error instanceof Error ? error.message : String(error)
+  );
+}

package/src/index.tsx

@@ -0,0 +1,78 @@
+import native from './NativeIconSwitcher';
+import { IconSwitcherError, mapNativeError } from './errors';
+import type { IconName } from './register';
+
+function _constants(): { isSupported: boolean; iconNames: string[] } {
+  if (native == null) {
+    return { isSupported: false, iconNames: [] };
+  }
+  return native.getConstants();
+}
+
+function _rejectUnsupported(): never {
+  throw new IconSwitcherError(
+    'unsupported',
+    'Alternate app icons are not supported'
+  );
+}
+
+function _assertKnownIcon(name: string): void {
+  if (!_constants().iconNames.includes(name)) {
+    throw new IconSwitcherError('unknown_icon', `Unknown icon: ${name}`);
+  }
+}
+
+const IconSwitcher = {
+  get isSupported(): boolean {
+    return _constants().isSupported;
+  },
+
+  list(): IconName[] {
+    return [..._constants().iconNames] as IconName[];
+  },
+
+  async getCurrent(): Promise<IconName> {
+    if (native == null) {
+      _rejectUnsupported();
+    }
+    try {
+      const current = await native.getCurrent();
+      return current as IconName;
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  },
+
+  async set(name: IconName): Promise<{ status: 'applied' | 'pending' }> {
+    if (!_constants().isSupported) {
+      _rejectUnsupported();
+    }
+    _assertKnownIcon(name as string);
+    try {
+      const result = await native!.set(name as string);
+      return result as { status: 'applied' | 'pending' };
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  },
+
+  async reset(): Promise<{ status: 'applied' | 'pending' }> {
+    return IconSwitcher.set('default' as IconName);
+  },
+
+  async applyPending(): Promise<{ status: 'applied' | 'none' }> {
+    if (native == null) {
+      _rejectUnsupported();
+    }
+    try {
+      const result = await native.applyPending();
+      return result as { status: 'applied' | 'none' };
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  },
+};
+
+export { IconSwitcher, IconSwitcherError };
+export type { IconName, Register } from './register';
+export default IconSwitcher;

package/src/register.ts

@@ -0,0 +1,4 @@
+/** Augment via `declare module 'react-native-icon-switcher' { interface Register { icons: ... } }`. */
+export interface Register {}
+
+export type IconName = Register extends { icons: infer T } ? T : string;

package/src/remote/index.ts

@@ -0,0 +1,142 @@
+import { AppState, Platform } from 'react-native';
+
+import IconSwitcher from '../index';
+import type { IconName } from '../register';
+
+const STORAGE_KEY_APPLIED = 'icon-switcher:lastApplied';
+const STORAGE_KEY_FAILED = 'icon-switcher:lastFailed';
+
+const DEFAULT_RETRY_AFTER_MS = 24 * 60 * 60 * 1000;
+
+export interface SyncIconStorage {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+}
+
+export interface SyncIconOptions {
+  fetchChoice: () => Promise<string | null | undefined>;
+  storage?: SyncIconStorage;
+  /** How long to skip re-applying a name after `set` failed. Default 24 h. */
+  retryAfterMs?: number;
+  onError?: (error: unknown) => void;
+}
+
+function _createMemoryStorage(): SyncIconStorage {
+  const data = new Map<string, string>();
+  return {
+    getItem: async (key) => data.get(key) ?? null,
+    setItem: async (key, value) => {
+      data.set(key, value);
+    },
+  };
+}
+
+function _encodeFailed(name: string): string {
+  return JSON.stringify({ name, at: Date.now() });
+}
+
+function _decodeFailed(
+  raw: string | null
+): { name: string; at: number } | null {
+  if (!raw || raw.length === 0) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw) as { name?: string; at?: number };
+    if (typeof parsed.name === 'string' && typeof parsed.at === 'number') {
+      return { name: parsed.name, at: parsed.at };
+    }
+  } catch {
+    // legacy: plain icon name with no timestamp — eligible for retry immediately
+    return { name: raw, at: 0 };
+  }
+  return null;
+}
+
+function _isFailedBlocked(
+  failed: { name: string; at: number } | null,
+  choice: string,
+  retryAfterMs: number
+): boolean {
+  if (!failed || failed.name !== choice) {
+    return false;
+  }
+  return Date.now() - failed.at < retryAfterMs;
+}
+
+/**
+ * Fetches the remote icon choice, validates it, and applies it via {@link IconSwitcher}.
+ * iOS: runs while the app is `active`. Android: calls `set` immediately (native may defer).
+ */
+export async function syncIcon(options: SyncIconOptions): Promise<() => void> {
+  const storage = options.storage ?? _createMemoryStorage();
+  const retryAfterMs = options.retryAfterMs ?? DEFAULT_RETRY_AFTER_MS;
+  const onError = options.onError;
+
+  let inFlight = false;
+
+  const run = async (): Promise<void> => {
+    if (inFlight) {
+      return;
+    }
+    inFlight = true;
+    try {
+      const choice = await options.fetchChoice();
+      if (choice == null || choice === '') {
+        return;
+      }
+      if (!IconSwitcher.list().includes(choice as IconName)) {
+        return;
+      }
+      if (!IconSwitcher.isSupported) {
+        return;
+      }
+
+      const failedRaw = await storage.getItem(STORAGE_KEY_FAILED);
+      const failed = _decodeFailed(failedRaw);
+      if (_isFailedBlocked(failed, choice, retryAfterMs)) {
+        return;
+      }
+
+      const current = await IconSwitcher.getCurrent();
+      if (choice === current) {
+        await storage.setItem(STORAGE_KEY_APPLIED, choice);
+        return;
+      }
+
+      try {
+        const result = await IconSwitcher.set(choice as IconName);
+        if (result.status === 'pending') {
+          return;
+        }
+        await storage.setItem(STORAGE_KEY_APPLIED, choice);
+        await storage.setItem(STORAGE_KEY_FAILED, '');
+      } catch {
+        await storage.setItem(STORAGE_KEY_FAILED, _encodeFailed(choice));
+      }
+    } catch (error) {
+      onError?.(error);
+    } finally {
+      inFlight = false;
+    }
+  };
+
+  const runWhenActive = (): void => {
+    if (AppState.currentState === 'active') {
+      void run();
+    }
+  };
+
+  if (Platform.OS === 'ios') {
+    const subscription = AppState.addEventListener('change', (state) => {
+      if (state === 'active') {
+        void run();
+      }
+    });
+    runWhenActive();
+    return () => subscription.remove();
+  }
+
+  await run();
+  return () => {};
+}

package/src/types.ts

@@ -0,0 +1,59 @@
+/** A path to a square PNG master, ideally 1024 px. Relative to the project root. */
+export type ImagePath = string;
+
+/** Hex colour, `#RGB` or `#RRGGBB`. */
+export type HexColor = string;
+
+export interface IosIconVariants {
+  light: ImagePath;
+  /** Phase 2. */
+  dark?: ImagePath;
+  /** Phase 2. */
+  tinted?: ImagePath;
+}
+
+export interface AndroidAdaptiveIcon {
+  foreground: ImagePath;
+  background: ImagePath | HexColor;
+  /** Phase 2. Android 13+ themed icons. */
+  monochrome?: ImagePath;
+}
+
+export interface IconSpec {
+  ios?: ImagePath | IosIconVariants;
+  android?: ImagePath | AndroidAdaptiveIcon;
+}
+
+/** A bare path means "same master for both platforms". */
+export type IconSource = ImagePath | IconSpec;
+
+export interface IconSwitcherConfig {
+  /** Primary icon. Omit on Expo to reuse `icon` / `android.adaptiveIcon`. */
+  default?: IconSource;
+  icons: Record<string, IconSource>;
+  ios?: {
+    /** Background colour that transparent pixels are flattened onto. Default `#FFFFFF`. */
+    flattenOn?: HexColor;
+  };
+  android?: {
+    /** Default `'background'`. */
+    applyOn?: 'background' | 'immediate';
+    /** Lower-cased `Build.BRAND` values where switching is disabled. Default `[]`. */
+    skipBrands?: string[];
+  };
+}
+
+/** Config after validation and defaults; every icon normalised to per-platform specs. */
+export interface ResolvedIcon {
+  name: string;
+  isDefault: boolean;
+  ios: IosIconVariants | null;
+  android: AndroidAdaptiveIcon | { legacy: ImagePath } | null;
+}
+
+export interface ResolvedConfig {
+  /** `default` first, then alternates in declaration order. */
+  icons: ResolvedIcon[];
+  ios: { flattenOn: HexColor };
+  android: { applyOn: 'background' | 'immediate'; skipBrands: string[] };
+}

package/src/typetests/icon-name.typetest.ts

@@ -0,0 +1,12 @@
+import 'react-native-icon-switcher';
+import IconSwitcher from 'react-native-icon-switcher';
+
+declare module 'react-native-icon-switcher' {
+  interface Register {
+    icons: 'default' | 'halloween' | 'midnight';
+  }
+}
+
+IconSwitcher.set('halloween');
+// @ts-expect-error icon name must come from Register.icons
+IconSwitcher.set('typo');

package/src/typetests/types-in-sync.typetest.ts

@@ -0,0 +1,16 @@
+// plugin/src/types.ts mirrors this package's config types because the plugin is compiled on its
+// own (rootDir: plugin/src). This fails typecheck the moment the two copies drift apart.
+import type * as Runtime from '../types';
+import type * as Plugin from '../../plugin/src/types';
+
+type Equal<X, Y> =
+  (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2
+    ? true
+    : false;
+
+export const typesInSync: [
+  Equal<Runtime.IconSource, Plugin.IconSource>,
+  Equal<Runtime.IconSwitcherConfig, Plugin.IconSwitcherConfig>,
+  Equal<Runtime.ResolvedIcon, Plugin.ResolvedIcon>,
+  Equal<Runtime.ResolvedConfig, Plugin.ResolvedConfig>,
+] = [true, true, true, true];