react-atom-trigger 1.1.0 → 2.0.0

package/LICENSE

@@ -1,12 +1,12 @@
 MIT License
 
-Copyright (c) 2022 innrVoice
+Copyright (c) 2022 Pavel Bochkov-Rastopchin
 
 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
+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

package/MIGRATION.md

@@ -0,0 +1,255 @@
+# Migration Guide: v1 to v2
+
+`react-atom-trigger@2` is a breaking release.
+
+The biggest change is simple: `AtomTrigger` does its own observation now. In `v1.x` you had to pass scroll state and dimensions in from the outside. In `v2.x` you pass callbacks and, when needed, a root element.
+
+## Before you start
+
+This is not just a prop rename release.
+
+Please re-check the behavior in the real UI after upgrading, especially if you use:
+
+- `threshold`
+- `rootMargin`
+- custom scroll containers
+- any code that was sensitive to the exact timing of the old callback
+
+The new version samples geometry internally, so some edge timing can feel a bit different near boundaries.
+
+## Quick prop map
+
+| v1.x                 | v2.x                                      |
+| -------------------- | ----------------------------------------- |
+| `callback`           | `onEnter`, `onLeave` or `onEvent`         |
+| `behavior="enter"`   | `onEnter`                                 |
+| `behavior="leave"`   | `onLeave`                                 |
+| `behavior="default"` | `onEvent` or both `onEnter` and `onLeave` |
+| `triggerOnce`        | `once` or `oncePerDirection`              |
+| `scrollEvent`        | removed                                   |
+| `dimensions`         | removed                                   |
+| `offset`             | `rootMargin`                              |
+| `getDebugInfo`       | read data from `AtomTriggerEvent`         |
+| `IAtomTriggerProps`  | `AtomTriggerProps`                        |
+
+## Hook and type changes
+
+| v1.x                                   | v2.x                                          |
+| -------------------------------------- | --------------------------------------------- |
+| `useWindowScroll`                      | `useScrollPosition()`                         |
+| `useContainerScroll({ containerRef })` | `useScrollPosition({ target: containerRef })` |
+| `useWindowDimensions`                  | `useViewportSize()`                           |
+| `Options`                              | `ListenerOptions`                             |
+| `ScrollEvent`                          | removed                                       |
+| `Dimensions`                           | removed                                       |
+| `DebugInfo`                            | removed                                       |
+| `log`                                  | removed                                       |
+
+## Common upgrades
+
+### 1. Simple enter trigger
+
+#### v1.x
+
+```tsx
+import React from 'react';
+import { AtomTrigger, useWindowDimensions, useWindowScroll } from 'react-atom-trigger';
+
+export function HeroAnimationTrigger() {
+  const scrollEvent = useWindowScroll();
+  const dimensions = useWindowDimensions();
+
+  return (
+    <AtomTrigger
+      behavior="enter"
+      callback={() => {
+        console.log('start animation');
+      }}
+      scrollEvent={scrollEvent}
+      dimensions={dimensions}
+    />
+  );
+}
+```
+
+#### v2.x
+
+```tsx
+import React from 'react';
+import { AtomTrigger } from 'react-atom-trigger';
+
+export function HeroAnimationTrigger() {
+  return <AtomTrigger onEnter={() => console.log('start animation')} />;
+}
+```
+
+### 2. Enter and leave in one place
+
+#### v1.x
+
+```tsx
+<AtomTrigger
+  behavior="default"
+  callback={() => {
+    console.log('visibility changed');
+  }}
+  scrollEvent={scrollEvent}
+  dimensions={dimensions}
+/>
+```
+
+#### v2.x
+
+```tsx
+<AtomTrigger
+  onEvent={event => {
+    console.log(event.type, event.position, event.counts);
+  }}
+/>
+```
+
+### 3. Custom scroll container
+
+#### v1.x
+
+```tsx
+import React from 'react';
+import { AtomTrigger, useContainerScroll } from 'react-atom-trigger';
+
+export function ContainerExample() {
+  const containerRef = React.useRef<HTMLDivElement>(null);
+  const scrollEvent = useContainerScroll({ containerRef });
+
+  return (
+    <div ref={containerRef} style={{ height: 320, overflowY: 'auto' }}>
+      <div style={{ height: 600 }} />
+      <AtomTrigger
+        behavior="enter"
+        callback={() => {
+          console.log('entered container viewport');
+        }}
+        scrollEvent={scrollEvent}
+        dimensions={{ width: 320, height: 320 }}
+      />
+      <div style={{ height: 600 }} />
+    </div>
+  );
+}
+```
+
+#### v2.x
+
+```tsx
+import React from 'react';
+import { AtomTrigger } from 'react-atom-trigger';
+
+export function ContainerExample() {
+  const containerRef = React.useRef<HTMLDivElement>(null);
+
+  return (
+    <div ref={containerRef} style={{ height: 320, overflowY: 'auto' }}>
+      <div style={{ height: 600 }} />
+      <AtomTrigger
+        rootRef={containerRef}
+        onEnter={() => {
+          console.log('entered container viewport');
+        }}
+      />
+      <div style={{ height: 600 }} />
+    </div>
+  );
+}
+```
+
+If you render the container in JSX, `rootRef` is usually the right choice.
+
+If you already have the DOM element instance from somewhere else, use `root`.
+
+If you want normal viewport behavior, pass neither.
+
+### 4. `offset` to `rootMargin`
+
+This part needs a little attention.
+
+`offset` and `rootMargin` are related, but not identical in meaning. If you were using:
+
+```tsx
+<AtomTrigger offset={[100, 0, 0, 0]} />
+```
+
+the usual `v2.x` equivalent is:
+
+```tsx
+<AtomTrigger rootMargin="-100px 0px 0px 0px" />
+```
+
+For pixel tuples, this also works:
+
+```tsx
+<AtomTrigger rootMargin={[-100, 0, 0, 0]} />
+```
+
+After migrating, please check it in the actual UI. `rootMargin` is the place where timing differences are easiest to notice.
+
+### 5. Replacing `getDebugInfo`
+
+#### v1.x
+
+```tsx
+<AtomTrigger
+  callback={handleTrigger}
+  getDebugInfo={info => {
+    console.log(info.trigger, info.timesTriggered);
+  }}
+  scrollEvent={scrollEvent}
+  dimensions={dimensions}
+/>
+```
+
+#### v2.x
+
+```tsx
+<AtomTrigger
+  onEvent={event => {
+    console.log(event.type);
+    console.log(event.counts);
+    console.log(event.position);
+    console.log(event.movementDirection);
+    console.log(event.entry.intersectionRatio);
+  }}
+/>
+```
+
+## Small hook examples
+
+### Replace `useWindowScroll`
+
+```tsx
+const position = useScrollPosition();
+console.log(position.y);
+```
+
+### Replace `useContainerScroll`
+
+```tsx
+const containerRef = React.useRef<HTMLDivElement>(null);
+const position = useScrollPosition({ target: containerRef });
+console.log(position.y);
+```
+
+### Replace `useWindowDimensions`
+
+```tsx
+const viewport = useViewportSize();
+console.log(viewport.height);
+```
+
+## Final check
+
+Your migration is probably done when all of these are true:
+
+1. No `AtomTrigger` still passes `scrollEvent`, `dimensions`, `behavior`, `callback`, `getDebugInfo`, `triggerOnce` or `offset`.
+2. Trigger handlers now use `onEnter`, `onLeave` and/or `onEvent`.
+3. Custom containers use `root` or `rootRef`.
+4. Hook imports were moved to `useScrollPosition` and `useViewportSize`.
+5. You checked the real UI, not only TypeScript errors, especially around `threshold` and `rootMargin`.

package/README.md

@@ -1,84 +1,302 @@
 # react-atom-trigger
 
-AtomTrigger helps solve the problem of executing code when some element "scrolls into (or out of) view". A pretty simple "[react-waypoint](https://www.npmjs.com/package/react-waypoint)" alternative written in Typescript.
+`react-atom-trigger` helps with the usual "run some code when this thing enters or leaves view" problem.
+It is a lightweight React alternative to `react-waypoint`, written in TypeScript.
 
