Feature/2.0.8

package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-atom-trigger",
-  "version": "2.0.7",
+  "version": "2.0.8",
   "description": "Geometry-based scroll trigger for React with precise enter/leave control. A modern alternative to react-waypoint.",
   "keywords": [
     "intersection",
@@ -26,6 +26,7 @@
     "MIGRATION.md"
   ],
   "type": "module",
+  "sideEffects": false,
   "main": "./lib/index.js",
   "module": "./lib/index.js",
   "types": "./lib/index.d.ts",

src/AtomTrigger.childMode.helpers.test.ts

@@ -10,11 +10,14 @@ import {
 } from './AtomTrigger.childMode';
 import {
   fragmentChildWarning,
+  getWarningMessage,
   invalidChildCountWarning,
   invalidChildElementWarning,
   unsupportedChildRefWarning,
 } from './AtomTrigger.warnings';
 
+const initialNodeEnv = process.env.NODE_ENV;
+
 function stubProcess(processValue: Partial<Pick<NodeJS.Process, 'env'>>): void {
   vi.stubGlobal('process', processValue as unknown as NodeJS.Process);
 }
@@ -46,7 +49,13 @@ function createBrokenChildElement(
 describe('AtomTrigger child mode helpers', () => {
   afterEach(() => {
     vi.useRealTimers();
+    vi.unstubAllGlobals();
     vi.restoreAllMocks();
+    if (initialNodeEnv === undefined) {
+      delete process.env.NODE_ENV;
+    } else {
+      process.env.NODE_ENV = initialNodeEnv;
+    }
   });
 
   describe('assignRef', () => {
@@ -139,6 +148,31 @@ describe('AtomTrigger child mode helpers', () => {
   });
 
   describe('useObservedChildNode', () => {
+    it('keeps non-DOM child ref warnings out of non-development runtimes', () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      let attachObservedChildRef: ((value: unknown) => void) | undefined;
+      process.env.NODE_ENV = 'production';
+
+      function Harness() {
+        const binding = useObservedChildNode({
+          originalChildRef: undefined,
+          hasObservedChild: true,
+          invalidChildWarning: null,
+          shouldWarnAboutMissingDomRef: true,
+        });
+        attachObservedChildRef = binding.attachObservedChildRef;
+        return null;
+      }
+
+      render(React.createElement(Harness));
+
+      act(() => {
+        attachObservedChildRef?.({ current: document.createElement('div') });
+      });
+
+      expect(warn).not.toHaveBeenCalled();
+    });
+
     it('keeps the delayed missing-dom warning silent when a DOM ref appears before the timer callback runs', () => {
       vi.useFakeTimers();
       const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
@@ -168,7 +202,63 @@ describe('AtomTrigger child mode helpers', () => {
         vi.advanceTimersByTime(16);
       });
 
-      expect(warn).not.toHaveBeenCalledWith(unsupportedChildRefWarning);
+      expect(warn).not.toHaveBeenCalledWith(getWarningMessage(unsupportedChildRefWarning));
+    });
+
+    it('keeps the observed child node stable when the same DOM ref is attached again', () => {
+      const node = document.createElement('div');
+      let attachObservedChildRef: ((value: unknown) => void) | undefined;
+      let observedChildNode: Element | null = null;
+
+      function Harness() {
+        const binding = useObservedChildNode({
+          originalChildRef: undefined,
+          hasObservedChild: true,
+          invalidChildWarning: null,
+          shouldWarnAboutMissingDomRef: false,
+        });
+        attachObservedChildRef = binding.attachObservedChildRef;
+        observedChildNode = binding.childNode;
+        return null;
+      }
+
+      render(React.createElement(Harness));
+
+      act(() => {
+        attachObservedChildRef?.(node);
+      });
+
+      expect(observedChildNode).toBe(node);
+
+      act(() => {
+        attachObservedChildRef?.(node);
+      });
+
+      expect(observedChildNode).toBe(node);
+    });
+
+    it('keeps delayed missing-dom warnings out of non-development runtimes', () => {
+      vi.useFakeTimers();
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      process.env.NODE_ENV = 'production';
+
+      function Harness() {
+        useObservedChildNode({
+          originalChildRef: undefined,
+          hasObservedChild: true,
+          invalidChildWarning: null,
+          shouldWarnAboutMissingDomRef: true,
+        });
+        return null;
+      }
+
+      render(React.createElement(Harness));
+
+      act(() => {
+        vi.advanceTimersByTime(16);
+      });
+
+      expect(warn).not.toHaveBeenCalledWith(getWarningMessage(unsupportedChildRefWarning));
     });
   });
 });

src/AtomTrigger.childMode.test.tsx

@@ -10,7 +10,11 @@ import {
   setRect,
   setupChildRootHarness,
 } from './AtomTrigger.testUtils';
-import { nonDomChildRefWarning, unsupportedChildRefWarning } from './AtomTrigger.warnings';
+import {
+  getWarningMessage,
+  nonDomChildRefWarning,
+  unsupportedChildRefWarning,
+} from './AtomTrigger.warnings';
 
 beforeEach(() => {
   prepareDomTestRun();
@@ -100,7 +104,7 @@ describe('AtomTrigger child mode', () => {
     );
 
     expect(view.getByTestId('imperative-handle-child')).toBeTruthy();
-    expect(warn).toHaveBeenCalledWith(nonDomChildRefWarning);
+    expect(warn).toHaveBeenCalledWith(getWarningMessage(nonDomChildRefWarning));
     expect(error).not.toHaveBeenCalled();
   });
 
@@ -166,7 +170,11 @@ describe('AtomTrigger child mode', () => {
       vi.advanceTimersByTime(16);
     });
 
-    expect(warn.mock.calls.some(([message]) => message === unsupportedChildRefWarning)).toBe(false);
+    expect(
+      warn.mock.calls.some(
+        ([message]) => message === getWarningMessage(unsupportedChildRefWarning),
+      ),
+    ).toBe(false);
   });
 
   it('warns and ignores className in child mode', () => {

src/AtomTrigger.childMode.ts

@@ -1,10 +1,12 @@
 import React from 'react';
 import {
   fragmentChildWarning,
+  getWarningMessage,
   invalidChildCountWarning,
   invalidChildElementWarning,
   nonDomChildRefWarning,
   unsupportedChildRefWarning,
+  type AtomTriggerWarning,
   warnOnce,
 } from './AtomTrigger.warnings';
 import { isDomElementLike } from './AtomTrigger.runtime';
@@ -68,7 +70,7 @@ export function getInvalidChildWarning(
   usesChildObservation: boolean,
   childCount: number,
   singleChildElement: React.ReactElement | null,
-): string | null {
+): AtomTriggerWarning | null {
   if (!usesChildObservation) {
     return null;
   }
@@ -96,7 +98,7 @@ export function useObservedChildNode({
 }: {
   originalChildRef: React.Ref<unknown> | undefined;
   hasObservedChild: boolean;
-  invalidChildWarning: string | null;
+  invalidChildWarning: AtomTriggerWarning | null;
   shouldWarnAboutMissingDomRef: boolean;
 }): ObservedChildBinding {
   const [childNode, setChildNode] = React.useState<Element | null>(null);
@@ -123,7 +125,9 @@ export function useObservedChildNode({
       }
 
       clearObservedChildNode();
-      warnOnce(nonDomChildRefWarning);
+      if (process.env.NODE_ENV === 'development') {
+        warnOnce(getWarningMessage(nonDomChildRefWarning));
+      }
     },
     [clearObservedChildNode, originalChildRef],
   );
@@ -141,7 +145,9 @@ export function useObservedChildNode({
         return;
       }
 
-      warnOnce(unsupportedChildRefWarning);
+      if (process.env.NODE_ENV === 'development') {
+        warnOnce(getWarningMessage(unsupportedChildRefWarning));
+      }
     }, missingDomRefWarningDelayMs);
 
     return () => {

src/AtomTrigger.geometry.test.ts

@@ -57,6 +57,17 @@ describe('AtomTrigger geometry helpers', () => {
         '[react-atom-trigger] Invalid rootMargin array [1,2,null,4]. Use exactly four finite numbers: [top, right, bottom, left]. Falling back to 0px.',
       );
     });
+
+    it('keeps invalid array warnings out of non-development runtimes', () => {
+      process.env.NODE_ENV = 'production';
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      expect(normalizeRootMargin([1, 2, Number.NaN, 4] as [number, number, number, number])).toBe(
+        '0px',
+      );
+
+      expect(warn).not.toHaveBeenCalled();
+    });
   });
 
   describe('getEffectiveRootBounds', () => {
@@ -93,6 +104,15 @@ describe('AtomTrigger geometry helpers', () => {
         '[react-atom-trigger] Invalid rootMargin "1px 2px 3px 4px 5px". Use 1 to 4 values in IntersectionObserver order. Falling back to 0px.',
       );
     });
+
+    it('keeps invalid rootMargin token warnings out of non-development runtimes', () => {
+      process.env.NODE_ENV = 'production';
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      expect(getEffectiveRootBounds(base, '1px auto')).toEqual(new DOMRect(10, 19, 200, 101));
+      expect(getEffectiveRootBounds(base, '1px 2px 3px 4px 5px')).toEqual(base);
+      expect(warn).not.toHaveBeenCalled();
+    });
   });
 
   describe('intersection math', () => {
@@ -162,6 +182,17 @@ describe('AtomTrigger geometry helpers', () => {
         '[react-atom-trigger] `threshold` should be between 0 and 1. Values are clamped.',
       );
     });
+
+    it('keeps invalid threshold warnings out of non-development runtimes', () => {
+      process.env.NODE_ENV = 'production';
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      expect(normalizeThreshold([Number.NaN, 0.25])).toBe(0.25);
+      expect(normalizeThreshold([Number.NaN])).toBe(0);
+      expect(normalizeThreshold('nope')).toBe(0);
+      expect(normalizeThreshold(1.5)).toBe(1);
+      expect(warn).not.toHaveBeenCalled();
+    });
   });
 
   it('detects movement direction across stationary, vertical, and horizontal changes', () => {

src/AtomTrigger.geometry.ts

@@ -36,28 +36,28 @@ export function normalizeRootMargin(
     return '0px';
   }
 
-  warnOnce(
-    `[react-atom-trigger] Invalid rootMargin array ${JSON.stringify(rootMargin)}. Use exactly four finite numbers: [top, right, bottom, left]. Falling back to 0px.`,
-  );
+  if (process.env.NODE_ENV === 'development') {
+    warnOnce(
+      `[react-atom-trigger] Invalid rootMargin array ${JSON.stringify(rootMargin)}. Use exactly four finite numbers: [top, right, bottom, left]. Falling back to 0px.`,
+    );
+  }
 
   return '0px';
 }
 
 function parseMarginPart(part: string, axisSize: number): number {
   const value = part.trim();
-  if (!value) {
-    return 0;
-  }
-
   if (/^[+-]?0(?:\.0+)?$/.test(value)) {
     return 0;
   }
 
   const match = value.match(/^([+-]?(?:\d+\.?\d*|\.\d+))(px|%)$/);
   if (!match) {
-    warnOnce(
-      `[react-atom-trigger] Invalid rootMargin token "${value}". Use px, % or 0. Falling back to 0px.`,
-    );
+    if (process.env.NODE_ENV === 'development') {
+      warnOnce(
+        `[react-atom-trigger] Invalid rootMargin token "${value}". Use px, % or 0. Falling back to 0px.`,
+      );
+    }
     return 0;
   }
 
@@ -78,9 +78,11 @@ function resolveRootMargin(
 ): RootMarginValues {
   const parts = rootMargin.trim().split(/\s+/).filter(Boolean);
   if (parts.length > 4) {
-    warnOnce(
-      `[react-atom-trigger] Invalid rootMargin "${rootMargin}". Use 1 to 4 values in IntersectionObserver order. Falling back to 0px.`,
-    );
+    if (process.env.NODE_ENV === 'development') {
+      warnOnce(
+        `[react-atom-trigger] Invalid rootMargin "${rootMargin}". Use 1 to 4 values in IntersectionObserver order. Falling back to 0px.`,
+      );
+    }
 
     return {
       top: 0,
@@ -159,9 +161,11 @@ function clampThreshold(value: number): number {
 
 export function normalizeThreshold(threshold: unknown): number {
   if (Array.isArray(threshold)) {
-    warnOnce(
-      '[react-atom-trigger] `threshold` expects a single number in v2. Using the first finite numeric entry.',
-    );
+    if (process.env.NODE_ENV === 'development') {
+      warnOnce(
+        '[react-atom-trigger] `threshold` expects a single number in v2. Using the first finite numeric entry.',
+      );
+    }
     const firstNumeric = threshold.find(
       (value): value is number => typeof value === 'number' && Number.isFinite(value),
     );
@@ -173,14 +177,18 @@ export function normalizeThreshold(threshold: unknown): number {
   }
 
   if (typeof threshold !== 'number' || !Number.isFinite(threshold)) {
-    warnOnce(
-      '[react-atom-trigger] `threshold` must be a finite number between 0 and 1. Falling back to 0.',
-    );
+    if (process.env.NODE_ENV === 'development') {
+      warnOnce(
+        '[react-atom-trigger] `threshold` must be a finite number between 0 and 1. Falling back to 0.',
+      );
+    }
     return 0;
   }
 
   if (threshold < 0 || threshold > 1) {
-    warnOnce('[react-atom-trigger] `threshold` should be between 0 and 1. Values are clamped.');
+    if (process.env.NODE_ENV === 'development') {
+      warnOnce('[react-atom-trigger] `threshold` should be between 0 and 1. Values are clamped.');
+    }
   }
 
   return clampThreshold(threshold);