@trackunit/react-components 1.9.7 → 1.9.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-components",
-  "version": "1.9.7",
+  "version": "1.9.9",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -16,12 +16,12 @@
     "@floating-ui/react": "^0.26.25",
     "string-ts": "^2.0.0",
     "tailwind-merge": "^2.0.0",
-    "@trackunit/ui-design-tokens": "1.7.5",
-    "@trackunit/css-class-variance-utilities": "1.7.5",
-    "@trackunit/shared-utils": "1.9.5",
-    "@trackunit/ui-icons": "1.7.6",
-    "@trackunit/react-table-pagination": "1.7.5",
-    "@trackunit/react-test-setup": "1.4.5",
+    "@trackunit/ui-design-tokens": "1.7.6",
+    "@trackunit/css-class-variance-utilities": "1.7.6",
+    "@trackunit/shared-utils": "1.9.6",
+    "@trackunit/ui-icons": "1.7.8",
+    "@trackunit/react-table-pagination": "1.7.6",
+    "@trackunit/react-test-setup": "1.4.6",
     "@tanstack/react-router": "1.114.29",
     "es-toolkit": "^1.39.10"
   },

package/src/common/Styleable.d.ts

@@ -0,0 +1,3 @@
+export type Styleable = {
+    style?: React.CSSProperties;
+};

package/src/common/index.d.ts

@@ -4,3 +4,4 @@ export * from "./CommonProps";
 export * from "./Density";
 export * from "./Size";
 export * from "./StorybookProps";
+export * from "./Styleable";

package/src/components/HorizontalOverflowScroller/HorizontalOverflowScroller.d.ts

@@ -0,0 +1,21 @@
+import { ReactElement, ReactNode } from "react";
+import { CommonProps } from "../../common/CommonProps";
+import { Styleable } from "../../common/Styleable";
+export interface HorizontalOverflowScrollerProps extends CommonProps, Styleable {
+    children: ReactNode;
+    /**
+     * Callback fired when scroll state changes (scrollable, at edges, etc.)
+     */
+    onScrollStateChange?: (state: {
+        isScrollable: boolean;
+        isAtBeginning: boolean;
+        isAtEnd: boolean;
+    }) => void;
+}
+/**
+ * Container for displaying components in a horizontal layout with overflow detection
+ *
+ * @param {HorizontalOverflowScrollerProps} props - The props for the component
+ * @returns {Element} HorizontalOverflowScroller component
+ */
+export declare const HorizontalOverflowScroller: ({ className, dataTestId, children, onScrollStateChange, }: HorizontalOverflowScrollerProps) => ReactElement;

package/src/components/HorizontalOverflowScroller/HorizontalOverflowScroller.variants.d.ts

@@ -0,0 +1,2 @@
+export declare const cvaHorizontalOverflowScroller: (props?: import("class-variance-authority/dist/types").ClassProp | undefined) => string;
+export declare const cvaHorizontalOverflowScrollerAndIndicatorsContainer: (props?: import("class-variance-authority/dist/types").ClassProp | undefined) => string;

package/src/components/HorizontalOverflowScroller/OverflowIndicator.d.ts

@@ -0,0 +1,22 @@
+import { ReactElement } from "react";
+import { CommonProps } from "../../common/CommonProps";
+type OverflowDirection = "left" | "right";
+export interface OverflowIndicatorProps extends CommonProps {
+    /**
+     * Direction of the overflow indicator
+     */
+    direction: OverflowDirection;
+    /**
+     * Callback function to handle scroll action
+     */
+    onClickScroll?: (event: React.MouseEvent<HTMLElement>) => void;
+}
+/**
+ * Overflow indicator component that shows visual cues when content extends beyond visible area
+ * Shows a scroll button on hover to navigate in the specified direction
+ *
+ * @param {OverflowIndicatorProps} props - The props for the component
+ * @returns {ReactElement} OverflowIndicator component
+ */
+export declare const OverflowIndicator: ({ className, dataTestId, direction, onClickScroll, }: OverflowIndicatorProps) => ReactElement;
+export {};

package/src/components/HorizontalOverflowScroller/OverflowIndicator.variants.d.ts

@@ -0,0 +1,8 @@
+export declare const cvaOverflowIndicatorContainer: (props?: import("class-variance-authority/dist/types").ClassProp | undefined) => string;
+export declare const cvaOverflowIndicatorGradient: (props?: ({
+    direction?: "left" | "right" | null | undefined;
+} & import("class-variance-authority/dist/types").ClassProp) | undefined) => string;
+export declare const cvaJustificationContainer: (props?: ({
+    direction?: "left" | "right" | null | undefined;
+} & import("class-variance-authority/dist/types").ClassProp) | undefined) => string;
+export declare const cvaOverflowIndicatorButton: (props?: import("class-variance-authority/dist/types").ClassProp | undefined) => string;