-## Basic features
+## v2 is a breaking release
 
+If you are coming from `v1.x`, please check [MIGRATION.md](./MIGRATION.md).
 
-Exposes `<AtomTrigger {...props} />` component, where `props` are:
+If you want to stay on the old API:
 
+```bash
+# pnpm
+pnpm add react-atom-trigger@^1
+
+# npm
+npm install react-atom-trigger@^1
+
+# yarn
+yarn add react-atom-trigger@^1
 ```
-interface IAtomTriggerProps {
-  scrollEvent: ScrollEvent;
-  dimensions: Dimensions;
-  behavior?: 'default' | 'enter' | 'leave';
-  callback: () => unknown;
-  getDebugInfo?: (data: DebugInfo) => void;
-  triggerOnce?: boolean;
-  className?: string;
-  offset?: [number, number, number, number];
+
+## Install
+
+```bash
+# pnpm
+pnpm add react-atom-trigger
+
+# npm
+npm install react-atom-trigger
+
+# yarn
+yarn add react-atom-trigger
+```
+
+## How it works
+
+`react-atom-trigger` uses a mixed approach.
+
+- Geometry is the real source of truth for `enter` and `leave`.
+- `IntersectionObserver` is only there to wake things up when the browser notices a layout shift.
+- `rootMargin` logic is handled by the library itself, so it stays consistent and does not depend on native observer quirks.
+
+In practice this means `AtomTrigger` reacts to:
+
+- scroll
+- window resize
+- root resize
+- sentinel resize
+- layout shifts that move the observed element even if no scroll event happened
+
+This is the main reason `v2` can support custom margin-aware behavior and still react to browser-driven layout changes.
+
+## Quick start
+
+```tsx
+import React from 'react';
+import { AtomTrigger } from 'react-atom-trigger';
+
+export function Example() {
+  return (
+    <AtomTrigger
+      onEnter={event => {
+        console.log('entered', event);
+      }}
+      onLeave={event => {
+        console.log('left', event);
+      }}
+      rootMargin="0px 0px 160px 0px"
+      oncePerDirection
+    />
+  );
 }
 ```
 
-In order to "work" `AtomTrigger` needs callback, dimensions and simple scroll event data provided.
+If you want an already-visible trigger to behave like a normal first `enter`, pass
+`fireOnInitialVisible`.
 
-### Callback
+```tsx
+import React from 'react';
+import { AtomTrigger } from 'react-atom-trigger';
 
-The function to be executed when AtomTrigger enters or leaves some container.
+export function RestoredScrollExample() {
+  return (
+    <AtomTrigger
+      fireOnInitialVisible
+      onEnter={event => {
+        if (event.isInitial) {
+          console.log('started visible after load');
+          return;
+        }
 
+        console.log('entered from scrolling');
+      }}
+    />
+  );
+}
 ```
-callback: () => unknown;
+
+## Child mode
+
+If you pass one top-level child, `AtomTrigger` observes that element directly instead of rendering its own sentinel.
+
+```tsx
+import React from 'react';
+import { AtomTrigger } from 'react-atom-trigger';
+
+export function HeroTrigger() {
+  return (
+    <AtomTrigger threshold={0.75} onEnter={() => console.log('hero is mostly visible')}>
+      <section style={{ minHeight: 240 }}>Hero content</section>
+    </AtomTrigger>
+  );
+}
+```
+
+This is usually the better mode when `threshold` should depend on a real element size.
+
+Intrinsic elements such as `<div>` and `<section>` work automatically.
+
+If you use a custom component, the ref that `AtomTrigger` passes down still has to reach a real DOM
+element:
+
+- in React 19, the component can receive `ref` as a prop and pass it through
+- in React 18 and older, use `React.forwardRef`
+
+If the ref never reaches a DOM node, child mode cannot observe anything.
+
+## API
+
+```ts
+interface AtomTriggerProps {
+  onEnter?: (event: AtomTriggerEvent) => void;
+  onLeave?: (event: AtomTriggerEvent) => void;
+  onEvent?: (event: AtomTriggerEvent) => void;
+  children?: React.ReactNode;
+  once?: boolean;
+  oncePerDirection?: boolean;
+  fireOnInitialVisible?: boolean;
+  disabled?: boolean;
+  threshold?: number;
+  root?: Element | null;
+  rootRef?: React.RefObject<Element | null>;
+  rootMargin?: string | [number, number, number, number];
+  className?: string;
+}
 ```
 
+### Props in short
 
-### Dimensions
+- `onEnter`, `onLeave`, `onEvent`: trigger callbacks with a rich event payload.
+- `children`: observe one real child element instead of the internal sentinel.
+- `once`: allow only the first transition overall.
+- `oncePerDirection`: allow one `enter` and one `leave`.
+- `fireOnInitialVisible`: emit an initial `enter` when observation starts and the trigger is already active.
+- `disabled`: stop observing without unmounting the component.
+- `threshold`: a number from `0` to `1`. It affects `enter`, not `leave`.
+- `root`: use a specific DOM element as the visible area.
+- `rootRef`: same idea as `root`, but better when the container is created in JSX. If both are passed, `rootRef` wins.
+- `rootMargin`: expand or shrink the effective root. String values use `IntersectionObserver`-style syntax. A four-number array is treated as `[top, right, bottom, left]` in pixels.
+- `className`: applies only to the internal sentinel.
 
-Dimensions of the main "container" (window in many cases). 
+## Event payload
 
+```ts
+type AtomTriggerEvent = {
+  type: 'enter' | 'leave';
+  isInitial: boolean;
+  entry: AtomTriggerEntry;
+  counts: {
+    entered: number;
+    left: number;
+  };
+  movementDirection: 'up' | 'down' | 'left' | 'right' | 'stationary' | 'unknown';
+  position: 'inside' | 'above' | 'below' | 'left' | 'right' | 'outside';
+  timestamp: number;
+};
 ```
-type Dimensions = {
-  width: number;
-  height: number;
+
+```ts
+type AtomTriggerEntry = {
+  target: Element;
+  rootBounds: DOMRectReadOnly | null;
+  boundingClientRect: DOMRectReadOnly;
+  intersectionRect: DOMRectReadOnly;
+  isIntersecting: boolean;
+  intersectionRatio: number;
+  source: 'geometry';
 };
 ```
 
-So if you have some logic of calculating container size and container resize handling, just provide needed data to AtomTrigger.
+The payload is library-owned geometry data. It is not a native `IntersectionObserverEntry`.
+
+`isInitial` is `true` only for the synthetic first `enter` created by
+`fireOnInitialVisible`.
 
-### Scroll Event
- 
-To trigger "events" `AtomTrigger` needs some kind of simple scroll event provided.
+## Hooks
 
+For someone who wants everything out-of-the-box, `useScrollPosition` and `useViewportSize` are also available.
+
+```ts
+useScrollPosition(options?: {
+  target?: Window | HTMLElement | React.RefObject<HTMLElement | null>;
+  passive?: boolean;
+  throttleMs?: number;
+  enabled?: boolean;
+}): { x: number; y: number }
 ```
-type ScrollEvent = { 
-    scrollX: number; 
-    scrollY: number;
-};
+
+```ts
+useViewportSize(options?: {
+  passive?: boolean;
+  throttleMs?: number;
+  enabled?: boolean;
+}): { width: number; height: number }
 ```
 
-So, if you already have some scroll event listener, just provide it to AtomTrigger.
+Both hooks are SSR-safe. Default throttling is `16ms`.
 
-## Utility hooks
-For someone who wants everything out-of-the-box, `useWindowDimensions`, `useWindowScroll` and `useContainerScroll` hooks are also available for import.
+## Notes
 
-## Build
-This package is built with `tsdown`.
+- In sentinel mode, `threshold` is usually only interesting if your sentinel has real width or height. The default sentinel is almost point-like.
+- Child mode needs exactly one top-level child and any custom component used there needs to pass the received ref through to a DOM element.
+- In React 19, a plain function component can also work in child mode if it passes the received `ref` prop through to a DOM element.
+- `rootMargin` is handled by the library geometry logic. `IntersectionObserver` is only used as a wake-up signal for layout shifts.
+
+## Migration from v1
+
+The short version:
+
+1. `callback` became `onEnter`, `onLeave` and `onEvent`.
+2. `behavior` is gone.
+3. `triggerOnce` became `once` or `oncePerDirection`.
+4. `scrollEvent`, `dimensions` and `offset` are gone.
+5. `useWindowScroll` / `useContainerScroll` became `useScrollPosition`.
+6. `useWindowDimensions` became `useViewportSize`.
+
+For the real upgrade notes and examples, see [MIGRATION.md](./MIGRATION.md).
+
+## Build output
 
-Build output:
+This package is built with `tsdown`.
 
 ```text
 lib/index.js
-lib/index.es.js
+lib/index.umd.js
 lib/index.d.ts
 ```
 
-## UMD global
 When the UMD bundle is loaded directly in the browser, the library is exposed as `window.reactAtomTrigger`.
 
 ## Examples
-It is sometimes better to tweak and see for yourself: [CodeSandbox examples](https://codesandbox.io/examples/package/react-atom-trigger).
 
- [**More detailed react-atom-trigger overview with examples**](https://visiofutura.com/solving-scroll-into-view-problem-in-react-my-way-a8056a1bdc11)
+### Storybook
+
+Storybook is the easiest way to see how the component behaves.
+
+- `AtomTrigger Demo`: regular usage examples.
+- `Extended Demo`: a larger animated interaction demo that shows AtomTrigger driving scene changes,
+  event timing and more realistic scroll-based UI behavior.
+- `Internal Tests`: interaction stories used for local checks and Storybook tests.
+
+To run Storybook locally:
+
+```bash
+pnpm storybook
+```
+
+### CodeSandbox
+
+Quick way to tweak it in the browser.
 
+- [Basic sentinel example](https://codesandbox.io/p/sandbox/react-atom-trigger-v2-basic-example-9xrzmg)
+- [Child mode threshold example](https://codesandbox.io/p/sandbox/react-atom-trigger-v2-child-mode-threshold-qcpv28)
+- [Fixed header offset example](https://codesandbox.io/p/devbox/react-atom-trigger-v2-fixed-header-offset-62lmrv)
+- [Initial visible on load example](https://codesandbox.io/p/devbox/react-atom-trigger-v2-initial-visible-on-load-ncqjtf)
+- [Horizontal scroll container example](https://codesandbox.io/p/devbox/react-atom-trigger-v2-horizontal-scroll-container-hs33gq)
+
+## Development
+
+```bash
+pnpm install
+pnpm lint
+pnpm test
+pnpm test:storybook
+pnpm build
+pnpm format:check
+```
+
+## Storybook (Static Build)
+
+Build:
+
+```bash
+pnpm build:sb
+```
 
+Output:
 
+`storybook-static/`
 
+This directory is used for deployment to `storybook.atomtrigger.dev`.

package/lib/index.d.ts

@@ -1,49 +1,69 @@
 import React from "react";
 
 //#region src/AtomTrigger.types.d.ts
-type ScrollEvent = {
-  scrollX: number;
-  scrollY: number;
+type MovementDirection = 'up' | 'down' | 'left' | 'right' | 'stationary' | 'unknown';
+type TriggerPosition = 'inside' | 'above' | 'below' | 'left' | 'right' | 'outside';
+type TriggerType = 'enter' | 'leave';
+type TriggerCounts = {
+  entered: number;
+  left: number;
 };
-type Dimensions = {
-  width: number;
-  height: number;
+type RootMarginTuple = readonly [number, number, number, number];
+type AtomTriggerEntry = {
+  target: Element;
+  rootBounds: DOMRectReadOnly | null;
+  boundingClientRect: DOMRectReadOnly;
+  intersectionRect: DOMRectReadOnly;
+  isIntersecting: boolean;
+  intersectionRatio: number;
+  source: 'geometry';
 };
-type DebugInfo = {
-  timesTriggered: {
-    leftViewport: number;
-    enteredViewport: number;
-  };
-  trigger: 'entered' | 'left';
+type AtomTriggerEvent = {
+  type: TriggerType;
+  isInitial: boolean;
+  entry: AtomTriggerEntry;
+  counts: TriggerCounts;
+  movementDirection: MovementDirection;
+  position: TriggerPosition;
+  timestamp: number;
 };
-interface IAtomTriggerProps {
-  scrollEvent: ScrollEvent;
-  behavior?: 'default' | 'enter' | 'leave';
-  callback: () => unknown;
-  getDebugInfo?: (data: DebugInfo) => void;
-  triggerOnce?: boolean;
+interface AtomTriggerProps {
+  onEnter?: (event: AtomTriggerEvent) => void;
+  onLeave?: (event: AtomTriggerEvent) => void;
+  onEvent?: (event: AtomTriggerEvent) => void;
+  children?: React.ReactNode;
+  once?: boolean;
+  oncePerDirection?: boolean;
+  fireOnInitialVisible?: boolean;
+  disabled?: boolean;
+  threshold?: number;
+  root?: Element | null;
+  rootRef?: React.RefObject<Element | null>;
+  rootMargin?: string | RootMarginTuple;
   className?: string;
-  dimensions: Dimensions;
-  offset?: [number, number, number, number];
 }
 //#endregion
 //#region src/AtomTrigger.d.ts
-declare const AtomTrigger: React.FC<IAtomTriggerProps>;
+declare const AtomTrigger: React.FC<AtomTriggerProps>;
 //#endregion
 //#region src/utils.d.ts
-type Options = {
-  passiveEventListener?: boolean;
-  eventListenerTimeoutMs?: number;
+type ScrollPosition = {
+  x: number;
+  y: number;
+};
+type ViewportSize = {
+  width: number;
+  height: number;
+};
+type ListenerOptions = {
+  passive?: boolean;
+  throttleMs?: number;
+  enabled?: boolean;
+};
+type UseScrollPositionOptions = ListenerOptions & {
+  target?: Window | HTMLElement | React.RefObject<HTMLElement | null>;
 };
-declare function log<T>(log: T, color?: string): void;
-declare function useWindowDimensions(options?: Options | undefined): Dimensions;
-declare function useContainerScroll({
-  containerRef,
-  options
-}: {
-  containerRef?: React.RefObject<HTMLDivElement>;
-  options?: Options;
-}): ScrollEvent;
-declare function useWindowScroll(options?: Options): ScrollEvent;
+declare function useViewportSize(options?: ListenerOptions): ViewportSize;
+declare function useScrollPosition(options?: UseScrollPositionOptions): ScrollPosition;
 //#endregion
-export { AtomTrigger, Options, log, useContainerScroll, useWindowDimensions, useWindowScroll };
+export { AtomTrigger, type AtomTriggerEntry, type AtomTriggerEvent, type AtomTriggerProps, type ListenerOptions, type MovementDirection, type RootMarginTuple, type ScrollPosition, type TriggerCounts, type TriggerPosition, type TriggerType, type UseScrollPositionOptions, type ViewportSize, useScrollPosition, useViewportSize };

package/lib/index.js

@@ -1 +1 @@
-(function(e,t){typeof exports==`object`&&typeof module<`u`?t(exports,require(`react`)):typeof define==`function`&&define.amd?define([`exports`,`react`],t):(e=typeof globalThis<`u`?globalThis:e||self,t(e.reactAtomTrigger={},e.React))})(this,function(e,t){Object.defineProperty(e,Symbol.toStringTag,{value:`Module`});var n=Object.create,r=Object.defineProperty,i=Object.getOwnPropertyDescriptor,a=Object.getOwnPropertyNames,o=Object.getPrototypeOf,s=Object.prototype.hasOwnProperty,c=(e,t,n,o)=>{if(t&&typeof t==`object`||typeof t==`function`)for(var c=a(t),l=0,u=c.length,d;l<u;l++)d=c[l],!s.call(e,d)&&d!==n&&r(e,d,{get:(e=>t[e]).bind(null,d),enumerable:!(o=i(t,d))||o.enumerable});return e};t=((e,t,i)=>(i=e==null?{}:n(o(e)),c(t||!e||!e.__esModule?r(i,`default`,{value:e,enumerable:!0}):i,e)))(t);let l=({scrollEvent:e,callback:n,getDebugInfo:r,triggerOnce:i=!1,className:a,behavior:o=`default`,dimensions:s,offset:c=[0,0,0,0]})=>{let l=t.default.useRef(null),[u,d]=t.default.useState(void 0),f=t.default.useRef(void 0),[p,m]=t.default.useState({leftViewport:0,enteredViewport:0});return t.default.useLayoutEffect(()=>{if(l.current){let e=l.current.getBoundingClientRect(),[t,n,r,i]=c;e.top>t&&e.bottom<s.height-r&&e.left>i&&e.right<s.width-n?d(`inViewport`):e.top>s.height-r?d(`bottom`):d(`top`)}},[l,e,s,c]),t.default.useLayoutEffect(()=>{if(f.current===void 0&&u!==void 0&&(f.current=u),u===`inViewport`&&(f.current===`bottom`||f.current===`top`)){if(o===`enter`&&(!i||i&&p.enteredViewport)||o===`default`&&(!i||i&&(p.enteredViewport<1||p.leftViewport<1))){n&&n();let e={...p,enteredViewport:p.enteredViewport+1};r&&r({timesTriggered:e,trigger:`entered`}),m(e)}f.current=u}if((u===`top`||u===`bottom`)&&f.current===`inViewport`&&(f.current=u,o===`leave`&&(!i||i&&p.leftViewport===0)||o===`default`&&(!i||i&&(p.leftViewport<1||p.enteredViewport<1)))){n&&n();let e={...p,leftViewport:p.leftViewport+1};r&&r({timesTriggered:e,trigger:`left`}),m(e)}},[u,n,i,o,r]),t.default.createElement(`div`,{ref:l,style:{display:`table`},className:a})};function u(e,t){}function d(){let{scrollX:e,scrollY:t}=window;return{scrollX:e,scrollY:t}}function f(){let{innerWidth:e,innerHeight:t}=window;return{width:e,height:t}}function p(e){let[n,r]=t.default.useState(f()),i=t.default.useRef(null),a=t.default.useRef(!1),o=e?.eventListenerTimeoutMs||15;return t.default.useEffect(()=>{r(f());function t(){i.current&&clearTimeout(i.current),i.current=setTimeout(()=>r(f()),o)}return window.addEventListener(`resize`,t,{passive:e?.passiveEventListener}),a.current=!0,()=>{a&&window.removeEventListener(`resize`,t)}},[]),n}function m({containerRef:e,options:n}){let[r,i]=t.default.useState(d()),a=t.default.useRef(null),o=t.default.useRef(!1);return t.default.useEffect(()=>{let t=e=>{let t=e.target;a.current&&clearTimeout(a.current),a.current=setTimeout(()=>{i({scrollX:t.scrollLeft,scrollY:t.scrollTop})},n?.eventListenerTimeoutMs||15)},r=e?.current;return r&&(r&&o.current===!1&&r.addEventListener(`scroll`,t,{passive:n?.passiveEventListener}),o.current=!0),()=>{o&&r&&r.removeEventListener(`scroll`,t)}},[e]),r}function h(e){let[n,r]=t.default.useState(d()),i=t.default.useRef(null),a=t.default.useRef(!1);return t.default.useEffect(()=>{let t=()=>{i.current&&clearTimeout(i.current),i.current=setTimeout(()=>{let{scrollX:e,scrollY:t}=d();r({scrollX:e,scrollY:t})},e?.eventListenerTimeoutMs||20)};return window.addEventListener(`scroll`,t,{passive:e?.passiveEventListener}),a.current=!0,()=>{a&&window.removeEventListener(`scroll`,t)}},[]),n}e.AtomTrigger=l,e.log=u,e.useContainerScroll=m,e.useWindowDimensions=p,e.useWindowScroll=h});
+import e from"react";const t=new Set;function n(){if(typeof process>`u`||!process.env)return null;let e=`production`;return e===`development`||e===`production`?e:null}function r(e){n()===`development`&&(t.has(e)||(t.add(e),typeof console<`u`&&console.warn&&console.warn(e)))}const i=Symbol.for(`react.forward_ref`),a=Symbol.for(`react.memo`);function o(e,t){if(e){if(typeof e==`function`){e(t);return}e.current=t}}function s(e){if(typeof e==`string`||typeof e==`function`)return!0;if(typeof e!=`object`||!e)return!1;let t=e;return t.$$typeof===i?!0:t.$$typeof===a&&t.type?s(t.type):!1}function c(t,n,r,i){return t?n===1?r?i===e.Fragment?`[react-atom-trigger] Child mode does not support React.Fragment. Wrap the content in a single DOM element. Observation is disabled for this render.`:(!i||s(i),null):`[react-atom-trigger] Child mode expects a React element child. Observation is disabled for this render.`:`[react-atom-trigger] Child mode expects exactly one top-level React element. Observation is disabled for this render.`:null}function l(e){return Array.isArray(e)&&e.length===4&&e.every(e=>typeof e==`number`&&Number.isFinite(e))}function u(e){return typeof e==`string`?e:l(e)?e.map(e=>`${Object.is(e,-0)?0:e}px`).join(` `):(e==null||r(`[react-atom-trigger] Invalid rootMargin array ${JSON.stringify(e)}. Use exactly four finite numbers: [top, right, bottom, left]. Falling back to 0px.`),`0px`)}function d(e,t){let n=e.trim();if(!n||/^[+-]?0(?:\.0+)?$/.test(n))return 0;let i=n.match(/^([+-]?(?:\d+\.?\d*|\.\d+))(px|%)$/);if(!i)return r(`[react-atom-trigger] Invalid rootMargin token "${n}". Use px, % or 0. Falling back to 0px.`),0;let[,a,o]=i,s=Number.parseFloat(a);return o===`%`?s/100*t:s}function f(e,t,n){let i=e.trim().split(/\s+/).filter(Boolean);if(i.length>4)return r(`[react-atom-trigger] Invalid rootMargin "${e}". Use 1 to 4 values in IntersectionObserver order. Falling back to 0px.`),{top:0,right:0,bottom:0,left:0};let[a=`0px`,o=a,s=a,c=o]=i;return{top:d(a,n),right:d(o,t),bottom:d(s,n),left:d(c,t)}}function p(e,t){let n=f(t,e.width,e.height);return new DOMRect(e.left-n.left,e.top-n.top,e.width+n.left+n.right,e.height+n.top+n.bottom)}function m(e){let t=e.width>0?e.width:1,n=e.height>0?e.height:1;return t===e.width&&n===e.height?e:new DOMRect(e.left,e.top,t,n)}function h(e,t){let n=Math.max(e.left,t.left),r=Math.max(e.top,t.top),i=Math.min(e.right,t.right),a=Math.min(e.bottom,t.bottom);return i<=n||a<=r?new DOMRect(0,0,0,0):new DOMRect(n,r,i-n,a-r)}function g(e,t){let n=e.width*e.height;return n<=0?0:t.width*t.height/n}function _(e){return Math.min(1,Math.max(0,e))}function v(e){return Array.isArray(e)?(r("[react-atom-trigger] `threshold` expects a single number in v2. Using the first finite numeric entry."),_(e.find(e=>typeof e==`number`&&Number.isFinite(e))??0)):e==null?0:typeof e!=`number`||!Number.isFinite(e)?(r("[react-atom-trigger] `threshold` must be a finite number between 0 and 1. Falling back to 0."),0):((e<0||e>1)&&r("[react-atom-trigger] `threshold` should be between 0 and 1. Values are clamped."),_(e))}function y(e,t){if(!e)return`unknown`;let n=t.left-e.left,r=t.top-e.top;return n===0&&r===0?`stationary`:Math.abs(r)>=Math.abs(n)?r<0?`up`:`down`:n<0?`left`:`right`}function b(e){if(e.isIntersecting)return`inside`;let t=e.boundingClientRect,n=e.rootBounds?.top??0,r=e.rootBounds?.bottom??window.innerHeight,i=e.rootBounds?.left??0,a=e.rootBounds?.right??window.innerWidth;return t.bottom<=n?`above`:t.top>=r?`below`:t.right<=i?`left`:t.left>=a?`right`:`outside`}const x=new WeakMap;function S(){return new DOMRect(0,0,window.innerWidth,window.innerHeight)}function C(e){return e===window||typeof Window<`u`&&e instanceof Window}function w(e,t,n,r){return!(n&&t.entered+t.left>0||r&&(e===`enter`&&t.entered>0||e===`leave`&&t.left>0))}function T(e){return e.once?e.counts.entered+e.counts.left>0:e.oncePerDirection?e.counts.entered>0&&e.counts.left>0:!1}function E(e){e.previousTriggerActive=void 0,e.previousRect=null}function D(e,t){let n=m(e.node.getBoundingClientRect()),r=p(t,e.rootMargin),i=h(n,r),a=g(n,i),o=a>0,s=e.previousTriggerActive,c=s===!0||e.threshold===0?o:a>=e.threshold,l=y(e.previousRect,n);e.previousRect=n,e.previousTriggerActive=c;let u=Date.now(),d={target:e.node,rootBounds:r,boundingClientRect:n,intersectionRect:i,isIntersecting:o,intersectionRatio:a,source:`geometry`},f=s===void 0;if(f&&(!e.fireOnInitialVisible||!c)||s===c)return;let _=c?`enter`:`leave`;if(!w(_,e.counts,e.once,e.oncePerDirection))return;let v=_===`enter`?{...e.counts,entered:e.counts.entered+1}:{...e.counts,left:e.counts.left+1};e.counts=v;let x={type:_,isInitial:f,entry:d,counts:v,movementDirection:l,position:b(d),timestamp:u};e.onEvent?.(x),_===`enter`?e.onEnter?.(x):e.onLeave?.(x),T(e)&&e.dispose?.()}function O(e){let t={registrations:new Set,rafId:0,resizeObserver:null,intersectionObserver:null,queueSample:()=>{},cleanup:()=>{}},n=()=>{if(t.rafId=0,t.registrations.size===0)return;let n=C(e)?S():e.getBoundingClientRect();for(let e of t.registrations)D(e,n)},r=()=>{if(t.rafId!==0)return;t.rafId=-1;let e=window.requestAnimationFrame(()=>{t.rafId=0,n()});t.rafId===-1&&(t.rafId=e)},i=()=>{r()};return e.addEventListener(`scroll`,i,{passive:!0}),window.addEventListener(`resize`,i),typeof ResizeObserver<`u`&&(t.resizeObserver=new ResizeObserver(i),C(e)||t.resizeObserver.observe(e)),typeof IntersectionObserver<`u`&&(t.intersectionObserver=new IntersectionObserver(()=>{r()},{root:C(e)?null:e,rootMargin:`200% 200% 200% 200%`,threshold:0})),t.queueSample=r,t.cleanup=()=>{t.rafId!==0&&(cancelAnimationFrame(t.rafId),t.rafId=0),e.removeEventListener(`scroll`,i),window.removeEventListener(`resize`,i),t.resizeObserver?.disconnect(),t.intersectionObserver?.disconnect()},t}function k(e){let t=x.get(e);if(t)return t;let n=O(e);return x.set(e,n),n}function A(e,t){let n=k(e),r=!1;n.registrations.add(t),n.resizeObserver?.observe(t.node),n.intersectionObserver?.observe(t.node),n.queueSample();let i=()=>{r||(r=!0,n.registrations.delete(t),n.resizeObserver?.unobserve(t.node),n.intersectionObserver?.unobserve(t.node),t.dispose=void 0,n.registrations.size===0&&(n.cleanup(),x.delete(e)))};return t.dispose=i,i}function j(e,t){return t?t.current:e||(typeof window>`u`?null:window)}const M={display:`table`},N=({onEnter:t,onLeave:n,onEvent:i,children:a,once:s=!1,oncePerDirection:l=!1,fireOnInitialVisible:d=!1,disabled:f=!1,threshold:p=0,root:m=null,rootRef:h,rootMargin:g=`0px`,className:_})=>{let y=e.useRef(null),[b,x]=e.useState(null),S=e.useRef(null),C=e.useRef(null),w=e.useRef(null),T=e.useRef(null),D=u(g),O=v(p),k=a!=null,N=e.Children.count(a),P=N===1&&e.isValidElement(a)?a:null,F=c(k,N,P,P?P.type:null),I=F||!P?null:P,L=I?.props.ref,R=e.useCallback(e=>{if(o(L,e),e===null){S.current=null,x(e=>e===null?e:null);return}if(e instanceof Element){S.current=e,x(t=>t===e?t:e);return}S.current=null,x(e=>e===null?e:null),r(`[react-atom-trigger] Child mode requires the child ref to resolve to a DOM element. Observation is disabled for this render.`)},[L]);return e.useEffect(()=>{r(`[react-atom-trigger] v2 uses a new internal observation engine. If you upgraded from v1.x, verify trigger behavior for timing, threshold and rootMargin.`)},[]),e.useEffect(()=>{k&&_&&r("[react-atom-trigger] `className` only applies to the internal sentinel. In child mode, style the child element directly.")},[_,k]),e.useEffect(()=>{F&&r(F)},[F]),e.useEffect(()=>{if(typeof window>`u`||!k||!I||F||b)return;let e=window.setTimeout(()=>{S.current||r(`[react-atom-trigger] Child mode expects a DOM element or a component that forwards its ref to a DOM element. Observation is disabled for this render.`)},0);return()=>{window.clearTimeout(e)}},[b,I,k,F]),e.useEffect(()=>{let e=C.current;e&&(e.onEnter=t,e.onLeave=n,e.onEvent=i)},[t,n,i]),e.useEffect(()=>{if(typeof window>`u`)return;let e=k?b:y.current,r=j(m,h);if(!e){C.current&&E(C.current),w.current?.(),w.current=null,T.current=null;return}C.current?(C.current.node=e,C.current.rootMargin=D,C.current.threshold=O,C.current.once=s,C.current.oncePerDirection=l,C.current.fireOnInitialVisible=d):C.current={node:e,rootMargin:D,threshold:O,once:s,oncePerDirection:l,fireOnInitialVisible:d,onEnter:t,onLeave:n,onEvent:i,previousTriggerActive:void 0,previousRect:null,counts:{entered:0,left:0}};let a=C.current;if(f||!r){E(a),w.current?.(),w.current=null,T.current=null;return}let o=T.current,c={node:e,target:r,rootMargin:D,threshold:O,once:s,oncePerDirection:l,fireOnInitialVisible:d};(!o||o.node!==c.node||o.target!==c.target||o.rootMargin!==c.rootMargin||o.threshold!==c.threshold||o.once!==c.once||o.oncePerDirection!==c.oncePerDirection||o.fireOnInitialVisible!==c.fireOnInitialVisible)&&(E(a),w.current?.(),w.current=A(r,a),T.current=c)},[f,D,O,s,l,d,b,m,h?.current,k]),e.useEffect(()=>()=>{w.current?.(),w.current=null,T.current=null},[]),k?I?e.cloneElement(I,{ref:R}):e.createElement(e.Fragment,null,a):e.createElement(`div`,{ref:y,style:M,className:_})},P={x:0,y:0},F=typeof window>`u`?e.useEffect:e.useLayoutEffect;function I(e,t){let n=null,r=null,i=()=>{n&&(clearTimeout(n),n=null),r=Date.now(),e()};return{schedule:()=>{if(t<=0){i();return}let e=Date.now();if(r===null||e-r>=t){i();return}n||(n=setTimeout(()=>{i()},t-(e-r)))},cancel:()=>{n&&(clearTimeout(n),n=null)}}}function L(){return typeof window>`u`?{width:0,height:0}:{width:window.innerWidth,height:window.innerHeight}}function R(e){return!!(e&&typeof e==`object`&&!(typeof Window<`u`&&e instanceof Window)&&`current`in e)}function z(e){return R(e)?e.current:e||(typeof window>`u`?null:window)}function B(e){return e===window||typeof Window<`u`&&e instanceof Window}function V(e){if(B(e))return{x:e.scrollX,y:e.scrollY};let t=e;return{x:t.scrollLeft,y:t.scrollTop}}function H(t){let[n,r]=e.useState(L);return e.useEffect(()=>{if(typeof window>`u`||t?.enabled===!1)return;let e=t?.throttleMs??16;r(L());let n=I(()=>{r(L())},e);return window.addEventListener(`resize`,n.schedule,{passive:t?.passive}),()=>{n.cancel(),window.removeEventListener(`resize`,n.schedule)}},[t?.enabled,t?.passive,t?.throttleMs]),n}function U(t){let n=t?.target,r=R(n),[i,a]=e.useState(()=>{let e=z(n);return e?V(e):P}),[o,s]=e.useState(()=>r?z(n):null);F(()=>{if(!r)return;let e=z(n);s(t=>t===e?t:e)});let c=r?o:z(n);return e.useEffect(()=>{if(t?.enabled===!1){a(P);return}if(!c){a(P);return}let e=t?.throttleMs??16;a(V(c));let n=I(()=>{a(V(c))},e);return c.addEventListener(`scroll`,n.schedule,{passive:t?.passive}),()=>{n.cancel(),c.removeEventListener(`scroll`,n.schedule)}},[t?.enabled,t?.passive,t?.throttleMs,c]),i}export{N as AtomTrigger,U as useScrollPosition,H as useViewportSize};

package/lib/index.umd.js

@@ -0,0 +1 @@
+(function(e,t){typeof exports==`object`&&typeof module<`u`?t(exports,require(`react`)):typeof define==`function`&&define.amd?define([`exports`,`react`],t):(e=typeof globalThis<`u`?globalThis:e||self,t(e.reactAtomTrigger={},e.React))})(this,function(e,t){Object.defineProperty(e,Symbol.toStringTag,{value:`Module`});var n=Object.create,r=Object.defineProperty,i=Object.getOwnPropertyDescriptor,a=Object.getOwnPropertyNames,o=Object.getPrototypeOf,s=Object.prototype.hasOwnProperty,c=(e,t,n,o)=>{if(t&&typeof t==`object`||typeof t==`function`)for(var c=a(t),l=0,u=c.length,d;l<u;l++)d=c[l],!s.call(e,d)&&d!==n&&r(e,d,{get:(e=>t[e]).bind(null,d),enumerable:!(o=i(t,d))||o.enumerable});return e};t=((e,t,i)=>(i=e==null?{}:n(o(e)),c(t||!e||!e.__esModule?r(i,`default`,{value:e,enumerable:!0}):i,e)))(t);let l=new Set;function u(){if(typeof process>`u`||!process.env)return null;let e=`production`;return e===`development`||e===`production`?e:null}function d(e){u()===`development`&&(l.has(e)||(l.add(e),typeof console<`u`&&console.warn&&console.warn(e)))}let f=Symbol.for(`react.forward_ref`),p=Symbol.for(`react.memo`);function m(e,t){if(e){if(typeof e==`function`){e(t);return}e.current=t}}function h(e){if(typeof e==`string`||typeof e==`function`)return!0;if(typeof e!=`object`||!e)return!1;let t=e;return t.$$typeof===f?!0:t.$$typeof===p&&t.type?h(t.type):!1}function g(e,n,r,i){return e?n===1?r?i===t.default.Fragment?`[react-atom-trigger] Child mode does not support React.Fragment. Wrap the content in a single DOM element. Observation is disabled for this render.`:(!i||h(i),null):`[react-atom-trigger] Child mode expects a React element child. Observation is disabled for this render.`:`[react-atom-trigger] Child mode expects exactly one top-level React element. Observation is disabled for this render.`:null}function _(e){return Array.isArray(e)&&e.length===4&&e.every(e=>typeof e==`number`&&Number.isFinite(e))}function v(e){return typeof e==`string`?e:_(e)?e.map(e=>`${Object.is(e,-0)?0:e}px`).join(` `):(e==null||d(`[react-atom-trigger] Invalid rootMargin array ${JSON.stringify(e)}. Use exactly four finite numbers: [top, right, bottom, left]. Falling back to 0px.`),`0px`)}function y(e,t){let n=e.trim();if(!n||/^[+-]?0(?:\.0+)?$/.test(n))return 0;let r=n.match(/^([+-]?(?:\d+\.?\d*|\.\d+))(px|%)$/);if(!r)return d(`[react-atom-trigger] Invalid rootMargin token "${n}". Use px, % or 0. Falling back to 0px.`),0;let[,i,a]=r,o=Number.parseFloat(i);return a===`%`?o/100*t:o}function b(e,t,n){let r=e.trim().split(/\s+/).filter(Boolean);if(r.length>4)return d(`[react-atom-trigger] Invalid rootMargin "${e}". Use 1 to 4 values in IntersectionObserver order. Falling back to 0px.`),{top:0,right:0,bottom:0,left:0};let[i=`0px`,a=i,o=i,s=a]=r;return{top:y(i,n),right:y(a,t),bottom:y(o,n),left:y(s,t)}}function x(e,t){let n=b(t,e.width,e.height);return new DOMRect(e.left-n.left,e.top-n.top,e.width+n.left+n.right,e.height+n.top+n.bottom)}function S(e){let t=e.width>0?e.width:1,n=e.height>0?e.height:1;return t===e.width&&n===e.height?e:new DOMRect(e.left,e.top,t,n)}function C(e,t){let n=Math.max(e.left,t.left),r=Math.max(e.top,t.top),i=Math.min(e.right,t.right),a=Math.min(e.bottom,t.bottom);return i<=n||a<=r?new DOMRect(0,0,0,0):new DOMRect(n,r,i-n,a-r)}function w(e,t){let n=e.width*e.height;return n<=0?0:t.width*t.height/n}function T(e){return Math.min(1,Math.max(0,e))}function E(e){return Array.isArray(e)?(d("[react-atom-trigger] `threshold` expects a single number in v2. Using the first finite numeric entry."),T(e.find(e=>typeof e==`number`&&Number.isFinite(e))??0)):e==null?0:typeof e!=`number`||!Number.isFinite(e)?(d("[react-atom-trigger] `threshold` must be a finite number between 0 and 1. Falling back to 0."),0):((e<0||e>1)&&d("[react-atom-trigger] `threshold` should be between 0 and 1. Values are clamped."),T(e))}function D(e,t){if(!e)return`unknown`;let n=t.left-e.left,r=t.top-e.top;return n===0&&r===0?`stationary`:Math.abs(r)>=Math.abs(n)?r<0?`up`:`down`:n<0?`left`:`right`}function O(e){if(e.isIntersecting)return`inside`;let t=e.boundingClientRect,n=e.rootBounds?.top??0,r=e.rootBounds?.bottom??window.innerHeight,i=e.rootBounds?.left??0,a=e.rootBounds?.right??window.innerWidth;return t.bottom<=n?`above`:t.top>=r?`below`:t.right<=i?`left`:t.left>=a?`right`:`outside`}let k=new WeakMap;function A(){return new DOMRect(0,0,window.innerWidth,window.innerHeight)}function j(e){return e===window||typeof Window<`u`&&e instanceof Window}function M(e,t,n,r){return!(n&&t.entered+t.left>0||r&&(e===`enter`&&t.entered>0||e===`leave`&&t.left>0))}function N(e){return e.once?e.counts.entered+e.counts.left>0:e.oncePerDirection?e.counts.entered>0&&e.counts.left>0:!1}function P(e){e.previousTriggerActive=void 0,e.previousRect=null}function F(e,t){let n=S(e.node.getBoundingClientRect()),r=x(t,e.rootMargin),i=C(n,r),a=w(n,i),o=a>0,s=e.previousTriggerActive,c=s===!0||e.threshold===0?o:a>=e.threshold,l=D(e.previousRect,n);e.previousRect=n,e.previousTriggerActive=c;let u=Date.now(),d={target:e.node,rootBounds:r,boundingClientRect:n,intersectionRect:i,isIntersecting:o,intersectionRatio:a,source:`geometry`},f=s===void 0;if(f&&(!e.fireOnInitialVisible||!c)||s===c)return;let p=c?`enter`:`leave`;if(!M(p,e.counts,e.once,e.oncePerDirection))return;let m=p===`enter`?{...e.counts,entered:e.counts.entered+1}:{...e.counts,left:e.counts.left+1};e.counts=m;let h={type:p,isInitial:f,entry:d,counts:m,movementDirection:l,position:O(d),timestamp:u};e.onEvent?.(h),p===`enter`?e.onEnter?.(h):e.onLeave?.(h),N(e)&&e.dispose?.()}function I(e){let t={registrations:new Set,rafId:0,resizeObserver:null,intersectionObserver:null,queueSample:()=>{},cleanup:()=>{}},n=()=>{if(t.rafId=0,t.registrations.size===0)return;let n=j(e)?A():e.getBoundingClientRect();for(let e of t.registrations)F(e,n)},r=()=>{if(t.rafId!==0)return;t.rafId=-1;let e=window.requestAnimationFrame(()=>{t.rafId=0,n()});t.rafId===-1&&(t.rafId=e)},i=()=>{r()};return e.addEventListener(`scroll`,i,{passive:!0}),window.addEventListener(`resize`,i),typeof ResizeObserver<`u`&&(t.resizeObserver=new ResizeObserver(i),j(e)||t.resizeObserver.observe(e)),typeof IntersectionObserver<`u`&&(t.intersectionObserver=new IntersectionObserver(()=>{r()},{root:j(e)?null:e,rootMargin:`200% 200% 200% 200%`,threshold:0})),t.queueSample=r,t.cleanup=()=>{t.rafId!==0&&(cancelAnimationFrame(t.rafId),t.rafId=0),e.removeEventListener(`scroll`,i),window.removeEventListener(`resize`,i),t.resizeObserver?.disconnect(),t.intersectionObserver?.disconnect()},t}function L(e){let t=k.get(e);if(t)return t;let n=I(e);return k.set(e,n),n}function R(e,t){let n=L(e),r=!1;n.registrations.add(t),n.resizeObserver?.observe(t.node),n.intersectionObserver?.observe(t.node),n.queueSample();let i=()=>{r||(r=!0,n.registrations.delete(t),n.resizeObserver?.unobserve(t.node),n.intersectionObserver?.unobserve(t.node),t.dispose=void 0,n.registrations.size===0&&(n.cleanup(),k.delete(e)))};return t.dispose=i,i}function z(e,t){return t?t.current:e||(typeof window>`u`?null:window)}let B={display:`table`},V=({onEnter:e,onLeave:n,onEvent:r,children:i,once:a=!1,oncePerDirection:o=!1,fireOnInitialVisible:s=!1,disabled:c=!1,threshold:l=0,root:u=null,rootRef:f,rootMargin:p=`0px`,className:h})=>{let _=t.default.useRef(null),[y,b]=t.default.useState(null),x=t.default.useRef(null),S=t.default.useRef(null),C=t.default.useRef(null),w=t.default.useRef(null),T=v(p),D=E(l),O=i!=null,k=t.default.Children.count(i),A=k===1&&t.default.isValidElement(i)?i:null,j=g(O,k,A,A?A.type:null),M=j||!A?null:A,N=M?.props.ref,F=t.default.useCallback(e=>{if(m(N,e),e===null){x.current=null,b(e=>e===null?e:null);return}if(e instanceof Element){x.current=e,b(t=>t===e?t:e);return}x.current=null,b(e=>e===null?e:null),d(`[react-atom-trigger] Child mode requires the child ref to resolve to a DOM element. Observation is disabled for this render.`)},[N]);return t.default.useEffect(()=>{d(`[react-atom-trigger] v2 uses a new internal observation engine. If you upgraded from v1.x, verify trigger behavior for timing, threshold and rootMargin.`)},[]),t.default.useEffect(()=>{O&&h&&d("[react-atom-trigger] `className` only applies to the internal sentinel. In child mode, style the child element directly.")},[h,O]),t.default.useEffect(()=>{j&&d(j)},[j]),t.default.useEffect(()=>{if(typeof window>`u`||!O||!M||j||y)return;let e=window.setTimeout(()=>{x.current||d(`[react-atom-trigger] Child mode expects a DOM element or a component that forwards its ref to a DOM element. Observation is disabled for this render.`)},0);return()=>{window.clearTimeout(e)}},[y,M,O,j]),t.default.useEffect(()=>{let t=S.current;t&&(t.onEnter=e,t.onLeave=n,t.onEvent=r)},[e,n,r]),t.default.useEffect(()=>{if(typeof window>`u`)return;let t=O?y:_.current,i=z(u,f);if(!t){S.current&&P(S.current),C.current?.(),C.current=null,w.current=null;return}S.current?(S.current.node=t,S.current.rootMargin=T,S.current.threshold=D,S.current.once=a,S.current.oncePerDirection=o,S.current.fireOnInitialVisible=s):S.current={node:t,rootMargin:T,threshold:D,once:a,oncePerDirection:o,fireOnInitialVisible:s,onEnter:e,onLeave:n,onEvent:r,previousTriggerActive:void 0,previousRect:null,counts:{entered:0,left:0}};let l=S.current;if(c||!i){P(l),C.current?.(),C.current=null,w.current=null;return}let d=w.current,p={node:t,target:i,rootMargin:T,threshold:D,once:a,oncePerDirection:o,fireOnInitialVisible:s};(!d||d.node!==p.node||d.target!==p.target||d.rootMargin!==p.rootMargin||d.threshold!==p.threshold||d.once!==p.once||d.oncePerDirection!==p.oncePerDirection||d.fireOnInitialVisible!==p.fireOnInitialVisible)&&(P(l),C.current?.(),C.current=R(i,l),w.current=p)},[c,T,D,a,o,s,y,u,f?.current,O]),t.default.useEffect(()=>()=>{C.current?.(),C.current=null,w.current=null},[]),O?M?t.default.cloneElement(M,{ref:F}):t.default.createElement(t.default.Fragment,null,i):t.default.createElement(`div`,{ref:_,style:B,className:h})},H={x:0,y:0},U=typeof window>`u`?t.default.useEffect:t.default.useLayoutEffect;function W(e,t){let n=null,r=null,i=()=>{n&&(clearTimeout(n),n=null),r=Date.now(),e()};return{schedule:()=>{if(t<=0){i();return}let e=Date.now();if(r===null||e-r>=t){i();return}n||(n=setTimeout(()=>{i()},t-(e-r)))},cancel:()=>{n&&(clearTimeout(n),n=null)}}}function G(){return typeof window>`u`?{width:0,height:0}:{width:window.innerWidth,height:window.innerHeight}}function K(e){return!!(e&&typeof e==`object`&&!(typeof Window<`u`&&e instanceof Window)&&`current`in e)}function q(e){return K(e)?e.current:e||(typeof window>`u`?null:window)}function J(e){return e===window||typeof Window<`u`&&e instanceof Window}function Y(e){if(J(e))return{x:e.scrollX,y:e.scrollY};let t=e;return{x:t.scrollLeft,y:t.scrollTop}}function X(e){let[n,r]=t.default.useState(G);return t.default.useEffect(()=>{if(typeof window>`u`||e?.enabled===!1)return;let t=e?.throttleMs??16;r(G());let n=W(()=>{r(G())},t);return window.addEventListener(`resize`,n.schedule,{passive:e?.passive}),()=>{n.cancel(),window.removeEventListener(`resize`,n.schedule)}},[e?.enabled,e?.passive,e?.throttleMs]),n}function Z(e){let n=e?.target,r=K(n),[i,a]=t.default.useState(()=>{let e=q(n);return e?Y(e):H}),[o,s]=t.default.useState(()=>r?q(n):null);U(()=>{if(!r)return;let e=q(n);s(t=>t===e?t:e)});let c=r?o:q(n);return t.default.useEffect(()=>{if(e?.enabled===!1){a(H);return}if(!c){a(H);return}let t=e?.throttleMs??16;a(Y(c));let n=W(()=>{a(Y(c))},t);return c.addEventListener(`scroll`,n.schedule,{passive:e?.passive}),()=>{n.cancel(),c.removeEventListener(`scroll`,n.schedule)}},[e?.enabled,e?.passive,e?.throttleMs,c]),i}e.AtomTrigger=V,e.useScrollPosition=Z,e.useViewportSize=X});

package/package.json

@@ -1,47 +1,96 @@
 {
   "name": "react-atom-trigger",
-  "type": "module",
-  "description": "React component to execute code when you scroll to an element. Simple react-waypoint alternative in typescript.",
-  "main": "lib/index.js",
-  "module": "lib/index.es.js",
-  "typings": "lib/index.d.ts",
-  "version": "1.1.0",
+  "version": "2.0.0",
+  "description": "Geometry-based scroll trigger for React with precise enter/leave control. A modern alternative to react-waypoint.",
+  "keywords": [
+    "intersection",
+    "observer",
+    "on-scroll",
+    "react",
+    "scroll",
+    "scroll-into-view",
+    "v2"
+  ],
+  "homepage": "https://atomtrigger.dev",
+  "bugs": {
+    "url": "https://github.com/innrvoice/react-atom-trigger/issues"
+  },
   "license": "MIT",
-  "author": "innrVoice <innrvoice@icloud.com>",
+  "author": "Pavel Bochkov-Rastopchin <hello@visiofutura.com>",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/innrvoice/react-atom-trigger.git"
   },
-  "bugs": {
-    "url": "https://github.com/innrvoice/react-atom-trigger/issues"
+  "files": [
+    "lib",
+    "MIGRATION.md"
+  ],
+  "type": "module",
+  "main": "./lib/index.js",
+  "module": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "typings": "./lib/index.d.ts",
+  "unpkg": "./lib/index.umd.js",
+  "jsdelivr": "./lib/index.umd.js",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "default": "./lib/index.js"
+    }
   },
   "scripts": {
     "build": "tsdown",
-    "lint": "oxlint . --ignore-pattern node_modules --ignore-pattern lib"
-  },
-  "peerDependencies": {
-    "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+    "build:sb": "pnpm build-storybook",
+    "deploy:storybook": "pnpm build:sb",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
+    "lint": "oxlint . --ignore-pattern node_modules --ignore-pattern lib",
+    "prepare": "node scripts/setup-git-hooks.mjs",
+    "preview:sb": "pnpm build:sb && npx serve -s storybook-static -l 3000",
+    "precommit:checks": "pnpm format:check && pnpm lint && pnpm test",
+    "test": "pnpm test:all",
+    "test:all": "pnpm test:unit && pnpm test:storybook",
+    "test:unit": "vitest run --project=unit --reporter=verbose",
+    "test:watch": "vitest --project=unit",
+    "test:storybook": "vitest run --project=storybook",
+    "storybook": "storybook dev",
+    "build-storybook": "storybook build -o storybook-static"
   },
   "devDependencies": {
+    "@storybook/addon-docs": "10.3.4",
+    "@storybook/addon-vitest": "10.3.4",
+    "@storybook/react-vite": "10.3.4",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
     "@types/node": "^20.6.3",
     "@types/react": "^19.0.12",
+    "@types/react-dom": "^19.2.3",
+    "@vitest/browser-playwright": "4.1.2",
+    "@vitest/coverage-v8": "4.1.2",
+    "jsdom": "^29.0.1",
+    "oxfmt": "^0.43.0",
     "oxlint": "^1.50.0",
-    "prettier": "^3.4.2",
-    "tsdown": "^0.21.0-beta.2",
+    "playwright": "^1.59.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "storybook": "10.3.4",
+    "tsdown": "^0.21.7",
     "tslib": "^2.8.0",
-    "typescript": "^5.6.3"
+    "typescript": "^5.6.3",
+    "vite": "^6.0.0",
+    "vitest": "^4.1.2"
+  },
+  "peerDependencies": {
+    "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
   },
-  "keywords": [
-    "react",
-    "scroll",
-    "on-scroll",
-    "scroll-into-view",
-    "waypoint-alternative"
-  ],
-  "files": [
-    "lib"
-  ],
   "engines": {
     "node": ">=20.19.0"
+  },
+  "packageManager": "pnpm@10.33.0+sha512.10568bb4a6afb58c9eb3630da90cc9516417abebd3fabbe6739f0ae795728da1491e9db5a544c76ad8eb7570f5c4bb3d6c637b2cb41bfdcdb47fa823c8649319",
+  "pnpm": {
+    "overrides": {
+      "picomatch": "^4.0.4"
+    }
   }
 }

package/lib/index.es.js

@@ -1 +0,0 @@
-import e from"react";const t=({scrollEvent:t,callback:n,getDebugInfo:r,triggerOnce:i=!1,className:a,behavior:o=`default`,dimensions:s,offset:c=[0,0,0,0]})=>{let l=e.useRef(null),[u,d]=e.useState(void 0),f=e.useRef(void 0),[p,m]=e.useState({leftViewport:0,enteredViewport:0});return e.useLayoutEffect(()=>{if(l.current){let e=l.current.getBoundingClientRect(),[t,n,r,i]=c;e.top>t&&e.bottom<s.height-r&&e.left>i&&e.right<s.width-n?d(`inViewport`):e.top>s.height-r?d(`bottom`):d(`top`)}},[l,t,s,c]),e.useLayoutEffect(()=>{if(f.current===void 0&&u!==void 0&&(f.current=u),u===`inViewport`&&(f.current===`bottom`||f.current===`top`)){if(o===`enter`&&(!i||i&&p.enteredViewport)||o===`default`&&(!i||i&&(p.enteredViewport<1||p.leftViewport<1))){n&&n();let e={...p,enteredViewport:p.enteredViewport+1};r&&r({timesTriggered:e,trigger:`entered`}),m(e)}f.current=u}if((u===`top`||u===`bottom`)&&f.current===`inViewport`&&(f.current=u,o===`leave`&&(!i||i&&p.leftViewport===0)||o===`default`&&(!i||i&&(p.leftViewport<1||p.enteredViewport<1)))){n&&n();let e={...p,leftViewport:p.leftViewport+1};r&&r({timesTriggered:e,trigger:`left`}),m(e)}},[u,n,i,o,r]),e.createElement(`div`,{ref:l,style:{display:`table`},className:a})};function n(e,t){}function r(){let{scrollX:e,scrollY:t}=window;return{scrollX:e,scrollY:t}}function i(){let{innerWidth:e,innerHeight:t}=window;return{width:e,height:t}}function a(t){let[n,r]=e.useState(i()),a=e.useRef(null),o=e.useRef(!1),s=t?.eventListenerTimeoutMs||15;return e.useEffect(()=>{r(i());function e(){a.current&&clearTimeout(a.current),a.current=setTimeout(()=>r(i()),s)}return window.addEventListener(`resize`,e,{passive:t?.passiveEventListener}),o.current=!0,()=>{o&&window.removeEventListener(`resize`,e)}},[]),n}function o({containerRef:t,options:n}){let[i,a]=e.useState(r()),o=e.useRef(null),s=e.useRef(!1);return e.useEffect(()=>{let e=e=>{let t=e.target;o.current&&clearTimeout(o.current),o.current=setTimeout(()=>{a({scrollX:t.scrollLeft,scrollY:t.scrollTop})},n?.eventListenerTimeoutMs||15)},r=t?.current;return r&&(r&&s.current===!1&&r.addEventListener(`scroll`,e,{passive:n?.passiveEventListener}),s.current=!0),()=>{s&&r&&r.removeEventListener(`scroll`,e)}},[t]),i}function s(t){let[n,i]=e.useState(r()),a=e.useRef(null),o=e.useRef(!1);return e.useEffect(()=>{let e=()=>{a.current&&clearTimeout(a.current),a.current=setTimeout(()=>{let{scrollX:e,scrollY:t}=r();i({scrollX:e,scrollY:t})},t?.eventListenerTimeoutMs||20)};return window.addEventListener(`scroll`,e,{passive:t?.passiveEventListener}),o.current=!0,()=>{o&&window.removeEventListener(`scroll`,e)}},[]),n}export{t as AtomTrigger,n as log,o as useContainerScroll,a as useWindowDimensions,s as useWindowScroll};