@uncinc/uncinc-react-kitchen-sink 2.26.0 → 2.26.1

package/dist/hooks/useScrollDepth.d.ts

@@ -0,0 +1,25 @@
+/**
+ * useScrollDepth
+ *
+ * Tracks scroll depth and calls `onThreshold` once per threshold per page.
+ *
+ * Why a custom hook instead of relying on third-party scroll tracking?
+ * Most trackers capture `document.scrollHeight` once at initialisation. With
+ * client-side rendering the page height changes as content loads asynchronously,
+ * so that snapshot is too small and all percentages end up wrong.
+ *
+ * How this avoids continuous re-renders:
+ * - All mutable state lives in `useRef` — nothing in `useState`.
+ * - Scroll events are throttled to one check per animation frame via
+ *   `requestAnimationFrame`; the handler is removed on cleanup.
+ * - `ResizeObserver` keeps `documentHeight` in sync as async content renders,
+ *   without triggering React renders.
+ *
+ * @param onThreshold - Called once per threshold per page with the percentage value.
+ * @param resetKey    - Change this value on every navigation (e.g. page title or
+ *                      pathname) to reset the fired thresholds for the new page.
+ * @param thresholds  - Scroll depth percentages (%) to track.
+ *                      Defaults to [25, 50, 75, 90, 100].
+ */
+declare const useScrollDepth: (onThreshold: (threshold: number) => void, resetKey?: unknown, thresholds?: number[]) => void;
+export default useScrollDepth;

package/dist/hooks/useScrollDepth.js

@@ -0,0 +1,104 @@
+import { useEffect, useRef } from 'react';
+
+/**
+ * useScrollDepth
+ *
+ * Tracks scroll depth and calls `onThreshold` once per threshold per page.
+ *
+ * Why a custom hook instead of relying on third-party scroll tracking?
+ * Most trackers capture `document.scrollHeight` once at initialisation. With
+ * client-side rendering the page height changes as content loads asynchronously,
+ * so that snapshot is too small and all percentages end up wrong.
+ *
+ * How this avoids continuous re-renders:
+ * - All mutable state lives in `useRef` — nothing in `useState`.
+ * - Scroll events are throttled to one check per animation frame via
+ *   `requestAnimationFrame`; the handler is removed on cleanup.
+ * - `ResizeObserver` keeps `documentHeight` in sync as async content renders,
+ *   without triggering React renders.
+ *
+ * @param onThreshold - Called once per threshold per page with the percentage value.
+ * @param resetKey    - Change this value on every navigation (e.g. page title or
+ *                      pathname) to reset the fired thresholds for the new page.
+ * @param thresholds  - Scroll depth percentages (%) to track.
+ *                      Defaults to [25, 50, 75, 90, 100].
+ */
+var useScrollDepth = function useScrollDepth(onThreshold, resetKey) {
+  var thresholds = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : [25, 50, 75, 90, 100];
+  // Tracks which thresholds have already fired for the current page.
+  // useRef so mutations never trigger a re-render.
+  var firedThresholds = useRef(new Set());
+  var rafId = useRef(null);
+  var documentHeight = useRef(0);
+  // Keep a ref to onThreshold so the effect never needs to re-run when the
+  // callback identity changes (e.g. inline arrow in parent), while still
+  // always calling the latest version.
+  var onThresholdRef = useRef(onThreshold);
+  onThresholdRef.current = onThreshold;
+  // Keep a ref to thresholds so the effect never needs to re-run when the
+  // array identity changes, while still always reading the latest value.
+  var thresholdsRef = useRef(thresholds);
+  thresholdsRef.current = thresholds;
+
+  // Reset fired thresholds on every page navigation.
+  useEffect(function () {
+    firedThresholds.current.clear();
+  }, [resetKey]);
+  useEffect(function () {
+    if (typeof window === 'undefined') return undefined;
+    var updateDocumentHeight = function updateDocumentHeight() {
+      // Use Math.max to handle cross-browser quirks (body vs documentElement).
+      documentHeight.current = Math.max(document.body.scrollHeight, document.documentElement.scrollHeight);
+    };
+    var checkScrollDepth = function checkScrollDepth() {
+      var scrollTop = window.scrollY;
+      var windowHeight = window.innerHeight;
+      var docHeight = documentHeight.current;
+
+      // Skip pages that fit entirely in the viewport — no meaningful depth to track.
+      if (docHeight <= windowHeight) return;
+
+      // scrollDepth = (scrollTop + viewportHeight) / documentHeight × 100
+      var scrollPercent = Math.round((scrollTop + windowHeight) / docHeight * 100);
+      thresholdsRef.current.forEach(function (threshold) {
+        if (scrollPercent >= threshold && !firedThresholds.current.has(threshold)) {
+          firedThresholds.current.add(threshold);
+          onThresholdRef.current(threshold);
+        }
+      });
+    };
+    var onScroll = function onScroll() {
+      // Gate on an active rAF so we calculate at most once per rendered frame,
+      // regardless of how fast the browser fires scroll events.
+      if (rafId.current !== null) return;
+      rafId.current = requestAnimationFrame(function () {
+        checkScrollDepth();
+        rafId.current = null;
+      });
+    };
+
+    // ResizeObserver re-measures the document whenever content loads in,
+    // keeping the height accurate as async content renders.
+    var resizeObserver = new ResizeObserver(function () {
+      updateDocumentHeight();
+      // Re-evaluate depth after a layout change; lazily-loaded content may
+      // have already scrolled us past a threshold.
+      checkScrollDepth();
+    });
+    updateDocumentHeight();
+    resizeObserver.observe(document.body);
+    window.addEventListener('scroll', onScroll, {
+      passive: true
+    });
+    return function () {
+      window.removeEventListener('scroll', onScroll);
+      resizeObserver.disconnect();
+      if (rafId.current !== null) {
+        cancelAnimationFrame(rafId.current);
+        rafId.current = null;
+      }
+    };
+  }, []); // Listeners are set up once; threshold resets are handled by the resetKey effect.
+};
+
+export default useScrollDepth;

