@chipmobilesdk/rn-ads 0.5.0 → 0.5.1

package/src/react/AdsProvider.tsx

@@ -1,57 +1,57 @@
-/**
- * Instance context (US1).
- *
- * Supplies one `AdsInstance` to the tree so `AdsBanner` and the hooks can reach
- * it without every screen threading it through props.
- *
- * The provider does not create the instance. The app does, and passes it in —
- * because `createAds` throws on a misconfigured catalog (FR-008, FR-012), and a
- * throw during render is a far worse place to discover that than a throw at
- * startup where the app can decide what to do about it.
- */
-
-import React, { createContext, useContext, useEffect, type ReactNode } from 'react';
-import { AppState, type AppStateStatus } from 'react-native';
-
-import type { AdsInstance } from '../core/adsInstance';
-
-const AdsContext = createContext<AdsInstance | null>(null);
-
-export interface AdsProviderProps {
-	readonly instance: AdsInstance;
-	/**
-	 * Whether the provider forwards foreground/background transitions to the
-	 * instance. On by default: FR-034's "never show while inactive" and
-	 * "re-evaluate a stale ad on return" both depend on the instance being told.
-	 * Turn it off only when the app already drives `setAppActive` itself.
-	 */
-	readonly trackAppState?: boolean;
-	readonly children: ReactNode;
-}
-
-export function AdsProvider({ instance, trackAppState = true, children }: AdsProviderProps) {
-	useEffect(() => {
-		if (!trackAppState) {
-			return;
-		}
-		const subscription = AppState.addEventListener('change', (status: AppStateStatus) => {
-			instance.setAppActive(status === 'active');
-		});
-		return () => {
-			subscription.remove();
-		};
-	}, [instance, trackAppState]);
-
-	return <AdsContext.Provider value={instance}>{children}</AdsContext.Provider>;
-}
-
-/**
- * Returns the instance, or null outside a provider.
- *
- * Null rather than a throw on purpose: a screen that renders a banner should
- * degrade to rendering nothing when ads are not wired up, not take the screen
- * down with it (NFR-005).
- */
-export function useAds(): AdsInstance | null {
-	return useContext(AdsContext);
-}
+/**
+ * Instance context (US1).
+ *
+ * Supplies one `AdsInstance` to the tree so `AdsBanner` and the hooks can reach
+ * it without every screen threading it through props.
+ *
+ * The provider does not create the instance. The app does, and passes it in —
+ * because `createAds` throws on a misconfigured catalog (FR-008, FR-012), and a
+ * throw during render is a far worse place to discover that than a throw at
+ * startup where the app can decide what to do about it.
+ */
+
+import React, { createContext, useContext, useEffect, type ReactNode } from 'react';
+import { AppState, type AppStateStatus } from 'react-native';
+
+import type { AdsInstance } from '../core/adsInstance';
+
+const AdsContext = createContext<AdsInstance | null>(null);
+
+export interface AdsProviderProps {
+	readonly instance: AdsInstance;
+	/**
+	 * Whether the provider forwards foreground/background transitions to the
+	 * instance. On by default: FR-034's "never show while inactive" and
+	 * "re-evaluate a stale ad on return" both depend on the instance being told.
+	 * Turn it off only when the app already drives `setAppActive` itself.
+	 */
+	readonly trackAppState?: boolean;
+	readonly children: ReactNode;
+}
+
+export function AdsProvider({ instance, trackAppState = true, children }: AdsProviderProps) {
+	useEffect(() => {
+		if (!trackAppState) {
+			return;
+		}
+		const subscription = AppState.addEventListener('change', (status: AppStateStatus) => {
+			instance.setAppActive(status === 'active');
+		});
+		return () => {
+			subscription.remove();
+		};
+	}, [instance, trackAppState]);
+
+	return <AdsContext.Provider value={instance}>{children}</AdsContext.Provider>;
+}
+
+/**
+ * Returns the instance, or null outside a provider.
+ *
+ * Null rather than a throw on purpose: a screen that renders a banner should
+ * degrade to rendering nothing when ads are not wired up, not take the screen
+ * down with it (NFR-005).
+ */
+export function useAds(): AdsInstance | null {
+	return useContext(AdsContext);
+}

package/src/react/hooks.ts

