@macrulez/inview-core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,153 @@
+type ScrollDirection = 'up' | 'down' | 'left' | 'right' | null;
+interface ScrollState {
+    x: number;
+    y: number;
+    direction: ScrollDirection;
+    /** 0..1 */
+    progress: number;
+    /** px per frame */
+    velocity: number;
+    isScrolling: boolean;
+}
+interface ScrollToOptions {
+    behavior?: 'auto' | 'smooth';
+}
+interface ScrollEngineOptions {
+    /** ms of scroll inactivity before isScrolling flips back to false */
+    idleTimeout?: number;
+}
+interface ScrollEngine {
+    getState(): ScrollState;
+    /** returns unsubscribe */
+    subscribe(cb: (state: ScrollState) => void): () => void;
+    scrollTo(pos: number | {
+        x?: number;
+        y?: number;
+    }, opts?: ScrollToOptions): void;
+    destroy(): void;
+}
+type IntersectionEdge = 'enter-top' | 'enter-bottom' | 'leave-top' | 'leave-bottom';
+interface IntersectionInfo {
+    isIntersecting: boolean;
+    intersectionRatio: number;
+    boundingClientRect: DOMRectReadOnly;
+    edge?: IntersectionEdge;
+}
+interface ObserverPoolOptions {
+    root?: Element | Document | null;
+    rootMargin?: string;
+    threshold?: number | number[];
+}
+interface VisibilityObserveOptions extends ObserverPoolOptions {
+    once?: boolean;
+    onEnter?: (info: IntersectionInfo) => void;
+    onLeave?: (info: IntersectionInfo) => void;
+}
+interface VisibilityEngine {
+    /** returns unsubscribe */
+    observe(el: Element, options: VisibilityObserveOptions, cb: (info: IntersectionInfo) => void): () => void;
+    destroy(): void;
+}
+interface DOMRectLike {
+    top: number;
+    left: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+}
+interface ElementTrackerState {
+    rect: DOMRectLike;
+    /** 0..1, from element entering at viewport bottom to leaving at viewport top */
+    viewportProgress: number;
+    /** px offset of element center from viewport center */
+    distanceFromCenter: number;
+}
+interface ElementTracker {
+    getState(): ElementTrackerState;
+    subscribe(cb: (state: ElementTrackerState) => void): () => void;
+    destroy(): void;
+}
+
+type ScrollTarget = Window | HTMLElement;
+/**
+ * Framework-agnostic scroll engine for window or a scrollable element.
+ * Batches DOM scroll events into one shared rAF loop and notifies
+ * subscribers only when the derived state actually changes.
+ */
+declare function createScrollEngine(target?: ScrollTarget, options?: ScrollEngineOptions): ScrollEngine;
+
+type EntryCallback = (entry: IntersectionObserverEntry) => void;
+/**
+ * Pools IntersectionObserver instances by (root, rootMargin, threshold),
+ * so many observed elements sharing the same options share one observer
+ * instead of spawning one per element.
+ */
+declare class ObserverPool {
+    private pools;
+    observe(el: Element, options: ObserverPoolOptions, cb: EntryCallback): () => void;
+}
+declare const observerPool: ObserverPool;
+
+/**
+ * Wraps the shared observer pool with enter/leave edge detection and
+ * `once` support, without any framework-specific reactivity.
+ */
+declare function createVisibilityEngine(pool?: ObserverPool): VisibilityEngine;
+
+/**
+ * Tracks an element's position relative to the viewport (rect,
+ * viewportProgress, distanceFromCenter) on the shared rAF loop.
+ */
+declare function createElementTracker(el: HTMLElement): ElementTracker;
+
+type Tick = (time: number) => void;
+/**
+ * One shared requestAnimationFrame loop for the whole engine, instead of
+ * every scroll/tracker subscription running its own rAF callback.
+ */
+declare class RafLoop {
+    private callbacks;
+    private handle;
+    add(cb: Tick): () => void;
+    private start;
+    private stop;
+}
+declare const rafLoop: RafLoop;
+
+/**
+ * Linearly maps `value` from the `from` range into the `to` range.
+ * Pass `clampResult: true` to keep the result within `to` at the edges.
+ */
+declare function mapRange(value: number, from: [number, number], to: [number, number], clampResult?: boolean): number;
+
+/**
+ * Writes a numeric progress value into a CSS custom property on `el`,
+ * so the resulting visual effect can be composed in plain CSS.
+ */
+declare function bindCSSVar(el: HTMLElement, name: string, value: number | string): void;
+
+declare function prefersReducedMotion(): boolean;
+
+declare function clamp(value: number, min: number, max: number): number;
+
+type Easing = (t: number) => number;
+/**
+ * Standard easing presets to apply to a 0..1 progress value before
+ * feeding it into an effect (parallax offset, CSS var, etc).
+ */
+declare const easings: {
+    linear: (t: number) => number;
+    easeInQuad: (t: number) => number;
+    easeOutQuad: (t: number) => number;
+    easeInOutQuad: (t: number) => number;
+    easeInCubic: (t: number) => number;
+    easeOutCubic: (t: number) => number;
+    easeInOutCubic: (t: number) => number;
+    easeInSine: (t: number) => number;
+    easeOutSine: (t: number) => number;
+    easeInOutSine: (t: number) => number;
+};
+type EasingName = keyof typeof easings;
+
+export { type DOMRectLike, type Easing, type EasingName, type ElementTracker, type ElementTrackerState, type IntersectionEdge, type IntersectionInfo, ObserverPool, type ObserverPoolOptions, type ScrollDirection, type ScrollEngine, type ScrollEngineOptions, type ScrollState, type ScrollToOptions, type VisibilityEngine, type VisibilityObserveOptions, bindCSSVar, clamp, createElementTracker, createScrollEngine, createVisibilityEngine, easings, mapRange, observerPool, prefersReducedMotion, rafLoop };