package/dist/hooks/useScrollDepthGTM.d.ts

@@ -0,0 +1,19 @@
+/**
+ * useScrollDepthGTM
+ *
+ * Convenience hook that combines `useScrollDepth` with the GTM data layer.
+ * Pushes a `scroll_depth` event at each threshold — once per page — and
+ * resets on navigation when `resetKey` changes.
+ *
+ * Use this hook when you want GTM scroll-depth tracking out of the box.
+ * Use the underlying `useScrollDepth` directly if you need a different
+ * analytics integration or want full control over the callback.
+ *
+ * @param resetKey   - Change on every navigation (e.g. pathname or page title)
+ *                     to reset the fired thresholds for the new page.
+ * @param thresholds - Scroll depth percentages (%) to track. Defaults to
+ *                     [25, 50, 75, 90, 100], mirroring GTM's built-in Scroll
+ *                     Depth trigger.
+ */
+declare const useScrollDepthGTM: (resetKey?: unknown, thresholds?: number[]) => void;
+export default useScrollDepthGTM;

package/dist/hooks/useScrollDepthGTM.js

@@ -0,0 +1,33 @@
+// gtm.js uses dynamic property assignment that TypeScript cannot infer from
+// the source. The generated dist/helpers/gtm.d.ts contains the correct types,
+// but during tsc compilation we cast to avoid the false-positive TS2339 error.
+import gtmHelper from '../helpers/gtm';
+import useScrollDepth from './useScrollDepth';
+var gtm = gtmHelper;
+
+/**
+ * useScrollDepthGTM
+ *
+ * Convenience hook that combines `useScrollDepth` with the GTM data layer.
+ * Pushes a `scroll_depth` event at each threshold — once per page — and
+ * resets on navigation when `resetKey` changes.
+ *
+ * Use this hook when you want GTM scroll-depth tracking out of the box.
+ * Use the underlying `useScrollDepth` directly if you need a different
+ * analytics integration or want full control over the callback.
+ *
+ * @param resetKey   - Change on every navigation (e.g. pathname or page title)
+ *                     to reset the fired thresholds for the new page.
+ * @param thresholds - Scroll depth percentages (%) to track. Defaults to
+ *                     [25, 50, 75, 90, 100], mirroring GTM's built-in Scroll
+ *                     Depth trigger.
+ */
+var useScrollDepthGTM = function useScrollDepthGTM(resetKey, thresholds) {
+  useScrollDepth(function (threshold) {
+    gtm.push({
+      event: 'scroll_depth',
+      percent_scrolled: threshold
+    });
+  }, resetKey, thresholds);
+};
+export default useScrollDepthGTM;

package/dist/index.d.ts

@@ -77,6 +77,8 @@ export { default as useDialogHelpers } from "./hooks/useDialogHelpers";
 export { default as useEscape } from "./hooks/useEscape";
 export { default as useOnScreen } from "./hooks/useOnScreen";
 export { default as usePrevious } from "./hooks/usePrevious";
+export { default as useScrollDepth } from "./hooks/useScrollDepth";
+export { default as useScrollDepthGTM } from "./hooks/useScrollDepthGTM";
 export { default as useScrollPosition } from "./hooks/useScrollPosition";
 export { default as useWindowDimensions } from "./hooks/useWindowDimensions";
 export { default as useTrapFocus } from "./hooks/useTrapFocus";

package/dist/index.js

@@ -90,6 +90,8 @@ export { default as useDialogHelpers } from './hooks/useDialogHelpers';
 export { default as useEscape } from './hooks/useEscape';
 export { default as useOnScreen } from './hooks/useOnScreen';
 export { default as usePrevious } from './hooks/usePrevious';
+export { default as useScrollDepth } from './hooks/useScrollDepth';
+export { default as useScrollDepthGTM } from './hooks/useScrollDepthGTM';
 export { default as useScrollPosition } from './hooks/useScrollPosition';
 export { default as useWindowDimensions } from './hooks/useWindowDimensions';
 export { default as useTrapFocus } from './hooks/useTrapFocus';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncinc/uncinc-react-kitchen-sink",
-  "version": "2.26.0",
+  "version": "2.26.1",
   "description": "Default React components that are easily extended.",
   "author": "uncinc",
   "license": "MIT",