@@ -1,75 +1,75 @@
-/**
- * React bindings (US1, FR-027).
- *
- * Each hook subscribes to exactly what it reads. `usePlacementState` subscribes
- * to one placement rather than to the whole event stream, which is what keeps a
- * banner from re-rendering because an unrelated interstitial was clicked —
- * PERF-002's bounded re-render assertion depends on it.
- *
- * None of these hand back an ad object. A consumer queries and subscribes to
- * state; it never holds provider-owned memory (FR-027).
- */
-
-import { useEffect, useState } from 'react';
-
-import type { InitStatus, PlacementState } from '../config/types';
-import type { AdEventListener } from '../diagnostics/events';
-import { useAds } from './AdsProvider';
-
-/** Live state for one placement. `unavailable` outside a provider. */
-export function usePlacementState(placementKey: string): PlacementState {
-	const ads = useAds();
-	const [state, setState] = useState<PlacementState>(() =>
-		ads ? ads.getPlacementState(placementKey) : 'unavailable',
-	);
-
-	useEffect(() => {
-		if (!ads) {
-			setState('unavailable');
-			return;
-		}
-		// Re-read on subscribe: the state may have moved between the initial
-		// render and this effect, and dropping that transition would leave the
-		// UI showing a state the instance has already left.
-		setState(ads.getPlacementState(placementKey));
-		return ads.subscribePlacement(placementKey, setState);
-	}, [ads, placementKey]);
-
-	return state;
-}
-
-/** Live initialization status. `unavailable` outside a provider. */
-export function useAdsStatus(): InitStatus {
-	const ads = useAds();
-	const [status, setStatus] = useState<InitStatus>(() => (ads ? ads.getStatus() : 'unavailable'));
-
-	useEffect(() => {
-		if (!ads) {
-			setStatus('unavailable');
-			return;
-		}
-		setStatus(ads.getStatus());
-		return ads.subscribeStatus(setStatus);
-	}, [ads]);
-
-	return status;
-}
-
-/**
- * Forwards every event to a listener without causing a render.
- *
- * Deliberately does not accumulate events into state: a package that kept an
- * event log would be persisting exactly the kind of history it promises not to
- * (FR-021), and re-rendering on every impression would defeat PERF-002. A screen
- * that wants a visible log keeps its own.
- */
-export function useAdsEvents(listener: AdEventListener): void {
-	const ads = useAds();
-
-	useEffect(() => {
-		if (!ads) {
-			return;
-		}
-		return ads.subscribeEvents(listener);
-	}, [ads, listener]);
-}
+/**
+ * React bindings (US1, FR-027).
+ *
+ * Each hook subscribes to exactly what it reads. `usePlacementState` subscribes
+ * to one placement rather than to the whole event stream, which is what keeps a
+ * banner from re-rendering because an unrelated interstitial was clicked —
+ * PERF-002's bounded re-render assertion depends on it.
+ *
+ * None of these hand back an ad object. A consumer queries and subscribes to
+ * state; it never holds provider-owned memory (FR-027).
+ */
+
+import { useEffect, useState } from 'react';
+
+import type { InitStatus, PlacementState } from '../config/types';
+import type { AdEventListener } from '../diagnostics/events';
+import { useAds } from './AdsProvider';
+
+/** Live state for one placement. `unavailable` outside a provider. */
+export function usePlacementState(placementKey: string): PlacementState {
+	const ads = useAds();
+	const [state, setState] = useState<PlacementState>(() =>
+		ads ? ads.getPlacementState(placementKey) : 'unavailable',
+	);
+
+	useEffect(() => {
+		if (!ads) {
+			setState('unavailable');
+			return;
+		}
+		// Re-read on subscribe: the state may have moved between the initial
+		// render and this effect, and dropping that transition would leave the
+		// UI showing a state the instance has already left.
+		setState(ads.getPlacementState(placementKey));
+		return ads.subscribePlacement(placementKey, setState);
+	}, [ads, placementKey]);
+
+	return state;
+}
+
+/** Live initialization status. `unavailable` outside a provider. */
+export function useAdsStatus(): InitStatus {
+	const ads = useAds();
+	const [status, setStatus] = useState<InitStatus>(() => (ads ? ads.getStatus() : 'unavailable'));
+
+	useEffect(() => {
+		if (!ads) {
+			setStatus('unavailable');
+			return;
+		}
+		setStatus(ads.getStatus());
+		return ads.subscribeStatus(setStatus);
+	}, [ads]);
+
+	return status;
+}
+
+/**
+ * Forwards every event to a listener without causing a render.
+ *
+ * Deliberately does not accumulate events into state: a package that kept an
+ * event log would be persisting exactly the kind of history it promises not to
+ * (FR-021), and re-rendering on every impression would defeat PERF-002. A screen
+ * that wants a visible log keeps its own.
+ */
+export function useAdsEvents(listener: AdEventListener): void {
+	const ads = useAds();
+
+	useEffect(() => {
+		if (!ads) {
+			return;
+		}
+		return ads.subscribeEvents(listener);
+	}, [ads, listener]);
+}