package/dist/index.d.ts

@@ -0,0 +1,153 @@
+type ScrollDirection = 'up' | 'down' | 'left' | 'right' | null;
+interface ScrollState {
+    x: number;
+    y: number;
+    direction: ScrollDirection;
+    /** 0..1 */
+    progress: number;
+    /** px per frame */
+    velocity: number;
+    isScrolling: boolean;
+}
+interface ScrollToOptions {
+    behavior?: 'auto' | 'smooth';
+}
+interface ScrollEngineOptions {
+    /** ms of scroll inactivity before isScrolling flips back to false */
+    idleTimeout?: number;
+}
+interface ScrollEngine {
+    getState(): ScrollState;
+    /** returns unsubscribe */
+    subscribe(cb: (state: ScrollState) => void): () => void;
+    scrollTo(pos: number | {
+        x?: number;
+        y?: number;
+    }, opts?: ScrollToOptions): void;
+    destroy(): void;
+}
+type IntersectionEdge = 'enter-top' | 'enter-bottom' | 'leave-top' | 'leave-bottom';
+interface IntersectionInfo {
+    isIntersecting: boolean;
+    intersectionRatio: number;
+    boundingClientRect: DOMRectReadOnly;
+    edge?: IntersectionEdge;
+}
+interface ObserverPoolOptions {
+    root?: Element | Document | null;
+    rootMargin?: string;
+    threshold?: number | number[];
+}
+interface VisibilityObserveOptions extends ObserverPoolOptions {
+    once?: boolean;
+    onEnter?: (info: IntersectionInfo) => void;
+    onLeave?: (info: IntersectionInfo) => void;
+}
+interface VisibilityEngine {
+    /** returns unsubscribe */
+    observe(el: Element, options: VisibilityObserveOptions, cb: (info: IntersectionInfo) => void): () => void;
+    destroy(): void;
+}
+interface DOMRectLike {
+    top: number;
+    left: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+}
+interface ElementTrackerState {
+    rect: DOMRectLike;
+    /** 0..1, from element entering at viewport bottom to leaving at viewport top */
+    viewportProgress: number;
+    /** px offset of element center from viewport center */
+    distanceFromCenter: number;
+}
+interface ElementTracker {
+    getState(): ElementTrackerState;
+    subscribe(cb: (state: ElementTrackerState) => void): () => void;
+    destroy(): void;
+}
+
+type ScrollTarget = Window | HTMLElement;
+/**
+ * Framework-agnostic scroll engine for window or a scrollable element.
+ * Batches DOM scroll events into one shared rAF loop and notifies
+ * subscribers only when the derived state actually changes.
+ */
+declare function createScrollEngine(target?: ScrollTarget, options?: ScrollEngineOptions): ScrollEngine;
+
+type EntryCallback = (entry: IntersectionObserverEntry) => void;
+/**
+ * Pools IntersectionObserver instances by (root, rootMargin, threshold),
+ * so many observed elements sharing the same options share one observer
+ * instead of spawning one per element.
+ */
+declare class ObserverPool {
+    private pools;
+    observe(el: Element, options: ObserverPoolOptions, cb: EntryCallback): () => void;
+}
+declare const observerPool: ObserverPool;
+
+/**
+ * Wraps the shared observer pool with enter/leave edge detection and
+ * `once` support, without any framework-specific reactivity.
+ */
+declare function createVisibilityEngine(pool?: ObserverPool): VisibilityEngine;
+
+/**
+ * Tracks an element's position relative to the viewport (rect,
+ * viewportProgress, distanceFromCenter) on the shared rAF loop.
+ */
+declare function createElementTracker(el: HTMLElement): ElementTracker;
+
+type Tick = (time: number) => void;
+/**
+ * One shared requestAnimationFrame loop for the whole engine, instead of
+ * every scroll/tracker subscription running its own rAF callback.
+ */
+declare class RafLoop {
+    private callbacks;
+    private handle;
+    add(cb: Tick): () => void;
+    private start;
+    private stop;
+}
+declare const rafLoop: RafLoop;
+
+/**
+ * Linearly maps `value` from the `from` range into the `to` range.
+ * Pass `clampResult: true` to keep the result within `to` at the edges.
+ */
+declare function mapRange(value: number, from: [number, number], to: [number, number], clampResult?: boolean): number;
+
+/**
+ * Writes a numeric progress value into a CSS custom property on `el`,
+ * so the resulting visual effect can be composed in plain CSS.
+ */
+declare function bindCSSVar(el: HTMLElement, name: string, value: number | string): void;
+
+declare function prefersReducedMotion(): boolean;
+
+declare function clamp(value: number, min: number, max: number): number;
+
+type Easing = (t: number) => number;
+/**
+ * Standard easing presets to apply to a 0..1 progress value before
+ * feeding it into an effect (parallax offset, CSS var, etc).
+ */
+declare const easings: {
+    linear: (t: number) => number;
+    easeInQuad: (t: number) => number;
+    easeOutQuad: (t: number) => number;
+    easeInOutQuad: (t: number) => number;
+    easeInCubic: (t: number) => number;
+    easeOutCubic: (t: number) => number;
+    easeInOutCubic: (t: number) => number;
+    easeInSine: (t: number) => number;
+    easeOutSine: (t: number) => number;
+    easeInOutSine: (t: number) => number;
+};
+type EasingName = keyof typeof easings;
+
+export { type DOMRectLike, type Easing, type EasingName, type ElementTracker, type ElementTrackerState, type IntersectionEdge, type IntersectionInfo, ObserverPool, type ObserverPoolOptions, type ScrollDirection, type ScrollEngine, type ScrollEngineOptions, type ScrollState, type ScrollToOptions, type VisibilityEngine, type VisibilityObserveOptions, bindCSSVar, clamp, createElementTracker, createScrollEngine, createVisibilityEngine, easings, mapRange, observerPool, prefersReducedMotion, rafLoop };