package/src/components/KPI/KPI.d.ts

@@ -1,6 +1,6 @@
 import { ReactElement } from "react";
-import { CommonProps } from "../../common";
-export interface KPIProps extends CommonProps {
+import { CommonProps, Styleable } from "../../common";
+export interface KPIProps extends CommonProps, Styleable {
     /**
      * The title of the KPI
      */
@@ -58,4 +58,4 @@ export interface KPIProps extends CommonProps {
  * @param {KPIProps} props - The props for the KPI component
  * @returns {ReactElement} KPI component
  */
-export declare const KPI: ({ title, value, loading, unit, className, dataTestId, tooltipLabel, variant, trend, ...rest }: KPIProps) => ReactElement;
+export declare const KPI: ({ title, value, loading, unit, className, dataTestId, tooltipLabel, variant, trend, style, ...rest }: KPIProps) => ReactElement;

package/src/components/List/List.d.ts

@@ -1,34 +1,124 @@
 import { VariantProps } from "@trackunit/css-class-variance-utilities";
 import { RelayPagination } from "@trackunit/react-table-pagination";
-import { ReactElement, RefObject } from "react";
+import { CSSProperties, ReactElement, Ref } from "react";
 import { CommonProps } from "../../common/CommonProps";
 import { cvaListItem } from "./List.variants";
+import { ListLoadingIndicatorProps } from "./ListLoadingIndicator";
 type Separator = NonNullable<VariantProps<typeof cvaListItem>["separator"]>;
-type LoadingIndicator = "spinner" | "skeletonLines";
-export interface ListProps extends CommonProps {
+/**
+ * Props that must be spread onto list items for proper virtualization.
+ * These handle positioning, measurement, accessibility, and interaction.
+ *
+ * **Important**: Consumers must add a `key` prop to their list items using the index parameter.
+ */ export interface VirtualizationListItemProps {
+    /** CSS classes for list styling and separators */
+    className: string;
+    /** Critical positioning styles for virtual scrolling */
+    style: CSSProperties;
+    /** Element ref for virtualization measurement */
+    ref?: Ref<any>;
+    /** Click handler for row-level interactions */
+    onClick?: () => void;
+    /** Data attribute for accessibility and debugging */
+    "data-index": number;
+    /** Tab index for keyboard navigation */
+    tabIndex: number;
+}
+export interface ListProps<TItem = unknown> extends CommonProps {
+    /**
+     * Number of items in the list (excluding header if provided).
+     */
     count: number;
-    rowHeight?: number;
+    /**
+     * Pagination configuration for infinite scrolling.
+     */
     pagination?: RelayPagination;
-    children: (index: number) => ReactElement | null;
+    /**
+     * Optional header element displayed at the top of the list.
+     *
+     * @example
+     * ```tsx
+     * <List header={<KPI title="Total" value={42} />} ... />
+     * ```
+     */
+    header?: ReactElement;
+    /**
+     * Function that returns the item data for a given index.
+     *
+     * @example
+     * ```tsx
+     * getItem={index => items[index]}
+     * ```
+     */
+    getItem: (index: number) => TItem;
+    /**
+     * Function that renders each list item. Must spread `listItemProps` onto your element and apply a `key` prop.
+     *
+     * @example
+     * ```tsx
+     * {(listItemProps, item, index) => (
+     *   <ListItem key={index} {...listItemProps} title={item.name} />
+     * )}
+     * ```
+     */
+    children: (listItemProps: VirtualizationListItemProps, item: TItem, index: number) => ReactElement | null;
+    /**
+     * Separator style between list items.
+     */
     separator?: Separator;
-    loadingIndicator?: LoadingIndicator;
-    skeletonLinesHeight?: string;
-    onRowClick?: (index: number) => void;
     /**
-     * The ref for the scroll container, only provide if you want to use the scroll event to fetch more data, on a different container than the list itself
+     * Loading indicator configuration for pagination loading.
+     */
+    loadingIndicator?: ListLoadingIndicatorProps;
+    /**
+     * Callback fired when a row is clicked.
+     */
+    onRowClick?: (item: TItem, index: number) => void;
+    /**
+     * Callback for scroll state changes.
      */
-    scrollRef?: RefObject<HTMLDivElement | null>;
+    onScrollStateChange?: (scrollOffset: number, isScrolling: boolean) => void;
+    /**
+     * Show a top separator when the list is scrolled.
+     */
+    topSeparatorOnScroll?: boolean;
+    /**
+     * Function to estimate item height for scroll performance.
+     *
+     * **Best Practice:** Always provide this function, even for fixed-height items.
+     * Measure the actual height in browser DevTools and return that value for optimal scrolling.
+     *
+     * The virtualizer uses these estimates for scroll calculations and viewport positioning.
+     * More accurate estimates result in smoother scrolling.
+     *
+     * @example Fixed height
+     * ```tsx
+     * estimateItemSize={() => 61} // Measured ListItem height
+     * ```
+     * @example Variable height
+     * ```tsx
+     * estimateItemSize={(index) => items[index]?.hasDescription ? 80 : 50}
+     * ```
+     */
+    estimateItemSize?: (index: number) => number;
 }
 /**
- * Render a performant virtualized list of items. Optionally with infinite scrolling.
+ * A performant virtualized list component with infinite scrolling support.
+ *
+ * ⚠️ **Important**: Requires a container with defined height to work properly.
+ *
+ * Features:
+ * - Virtualized rendering using TanStack Virtual for performance with large datasets
+ * - Automatic infinite scroll loading when approaching the end of the list
+ * - Optional header support (automatically managed, scrolls with content)
+ * - Built-in pagination with relay-style cursor support
+ * - Configurable loading indicators (skeleton, spinner, or custom)
+ * - Scroll state detection and callbacks
+ * - Variable-height item support via `estimateItemSize`
  *
- * @property {number} count - The total number of items in the list.
- * @property {number} [rowHeight="40"] - The estimated height of each row in the list.
- * @property {RelayPagination | undefined} pagination - Pagination configuration for the list.
- * @property {separator} [separator="line"] - The separator style between items in the list.
- * @property {(index: number) =>ReactElement} children - A function that takes an index and returns the JSX element to be rendered at said index.
- * @property {loadingIndicator} [loadingIndicator="spinner"] - The type of loading indicator in the list.
- * @property {skeletonLinesHeight} [skeletonLinesHeight="2rem"] - The height of the skeleton lines.
+ * The component automatically loads more data when:
+ * - User scrolls to the last visible item
+ * - Content height is insufficient to fill the container
  */
-export declare const List: ({ count, rowHeight, pagination, children, className, dataTestId, separator, loadingIndicator, skeletonLinesHeight, onRowClick, scrollRef, }: ListProps) => ReactElement;
+export declare const List: <TItem = unknown>({ count, pagination, children, className, dataTestId, separator, loadingIndicator, onRowClick, onScrollStateChange, topSeparatorOnScroll, estimateItemSize, header, getItem, }: ListProps<TItem>) => ReactElement;
 export {};

package/src/components/List/List.variants.d.ts

@@ -1,7 +1,7 @@
 export declare const cvaListContainer: (props?: ({
-    parentControlledScrollable?: boolean | null | undefined;
+    withTopSeparator?: boolean | null | undefined;
 } & import("class-variance-authority/dist/types").ClassProp) | undefined) => string;
 export declare const cvaList: (props?: import("class-variance-authority/dist/types").ClassProp | undefined) => string;
 export declare const cvaListItem: (props?: ({
-    separator?: "alternating" | "line" | "none" | "space" | null | undefined;
+    separator?: "line" | "none" | null | undefined;
 } & import("class-variance-authority/dist/types").ClassProp) | undefined) => string;

package/src/components/List/ListLoadingIndicator.d.ts

@@ -0,0 +1,71 @@
+import { ReactElement } from "react";
+type NoneLoadingIndicator = {
+    type: "none";
+    component?: never;
+    initialLoadingCount?: never;
+    scrollLoadingCount?: never;
+    hasThumbnail?: never;
+    thumbnailShape?: never;
+    hasDescription?: never;
+    hasMeta?: never;
+    hasDetails?: never;
+};
+type SpinnerLoadingIndicator = {
+    type: "spinner";
+    component?: never;
+    initialLoadingCount?: never;
+    scrollLoadingCount?: never;
+    hasThumbnail?: never;
+    thumbnailShape?: never;
+    hasDescription?: never;
+    hasMeta?: never;
+    hasDetails?: never;
+};
+type CustomLoadingIndicator = {
+    type: "custom";
+    component: ReactElement;
+    /**
+     * Number of loading indicators to show on initial load
+     *
+     * @default 3
+     */
+    initialLoadingCount?: number;
+    /**
+     * Number of loading indicators to show when loading more items during scroll
+     *
+     * @default 10
+     */
+    scrollLoadingCount?: number;
+    hasThumbnail?: never;
+    thumbnailShape?: never;
+    hasDescription?: never;
+    hasMeta?: never;
+    hasDetails?: never;
+};
+type SkeletonLoadingIndicator = {
+    type: "skeleton";
+    component?: never;
+    hasThumbnail?: boolean;
+    thumbnailShape?: "circle" | "square";
+    hasDescription?: boolean;
+    hasMeta?: boolean;
+    hasDetails?: boolean;
+    /**
+     * Number of loading indicators to show on initial load
+     *
+     * @default 3
+     */
+    initialLoadingCount?: number;
+    /**
+     * Number of loading indicators to show when loading more items during scroll
+     *
+     * @default 10
+     */
+    scrollLoadingCount?: number;
+};
+export type ListLoadingIndicatorProps = NoneLoadingIndicator | SpinnerLoadingIndicator | CustomLoadingIndicator | SkeletonLoadingIndicator;
+/**
+ *
+ */
+export declare const ListLoadingIndicator: ({ type, hasThumbnail, thumbnailShape, hasDescription, component, hasMeta, hasDetails, }: ListLoadingIndicatorProps) => ReactElement | null;
+export {};

package/src/components/ListItem/ListItem.d.ts

@@ -1,7 +1,7 @@
 import { VariantProps } from "@trackunit/css-class-variance-utilities";
 import { MappedOmit } from "@trackunit/shared-utils";
 import { tailwindPalette, ThemeColors } from "@trackunit/ui-design-tokens";
-import { MouseEventHandler, ReactElement, ReactNode } from "react";
+import { CSSProperties, MouseEventHandler, ReactElement, ReactNode, Ref } from "react";
 import { CommonProps } from "../../common/CommonProps";
 import { cvaListItem } from "./ListItem.variants";
 type ThemeColorShades = `${keyof (typeof tailwindPalette)[keyof typeof tailwindPalette]}`;
@@ -15,7 +15,7 @@ export interface ListItemProps extends CommonProps, MappedOmit<VariantProps<type
     /**Optional thumbnail for the ListItem. Can be used to display an image or icon. */
     thumbnail?: ReactElement;
     /**Makes the items interactive. Can be used to navigate to a different page when an item is clicked. */
-    onClick?: MouseEventHandler<HTMLDivElement>;
+    onClick?: MouseEventHandler<HTMLElement>;
     /**Details can be used to nest a component on the right side of the ListItem (can be used to display a tag, icon, highlight, text, etc.)   */
     details?: ReactNode;
     /**If an icon is chosen as thumbnail, use this to set the color of the icon. */
@@ -24,6 +24,14 @@ export interface ListItemProps extends CommonProps, MappedOmit<VariantProps<type
      * If asset image is chosen as thumbnail, make the thumbnailBackground "white".
      */
     thumbnailBackground?: `${ThemeColors}-${ThemeColorShades}` | `${ThemeColors}`;
+    /** @internal */
+    style?: CSSProperties;
+    /** @internal */
+    ref?: Ref<HTMLLIElement>;
+    /** @internal */
+    tabIndex?: number;
+    /** @internal */
+    "data-index"?: number;
 }
 /**
  *   The ListItem is designed to present a concise set of items for quick scanning and navigation. It supports multiple content types and actions, and its flexible layout allows for customization based on the type of data being shown - assets, events, users, etc.
@@ -31,5 +39,5 @@ export interface ListItemProps extends CommonProps, MappedOmit<VariantProps<type
  * @param { ListItemProps} props - The props for the ListItem component
  * @returns {Element}  ListItem component
  */
-export declare const ListItem: ({ className, dataTestId, onClick, details, title, description, meta, thumbnail, thumbnailColor, thumbnailBackground, }: ListItemProps) => ReactElement;
+export declare const ListItem: ({ className, dataTestId, onClick, details, title, description, meta, thumbnail, thumbnailColor, thumbnailBackground, ...rest }: ListItemProps) => ReactElement;
 export {};

package/src/components/ListItem/ListItemSkeleton.d.ts

@@ -0,0 +1,25 @@
+import { ReactElement } from "react";
+export declare const DEFAULT_SKELETON_LIST_ITEM_PROPS: {
+    readonly hasThumbnail: true;
+    readonly thumbnailShape: "circle";
+    readonly hasDescription: true;
+    readonly hasMeta: false;
+    readonly hasDetails: false;
+};
+export interface ListItemSkeletonProps {
+    /** Whether to show a thumbnail skeleton */
+    hasThumbnail?: boolean;
+    /** Shape of the thumbnail when present */
+    thumbnailShape?: "circle" | "square";
+    /** Whether to show a description line */
+    hasDescription?: boolean;
+    /** Whether to show a meta line */
+    hasMeta?: boolean;
+    /** Whether to show details on the right side */
+    hasDetails?: boolean;
+}
+/**
+ * Skeleton loading indicator that mimics the ListItem component structure.
+ * Uses the same layout, spacing, and visual hierarchy as ListItem.
+ */
+export declare const ListItemSkeleton: ({ hasThumbnail, thumbnailShape, hasDescription, hasMeta, hasDetails, }: ListItemSkeletonProps) => ReactElement;

package/src/components/SkeletonLines/SkeletonLines.d.ts

@@ -1,24 +1,25 @@
-import { ReactElement } from "react";
 import { CommonProps } from "../../common/CommonProps";
+type SkeletonDimension = number | string | Array<number | string>;
 export interface SkeletonLinesProps extends CommonProps {
     /**
      * The number of lines to display.
      */
     lines?: number;
     /**
-     * The height of lines. Can be a number or an array of numbers or string.
+     * The height of lines. Can be a number, string, or an array of numbers/strings.
      */
-    height?: number | Array<number> | string;
+    height?: SkeletonDimension;
     /**
-     * The width of each line. Can be a number or an array of numbers or string.
+     * The width of each line. Can be a number, string, or an array of numbers/strings.
      */
-    width?: number | Array<number> | string;
+    width?: SkeletonDimension;
     /**
-     * Margin of lines.
+     * Gap between skeleton lines in pixels.
      */
-    margin?: string;
+    margin?: number | string;
 }
 /**
  * Display placeholder lines before the data gets loaded to reduce load-time frustration.
  */
-export declare const SkeletonLines: import("react").MemoExoticComponent<({ margin, lines, height, width, className, dataTestId, }: SkeletonLinesProps) => ReactElement>;
+export declare const SkeletonLines: import("react").NamedExoticComponent<SkeletonLinesProps>;
+export {};

package/src/components/SkeletonLines/SkeletonLines.variants.d.ts

@@ -1 +1,2 @@
+export declare const cvaSkeletonContainer: (props?: import("class-variance-authority/dist/types").ClassProp | undefined) => string;
 export declare const cvaSkeletonLine: (props?: import("class-variance-authority/dist/types").ClassProp | undefined) => string;

package/src/components/SkeletonLines/index.d.ts

@@ -1 +1,2 @@
+export * from "./skeleton-utils";
 export * from "./SkeletonLines";

package/src/components/SkeletonLines/skeleton-utils.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Generates a random width percentage string for skeleton loading components.
+ *
+ * @param {object} params - The parameter object
+ * @param {number} params.min - Minimum percentage value (e.g., 30 for 30%)
+ * @param {number} params.max - Maximum percentage value (e.g., 80 for 80%)
+ * @returns {string} A percentage string (e.g., "65%")
+ */
+export declare const getResponsiveRandomWidthPercentage: ({ min, max }: {
+    min: number;
+    max: number;
+}) => string;

package/src/components/Tooltip/Tooltip.d.ts

@@ -1,9 +1,9 @@
 import { Placement } from "@floating-ui/react";
 import { ReactElement, ReactNode } from "react";
-import { CommonProps } from "../../common";
+import { CommonProps, Styleable } from "../../common";
 import { IconProps } from "../Icon/Icon";
 export type TooltipPlacement = Placement | "auto";
-export interface TooltipProps extends CommonProps {
+export interface TooltipProps extends CommonProps, Styleable {
     /**
      * The text to be displayed in the tooltip.
      */
@@ -45,4 +45,4 @@ export interface TooltipProps extends CommonProps {
  * @param {TooltipProps} props - The props for the Tooltip component
  * @returns {ReactElement} Tooltip component
  */
-export declare const Tooltip: ({ children, dataTestId, disabled, className, label, placement, mode, iconProps, id, }: TooltipProps) => ReactElement;
+export declare const Tooltip: ({ children, dataTestId, disabled, className, label, placement, mode, iconProps, id, style, }: TooltipProps) => ReactElement;

package/src/components/index.d.ts

@@ -13,6 +13,7 @@ export * from "./EmptyValue/EmptyValue";
 export * from "./ExternalLink/ExternalLink";
 export * from "./Heading";
 export * from "./Highlight/Highlight";
+export * from "./HorizontalOverflowScroller/HorizontalOverflowScroller";
 export * from "./Icon/Icon";
 export * from "./Indicator";
 export * from "./KPI/KPI";

package/src/hooks/index.d.ts

@@ -14,6 +14,7 @@ export * from "./useModifierKey";
 export * from "./useResize";
 export * from "./useScrollDetection";
 export * from "./useSelfUpdatingRef";
+export * from "./useStable";
 export * from "./useTimeout";
 export * from "./useViewportBreakpoints";
 export * from "./useWatch";

package/src/hooks/useGeometry.d.ts

@@ -1,9 +1,12 @@
 import { RefObject } from "react";
+interface UseGeometryOptions {
+    skip?: boolean;
+}
 /**
  * Custom hook to get the geometry of an element.
  * Size and position of the element relative to the viewport.
  */
-export declare const useGeometry: (ref: RefObject<HTMLElement | null>) => {
+export declare const useGeometry: (ref: RefObject<HTMLElement | null>, { skip }?: UseGeometryOptions) => {
     width: number;
     height: number;
     top: number;
@@ -13,3 +16,4 @@ export declare const useGeometry: (ref: RefObject<HTMLElement | null>) => {
     x: number;
     y: number;
 };
+export {};

package/src/hooks/useResize.d.ts

@@ -2,9 +2,14 @@ export interface WindowSize {
     height: number;
     width: number;
 }
+interface UseResizeOptions {
+    skip?: boolean;
+}
 /**
  * Custom hook to handle window resize events and provide the current window size.
  *
+ * @param {UseResizeOptions} options - Options for the hook.
  * @returns {WindowSize} An object containing the current window height and width.
  */
-export declare const useResize: () => WindowSize;
+export declare const useResize: ({ skip }?: UseResizeOptions) => WindowSize;
+export {};

package/src/hooks/useScrollDetection.d.ts

@@ -1,16 +1,24 @@
 import { type RefObject } from "react";
-/**
- * Hook for getting detecting scroll values.
- *
- * @param {useRef} elementRef - Ref hook holding the element that needs to be observed during scrolling
- * @returns {object} An object containing if the element is scrollable, is at the top, is at the bottom, and its current scroll position.
- */
-export declare const useScrollDetection: (elementRef?: RefObject<HTMLElement | null>) => {
+type ScrollDirection = "horizontal" | "vertical";
+type ScrollState = {
     isScrollable: boolean;
-    isAtTop: boolean;
-    isAtBottom: boolean;
+    isAtBeginning: boolean;
+    isAtEnd: boolean;
     scrollPosition: {
-        top: number;
-        bottom: number;
+        start: number;
+        end: number;
     };
 };
+type UseScrollDetectionOptions = {
+    direction?: ScrollDirection;
+    onScrollStateChange?: (state: ScrollState) => void;
+};
+/**
+ * Hook for detecting scroll values in horizontal or vertical direction.
+ *
+ * @param {useRef} elementRef - Ref hook holding the element that needs to be observed during scrolling
+ * @param {object} options - Options object containing direction and onScrollStateChange callback
+ * @returns {object} An object containing if the element is scrollable, is at the beginning, is at the end, and its current scroll position.
+ */
+export declare const useScrollDetection: (elementRef?: RefObject<HTMLElement | null>, options?: UseScrollDetectionOptions) => ScrollState;
+export {};

package/src/hooks/useStable.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The useStable hook ensures that a value is computed only once and remains stable across renders.
+ * This is useful for expensive computations or when you need a value to never change after initial creation.
+ * Perfect for generating stable random values, creating stable object references, or any one-time computation.
+ *
+ * @example
+ * // Stable random ID that never changes
+ * const stableId = useStable(() => Math.random().toString(36));
+ * @example
+ * // Stable configuration object
+ * const config = useStable(() => ({
+ *   apiKey: generateApiKey(),
+ *   timestamp: Date.now()
+ * }));
+ * @example
+ * // Stable random widths for skeleton loading
+ * const lineWidths = useStable(() => ({
+ *   title: Math.floor(Math.random() * 100) + 120,
+ *   description: Math.floor(Math.random() * 80) + 80
+ * }));
+ */
+export declare const useStable: <TValue>(factory: () => TValue) => TValue;