real-view 1.0.0

package/README.md

@@ -0,0 +1,197 @@
+# Real View 👁️
+
+[![npm version](https://img.shields.io/npm/v/real-view.svg?style=flat-square)](https://www.npmjs.com/package/real-view)
+[![minzipped size](https://img.shields.io/bundlephobia/minzip/real-view?style=flat-square)](https://bundlephobia.com/package/real-view)
+[![license](https://img.shields.io/npm/l/real-view?style=flat-square)](LICENSE)
+
+> **Stop guessing. Start knowing.**
+> The only visibility tracker that knows if your user *actually* sees the element.
+
+## Why? 🤔
+
+You use `IntersectionObserver` to track impressions. **You are lying to your analytics.**
+
+Native observers fail in these common scenarios:
+- ❌ **Occlusion:** A sticky header, modal, or dropdown covers the element.
+- ❌ **Opacity:** The element is transparent (`opacity: 0`) or `visibility: hidden`.
+- ❌ **Background Tabs:** The user switched tabs or minimized the browser.
+- ❌ **Zero Size:** The element collapsed to 0x0 pixels.
+
+**Real View** solves this. It combines `IntersectionObserver` with **DOM Raycasting**, **Computed Styles**, and **Page Visibility API** to guarantee physical visibility.
+
+- **Universal:** First-class support for React, Vue, Svelte, Solid, Angular, and Vanilla.
+- **Tiny:** ~1KB gzipped.
+- **Smart:** Uses `requestIdleCallback` to prevent main-thread blocking.
+
+---
+
+## Installation 📦
+
+```bash
+npm install real-view
+# or
+pnpm add real-view
+# or
+yarn add real-view
+```
+
+---
+
+## Usage 🚀
+
+### React
+
+Use the `useRealView` hook.
+
+```jsx
+import { useEffect } from 'react'
+import { useRealView } from 'real-view/react'
+
+const AdBanner = () => {
+    const [ref, isVisible] = useRealView({ pollInterval: 1000 })
+
+    useEffect(() => {
+        if (isVisible) console.log("User is ACTUALLY looking at this!")
+    }, [isVisible])
+
+    return <div ref={ref}>Buy Now</div>
+}
+
+```
+
+### Vue 3
+
+Use the `useRealView` composable.
+
+```html
+<script setup>
+    import { ref } from 'vue'
+    import { useRealView } from 'real-view/vue'
+
+    const el = ref(null)
+    const isVisible = useRealView(el)
+</script>
+
+<template>
+    <div ref="el">
+        Status: {{ isVisible ? 'SEEN' : 'HIDDEN' }}
+    </div>
+</template>
+
+```
+
+### Svelte
+
+Use the `realView` action.
+
+```svelte
+<script>
+  import { realView } from 'real-view/svelte'
+  let visible = false;
+</script>
+
+<div use:realView={{ onUpdate: (v) => visible = v }}>
+  I am {visible ? 'visible' : 'hidden'}
+</div>
+```
+
+### SolidJS
+
+Use the `realView` directive.
+
+```tsx
+iimport { createSignal } from 'solid-js';
+import { realView } from 'real-view/solid';
+
+// Typescript: declare module 'solid-js' { namespace JSX { interface Directives { realView: any; } } }
+
+function App() {
+    const [visible, setVisible] = createSignal(false);
+
+    return (
+        <div use:realView={{ onUpdate: setVisible }}>
+            {visible() ? "I see you!" : "Where are you?"}
+        </div>
+    );
+}
+
+```
+
+### Angular (14+)
+
+Use the standalone `RealViewDirective`.
+
+```typescript
+import { Component } from '@angular/core';
+import { RealViewDirective } from 'real-view/angular';
+
+@Component({
+    selector: 'app-tracker',
+    standalone: true,
+    imports: [RealViewDirective],
+    template: `
+    <div (realView)="onVisibilityChange($event)">
+      Track Me
+    </div>
+  `
+})
+export class TrackerComponent {
+    onVisibilityChange(isVisible: boolean) {
+        console.log('Visibility:', isVisible);
+    }
+}
+```
+
+### Vanilla JS
+
+```js
+import { RealView } from 'real-view'
+
+const el = document.querySelector('#banner')
+
+const cleanup = RealView.observe(el, (isVisible) => {
+    console.log(isVisible ? 'Visible' : 'Hidden')
+})
+
+// Later
+// cleanup()
+```
+
+---
+
+## Configuration ⚙️
+
+You can customize the strictness of the detection.
+
+```js
+// React example
+useRealView({
+    threshold: 0.5,
+    pollInterval: 500,
+    trackTab: true
+})
+```
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `threshold` | `number` | `0` | How much of the element must be in viewport (0.0 - 1.0). |
+| `pollInterval` | `number` | `1000` | How often (in ms) to check for occlusion (z-index). |
+| `trackTab` | `boolean` | `true` | If `true`, reports `false` when user switches browser tabs. |
+
+---
+
+## How it works 🧊
+
+Real View uses a **"Lazy Raycasting"** architecture to keep performance high:
+
+1. **Gatekeeper:** It uses `IntersectionObserver` first. If the element is off-screen, the CPU usage is **0%**.
+2. **Raycasting:** Once on-screen, it fires a ray (`document.elementFromPoint`) at the center of your element. If the ray hits a modal, a sticky header, or a dropdown menu instead of your element, visibility is `false`.
+3. **Style Audit:** It recursively checks `opacity`, `visibility`, and `display` up the DOM tree.
+4. **Tab Hygiene:** It listens to the Page Visibility API to pause tracking when the tab is backgrounded.
+
+## License
+
+MIT
+
+## Keywords
+`visibility` `viewport` `intersection` `occlusion` `tracking` `analytics` `impression` `react` `vue` `svelte` `angular` `solid` `dom` `monitor` `viewability`
+

package/dist/angular.cjs

@@ -0,0 +1,174 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+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;
+};
+
+// src/angular.ts
+var angular_exports = {};
+__export(angular_exports, {
+  realViewDirective: () => realViewDirective
+});
+module.exports = __toCommonJS(angular_exports);
+var import_core = require("@angular/core");
+
+// src/core/utils.ts
+var isBrowser = () => {
+  return typeof window !== "undefined" && typeof window.document !== "undefined";
+};
+
+// src/core/engine.ts
+var realViewEngine = class _realViewEngine {
+  constructor() {
+    this.observer = null;
+    this.watchers = /* @__PURE__ */ new Map();
+    if (!isBrowser()) return;
+    this.initObserver();
+    this.initTabListener();
+  }
+  static get() {
+    if (!this.instance) this.instance = new _realViewEngine();
+    return this.instance;
+  }
+  initObserver() {
+    this.observer = new IntersectionObserver(this.handleIntersect.bind(this), {
+      threshold: 0
+    });
+  }
+  initTabListener() {
+    document.addEventListener("visibilitychange", () => {
+      const isHidden = document.hidden;
+      this.watchers.forEach((w) => {
+        if (w.opts.trackTab && isHidden) {
+          this.notify(w, false);
+        } else if (w.state.inViewport && !isHidden) {
+          this.checkOcclusion(w);
+        }
+      });
+    });
+  }
+  handleIntersect(entries) {
+    entries.forEach((entry) => {
+      const watcher = this.watchers.get(entry.target);
+      if (!watcher) return;
+      watcher.state.inViewport = entry.isIntersecting;
+      if (entry.isIntersecting) {
+        this.startPolling(watcher);
+      } else {
+        this.stopPolling(watcher);
+        this.notify(watcher, false);
+      }
+    });
+  }
+  checkOcclusion(w) {
+    if (w.opts.trackTab && document.hidden) return this.notify(w, false);
+    const rect = w.el.getBoundingClientRect();
+    if (rect.width === 0 || rect.height === 0) return this.notify(w, false);
+    const style = window.getComputedStyle(w.el);
+    if (style.opacity === "0" || style.visibility === "hidden") return this.notify(w, false);
+    const x = rect.left + rect.width / 2;
+    const y = rect.top + rect.height / 2;
+    const topEl = document.elementFromPoint(x, y);
+    const isVisible = topEl ? w.el.contains(topEl) || w.el === topEl : false;
+    this.notify(w, isVisible);
+  }
+  startPolling(w) {
+    if (w.state.timer) return;
+    const tick = () => {
+      if ("requestIdleCallback" in window) {
+        window.requestIdleCallback(() => this.checkOcclusion(w));
+      } else {
+        this.checkOcclusion(w);
+      }
+    };
+    tick();
+    w.state.timer = window.setInterval(tick, w.opts.pollInterval);
+  }
+  stopPolling(w) {
+    if (w.state.timer) {
+      clearInterval(w.state.timer);
+      w.state.timer = null;
+    }
+  }
+  notify(w, isVisible) {
+    if (w.state.isOccluded !== !isVisible) {
+      w.state.isOccluded = !isVisible;
+      w.cb(isVisible);
+    }
+  }
+  observe(el, cb, options = {}) {
+    if (!isBrowser()) return () => {
+    };
+    const opts = {
+      threshold: 0,
+      pollInterval: 1e3,
+      trackTab: true,
+      ...options
+    };
+    this.watchers.set(el, {
+      el,
+      cb,
+      opts,
+      state: { inViewport: false, isOccluded: false, timer: null }
+    });
+    this.observer?.observe(el);
+    return () => {
+      this.stopPolling(this.watchers.get(el));
+      this.observer?.unobserve(el);
+      this.watchers.delete(el);
+    };
+  }
+};
+
+// src/angular.ts
+var realViewDirective = class {
+  constructor(el) {
+    this.el = el;
+    this.visibleChange = new import_core.EventEmitter();
+    this.stop = null;
+  }
+  ngOnInit() {
+    this.stop = realViewEngine.get().observe(this.el.nativeElement, (v) => {
+      this.visibleChange.emit(v);
+    }, this.options);
+  }
+  ngOnDestroy() {
+    this.stop?.();
+  }
+};
+__decorateClass([
+  (0, import_core.Input)()
+], realViewDirective.prototype, "options", 2);
+__decorateClass([
+  (0, import_core.Output)()
+], realViewDirective.prototype, "visibleChange", 2);
+realViewDirective = __decorateClass([
+  (0, import_core.Directive)({
+    selector: "[realView]",
+    standalone: true
+  })
+], realViewDirective);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  realViewDirective
+});

package/dist/angular.d.cts

@@ -0,0 +1,14 @@
+import { OnInit, OnDestroy, EventEmitter, ElementRef } from '@angular/core';
+import { realViewOptions } from './index.cjs';
+
+declare class realViewDirective implements OnInit, OnDestroy {
+    private el;
+    options?: realViewOptions;
+    visibleChange: EventEmitter<boolean>;
+    private stop;
+    constructor(el: ElementRef);
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+}
+
+export { realViewDirective };

package/dist/angular.d.ts

@@ -0,0 +1,14 @@
+import { OnInit, OnDestroy, EventEmitter, ElementRef } from '@angular/core';
+import { realViewOptions } from './index.js';
+
+declare class realViewDirective implements OnInit, OnDestroy {
+    private el;
+    options?: realViewOptions;
+    visibleChange: EventEmitter<boolean>;
+    private stop;
+    constructor(el: ElementRef);
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+}
+
+export { realViewDirective };

package/dist/angular.js

@@ -0,0 +1,37 @@
+import {
+  __decorateClass,
+  realViewEngine
+} from "./chunk-UW5FKFTH.js";
+
+// src/angular.ts
+import { Directive, Output, EventEmitter, Input } from "@angular/core";
+var realViewDirective = class {
+  constructor(el) {
+    this.el = el;
+    this.visibleChange = new EventEmitter();
+    this.stop = null;
+  }
+  ngOnInit() {
+    this.stop = realViewEngine.get().observe(this.el.nativeElement, (v) => {
+      this.visibleChange.emit(v);
+    }, this.options);
+  }
+  ngOnDestroy() {
+    this.stop?.();
+  }
+};
+__decorateClass([
+  Input()
+], realViewDirective.prototype, "options", 2);
+__decorateClass([
+  Output()
+], realViewDirective.prototype, "visibleChange", 2);
+realViewDirective = __decorateClass([
+  Directive({
+    selector: "[realView]",
+    standalone: true
+  })
+], realViewDirective);
+export {
+  realViewDirective
+};

package/dist/chunk-UW5FKFTH.js

@@ -0,0 +1,123 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+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;
+};
+
+// src/core/utils.ts
+var isBrowser = () => {
+  return typeof window !== "undefined" && typeof window.document !== "undefined";
+};
+
+// src/core/engine.ts
+var realViewEngine = class _realViewEngine {
+  constructor() {
+    this.observer = null;
+    this.watchers = /* @__PURE__ */ new Map();
+    if (!isBrowser()) return;
+    this.initObserver();
+    this.initTabListener();
+  }
+  static get() {
+    if (!this.instance) this.instance = new _realViewEngine();
+    return this.instance;
+  }
+  initObserver() {
+    this.observer = new IntersectionObserver(this.handleIntersect.bind(this), {
+      threshold: 0
+    });
+  }
+  initTabListener() {
+    document.addEventListener("visibilitychange", () => {
+      const isHidden = document.hidden;
+      this.watchers.forEach((w) => {
+        if (w.opts.trackTab && isHidden) {
+          this.notify(w, false);
+        } else if (w.state.inViewport && !isHidden) {
+          this.checkOcclusion(w);
+        }
+      });
+    });
+  }
+  handleIntersect(entries) {
+    entries.forEach((entry) => {
+      const watcher = this.watchers.get(entry.target);
+      if (!watcher) return;
+      watcher.state.inViewport = entry.isIntersecting;
+      if (entry.isIntersecting) {
+        this.startPolling(watcher);
+      } else {
+        this.stopPolling(watcher);
+        this.notify(watcher, false);
+      }
+    });
+  }
+  checkOcclusion(w) {
+    if (w.opts.trackTab && document.hidden) return this.notify(w, false);
+    const rect = w.el.getBoundingClientRect();
+    if (rect.width === 0 || rect.height === 0) return this.notify(w, false);
+    const style = window.getComputedStyle(w.el);
+    if (style.opacity === "0" || style.visibility === "hidden") return this.notify(w, false);
+    const x = rect.left + rect.width / 2;
+    const y = rect.top + rect.height / 2;
+    const topEl = document.elementFromPoint(x, y);
+    const isVisible = topEl ? w.el.contains(topEl) || w.el === topEl : false;
+    this.notify(w, isVisible);
+  }
+  startPolling(w) {
+    if (w.state.timer) return;
+    const tick = () => {
+      if ("requestIdleCallback" in window) {
+        window.requestIdleCallback(() => this.checkOcclusion(w));
+      } else {
+        this.checkOcclusion(w);
+      }
+    };
+    tick();
+    w.state.timer = window.setInterval(tick, w.opts.pollInterval);
+  }
+  stopPolling(w) {
+    if (w.state.timer) {
+      clearInterval(w.state.timer);
+      w.state.timer = null;
+    }
+  }
+  notify(w, isVisible) {
+    if (w.state.isOccluded !== !isVisible) {
+      w.state.isOccluded = !isVisible;
+      w.cb(isVisible);
+    }
+  }
+  observe(el, cb, options = {}) {
+    if (!isBrowser()) return () => {
+    };
+    const opts = {
+      threshold: 0,
+      pollInterval: 1e3,
+      trackTab: true,
+      ...options
+    };
+    this.watchers.set(el, {
+      el,
+      cb,
+      opts,
+      state: { inViewport: false, isOccluded: false, timer: null }
+    });
+    this.observer?.observe(el);
+    return () => {
+      this.stopPolling(this.watchers.get(el));
+      this.observer?.unobserve(el);
+      this.watchers.delete(el);
+    };
+  }
+};
+
+export {
+  __decorateClass,
+  realViewEngine
+};

package/dist/index.cjs

@@ -0,0 +1,136 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  realViewEngine: () => realViewEngine
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/core/utils.ts
+var isBrowser = () => {
+  return typeof window !== "undefined" && typeof window.document !== "undefined";
+};
+
+// src/core/engine.ts
+var realViewEngine = class _realViewEngine {
+  constructor() {
+    this.observer = null;
+    this.watchers = /* @__PURE__ */ new Map();
+    if (!isBrowser()) return;
+    this.initObserver();
+    this.initTabListener();
+  }
+  static get() {
+    if (!this.instance) this.instance = new _realViewEngine();
+    return this.instance;
+  }
+  initObserver() {
+    this.observer = new IntersectionObserver(this.handleIntersect.bind(this), {
+      threshold: 0
+    });
+  }
+  initTabListener() {
+    document.addEventListener("visibilitychange", () => {
+      const isHidden = document.hidden;
+      this.watchers.forEach((w) => {
+        if (w.opts.trackTab && isHidden) {
+          this.notify(w, false);
+        } else if (w.state.inViewport && !isHidden) {
+          this.checkOcclusion(w);
+        }
+      });
+    });
+  }
+  handleIntersect(entries) {
+    entries.forEach((entry) => {
+      const watcher = this.watchers.get(entry.target);
+      if (!watcher) return;
+      watcher.state.inViewport = entry.isIntersecting;
+      if (entry.isIntersecting) {
+        this.startPolling(watcher);
+      } else {
+        this.stopPolling(watcher);
+        this.notify(watcher, false);
+      }
+    });
+  }
+  checkOcclusion(w) {
+    if (w.opts.trackTab && document.hidden) return this.notify(w, false);
+    const rect = w.el.getBoundingClientRect();
+    if (rect.width === 0 || rect.height === 0) return this.notify(w, false);
+    const style = window.getComputedStyle(w.el);
+    if (style.opacity === "0" || style.visibility === "hidden") return this.notify(w, false);
+    const x = rect.left + rect.width / 2;
+    const y = rect.top + rect.height / 2;
+    const topEl = document.elementFromPoint(x, y);
+    const isVisible = topEl ? w.el.contains(topEl) || w.el === topEl : false;
+    this.notify(w, isVisible);
+  }
+  startPolling(w) {
+    if (w.state.timer) return;
+    const tick = () => {
+      if ("requestIdleCallback" in window) {
+        window.requestIdleCallback(() => this.checkOcclusion(w));
+      } else {
+        this.checkOcclusion(w);
+      }
+    };
+    tick();
+    w.state.timer = window.setInterval(tick, w.opts.pollInterval);
+  }
+  stopPolling(w) {
+    if (w.state.timer) {
+      clearInterval(w.state.timer);
+      w.state.timer = null;
+    }
+  }
+  notify(w, isVisible) {
+    if (w.state.isOccluded !== !isVisible) {
+      w.state.isOccluded = !isVisible;
+      w.cb(isVisible);
+    }
+  }
+  observe(el, cb, options = {}) {
+    if (!isBrowser()) return () => {
+    };
+    const opts = {
+      threshold: 0,
+      pollInterval: 1e3,
+      trackTab: true,
+      ...options
+    };
+    this.watchers.set(el, {
+      el,
+      cb,
+      opts,
+      state: { inViewport: false, isOccluded: false, timer: null }
+    });
+    this.observer?.observe(el);
+    return () => {
+      this.stopPolling(this.watchers.get(el));
+      this.observer?.unobserve(el);
+      this.watchers.delete(el);
+    };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  realViewEngine
+});