flet-box 0.0.0-stage → 1.0.2

package/src/widgets/AdMob.js

@@ -0,0 +1,315 @@
+/**
+ * @file AdMob.js
+ * @description Google AdMob for native Capacitor targets (Android/iOS). This is
+ * the mobile counterpart of `AdSense`: instead of a web SDK it drives the native
+ * `@capacitor-community/admob` plugin. The widget renders a DOM placeholder that
+ * reserves space and, when `autoInitialize: true`, shows the banner / prepares
+ * full-screen ads over the native layer. On the web (no Capacitor) it degrades
+ * to the placeholder and logs a single warning.
+ *
+ * Native ads are an explicit opt-in (`autoInitialize: true`) because the Google
+ * SDK hard-aborts the app when its AdMob App ID is not configured. Mounting an
+ * AdMob widget must never crash a misconfigured app, so the placeholder renders
+ * and the plugin is left untouched until the developer opts in and sets the App
+ * ID in the native config (`GADApplicationIdentifier` in Info.plist, `APPLICATION_ID`
+ * meta-data in AndroidManifest.xml).
+ */
+
+import { WidgetFactory } from "../widget-factory/index.js";
+import { composeUpdate } from "../utils/composeUpdate.js";
+
+// Google's public sample unit ids — safe to use while developing. Replace them
+// with your own real ids before shipping (keep isTesting once you go live only
+// if you actually want test ads).
+const TEST_BANNER_ID = "ca-app-pub-3940256099942544/6300978111";
+const TEST_INTERSTITIAL_ID = "ca-app-pub-3940256099942544/1033173712";
+const TEST_REWARDED_ID = "ca-app-pub-3940256099942544/5224354917";
+
+const DEFAULT_COLOR = "#9ca3af";
+const DEFAULT_BORDER_COLOR = "#d1d5db";
+
+const WIDGET_PROP_KEYS = [
+  "adId",
+  "isTesting",
+  "position",
+  "size",
+  "margin",
+  "label",
+  "placeholder",
+  "interstitialId",
+  "rewardedId",
+  "autoInitialize",
+];
+
+// Initialisation is app-wide, so it only needs to happen once per plugin.
+let initPromise = null;
+let warnedMissingPlugin = false;
+let warnedNotInitialized = false;
+
+/**
+ * Resolves the native AdMob plugin from an explicit prop or the Capacitor
+ * bridge. `@capacitor-community/admob` registers itself as
+ * `Capacitor.Plugins.AdMob`, which keeps FletBox dependency-free.
+ *
+ * @param {Object|null} [explicit] - Plugin instance passed by the caller.
+ * @returns {Object|null}
+ */
+const resolvePlugin = (explicit) => {
+  if (explicit) return explicit;
+  const capacitor = globalThis.Capacitor;
+  return (capacitor && capacitor.Plugins && capacitor.Plugins.AdMob) || null;
+};
+
+const ensureInitialized = (plugin) => {
+  if (!plugin || typeof plugin.initialize !== "function") return Promise.resolve();
+  if (!initPromise) {
+    initPromise = Promise.resolve(plugin.initialize({})).catch((error) => {
+      console.warn("[FletBox AdMob] initialize failed:", error);
+    });
+  }
+  return initPromise;
+};
+
+/**
+ * Creates a Google AdMob widget for native Capacitor builds.
+ *
+ * On a real device it shows a banner (top/bottom) and exposes methods for
+ * interstitial and rewarded ads. In the browser it returns the same element but
+ * does nothing beyond a one-time warning, so the app keeps working during web
+ * development.
+ *
+ * @param {Object}  props
+ * @param {string}  [props.adId=""] - Banner ad unit id. Defaults to Google's test unit.
+ * @param {boolean} [props.isTesting=false] - Force Google test ads (recommended before release).
+ * @param {"top"|"bottom"} [props.position="bottom"] - Native banner position.
+ * @param {string}  [props.size="ADAPTIVE_BANNER"] - Banner size keyword ("ADAPTIVE_BANNER", "BANNER", "LARGE_BANNER", "MEDIUM_RECTANGLE", "FULL_BANNER", "LEADERBOARD", "SMART_BANNER").
+ * @param {number}  [props.margin=0] - Distance in pixels from the chosen edge.
+ * @param {string}  [props.interstitialId=""] - Ad unit id for `showInterstitial()`.
+ * @param {string}  [props.rewardedId=""] - Ad unit id for `showRewarded()`.
+ * @param {boolean} [props.autoShow=true] - Show the banner automatically on mount.
+ * @param {boolean} [props.autoInitialize=false] - Opt in to native ads. Requires a
+ * configured AdMob App ID (`GADApplicationIdentifier` in Info.plist, `APPLICATION_ID`
+ * in AndroidManifest.xml); until set, mounting the widget is placeholder-only so a
+ * misconfigured app never crashes (the Google SDK aborts otherwise).
+ * @param {number|string} [props.width="100%"] - Placeholder width.
+ * @param {number|string} [props.height=50] - Placeholder height (reserve banner space).
+ * @param {boolean} [props.placeholder=true] - Show the dashed placeholder.
+ * @param {string}  [props.label="AdMob banner"] - Placeholder text.
+ * @param {string}  [props.bgColor] - Placeholder background color.
+ * @param {string}  [props.color=#9ca3af] - Placeholder label color.
+ * @param {string}  [props.borderColor=#d1d5db] - Placeholder dashed border color.
+ * @param {Object}  [props.plugin] - Explicit plugin instance (defaults to `Capacitor.Plugins.AdMob`).
+ * @param {(widget: HTMLElement) => void} [props.onLoaded] - Called after the banner is shown.
+ * @param {(error: Error, widget: HTMLElement) => void} [props.onFailed] - Called when a native call fails.
+ * @param {() => void} [props.onDismissed] - Called after a full-screen ad is dismissed.
+ * @returns {HTMLElement} The placeholder container, stamped `widgetName: "AdMob"`.
+ */
+export const AdMob = (props) => {
+  const {
+    adId = "",
+    isTesting = false,
+    position = "bottom",
+    size = "ADAPTIVE_BANNER",
+    margin = 0,
+    interstitialId = "",
+    rewardedId = "",
+    autoShow = true,
+    autoInitialize = false,
+    width = "100%",
+    height = 50,
+    placeholder = true,
+    label = "AdMob banner",
+    bgColor,
+    color = DEFAULT_COLOR,
+    borderColor = DEFAULT_BORDER_COLOR,
+    plugin: pluginProp = null,
+    onLoaded,
+    onFailed,
+    onDismissed,
+    ...rest
+  } = props;
+
+  let currentAdId = adId;
+  let currentIsTesting = isTesting;
+  let currentPosition = position;
+  let currentSize = size;
+  let currentMargin = margin;
+  let currentLabel = label;
+  let currentPlaceholder = placeholder;
+  let currentAutoInitialize = autoInitialize;
+  let bannerVisible = false;
+  let disposed = false;
+  let labelElement = null;
+
+  const bannerId = () => currentAdId || TEST_BANNER_ID;
+
+  const withPlugin = (run) => {
+    if (!currentAutoInitialize) {
+      if (!warnedNotInitialized) {
+        warnedNotInitialized = true;
+        console.warn(
+          "[FletBox AdMob] native ads are disabled (missing `autoInitialize: true`). Mounting an AdMob widget is placeholder-only by default because the Google SDK aborts the app when its AdMob App ID is not configured. To enable ads, set `autoInitialize: true` AND add the App ID to the native config: `GADApplicationIdentifier` in ios/App/App/Info.plist or the `APPLICATION_ID` meta-data in AndroidManifest.xml, then run `npm run ios:sync` / `android:sync`.",
+        );
+      }
+      return Promise.resolve(null);
+    }
+    const plugin = resolvePlugin(pluginProp);
+    if (!plugin) {
+      if (!warnedMissingPlugin) {
+        warnedMissingPlugin = true;
+        console.warn(
+          "[FletBox AdMob] native plugin not found. Install @capacitor-community/admob and run `npx cap sync` in your Capacitor project.",
+        );
+      }
+      return Promise.resolve(null);
+    }
+    return ensureInitialized(plugin).then(() => run(plugin));
+  };
+
+  const container = WidgetFactory({
+    widgetName: "AdMob",
+    boxSizing: "border-box",
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    overflow: "hidden",
+    width,
+    height,
+    backgroundColor: bgColor,
+    borderStyle: "dashed",
+    borderWidth: currentPlaceholder ? 1 : 0,
+    borderColor,
+    ...rest,
+  });
+
+  const refreshPlaceholder = () => {
+    container.style.borderWidth = currentPlaceholder ? "1px" : "0px";
+    if (!labelElement) return;
+    labelElement.style.display = currentPlaceholder ? "" : "none";
+    if (currentPlaceholder) labelElement.textContent = currentLabel.toUpperCase();
+  };
+
+  if (currentPlaceholder) {
+    labelElement = WidgetFactory({
+      widgetName: "Text",
+      tag: "span",
+      text: currentLabel.toUpperCase(),
+      color,
+      fontSize: 11,
+      fontWeight: 600,
+      letterSpacing: 2,
+      userSelect: "none",
+      pointerEvents: "none",
+    });
+    container.appendChild(labelElement);
+  }
+
+  const showBanner = () => {
+    if (disposed || !autoShow || bannerVisible) return Promise.resolve(null);
+    return withPlugin((plugin) =>
+      Promise.resolve(
+        plugin.showBanner({
+          adId: bannerId(),
+          adSize: currentSize,
+          position: currentPosition === "top" ? "TOP_CENTER" : "BOTTOM_CENTER",
+          margin: currentMargin,
+          isTesting: currentIsTesting,
+        }),
+      ).then(() => {
+        bannerVisible = true;
+        if (typeof onLoaded === "function") onLoaded(container);
+      }),
+    ).catch((error) => {
+      if (disposed) return null;
+      console.warn("[FletBox AdMob] showBanner failed:", error);
+      if (typeof onFailed === "function") onFailed(error, container);
+      return null;
+    });
+  };
+
+  const hideBanner = () => {
+    bannerVisible = false;
+    return withPlugin((plugin) => {
+      const remove = plugin.removeBanner || plugin.hideBanner;
+      return typeof remove === "function" ? Promise.resolve(remove.call(plugin)) : null;
+    }).catch(() => null);
+  };
+
+  const showFullScreen = (prepareProps, prepareName, showName) =>
+    withPlugin((plugin) => {
+      const prepare = plugin[prepareName];
+      if (typeof prepare !== "function") {
+        console.warn(`[FletBox AdMob] plugin has no ${prepareName}()`);
+        return null;
+      }
+      return Promise.resolve(prepare.call(plugin, prepareProps))
+        .then(() => plugin[showName]())
+        .then((result) => {
+          if (typeof onDismissed === "function") onDismissed();
+          return result;
+        });
+    }).catch((error) => {
+      console.warn(`[FletBox AdMob] ${showName} failed:`, error);
+      if (typeof onFailed === "function") onFailed(error, container);
+      return null;
+    });
+
+  /** Shows or re-shows the banner. */
+  container.show = showBanner;
+
+  /** Hides the banner (keeps it prepared). */
+  container.hide = hideBanner;
+
+  /** Prepares and shows an interstitial ad. */
+  container.showInterstitial = () =>
+    showFullScreen(
+      {
+        adId: interstitialId || TEST_INTERSTITIAL_ID,
+        isTesting: currentIsTesting,
+      },
+      "prepareInterstitial",
+      "showInterstitial",
+    );
+
+  /** Prepares and shows a rewarded video ad. */
+  container.showRewarded = () =>
+    showFullScreen(
+      { adId: rewardedId || TEST_REWARDED_ID, isTesting: currentIsTesting },
+      "prepareRewardVideoAd",
+      "showRewardVideoAd",
+    );
+
+  /** @returns {Object|null} The resolved native plugin, if any. */
+  container.getPlugin = () => resolvePlugin(pluginProp);
+
+  composeUpdate(container, WIDGET_PROP_KEYS, (widgetProps) => {
+    if ("adId" in widgetProps) currentAdId = widgetProps.adId;
+    if ("isTesting" in widgetProps) currentIsTesting = widgetProps.isTesting;
+    if ("position" in widgetProps) currentPosition = widgetProps.position;
+    if ("size" in widgetProps) currentSize = widgetProps.size;
+    if ("margin" in widgetProps) currentMargin = widgetProps.margin;
+    if ("label" in widgetProps) currentLabel = widgetProps.label;
+    if ("placeholder" in widgetProps) currentPlaceholder = widgetProps.placeholder;
+    if ("autoInitialize" in widgetProps) currentAutoInitialize = widgetProps.autoInitialize;
+    refreshPlaceholder();
+  });
+
+  const dispose = () => {
+    if (disposed) return;
+    disposed = true;
+    if (!currentAutoInitialize) return;
+    const plugin = resolvePlugin(pluginProp);
+    if (plugin && typeof plugin.removeBanner === "function") {
+      Promise.resolve(plugin.removeBanner()).catch(() => {});
+    }
+  };
+  container.onUnmount(dispose);
+
+  container.onMount(showBanner);
+
+  refreshPlaceholder();
+
+  return container;
+};
+
+export default AdMob;

