smart-adsense 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dmytro Shovchko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,203 @@
+# smart-adsense
+
+A drop-in AdSense service configuration with a `<smart-adsense>` custom element for retry, refresh, and status tracking.
+
+## Features
+
+- **Lazy loading element**: `loading="lazy"` and  [Exadel Smart Library media query](https://esl-ui.com/core/esl-media-query/) `display` gate script execution until the slot is visible or matches a breakpoint.
+- **Retry + refresh orchestration**: configurable delay/count for unfilled slots and interval-based refresh when filled.
+- **Resize awareness**: if the `params` attribute sets `refreshOnResize=true`, a filled element re-renders whenever its width changes (attribute described in the Element API section).
+- **Mutation-based status detection** via `MutationObserver`, emitting `adsense:status` (`filled`, `unfilled`, `pending`, etc.).
+- **SSR/CSR safe service** built on `smart-load-manager` (mutexed script loading, early hints, debug logging support).
+
+## Service vs. element
+
+- **Service (`SmartAdsense`)** - extends `SmartService` to own script loading, retries, refresh timers, and early-hint helpers. You can call it directly (`SmartAdsense.load()`, `SmartAdsense.preload()`, `SmartAdsense.setupEarlyHints()`) or wire it into `SmartLoad.queue()`.
+- **Element (`<smart-adsense>`)** - wraps the service so markup can express lazy/conditional activation (`loading`, `display`), resize awareness, and DOM events for status tracking.
+
+*Typical flow*: configure the service once (`SmartAdsense.config()`), register the element, and sprinkle `<smart-adsense>` components throughout templates. When you need bespoke orchestration, trigger the same service instance via `SmartLoad` or manual calls while the element reacts to `SmartAdsense.instance.load()` resolution.
+
+> ⚠️ `SmartAdsense.config()` mutates global defaults for the singleton service. Call it during bootstrap (before rendering elements) and avoid per-request overrides unless you intentionally change the global state.
+
+> ℹ️ The custom element is not auto-registered. Call `SmartAdsenseElement.register()` once during app startup (before using `<smart-adsense>` in markup).
+
+## Install
+
+```bash
+npm install smart-adsense smart-load-manager @exadel/esl
+```
+
+`smart-adsense` wraps `smart-load-manager` and re-exports pieces from it. Both packages expect [`@exadel/esl`](https://www.npmjs.com/package/@exadel/esl) as a peer dependency (you can learn more about ESL on the library [website](https://esl-ui.com/)). Your package manager will prompt if ESL is missing; if your project already ships a compatible ESL build, you can skip it from the install command above.
+
+The CSS file `smart-adsense.css` ships in `dist/` folder - copy or import it wherever you register the element.
+
+## Quick start
+
+```ts
+import {SmartAdsense, SmartAdsenseElement} from 'smart-adsense';
+import 'smart-adsense/dist/smart-adsense.css';
+
+SmartAdsense.config({
+  url: 'https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=ca-pub-XXXX',
+  retryDelay: 20,
+  retryCount: 3,
+  refreshInterval: 0,
+  refreshOnResize: false,
+});
+
+SmartAdsenseElement.register(); // recommended after config so early instances see your defaults (safe to swap if needed)
+```
+
+```html
+<smart-adsense
+  display="(min-width: 768px)"
+  loading="lazy"
+  params='{"retryDelay":10,"refreshInterval":60}'
+>
+  <!-- your ins data-ad-code -->
+</smart-adsense>
+```
+
+- `SmartAdsense.config()` merges defaults with global service options (delegates to `SmartService`).
+- The custom element loads scripts lazily (using `SmartAdsense.instance.load()`), tracks mutations, and dispatches `smart-adsense:change` events whenever status updates.
+
+### Coordinating with other services
+
+Because `SmartAdsense` extends `SmartService`, it participates in the same orchestration primitives as any other loader:
+
+```ts
+import {SmartService, SmartLoad} from 'smart-load-manager';
+import {SmartAdsense} from 'smart-adsense';
+
+const consent = SmartService.create({name: 'Consent', url: 'https://cdn.example.com/consent.js'});
+SmartAdsense.config({url: 'https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=ca-pub-XXXX'});
+
+SmartLoad.queue(consent);
+SmartLoad.queue(SmartAdsense, consent.load); // load AdSense only after the consent has been loaded
+SmartLoad.start();
+```
+
+You can also call `SmartAdsense.load()` directly and branch on success/failure to attach fallbacks.
+
+**Idle window orchestration**
+
+```ts
+import {SmartLoad, waitAny, waitIdle, waitUserActivity} from 'smart-load-manager';
+import {SmartAdsense} from 'smart-adsense';
+
+SmartAdsense.config({url: 'https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=ca-pub-XXXX'});
+
+SmartLoad.queue(SmartAdsense, async () => waitAny([
+  // Wait until the browser provides ~50ms of idle time
+  waitIdle({thresholds: {duration: 50, ratio: 0.9}, timeout: 8000}),
+  // or until the user interacts with the page
+  waitUserActivity()
+]));
+SmartLoad.start();
+SmartAdsense.load().catch(() => console.log('?> AdSense failed! Will do something else...'));
+```
+
+This pattern defers AdSense bootstrapping until the page settles (e.g., after above-the-fold work) or the user starts interacting with the page. Combine with other wait tasks to tailor the user journey.
+
+## Configuration
+
+`SmartAdsenseOptions` extend `SmartServiceOptions`:
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `retryDelay` | `number` | Seconds before retrying unfilled units (0 disables retries). |
+| `retryCount` | `number` | Max number of retries; `0` = unlimited. |
+| `refreshInterval` | `number` | Seconds before refreshing filled ads; `0` disables refresh. |
+| `refreshOnResize` | `boolean` | Refresh when element width changes after a filled state. |
+| `debug` | `boolean` | When true, element logs lifecycle events. |
+
+Use `SmartAdsense.config()` globally and override per-element via the `params` attribute (JSON string merged over defaults).
+
+> `retryCount = 0` means "retry indefinitely". This matches the legacy AdSense behavior where omitting the limit reattempts until a fill occurs. Set it to a positive integer to cap retries, or pair with `retryDelay = 0` to disable retries entirely.
+
+## Element API
+
+`<smart-adsense>` extends `SmartAdsenseElement` (an [`ESLBaseElement`](https://esl-ui.com/core/esl-base-element/)). It exposes declarative attributes, runtime properties, and status events so you can wire UI around AdSense lifecycles.
+
+### Static helpers
+
+| Member | Description |
+| --- | --- |
+| `SmartAdsenseElement.create()` | Creates an instance of the `SmartAdsenseElement`. |
+| `SmartAdsenseElement.register()` | Defines the custom element (call once after configuring `SmartAdsense`). |
+
+### Attributes
+
+| Attribute | Default | Purpose |
+| --- | --- | --- |
+| `display` | `all` | (`ESLMediaQuery`)[https://esl-ui.com/core/esl-media-query/] expression controlling visibility/lazy init. |
+| `loading` | `lazy` | `lazy` waits for intersection, `eager` loads immediately. |
+| `params` | `{}` | JSON encoded partial `SmartAdsenseOptions`. |
+| `status` | `init` | Reflects current lifecycle (`init`, `pending`, `filled`, `unfilled`, `hidden`, `failed`). |
+
+### Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `config` | `SmartAdsenseOptions` | Read-only view of the effective configuration (global `SmartAdsense.config()` merged with `params`). Use it to inspect retry/refresh values at runtime. |
+| `status` | `string` | Getter/Setter for the current lifecycle (`init`, `pending`, etc.). Setting it manually forces a lifecycle update and dispatches `smart-adsense:change`. |
+| `inactive` | `boolean` | Indicates whether the slot is gated (set to `false` when the element intersects or `loading="eager"`). |
+| `params` | `Partial<SmartAdsenseOptions>` | Runtime getter/setter for JSON params; changing it re-merges config on the next load. |
+
+### Events
+
+- `adsense:status` - fires from the inner `<ins class="adsbygoogle">` created by Google. Listen when you need the raw AdSense signal (e.g., mirroring their exact payload or forwarding to analytics). It bubbles, so you can capture it at the document level.
+- `smart-adsense:change` - emitted by the custom element whenever its `status` property updates (after debounce, including retries/refresh). Prefer this event for UI reactions, state machines, or whenever you only need the normalized status without touching Google's DOM.
+
+### Usage notes
+
+- **Slot content** - Provide at least one `<ins class="adsbygoogle" ...>` child. If the slot is empty the component stays `hidden` and never requests AdSense. Multiple `<ins>` tags are technically supported (the markup is restored verbatim for retries), but Google typically expects one ad per element—use separate wrappers for distinct placements.
+- **Conditional loading** - Toggle the `display` media query or switch the `loading` attribute between `lazy`/`eager`. Prefer media queries powered by [ESL's `<esl-media-query>`](https://esl-ui.com/core/esl-media-query/) so breakpoints stay declarative. The `inactive` attribute is only a status flag controlled by the component; do not modify it directly.
+- **Cleanup/re-mount** - Remove the element from the DOM to destroy it. `disconnectedCallback` restores the original markup automatically, so you can reattach the element later without losing the `<ins>` payload.
+
+## Recipes
+
+**Lazy + retry combo**
+
+```html
+<smart-adsense
+  loading="lazy"
+  params='{"retryDelay":5,"retryCount":5}'
+>
+  <ins class="adsbygoogle" data-ad-client="ca-pub-XXXX" data-ad-slot="123"></ins>
+</smart-adsense>
+```
+
+**Always refresh on resize**
+
+```html
+<smart-adsense
+  params='{"refreshOnResize":true,"refreshInterval":0}'
+>
+  <ins class="adsbygoogle" data-ad-client="ca-pub-XXXX" data-ad-slot="456"></ins>
+</smart-adsense>
+```
+
+**Track status changes**
+
+```ts
+document.addEventListener('smart-adsense:change', (event) => {
+  const {detail: status} = event as CustomEvent<string>;
+  console.info('Ad status changed:', status);
+});
+```
+
+**Create element programmatically**
+
+```ts
+const el = SmartAdsenseElement.create();
+el.display = '(min-width: 1024px)';
+el.params = {retryDelay: 15};
+el.innerHTML = '<ins class="adsbygoogle" data-ad-slot="xxxxxxxxx"></ins>';
+document.body.appendChild(el);
+```
+
+## Compatibility & performance
+
+- **Browser support**: Requires ES2019+ syntax (async/await, optional chaining, nullish coalescing), Custom Elements, IntersectionObserver, ResizeObserver, and AbortController (same as `smart-load-manager`). Add polyfills before registering the element if you target legacy browsers (e.g., [@webcomponents/custom-elements](https://github.com/webcomponents/polyfills/tree/master/packages/custom-elements), [intersection-observer](https://github.com/w3c/IntersectionObserver/tree/main/polyfill)).
+- **Performance impact**: The service defers AdSense execution via idle/interaction guards, reducing layout shifts and blocking time. Using `SmartLoad.queue()` serializes queued third-party script loads (not every resource), so only one ad/marketing script fetch runs at a time, which helps stabilize Core Web Vitals on ad-heavy pages.

package/dist/index.cjs

@@ -0,0 +1,329 @@
+'use strict';
+
+var dom_js = require('@exadel/esl/modules/esl-utils/dom.js');
+var smartLoadManager = require('smart-load-manager');
+var core_js$1 = require('@exadel/esl/modules/esl-base-element/core.js');
+var decorators_js = require('@exadel/esl/modules/esl-utils/decorators.js');
+var async_js = require('@exadel/esl/modules/esl-utils/async.js');
+var core_js = require('@exadel/esl/modules/esl-event-listener/core.js');
+var intersection_target_js = require('@exadel/esl/modules/esl-event-listener/core/targets/intersection.target.js');
+var core_js$2 = require('@exadel/esl/modules/esl-media-query/core.js');
+
+const STATUS_EVENT = "adsense:status";
+const AD_STATUS_ATTR = "data-ad-status";
+const ADSBYGOOGLE_STATUS_ATTR = "data-adsbygoogle-status";
+class SmartAdsense extends smartLoadManager.SmartService {
+  _initStatusObserving() {
+    if (typeof document === "undefined" || typeof MutationObserver === "undefined") return;
+    const mutation$$ = new MutationObserver(this._onMutation);
+    mutation$$.observe(document.documentElement, {
+      subtree: true,
+      childList: true,
+      attributes: true,
+      attributeFilter: [AD_STATUS_ATTR, ADSBYGOOGLE_STATUS_ATTR]
+    });
+  }
+  _onMutation(mutations) {
+    mutations.forEach((record) => {
+      const { attributeName, target, type } = record;
+      if (type !== "attributes" || attributeName !== AD_STATUS_ATTR && attributeName !== ADSBYGOOGLE_STATUS_ATTR) return;
+      const { adStatus, adsbygoogleStatus } = target.dataset;
+      if (adStatus) {
+        dom_js.dispatchCustomEvent(target, STATUS_EVENT, { detail: adStatus });
+        return;
+      }
+      if (adsbygoogleStatus === "done" && !adStatus) {
+        const status = target.innerHTML.trim() === "" ? "unfilled" : "filled";
+        dom_js.dispatchCustomEvent(target, STATUS_EVENT, { detail: status });
+      }
+    });
+  }
+  _onLoadScript() {
+    super._onLoadScript();
+    this._initStatusObserving();
+  }
+}
+SmartAdsense._config = {
+  name: "Adsense",
+  retryDelay: 20,
+  retryCount: 3,
+  refreshInterval: 0,
+  refreshOnResize: false,
+  attrs: { crossorigin: "anonymous" }
+};
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop2 in b || (b = {}))
+    if (__hasOwnProp.call(b, prop2))
+      __defNormalProp(a, prop2, b[prop2]);
+  if (__getOwnPropSymbols)
+    for (var prop2 of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop2))
+        __defNormalProp(a, prop2, b[prop2]);
+    }
+  return a;
+};
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+var __async = (__this, __arguments, generator) => {
+  return new Promise((resolve, reject) => {
+    var fulfilled = (value) => {
+      try {
+        step(generator.next(value));
+      } catch (e) {
+        reject(e);
+      }
+    };
+    var rejected = (value) => {
+      try {
+        step(generator.throw(value));
+      } catch (e) {
+        reject(e);
+      }
+    };
+    var step = (x) => x.done ? resolve(x.value) : Promise.resolve(x.value).then(fulfilled, rejected);
+    step((generator = generator.apply(__this, __arguments)).next());
+  });
+};
+class SmartAdsenseElement extends core_js$1.ESLBaseElement {
+  constructor() {
+    super(...arguments);
+    this.params = {};
+    this.inactive = true;
+    this._content = "";
+    this._lastWidth = 0;
+    this._retries = 0;
+    this._status = "init";
+    this._task = new async_js.DelayedTask();
+  }
+  get config() {
+    return __spreadValues(__spreadValues({}, SmartAdsense.config()), this.params || {});
+  }
+  get displayQuery() {
+    return core_js$2.ESLMediaQuery.for(this.display);
+  }
+  /** Check if ad content is empty */
+  get isEmpty() {
+    return this._content.trim() === "";
+  }
+  /** Current ad status */
+  get status() {
+    return this._status;
+  }
+  set status(value) {
+    if (this._status === value) return;
+    this.setAttribute("status", this._status = value);
+    this._onStatusChange();
+  }
+  /** IntersectionObserver rootMargin value */
+  get rootMargin() {
+    return `${this.baseMargin * this.connectionRatio}px`;
+  }
+  /** Connection speed ratio */
+  get connectionRatio() {
+    var _a;
+    switch ((_a = navigator.connection) == null ? void 0 : _a.effectiveType) {
+      case "slow-2g":
+      case "2g":
+        return 2;
+      case "3g":
+        return 1.5;
+      case "4g":
+      default:
+        return 1;
+    }
+  }
+  connectedCallback() {
+    super.connectedCallback();
+    this.inactive = this.loading !== "eager";
+    this.storeContent();
+    this.init();
+    this.initA11y();
+  }
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.restoreContent();
+  }
+  attributeChangedCallback(attrName, oldVal, newVal) {
+    if (!this.connected) return;
+    if (attrName === "display") {
+      decorators_js.memoize.clear(this, "displayQuery");
+      this.$$on(this._onDisplayChange);
+      this.init();
+    }
+  }
+  /** Initializes ad */
+  init() {
+    return __async(this, null, function* () {
+      if (this.isEmpty) return;
+      if (!this.displayQuery.matches) {
+        this._task.put(this.hideAd);
+        return;
+      }
+      if (this.inactive) return;
+      try {
+        yield SmartAdsense.instance.load();
+        this._task.put(this.refreshAd, 0);
+      } catch (e) {
+        this.status = "failed";
+      }
+    });
+  }
+  /** Sets initial a11y attributes */
+  initA11y() {
+    if (!this.hasAttribute("role")) this.setAttribute("role", "complementary");
+  }
+  /** Stores initial ad content */
+  storeContent() {
+    this._content = this.innerHTML;
+    this.innerHTML = "";
+  }
+  /** Restores initial ad content */
+  restoreContent() {
+    this.innerHTML = this._content;
+  }
+  /** Pushes ad to the DOM */
+  pushAd() {
+    try {
+      (adsbygoogle = window.adsbygoogle || []).push({});
+    } catch (e) {
+    }
+  }
+  hideAd() {
+    this.status = "hidden";
+    this.innerHTML = "";
+    this._retries = 0;
+  }
+  refreshAd() {
+    this.status = "pending";
+    this._retries++;
+    this.restoreContent();
+    this.pushAd();
+  }
+  _onResize(event) {
+    const { contentRect } = event;
+    if (this._lastWidth === contentRect.width) return;
+    if (this._lastWidth > 0 && this.status === "filled") {
+      this._retries = 0;
+      this._task.put(this.refreshAd, 0);
+      this._log("Ad is refreshing on resize", this._lastWidth);
+    }
+    this._lastWidth = contentRect.width;
+  }
+  _onAdsenseStatusChange(event) {
+    this._log("Ad status:", event.detail);
+    this.status = event.detail;
+    if (event.detail === "unfilled") {
+      const { retryCount, retryDelay } = this.config;
+      const canRetry = retryCount === 0 || this._retries < retryCount;
+      if (retryDelay > 0 && canRetry) {
+        this._task.put(this.refreshAd, retryDelay * 1e3);
+        this._log(`Ad unfilled will be reattempted in ${retryDelay}s (${this._retries})`);
+      }
+    } else {
+      const { refreshInterval } = this.config;
+      this._log("Refresh interval:", refreshInterval);
+      if (refreshInterval > 0) {
+        this._task.put(this.refreshAd, (refreshInterval + Math.random()) * 1e3);
+        this._log(`Ad filled will be refreshed in ${refreshInterval}s [${this._retries}]`);
+      }
+    }
+  }
+  _onIntersect(e) {
+    this.inactive = false;
+    this.init();
+  }
+  _onDisplayChange(event) {
+    this.init();
+  }
+  _onStatusChange() {
+    dom_js.dispatchCustomEvent(this, "smart-adsense:change", { bubbles: false });
+  }
+  /** Logs messages to the console if debug mode is enabled */
+  _log(...args) {
+    if (!this.config.debug) return;
+    console.log(...args);
+  }
+}
+SmartAdsenseElement.is = "smart-adsense";
+SmartAdsenseElement.observedAttributes = ["display"];
+__decorateClass([
+  decorators_js.prop(750)
+], SmartAdsenseElement.prototype, "baseMargin", 2);
+__decorateClass([
+  decorators_js.prop([0, 0.01])
+], SmartAdsenseElement.prototype, "INTERSECTION_THRESHOLD", 2);
+__decorateClass([
+  decorators_js.prop("smart-adsense:change")
+], SmartAdsenseElement.prototype, "CHANGE_EVENT", 2);
+__decorateClass([
+  decorators_js.attr({ defaultValue: "all" })
+], SmartAdsenseElement.prototype, "display", 2);
+__decorateClass([
+  decorators_js.attr({ defaultValue: "lazy" })
+], SmartAdsenseElement.prototype, "loading", 2);
+__decorateClass([
+  decorators_js.jsonAttr()
+], SmartAdsenseElement.prototype, "params", 2);
+__decorateClass([
+  decorators_js.boolAttr()
+], SmartAdsenseElement.prototype, "inactive", 2);
+__decorateClass([
+  decorators_js.memoize()
+], SmartAdsenseElement.prototype, "config", 1);
+__decorateClass([
+  decorators_js.memoize()
+], SmartAdsenseElement.prototype, "displayQuery", 1);
+__decorateClass([
+  decorators_js.bind
+], SmartAdsenseElement.prototype, "hideAd", 1);
+__decorateClass([
+  decorators_js.bind
+], SmartAdsenseElement.prototype, "refreshAd", 1);
+__decorateClass([
+  decorators_js.listen({
+    event: "resize",
+    condition: ($this) => {
+      var _a;
+      return (_a = $this.config.refreshOnResize) != null ? _a : false;
+    },
+    target: core_js.ESLResizeObserverTarget.for
+  }),
+  decorators_js.decorate(async_js.debounce, 1e3)
+], SmartAdsenseElement.prototype, "_onResize", 1);
+__decorateClass([
+  decorators_js.listen("adsense:status")
+], SmartAdsenseElement.prototype, "_onAdsenseStatusChange", 1);
+__decorateClass([
+  decorators_js.listen({
+    event: intersection_target_js.ESLIntersectionEvent.IN,
+    once: true,
+    condition: (that) => that.loading !== "eager",
+    target: (that) => intersection_target_js.ESLIntersectionTarget.for(that, {
+      rootMargin: that.rootMargin,
+      threshold: that.INTERSECTION_THRESHOLD
+    })
+  })
+], SmartAdsenseElement.prototype, "_onIntersect", 1);
+__decorateClass([
+  decorators_js.listen({ event: "change", target: ($this) => $this.displayQuery })
+], SmartAdsenseElement.prototype, "_onDisplayChange", 1);
+__decorateClass([
+  decorators_js.decorate(async_js.microtask)
+], SmartAdsenseElement.prototype, "_onStatusChange", 1);
+
+exports.STATUS_EVENT = STATUS_EVENT;
+exports.SmartAdsense = SmartAdsense;
+exports.SmartAdsenseElement = SmartAdsenseElement;

package/dist/index.d.cts

@@ -0,0 +1,113 @@
+import { SmartServiceOptions, SmartService } from 'smart-load-manager';
+import { ESLBaseElement } from '@exadel/esl/modules/esl-base-element/core';
+import { DelayedTask } from '@exadel/esl/modules/esl-utils/async';
+import { ESLIntersectionEvent } from '@exadel/esl/modules/esl-event-listener/core/targets/intersection.target';
+import { ESLMediaQuery, ESLMediaChangeEvent } from '@exadel/esl/modules/esl-media-query/core';
+import { ESLElementResizeEvent } from '@exadel/esl/modules/esl-event-listener/core';
+
+/** Configuration options for SmartAdsense */
+interface SmartAdsenseOptions extends SmartServiceOptions {
+    /** Retrying unfilled ads: delay between retry attempts in seconds, 0 means no retrying */
+    retryDelay: number;
+    /** Retrying unfilled ads: number of retry attempts, 0 means infinite */
+    retryCount: number;
+    /** Refreshing filled ads: interval in seconds, 0 means no refresh */
+    refreshInterval: number;
+    /** Refreshing filled ads: refresh on ad block resize, false means no refresh */
+    refreshOnResize: boolean;
+}
+declare const STATUS_EVENT = "adsense:status";
+/** SmartAdsense service class for managing adsense scripts and status observing */
+declare class SmartAdsense extends SmartService {
+    protected static _config: SmartAdsenseOptions;
+    protected _initStatusObserving(): void;
+    protected _onMutation(mutations: MutationRecord[]): void;
+    protected _onLoadScript(): void;
+}
+
+/** SmartAdsense web component for displaying Adsense ads */
+declare class SmartAdsenseElement extends ESLBaseElement {
+    static is: string;
+    static observedAttributes: string[];
+    baseMargin: number;
+    protected INTERSECTION_THRESHOLD: number[];
+    CHANGE_EVENT: string;
+    /** Condition {@link ESLMediaQuery} to allow display of ad. Default: `all` */
+    display: string;
+    /** Ad loading strategy ('lazy' or 'eager'). Default: `lazy` */
+    loading: string;
+    /** Configuration parameters for SmartAdsense */
+    params: Partial<SmartAdsenseOptions>;
+    /** Inactive state of the ad (not loaded until becomes active) */
+    inactive: boolean;
+    protected _content: string;
+    protected _lastWidth: number;
+    protected _retries: number;
+    protected _status: string;
+    protected _task: DelayedTask;
+    /** Current configuration */
+    get config(): SmartAdsenseOptions;
+    /** ESLMediaQuery to limit display */
+    protected get displayQuery(): ESLMediaQuery;
+    /** Check if ad content is empty */
+    protected get isEmpty(): boolean;
+    /** Current ad status */
+    get status(): string;
+    set status(value: string);
+    /** IntersectionObserver rootMargin value */
+    protected get rootMargin(): string;
+    /** Connection speed ratio */
+    protected get connectionRatio(): number;
+    protected connectedCallback(): void;
+    protected disconnectedCallback(): void;
+    protected attributeChangedCallback(attrName: string, oldVal: string, newVal: string): void;
+    /** Initializes ad */
+    protected init(): Promise<void>;
+    /** Sets initial a11y attributes */
+    protected initA11y(): void;
+    /** Stores initial ad content */
+    protected storeContent(): void;
+    /** Restores initial ad content */
+    protected restoreContent(): void;
+    /** Pushes ad to the DOM */
+    protected pushAd(): void;
+    /** Hides the ad */
+    protected hideAd(): void;
+    /** Refreshes the ad */
+    protected refreshAd(): void;
+    /** Handles resize of ad */
+    protected _onResize(event: ESLElementResizeEvent): void;
+    /** Handles adsense status change */
+    protected _onAdsenseStatusChange(event: CustomEvent): void;
+    /** Handles intersection event to initialize ad loading */
+    protected _onIntersect(e: ESLIntersectionEvent): void;
+    /** Handles display query change and processes reinitialization of ad */
+    protected _onDisplayChange(event?: ESLMediaChangeEvent): void;
+    /** Handles status changing */
+    protected _onStatusChange(): void;
+    /** Logs messages to the console if debug mode is enabled */
+    protected _log(...args: unknown[]): void;
+}
+declare global {
+    export interface HTMLElementTagNameMap {
+        'smart-adsense': SmartAdsenseElement;
+    }
+    let adsbygoogle: {
+        [key: string]: unknown;
+    }[];
+    interface Window {
+        adsbygoogle: {
+            [key: string]: unknown;
+        }[];
+    }
+    interface Navigator extends NavigatorNetworkInformation {
+    }
+    interface NavigatorNetworkInformation {
+        readonly connection?: {
+            readonly effectiveType: 'slow-2g' | '2g' | '3g' | '4g';
+        };
+    }
+}
+
+export { STATUS_EVENT, SmartAdsense, SmartAdsenseElement };
+export type { SmartAdsenseOptions };

package/dist/index.d.mts

@@ -0,0 +1,113 @@
+import { SmartServiceOptions, SmartService } from 'smart-load-manager';
+import { ESLBaseElement } from '@exadel/esl/modules/esl-base-element/core';
+import { DelayedTask } from '@exadel/esl/modules/esl-utils/async';
+import { ESLIntersectionEvent } from '@exadel/esl/modules/esl-event-listener/core/targets/intersection.target';
+import { ESLMediaQuery, ESLMediaChangeEvent } from '@exadel/esl/modules/esl-media-query/core';
+import { ESLElementResizeEvent } from '@exadel/esl/modules/esl-event-listener/core';
+
+/** Configuration options for SmartAdsense */
+interface SmartAdsenseOptions extends SmartServiceOptions {
+    /** Retrying unfilled ads: delay between retry attempts in seconds, 0 means no retrying */
+    retryDelay: number;
+    /** Retrying unfilled ads: number of retry attempts, 0 means infinite */
+    retryCount: number;
+    /** Refreshing filled ads: interval in seconds, 0 means no refresh */
+    refreshInterval: number;
+    /** Refreshing filled ads: refresh on ad block resize, false means no refresh */
+    refreshOnResize: boolean;
+}
+declare const STATUS_EVENT = "adsense:status";
+/** SmartAdsense service class for managing adsense scripts and status observing */
+declare class SmartAdsense extends SmartService {
+    protected static _config: SmartAdsenseOptions;
+    protected _initStatusObserving(): void;
+    protected _onMutation(mutations: MutationRecord[]): void;
+    protected _onLoadScript(): void;
+}
+
+/** SmartAdsense web component for displaying Adsense ads */
+declare class SmartAdsenseElement extends ESLBaseElement {
+    static is: string;
+    static observedAttributes: string[];
+    baseMargin: number;
+    protected INTERSECTION_THRESHOLD: number[];
+    CHANGE_EVENT: string;
+    /** Condition {@link ESLMediaQuery} to allow display of ad. Default: `all` */
+    display: string;
+    /** Ad loading strategy ('lazy' or 'eager'). Default: `lazy` */
+    loading: string;
+    /** Configuration parameters for SmartAdsense */
+    params: Partial<SmartAdsenseOptions>;
+    /** Inactive state of the ad (not loaded until becomes active) */
+    inactive: boolean;
+    protected _content: string;
+    protected _lastWidth: number;
+    protected _retries: number;
+    protected _status: string;
+    protected _task: DelayedTask;
+    /** Current configuration */
+    get config(): SmartAdsenseOptions;
+    /** ESLMediaQuery to limit display */
+    protected get displayQuery(): ESLMediaQuery;
+    /** Check if ad content is empty */
+    protected get isEmpty(): boolean;
+    /** Current ad status */
+    get status(): string;
+    set status(value: string);
+    /** IntersectionObserver rootMargin value */
+    protected get rootMargin(): string;
+    /** Connection speed ratio */
+    protected get connectionRatio(): number;
+    protected connectedCallback(): void;
+    protected disconnectedCallback(): void;
+    protected attributeChangedCallback(attrName: string, oldVal: string, newVal: string): void;
+    /** Initializes ad */
+    protected init(): Promise<void>;
+    /** Sets initial a11y attributes */
+    protected initA11y(): void;
+    /** Stores initial ad content */
+    protected storeContent(): void;
+    /** Restores initial ad content */
+    protected restoreContent(): void;
+    /** Pushes ad to the DOM */
+    protected pushAd(): void;
+    /** Hides the ad */
+    protected hideAd(): void;
+    /** Refreshes the ad */
+    protected refreshAd(): void;
+    /** Handles resize of ad */
+    protected _onResize(event: ESLElementResizeEvent): void;
+    /** Handles adsense status change */
+    protected _onAdsenseStatusChange(event: CustomEvent): void;
+    /** Handles intersection event to initialize ad loading */
+    protected _onIntersect(e: ESLIntersectionEvent): void;
+    /** Handles display query change and processes reinitialization of ad */
+    protected _onDisplayChange(event?: ESLMediaChangeEvent): void;
+    /** Handles status changing */
+    protected _onStatusChange(): void;
+    /** Logs messages to the console if debug mode is enabled */
+    protected _log(...args: unknown[]): void;
+}
+declare global {
+    export interface HTMLElementTagNameMap {
+        'smart-adsense': SmartAdsenseElement;
+    }
+    let adsbygoogle: {
+        [key: string]: unknown;
+    }[];
+    interface Window {
+        adsbygoogle: {
+            [key: string]: unknown;
+        }[];
+    }
+    interface Navigator extends NavigatorNetworkInformation {
+    }
+    interface NavigatorNetworkInformation {
+        readonly connection?: {
+            readonly effectiveType: 'slow-2g' | '2g' | '3g' | '4g';
+        };
+    }
+}
+
+export { STATUS_EVENT, SmartAdsense, SmartAdsenseElement };
+export type { SmartAdsenseOptions };

package/dist/index.mjs

@@ -0,0 +1,325 @@
+import { dispatchCustomEvent } from '@exadel/esl/modules/esl-utils/dom.js';
+import { SmartService } from 'smart-load-manager';
+import { ESLBaseElement } from '@exadel/esl/modules/esl-base-element/core.js';
+import { prop, attr, jsonAttr, boolAttr, memoize, bind, listen, decorate } from '@exadel/esl/modules/esl-utils/decorators.js';
+import { debounce, microtask, DelayedTask } from '@exadel/esl/modules/esl-utils/async.js';
+import { ESLResizeObserverTarget } from '@exadel/esl/modules/esl-event-listener/core.js';
+import { ESLIntersectionTarget, ESLIntersectionEvent } from '@exadel/esl/modules/esl-event-listener/core/targets/intersection.target.js';
+import { ESLMediaQuery } from '@exadel/esl/modules/esl-media-query/core.js';
+
+const STATUS_EVENT = "adsense:status";
+const AD_STATUS_ATTR = "data-ad-status";
+const ADSBYGOOGLE_STATUS_ATTR = "data-adsbygoogle-status";
+class SmartAdsense extends SmartService {
+  _initStatusObserving() {
+    if (typeof document === "undefined" || typeof MutationObserver === "undefined") return;
+    const mutation$$ = new MutationObserver(this._onMutation);
+    mutation$$.observe(document.documentElement, {
+      subtree: true,
+      childList: true,
+      attributes: true,
+      attributeFilter: [AD_STATUS_ATTR, ADSBYGOOGLE_STATUS_ATTR]
+    });
+  }
+  _onMutation(mutations) {
+    mutations.forEach((record) => {
+      const { attributeName, target, type } = record;
+      if (type !== "attributes" || attributeName !== AD_STATUS_ATTR && attributeName !== ADSBYGOOGLE_STATUS_ATTR) return;
+      const { adStatus, adsbygoogleStatus } = target.dataset;
+      if (adStatus) {
+        dispatchCustomEvent(target, STATUS_EVENT, { detail: adStatus });
+        return;
+      }
+      if (adsbygoogleStatus === "done" && !adStatus) {
+        const status = target.innerHTML.trim() === "" ? "unfilled" : "filled";
+        dispatchCustomEvent(target, STATUS_EVENT, { detail: status });
+      }
+    });
+  }
+  _onLoadScript() {
+    super._onLoadScript();
+    this._initStatusObserving();
+  }
+}
+SmartAdsense._config = {
+  name: "Adsense",
+  retryDelay: 20,
+  retryCount: 3,
+  refreshInterval: 0,
+  refreshOnResize: false,
+  attrs: { crossorigin: "anonymous" }
+};
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop2 in b || (b = {}))
+    if (__hasOwnProp.call(b, prop2))
+      __defNormalProp(a, prop2, b[prop2]);
+  if (__getOwnPropSymbols)
+    for (var prop2 of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop2))
+        __defNormalProp(a, prop2, b[prop2]);
+    }
+  return a;
+};
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+var __async = (__this, __arguments, generator) => {
+  return new Promise((resolve, reject) => {
+    var fulfilled = (value) => {
+      try {
+        step(generator.next(value));
+      } catch (e) {
+        reject(e);
+      }
+    };
+    var rejected = (value) => {
+      try {
+        step(generator.throw(value));
+      } catch (e) {
+        reject(e);
+      }
+    };
+    var step = (x) => x.done ? resolve(x.value) : Promise.resolve(x.value).then(fulfilled, rejected);
+    step((generator = generator.apply(__this, __arguments)).next());
+  });
+};
+class SmartAdsenseElement extends ESLBaseElement {
+  constructor() {
+    super(...arguments);
+    this.params = {};
+    this.inactive = true;
+    this._content = "";
+    this._lastWidth = 0;
+    this._retries = 0;
+    this._status = "init";
+    this._task = new DelayedTask();
+  }
+  get config() {
+    return __spreadValues(__spreadValues({}, SmartAdsense.config()), this.params || {});
+  }
+  get displayQuery() {
+    return ESLMediaQuery.for(this.display);
+  }
+  /** Check if ad content is empty */
+  get isEmpty() {
+    return this._content.trim() === "";
+  }
+  /** Current ad status */
+  get status() {
+    return this._status;
+  }
+  set status(value) {
+    if (this._status === value) return;
+    this.setAttribute("status", this._status = value);
+    this._onStatusChange();
+  }
+  /** IntersectionObserver rootMargin value */
+  get rootMargin() {
+    return `${this.baseMargin * this.connectionRatio}px`;
+  }
+  /** Connection speed ratio */
+  get connectionRatio() {
+    var _a;
+    switch ((_a = navigator.connection) == null ? void 0 : _a.effectiveType) {
+      case "slow-2g":
+      case "2g":
+        return 2;
+      case "3g":
+        return 1.5;
+      case "4g":
+      default:
+        return 1;
+    }
+  }
+  connectedCallback() {
+    super.connectedCallback();
+    this.inactive = this.loading !== "eager";
+    this.storeContent();
+    this.init();
+    this.initA11y();
+  }
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.restoreContent();
+  }
+  attributeChangedCallback(attrName, oldVal, newVal) {
+    if (!this.connected) return;
+    if (attrName === "display") {
+      memoize.clear(this, "displayQuery");
+      this.$$on(this._onDisplayChange);
+      this.init();
+    }
+  }
+  /** Initializes ad */
+  init() {
+    return __async(this, null, function* () {
+      if (this.isEmpty) return;
+      if (!this.displayQuery.matches) {
+        this._task.put(this.hideAd);
+        return;
+      }
+      if (this.inactive) return;
+      try {
+        yield SmartAdsense.instance.load();
+        this._task.put(this.refreshAd, 0);
+      } catch (e) {
+        this.status = "failed";
+      }
+    });
+  }
+  /** Sets initial a11y attributes */
+  initA11y() {
+    if (!this.hasAttribute("role")) this.setAttribute("role", "complementary");
+  }
+  /** Stores initial ad content */
+  storeContent() {
+    this._content = this.innerHTML;
+    this.innerHTML = "";
+  }
+  /** Restores initial ad content */
+  restoreContent() {
+    this.innerHTML = this._content;
+  }
+  /** Pushes ad to the DOM */
+  pushAd() {
+    try {
+      (adsbygoogle = window.adsbygoogle || []).push({});
+    } catch (e) {
+    }
+  }
+  hideAd() {
+    this.status = "hidden";
+    this.innerHTML = "";
+    this._retries = 0;
+  }
+  refreshAd() {
+    this.status = "pending";
+    this._retries++;
+    this.restoreContent();
+    this.pushAd();
+  }
+  _onResize(event) {
+    const { contentRect } = event;
+    if (this._lastWidth === contentRect.width) return;
+    if (this._lastWidth > 0 && this.status === "filled") {
+      this._retries = 0;
+      this._task.put(this.refreshAd, 0);
+      this._log("Ad is refreshing on resize", this._lastWidth);
+    }
+    this._lastWidth = contentRect.width;
+  }
+  _onAdsenseStatusChange(event) {
+    this._log("Ad status:", event.detail);
+    this.status = event.detail;
+    if (event.detail === "unfilled") {
+      const { retryCount, retryDelay } = this.config;
+      const canRetry = retryCount === 0 || this._retries < retryCount;
+      if (retryDelay > 0 && canRetry) {
+        this._task.put(this.refreshAd, retryDelay * 1e3);
+        this._log(`Ad unfilled will be reattempted in ${retryDelay}s (${this._retries})`);
+      }
+    } else {
+      const { refreshInterval } = this.config;
+      this._log("Refresh interval:", refreshInterval);
+      if (refreshInterval > 0) {
+        this._task.put(this.refreshAd, (refreshInterval + Math.random()) * 1e3);
+        this._log(`Ad filled will be refreshed in ${refreshInterval}s [${this._retries}]`);
+      }
+    }
+  }
+  _onIntersect(e) {
+    this.inactive = false;
+    this.init();
+  }
+  _onDisplayChange(event) {
+    this.init();
+  }
+  _onStatusChange() {
+    dispatchCustomEvent(this, "smart-adsense:change", { bubbles: false });
+  }
+  /** Logs messages to the console if debug mode is enabled */
+  _log(...args) {
+    if (!this.config.debug) return;
+    console.log(...args);
+  }
+}
+SmartAdsenseElement.is = "smart-adsense";
+SmartAdsenseElement.observedAttributes = ["display"];
+__decorateClass([
+  prop(750)
+], SmartAdsenseElement.prototype, "baseMargin", 2);
+__decorateClass([
+  prop([0, 0.01])
+], SmartAdsenseElement.prototype, "INTERSECTION_THRESHOLD", 2);
+__decorateClass([
+  prop("smart-adsense:change")
+], SmartAdsenseElement.prototype, "CHANGE_EVENT", 2);
+__decorateClass([
+  attr({ defaultValue: "all" })
+], SmartAdsenseElement.prototype, "display", 2);
+__decorateClass([
+  attr({ defaultValue: "lazy" })
+], SmartAdsenseElement.prototype, "loading", 2);
+__decorateClass([
+  jsonAttr()
+], SmartAdsenseElement.prototype, "params", 2);
+__decorateClass([
+  boolAttr()
+], SmartAdsenseElement.prototype, "inactive", 2);
+__decorateClass([
+  memoize()
+], SmartAdsenseElement.prototype, "config", 1);
+__decorateClass([
+  memoize()
+], SmartAdsenseElement.prototype, "displayQuery", 1);
+__decorateClass([
+  bind
+], SmartAdsenseElement.prototype, "hideAd", 1);
+__decorateClass([
+  bind
+], SmartAdsenseElement.prototype, "refreshAd", 1);
+__decorateClass([
+  listen({
+    event: "resize",
+    condition: ($this) => {
+      var _a;
+      return (_a = $this.config.refreshOnResize) != null ? _a : false;
+    },
+    target: ESLResizeObserverTarget.for
+  }),
+  decorate(debounce, 1e3)
+], SmartAdsenseElement.prototype, "_onResize", 1);
+__decorateClass([
+  listen("adsense:status")
+], SmartAdsenseElement.prototype, "_onAdsenseStatusChange", 1);
+__decorateClass([
+  listen({
+    event: ESLIntersectionEvent.IN,
+    once: true,
+    condition: (that) => that.loading !== "eager",
+    target: (that) => ESLIntersectionTarget.for(that, {
+      rootMargin: that.rootMargin,
+      threshold: that.INTERSECTION_THRESHOLD
+    })
+  })
+], SmartAdsenseElement.prototype, "_onIntersect", 1);
+__decorateClass([
+  listen({ event: "change", target: ($this) => $this.displayQuery })
+], SmartAdsenseElement.prototype, "_onDisplayChange", 1);
+__decorateClass([
+  decorate(microtask)
+], SmartAdsenseElement.prototype, "_onStatusChange", 1);
+
+export { STATUS_EVENT, SmartAdsense, SmartAdsenseElement };