package/dist/index.js

@@ -0,0 +1,379 @@
+// src/raf-loop.ts
+var RafLoop = class {
+  constructor() {
+    this.callbacks = /* @__PURE__ */ new Set();
+    this.handle = null;
+  }
+  add(cb) {
+    this.callbacks.add(cb);
+    this.start();
+    return () => {
+      this.callbacks.delete(cb);
+      if (this.callbacks.size === 0) this.stop();
+    };
+  }
+  start() {
+    if (this.handle !== null || typeof requestAnimationFrame === "undefined") return;
+    const loop = (time) => {
+      this.callbacks.forEach((cb) => cb(time));
+      if (this.callbacks.size > 0) {
+        this.handle = requestAnimationFrame(loop);
+      } else {
+        this.handle = null;
+      }
+    };
+    this.handle = requestAnimationFrame(loop);
+  }
+  stop() {
+    if (this.handle !== null && typeof cancelAnimationFrame !== "undefined") {
+      cancelAnimationFrame(this.handle);
+    }
+    this.handle = null;
+  }
+};
+var rafLoop = new RafLoop();
+
+// src/utils/clamp.ts
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+
+// src/utils/prefersReducedMotion.ts
+function prefersReducedMotion() {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return false;
+  return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+
+// src/scroll-engine.ts
+function isWindowTarget(target) {
+  return typeof window !== "undefined" && target === window;
+}
+function getScrollPosition(target) {
+  if (isWindowTarget(target)) return { x: window.scrollX, y: window.scrollY };
+  return { x: target.scrollLeft, y: target.scrollTop };
+}
+function getMaxScroll(target) {
+  if (isWindowTarget(target)) {
+    const doc = document.documentElement;
+    return {
+      x: Math.max(doc.scrollWidth - window.innerWidth, 0),
+      y: Math.max(doc.scrollHeight - window.innerHeight, 0)
+    };
+  }
+  return {
+    x: Math.max(target.scrollWidth - target.clientWidth, 0),
+    y: Math.max(target.scrollHeight - target.clientHeight, 0)
+  };
+}
+function computeProgress(target, x, y) {
+  const max = getMaxScroll(target);
+  if (max.y > 0) return clamp(y / max.y, 0, 1);
+  if (max.x > 0) return clamp(x / max.x, 0, 1);
+  return 0;
+}
+function createNoopEngine() {
+  const state = { x: 0, y: 0, direction: null, progress: 0, velocity: 0, isScrolling: false };
+  return {
+    getState: () => state,
+    subscribe: (cb) => {
+      cb(state);
+      return () => {
+      };
+    },
+    scrollTo: () => {
+    },
+    destroy: () => {
+    }
+  };
+}
+function createScrollEngine(target = typeof window !== "undefined" ? window : void 0, options = {}) {
+  if (typeof window === "undefined" || !target) return createNoopEngine();
+  const idleTimeout = options.idleTimeout ?? 150;
+  const subscribers = /* @__PURE__ */ new Set();
+  const initial = getScrollPosition(target);
+  let state = {
+    x: initial.x,
+    y: initial.y,
+    direction: null,
+    progress: computeProgress(target, initial.x, initial.y),
+    velocity: 0,
+    isScrolling: false
+  };
+  let frameLastX = initial.x;
+  let frameLastY = initial.y;
+  let idleHandle = null;
+  function notify() {
+    subscribers.forEach((cb) => cb(state));
+  }
+  function onScroll() {
+    const pos = getScrollPosition(target);
+    const dx = pos.x - state.x;
+    const dy = pos.y - state.y;
+    let direction = state.direction;
+    if (dy > 0) direction = "down";
+    else if (dy < 0) direction = "up";
+    else if (dx > 0) direction = "right";
+    else if (dx < 0) direction = "left";
+    state = {
+      ...state,
+      x: pos.x,
+      y: pos.y,
+      direction,
+      progress: computeProgress(target, pos.x, pos.y),
+      isScrolling: true
+    };
+    if (idleHandle !== null) clearTimeout(idleHandle);
+    idleHandle = setTimeout(() => {
+      idleHandle = null;
+      state = { ...state, isScrolling: false, velocity: 0 };
+      notify();
+    }, idleTimeout);
+    notify();
+  }
+  target.addEventListener("scroll", onScroll, { passive: true });
+  const removeRaf = rafLoop.add(() => {
+    const velocity = Math.hypot(state.x - frameLastX, state.y - frameLastY);
+    frameLastX = state.x;
+    frameLastY = state.y;
+    if (velocity !== state.velocity) {
+      state = { ...state, velocity };
+      notify();
+    }
+  });
+  function scrollTo(pos, opts = {}) {
+    const behavior = opts.behavior ?? (prefersReducedMotion() ? "auto" : "smooth");
+    const left = typeof pos === "number" ? void 0 : pos.x;
+    const top = typeof pos === "number" ? pos : pos.y;
+    target.scrollTo({ left, top, behavior });
+  }
+  return {
+    getState: () => state,
+    subscribe(cb) {
+      subscribers.add(cb);
+      cb(state);
+      return () => subscribers.delete(cb);
+    },
+    scrollTo,
+    destroy() {
+      target.removeEventListener("scroll", onScroll);
+      if (idleHandle !== null) clearTimeout(idleHandle);
+      removeRaf();
+      subscribers.clear();
+    }
+  };
+}
+
+// src/observer-pool.ts
+function keyFor(options) {
+  const threshold = Array.isArray(options.threshold) ? options.threshold.join(",") : String(options.threshold ?? 0);
+  const root = options.root ? "r" : "window";
+  return `${root}|${options.rootMargin ?? "0px"}|${threshold}`;
+}
+var ObserverPool = class {
+  constructor() {
+    this.pools = /* @__PURE__ */ new Map();
+  }
+  observe(el, options, cb) {
+    if (typeof IntersectionObserver === "undefined") return () => {
+    };
+    const key = keyFor(options);
+    let pool = this.pools.get(key);
+    if (!pool) {
+      const callbacks2 = /* @__PURE__ */ new Map();
+      const observer = new IntersectionObserver(
+        (entries) => {
+          for (const entry of entries) {
+            callbacks2.get(entry.target)?.forEach((fn) => fn(entry));
+          }
+        },
+        {
+          root: options.root ?? null,
+          rootMargin: options.rootMargin ?? "0px",
+          threshold: options.threshold ?? 0
+        }
+      );
+      pool = { observer, callbacks: callbacks2 };
+      this.pools.set(key, pool);
+    }
+    let callbacks = pool.callbacks.get(el);
+    if (!callbacks) {
+      callbacks = /* @__PURE__ */ new Set();
+      pool.callbacks.set(el, callbacks);
+    }
+    const isNewElement = callbacks.size === 0;
+    callbacks.add(cb);
+    if (isNewElement) pool.observer.observe(el);
+    const currentPool = pool;
+    return () => {
+      const set = currentPool.callbacks.get(el);
+      if (!set) return;
+      set.delete(cb);
+      if (set.size === 0) {
+        currentPool.callbacks.delete(el);
+        currentPool.observer.unobserve(el);
+      }
+      if (currentPool.callbacks.size === 0) {
+        currentPool.observer.disconnect();
+        this.pools.delete(key);
+      }
+    };
+  }
+};
+var observerPool = new ObserverPool();
+
+// src/visibility-engine.ts
+function computeEdge(entry, wasIntersecting) {
+  if (entry.isIntersecting === wasIntersecting) return void 0;
+  const rootTop = entry.rootBounds ? entry.rootBounds.top : 0;
+  const enteringOrLeavingFromBottom = entry.boundingClientRect.top > rootTop;
+  if (entry.isIntersecting) return enteringOrLeavingFromBottom ? "enter-bottom" : "enter-top";
+  return enteringOrLeavingFromBottom ? "leave-bottom" : "leave-top";
+}
+function createVisibilityEngine(pool = observerPool) {
+  const unsubs = /* @__PURE__ */ new Set();
+  function observe(el, options, cb) {
+    let wasIntersecting = false;
+    const unobserve = pool.observe(el, options, (entry) => {
+      const edge = computeEdge(entry, wasIntersecting);
+      wasIntersecting = entry.isIntersecting;
+      const info = {
+        isIntersecting: entry.isIntersecting,
+        intersectionRatio: entry.intersectionRatio,
+        boundingClientRect: entry.boundingClientRect,
+        edge
+      };
+      cb(info);
+      if (edge === "enter-top" || edge === "enter-bottom") options.onEnter?.(info);
+      if (edge === "leave-top" || edge === "leave-bottom") options.onLeave?.(info);
+      if (options.once && entry.isIntersecting) {
+        unsubs.delete(unobserve);
+        unobserve();
+      }
+    });
+    unsubs.add(unobserve);
+    return () => {
+      unsubs.delete(unobserve);
+      unobserve();
+    };
+  }
+  return {
+    observe,
+    destroy() {
+      unsubs.forEach((fn) => fn());
+      unsubs.clear();
+    }
+  };
+}
+
+// src/element-tracker.ts
+function toDomRectLike(rect) {
+  return {
+    top: rect.top,
+    left: rect.left,
+    right: rect.right,
+    bottom: rect.bottom,
+    width: rect.width,
+    height: rect.height
+  };
+}
+var emptyRect = { top: 0, left: 0, right: 0, bottom: 0, width: 0, height: 0 };
+function computeViewportProgress(rect, viewportHeight) {
+  const total = viewportHeight + rect.height;
+  if (total <= 0) return 0;
+  const traveled = viewportHeight - rect.top;
+  return clamp(traveled / total, 0, 1);
+}
+function computeState(el) {
+  const rect = el.getBoundingClientRect();
+  const viewportHeight = window.innerHeight;
+  const elementCenter = rect.top + rect.height / 2;
+  const viewportCenter = viewportHeight / 2;
+  return {
+    rect: toDomRectLike(rect),
+    viewportProgress: computeViewportProgress(rect, viewportHeight),
+    distanceFromCenter: elementCenter - viewportCenter
+  };
+}
+function statesEqual(a, b) {
+  return a.rect.top === b.rect.top && a.rect.left === b.rect.left && a.rect.width === b.rect.width && a.rect.height === b.rect.height && a.viewportProgress === b.viewportProgress && a.distanceFromCenter === b.distanceFromCenter;
+}
+function createElementTracker(el) {
+  if (typeof window === "undefined") {
+    const state2 = { rect: emptyRect, viewportProgress: 0, distanceFromCenter: 0 };
+    return {
+      getState: () => state2,
+      subscribe: (cb) => {
+        cb(state2);
+        return () => {
+        };
+      },
+      destroy: () => {
+      }
+    };
+  }
+  const subscribers = /* @__PURE__ */ new Set();
+  let state = computeState(el);
+  const removeRaf = rafLoop.add(() => {
+    const next = computeState(el);
+    if (!statesEqual(next, state)) {
+      state = next;
+      subscribers.forEach((cb) => cb(state));
+    }
+  });
+  return {
+    getState: () => state,
+    subscribe(cb) {
+      subscribers.add(cb);
+      cb(state);
+      return () => subscribers.delete(cb);
+    },
+    destroy() {
+      removeRaf();
+      subscribers.clear();
+    }
+  };
+}
+
+// src/utils/mapRange.ts
+function mapRange(value, from, to, clampResult = false) {
+  const [inMin, inMax] = from;
+  const [outMin, outMax] = to;
+  const ratio = inMax === inMin ? 0 : (value - inMin) / (inMax - inMin);
+  const result = outMin + ratio * (outMax - outMin);
+  if (!clampResult) return result;
+  return clamp(result, Math.min(outMin, outMax), Math.max(outMin, outMax));
+}
+
+// src/utils/bindCSSVar.ts
+function bindCSSVar(el, name, value) {
+  const varName = name.startsWith("--") ? name : `--${name}`;
+  el.style.setProperty(varName, String(value));
+}
+
+// src/easing.ts
+var easings = {
+  linear: (t) => t,
+  easeInQuad: (t) => t * t,
+  easeOutQuad: (t) => t * (2 - t),
+  easeInOutQuad: (t) => t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t,
+  easeInCubic: (t) => t * t * t,
+  easeOutCubic: (t) => 1 - Math.pow(1 - t, 3),
+  easeInOutCubic: (t) => t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2,
+  easeInSine: (t) => 1 - Math.cos(t * Math.PI / 2),
+  easeOutSine: (t) => Math.sin(t * Math.PI / 2),
+  easeInOutSine: (t) => -(Math.cos(Math.PI * t) - 1) / 2
+};
+export {
+  ObserverPool,
+  bindCSSVar,
+  clamp,
+  createElementTracker,
+  createScrollEngine,
+  createVisibilityEngine,
+  easings,
+  mapRange,
+  observerPool,
+  prefersReducedMotion,
+  rafLoop
+};
+//# sourceMappingURL=index.js.map