package/src/widgets/AdSense.js

@@ -0,0 +1,268 @@
+/**
+ * @file AdSense.js
+ * @description Google AdSense display unit for the web. Loads the official
+ * `adsbygoogle.js` SDK exactly once per publisher client and asks it to fill a
+ * `<ins class="adsbygoogle">` slot. Use this widget in browser / PWA / webview
+ * targets; for native Android/iOS banners use the `AdMob` widget instead.
+ */
+
+import { WidgetFactory } from "../widget-factory/index.js";
+import { composeUpdate } from "../utils/composeUpdate.js";
+import { injectScript } from "../utils/scriptInjector.js";
+import { toREM } from "../utils/units.js";
+
+const ADSENSE_SRC =
+  "https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js";
+
+// Widget-owned props: routed to the widget's own updater, never to the factory.
+const WIDGET_PROP_KEYS = ["client", "slot", "format", "responsive", "label", "placeholder", "test", "height"];
+
+// Formats that size themselves from content (Google grows the slot after fill).
+const SELF_SIZING_FORMATS = new Set(["autorelaxed", "fluid"]);
+
+const DEFAULT_COLOR = "#9ca3af";
+const DEFAULT_BORDER_COLOR = "#d1d5db";
+
+/** Builds the per-publisher SDK URL so each client loads the script once. */
+const adsenseScriptUrl = (client) =>
+  `${ADSENSE_SRC}?client=${encodeURIComponent(client)}`;
+
+/** Hands one unit to the shared `adsbygoogle` command queue. */
+const pushAd = () => {
+  if (typeof window === "undefined") return;
+  try {
+    (window.adsbygoogle = window.adsbygoogle || []).push({});
+  } catch (error) {
+    console.warn("[FletBox AdSense] could not request an ad:", error);
+  }
+};
+
+/**
+ * Creates a Google AdSense display unit.
+ *
+ * The widget is inert until both `client` (publisher id) and `slot` (ad unit id)
+ * are set. Once configured and mounted it injects the AdSense SDK (shared with
+ * every other `AdSense` on the page) and pushes the unit to be filled. A dashed
+ * placeholder is shown while the widget is unconfigured unless
+ * `placeholder={false}`.
+ *
+ * @param {Object}  props
+ * @param {string}  [props.client=""] - Publisher id, e.g. `"ca-pub-1234567890123456"`.
+ * @param {string}  [props.slot=""] - Ad unit id (numeric string).
+ * @param {string}  [props.format="auto"] - `data-ad-format` keyword ("auto", "horizontal", "rectangle", "vertical", "fluid", "autorelaxed").
+ * @param {boolean} [props.responsive=true] - Emit `data-full-width-responsive="true"`.
+ * @param {boolean} [props.test=false] - Emit `data-adtest="on"` so Google serves
+ *   sample test ads from its test pool (ignores domain approval). Never ship
+ *   with `test` enabled.
+ * @param {number|string} [props.width="100%"] - Slot width.
+ * @param {number|string} [props.height=280] - Reserved slot height.
+ * @param {boolean} [props.placeholder=true] - Show the dashed placeholder while unconfigured.
+ * @param {string}  [props.label="Advertisement"] - Placeholder text.
+ * @param {string}  [props.bgColor] - Slot background color.
+ * @param {string}  [props.color=#9ca3af] - Placeholder label color.
+ * @param {string}  [props.borderColor=#d1d5db] - Placeholder dashed border color.
+ * @param {(widget: HTMLElement) => void} [props.onLoad] - Called once the SDK is ready and the unit pushed.
+ * @param {(error: Error, widget: HTMLElement) => void} [props.onError] - Called when the SDK fails to load.
+ * @param {Widget[]} [props.children] - Extra host markup placed inside the slot.
+ * @returns {HTMLElement} The slot container, stamped `widgetName: "AdSense"`.
+ */
+export const AdSense = (props) => {
+  let {
+    client = "",
+    slot = "",
+    format = "auto",
+    responsive = true,
+    test = false,
+    width = "100%",
+    height = 280,
+    placeholder = true,
+    label = "Advertisement",
+    bgColor,
+    color = DEFAULT_COLOR,
+    borderColor = DEFAULT_BORDER_COLOR,
+    onLoad,
+    onError,
+    ...rest
+  } = props;
+
+  let currentClient = client;
+  let currentSlot = slot;
+  let currentFormat = format;
+  let currentResponsive = responsive;
+  let currentTest = test;
+  let insElement = null;
+  let labelElement = null;
+  let disposed = false;
+  let mounted = false;
+  let configured = !!client && !!slot;
+
+  const isConfigured = () => !!currentClient && !!currentSlot;
+
+  const isSelfSizing = () => SELF_SIZING_FORMATS.has(currentFormat);
+
+  const container = WidgetFactory({
+    widgetName: "AdSense",
+    boxSizing: "border-box",
+    position: "relative",
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    overflow: "hidden",
+    width,
+    height,
+    backgroundColor: bgColor,
+    borderStyle: "dashed",
+    borderWidth: isConfigured() ? 0 : 1,
+    borderColor,
+    ...rest,
+  });
+
+  // Display/auto units reserve a fixed slot height; self-sizing formats
+  // (autorelaxed, fluid) must grow with the content Google injects.
+  const syncSizing = () => {
+    if (isSelfSizing()) {
+      container.style.height = "auto";
+      container.style.overflow = "visible";
+    } else {
+      container.style.height = toREM(height);
+      container.style.overflow = "hidden";
+    }
+    if (insElement) insElement.style.height = isSelfSizing() ? "auto" : "100%";
+  };
+
+  // If the initial format is self-sizing, drop the reserved height immediately.
+  syncSizing();
+
+  const applyAttrs = () => {
+    if (!insElement) return;
+    insElement.setAttribute("data-ad-client", currentClient);
+    insElement.setAttribute("data-ad-slot", currentSlot);
+    if (currentFormat) insElement.setAttribute("data-ad-format", currentFormat);
+    else insElement.removeAttribute("data-ad-format");
+    if (currentResponsive) {
+      insElement.setAttribute("data-full-width-responsive", "true");
+    } else {
+      insElement.removeAttribute("data-full-width-responsive");
+    }
+    if (currentTest) {
+      insElement.setAttribute("data-adtest", "on");
+    } else {
+      insElement.removeAttribute("data-adtest");
+    }
+  };
+
+  const ensureIns = () => {
+    if (insElement) return insElement;
+    insElement = document.createElement("ins");
+    insElement.className = "adsbygoogle";
+    insElement.style.display = "block";
+    insElement.style.width = "100%";
+    container.appendChild(insElement);
+    applyAttrs();
+    syncSizing();
+    return insElement;
+  };
+
+  const syncPlaceholder = () => {
+    const show = placeholder && !isConfigured();
+    container.style.borderWidth = show ? "1px" : "0px";
+    if (!show) {
+      if (labelElement) labelElement.style.display = "none";
+      return;
+    }
+    if (!labelElement) {
+      labelElement = WidgetFactory({
+        widgetName: "Text",
+        tag: "span",
+        text: label.toUpperCase(),
+        color,
+        fontSize: 11,
+        fontWeight: 600,
+        letterSpacing: 2,
+        userSelect: "none",
+        pointerEvents: "none",
+        position: "absolute",
+      });
+      container.appendChild(labelElement);
+    }
+    labelElement.style.display = "";
+    labelElement.textContent = label.toUpperCase();
+  };
+
+  const load = () => {
+    if (disposed) return;
+    if (!isConfigured()) {
+      syncPlaceholder();
+      return;
+    }
+    syncPlaceholder();
+    ensureIns();
+    injectScript(adsenseScriptUrl(currentClient), {
+      async: true,
+      crossOrigin: "anonymous",
+    })
+      .then(() => {
+        if (disposed) return;
+        pushAd();
+        if (typeof onLoad === "function") onLoad(container);
+      })
+      .catch((error) => {
+        if (disposed) return;
+        console.warn("[FletBox AdSense] SDK failed to load:", error);
+        if (typeof onError === "function") onError(error, container);
+      });
+  };
+
+  /** Requests another ad for the same unit (e.g. after a route change). */
+  container.refresh = () => {
+    if (isConfigured()) {
+      ensureIns();
+      pushAd();
+    }
+    return container;
+  };
+
+  /** Starts (or restarts) the SDK load + fill cycle. */
+  container.load = load;
+
+  /** @returns {HTMLElement} The `<ins>` unit when live, otherwise the container. */
+  container.getElement = () => insElement || container;
+
+  composeUpdate(container, WIDGET_PROP_KEYS, (widgetProps) => {
+    if ("client" in widgetProps) currentClient = widgetProps.client;
+    if ("slot" in widgetProps) currentSlot = widgetProps.slot;
+    if ("format" in widgetProps) currentFormat = widgetProps.format;
+    if ("responsive" in widgetProps) currentResponsive = widgetProps.responsive;
+    if ("test" in widgetProps) currentTest = widgetProps.test;
+    if ("height" in widgetProps) height = widgetProps.height;
+    if ("label" in widgetProps) label = widgetProps.label;
+    if ("placeholder" in widgetProps) placeholder = widgetProps.placeholder;
+    applyAttrs();
+    syncSizing();
+    syncPlaceholder();
+
+    // Going from unconfigured to configured after mount should actually start
+    // serving; before mount the `onMount` hook handles it.
+    const nowConfigured = isConfigured();
+    if (nowConfigured && !configured && mounted) load();
+    configured = nowConfigured;
+  });
+
+  const dispose = () => {
+    if (disposed) return;
+    disposed = true;
+    mounted = false;
+  };
+  container.onUnmount(dispose);
+
+  container.onMount(() => {
+    mounted = true;
+    load();
+  });
+
+  syncPlaceholder();
+
+  return container;
+};
+
+export default AdSense;