package/dist/smart-adsense.css

@@ -0,0 +1,26 @@
+smart-adsense {
+  display: block;
+  overflow: hidden;
+}
+
+smart-adsense[status=hidden] {
+  display: none;
+}
+
+.smart-adsense-container {
+  display: flex;
+  align-items: center;
+}
+
+.smart-adsense-container smart-adsense {
+  height: 100%;
+  width: 100%;
+}
+
+.smart-adsense-container smart-adsense[status=filled] {
+  height: auto;
+}
+
+.smart-adsense-container:has(smart-adsense[status=hidden]) {
+  display: none;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "smart-adsense",
+  "version": "1.0.0",
+  "description": "A service and web component for enhanced loading and management of AdSense ad blocks in your web application",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    "require": {
+      "types": "./dist/index.d.cts",
+      "default": "./dist/index.cjs"
+    },
+    "import": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dshovchko/smart-services.git",
+    "directory": "packages/smart-adsense"
+  },
+  "keywords": [
+    "ads",
+    "adsense",
+    "lazy-load",
+    "web-component",
+    "performance",
+    "optimization",
+    "core-web-vitals"
+  ],
+  "author": "Dmytro Shovchko",
+  "license": "MIT",
+  "dependencies": {
+    "smart-load-manager": "^1.0.0"
+  },
+  "scripts": {
+    "clear": "rm -rf dist",
+    "build": "npm run clear && pkgroll && cp src/smart-adsense.css dist/",
+    "lint": "eslint \"src/**/*.ts\" --max-warnings 3",
+    "test": "npm run type-check && npm run lint && npm run test:run",
+    "test:run": "vitest run",
+    "test:watch": "vitest watch",
+    "type-check": "tsc --noEmit -p tsconfig.type-check.json"
+  },
+  "peerDependencies": {
+    "@exadel/esl": "^5.15.0"
+  }
+}