@trackunit/react-components 1.10.42 → 1.10.43

package/src/hooks/index.d.ts

@@ -11,9 +11,8 @@ export * from "./useInfiniteScroll";
 export * from "./useIsFirstRender";
 export * from "./useIsFullScreen";
 export * from "./useIsTextTruncated";
-export * from "./useMeasure/useMeasure";
-export * from "./useMeasure/useMeasureElement";
-export type { Geometry } from "./useMeasure/useMeasureShared";
+export * from "./useMeasure";
+export * from "./useMergeRefs";
 export * from "./useModifierKey";
 export * from "./useRelayPagination";
 export * from "./useResize";

package/src/hooks/{useMeasure/useMeasure.d.ts → useMeasure.d.ts}

@@ -1,6 +1,18 @@
 import { RefCallback } from "react";
-import { Geometry, UseMeasureSharedOptions } from "./useMeasureShared";
-type UseMeasureOptions = UseMeasureSharedOptions;
+export type Geometry = {
+    readonly height: number;
+    readonly width: number;
+    readonly x: number;
+    readonly y: number;
+    readonly bottom: number;
+    readonly left: number;
+    readonly right: number;
+    readonly top: number;
+};
+type UseMeasureOptions = {
+    skip?: boolean;
+    onChange?: (geometry: Geometry) => void;
+};
 type UseMeasureResult<TElement extends HTMLElement = HTMLElement> = {
     geometry: Geometry | undefined;
     ref: RefCallback<TElement>;
@@ -10,8 +22,8 @@ type UseMeasureResult<TElement extends HTMLElement = HTMLElement> = {
  * Custom hook to measure the geometry of an element using a callback ref.
  * Measures the size and position of the element relative to the viewport.
  *
- * @returns {UseMeasureResult<HTMLElement>} An object containing `geometry`, `ref` callback, and `element`.
  * @template TElement extends HTMLElement
+ * @returns {UseMeasureResult<HTMLElement>} An object containing `geometry`, `ref` callback, and `element`.
  * @example
  * ```tsx
  * const { geometry, ref } = useMeasure();

package/src/hooks/useMergeRefs.d.ts

@@ -0,0 +1,23 @@
+import { type Ref, type RefCallback, type RefObject } from "react";
+type MergeableRef<TInstance> = Exclude<Ref<TInstance>, RefObject<TInstance>> | {
+    current: TInstance | null;
+};
+/**
+ * Merges an array of refs into a single memoized callback ref or `null`.
+ * Useful when you need to attach multiple refs to the same element,
+ * such as when composing multiple hooks that each need a ref.
+ *
+ * @template TInstance - The type of the element instance
+ * @param {ReadonlyArray<MergeableRef<TInstance> | undefined>} refs - Array of refs to merge (can be RefObjects, RefCallbacks, or undefined)
+ * @returns {null | RefCallback<TInstance>} A single ref callback that will update all provided refs, or null if all refs are null
+ * @example
+ * ```tsx
+ * const { ref: measureRef } = useMeasure();
+ * const { ref: scrollRef } = useScrollDetection();
+ * const mergedRef = useMergeRefs([measureRef, scrollRef]);
+ *
+ * return <div ref={mergedRef}>Content</div>;
+ * ```
+ */
+export declare function useMergeRefs<TInstance>(refs: ReadonlyArray<MergeableRef<TInstance> | undefined>): null | RefCallback<TInstance>;
+export {};

package/src/hooks/useScrollDetection.d.ts

@@ -1,4 +1,4 @@
-import { type RefObject } from "react";
+import { type RefCallback } from "react";
 type ScrollDirection = "horizontal" | "vertical";
 type ScrollState = {
     isScrollable: boolean;
@@ -14,12 +14,22 @@ type UseScrollDetectionOptions = {
     onScrollStateChange?: (state: ScrollState) => void;
     skip?: boolean;
 };
+type UseScrollDetectionResult<TElement extends HTMLElement = HTMLElement> = ScrollState & {
+    ref: RefCallback<TElement>;
+    element: TElement | null;
+};
 /**
  * Hook for detecting scroll values in horizontal or vertical direction.
+ * Returns a ref callback to attach to the element you want to observe.
  *
- * @param {useRef} elementRef - Ref hook holding the element that needs to be observed during scrolling
  * @param {object} options - Options object containing direction, onScrollStateChange callback, and skip
- * @returns {object} An object containing if the element is scrollable, is at the beginning, is at the end, and its current scroll position.
+ * @returns {object} An object containing ref callback, element, and scroll state (isScrollable, isAtBeginning, isAtEnd, scrollPosition)
+ * @template TElement extends HTMLElement
+ * @example
+ * ```tsx
+ * const { ref, isScrollable, isAtBeginning } = useScrollDetection({ direction: "horizontal" });
+ * return <div ref={ref}>Scrollable content</div>;
+ * ```
  */
-export declare const useScrollDetection: (elementRef?: RefObject<HTMLElement | null>, options?: UseScrollDetectionOptions) => ScrollState;
+export declare const useScrollDetection: <TElement extends HTMLElement = HTMLElement>(options?: UseScrollDetectionOptions) => UseScrollDetectionResult<TElement>;
 export {};

package/src/hooks/useMeasure/useMeasureElement.d.ts

@@ -1,19 +0,0 @@
-import { RefObject } from "react";
-import { Geometry, UseMeasureSharedOptions } from "./useMeasureShared";
-type UseMeasureElementOptions = UseMeasureSharedOptions;
-/**
- * Custom hook to measure the geometry of an element from a RefObject.
- * Use this when you already have a ref (e.g., from useRef or for composition with other hooks).
- * Measures the size and position of the element relative to the viewport.
- *
- * @param ref - RefObject pointing to the element to measure
- * @returns {Geometry} The geometry of the element
- * @example
- * ```tsx
- * const ref = useRef<HTMLDivElement>(null);
- * const geometry = useMeasureElement(ref);
- * return <div ref={ref}>Width: {geometry.width}</div>;
- * ```
- */
-export declare const useMeasureElement: <TElement extends HTMLElement = HTMLElement>(ref: RefObject<TElement | null>, { skip, onChange }?: UseMeasureElementOptions) => Geometry | undefined;
-export {};

package/src/hooks/useMeasure/useMeasureShared.d.ts

@@ -1,19 +0,0 @@
-export type Geometry = {
-    readonly height: number;
-    readonly width: number;
-    readonly x: number;
-    readonly y: number;
-    readonly bottom: number;
-    readonly left: number;
-    readonly right: number;
-    readonly top: number;
-};
-export type UseMeasureSharedOptions = {
-    skip?: boolean;
-    onChange?: (geometry: Geometry) => void;
-};
-/**
- * Shared measurement logic used by both useMeasure and useMeasureElement.
- * This hook observes an element and measures its geometry.
- */
-export declare const useMeasureShared: <TElement extends HTMLElement>(element: TElement | null, { skip, onChange }?: UseMeasureSharedOptions) => Geometry | undefined;