@codefast/ui 0.3.11-canary.1 → 0.3.11

package/dist/hooks/use-media-query.d.ts

@@ -1,3 +1,4 @@
+//#region src/hooks/use-media-query.d.ts
 /**
  * Subscribe to a CSS media query and receive its match state.
  *
@@ -12,4 +13,6 @@
  * const isNarrow = useMediaQuery("(max-width: 768px)");
  * ```
  */
-export declare function useMediaQuery(query: string): boolean;
+declare function useMediaQuery(query: string): boolean;
+//#endregion
+export { useMediaQuery };

package/dist/hooks/use-media-query.js

@@ -1,23 +1,50 @@
 "use client";
 import { useEffect, useState } from "react";
+//#region src/hooks/use-media-query.ts
+/**
+* Subscribe to a CSS media query and receive its match state.
+*
+* Evaluates the query immediately (when supported) and updates on changes
+* via an event listener.
+*
+* @param query - A valid media query string (e.g., "(max-width: 768px)").
+* @returns true when the media query currently matches; otherwise false.
+*
+* @example
+* ```tsx
+* const isNarrow = useMediaQuery("(max-width: 768px)");
+* ```
+*/
 function useMediaQuery(query) {
-    const [matches, setMatches] = useState(()=>{
-        if ("u" > typeof window && "function" == typeof window.matchMedia) return window.matchMedia(query).matches;
-        return false;
-    });
-    useEffect(()=>{
-        if ("u" < typeof window) return;
-        const mediaQueryList = window.matchMedia(query);
-        const onChange = (event)=>{
-            setMatches(event.matches);
-        };
-        mediaQueryList.addEventListener("change", onChange);
-        return ()=>{
-            mediaQueryList.removeEventListener("change", onChange);
-        };
-    }, [
-        query
-    ]);
-    return matches;
+	/**
+	* State to store whether the query matches.
+	* The initial value is calculated based on the current window state.
+	*/
+	const [matches, setMatches] = useState(() => {
+		if (typeof window !== "undefined" && typeof window.matchMedia === "function") return window.matchMedia(query).matches;
+		return false;
+	});
+	useEffect(() => {
+		if (typeof window === "undefined") return;
+		/**
+		* MediaQueryList to evaluate and observe the provided query.
+		*/
+		const mediaQueryList = window.matchMedia(query);
+		/**
+		* Update state when the media query status changes.
+		*/
+		const onChange = (event) => {
+			setMatches(event.matches);
+		};
+		mediaQueryList.addEventListener("change", onChange);
+		/**
+		* Remove the event listener on unmount or when the query changes.
+		*/
+		return () => {
+			mediaQueryList.removeEventListener("change", onChange);
+		};
+	}, [query]);
+	return matches;
 }
+//#endregion
 export { useMediaQuery };

package/dist/hooks/use-mutation-observer.d.ts

@@ -1,4 +1,6 @@
-import type { RefObject } from "react";
+import { RefObject } from "react";
+
+//#region src/hooks/use-mutation-observer.d.ts
 /**
  * Observe DOM mutations on a referenced element and invoke a callback.
  *
@@ -12,4 +14,6 @@ import type { RefObject } from "react";
  *
  * @see [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver)
  */
-export declare function useMutationObserver(ref: RefObject<HTMLElement | null>, callback: MutationCallback, options?: MutationObserverInit): void;
+declare function useMutationObserver(ref: RefObject<HTMLElement | null>, callback: MutationCallback, options?: MutationObserverInit): void;
+//#endregion
+export { useMutationObserver };

package/dist/hooks/use-mutation-observer.js

@@ -1,23 +1,41 @@
 "use client";
 import { useEffect } from "react";
+//#region src/hooks/use-mutation-observer.ts
+/**
+* Default options for MutationObserver observing common mutation types.
+*/
 const defaultOptions = {
-    attributes: true,
-    characterData: true,
-    childList: true,
-    subtree: true
+	attributes: true,
+	characterData: true,
+	childList: true,
+	subtree: true
 };
+/**
+* Observe DOM mutations on a referenced element and invoke a callback.
+*
+* Attaches a MutationObserver to the provided element reference with the given
+* options and calls the callback whenever mutations occur.
+*
+* @param ref - Ref to the target HTMLElement to observe.
+* @param callback - Mutation callback invoked with observed records.
+* @param options - Observer configuration. Defaults watch attributes, characterData, childList, subtree.
+* @returns void
+*
+* @see [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver)
+*/
 function useMutationObserver(ref, callback, options = defaultOptions) {
-    useEffect(()=>{
-        if (!ref.current) return;
-        const observer = new MutationObserver(callback);
-        observer.observe(ref.current, options);
-        return ()=>{
-            observer.disconnect();
-        };
-    }, [
-        ref,
-        callback,
-        options
-    ]);
+	useEffect(() => {
+		if (!ref.current) return;
+		const observer = new MutationObserver(callback);
+		observer.observe(ref.current, options);
+		return () => {
+			observer.disconnect();
+		};
+	}, [
+		ref,
+		callback,
+		options
+	]);
 }
+//#endregion
 export { useMutationObserver };

package/dist/hooks/use-pagination.d.ts

@@ -1,18 +1,19 @@
-export interface UsePaginationProps {
-    /** Current active page number. */
-    currentPage: number;
-    /** Number of results displayed per page. */
-    resultsPerPage: number;
-    /**
-     * Number of sibling pages to show on each side of the current page.
-     * Defaults to 1.
-     */
-    siblingPagesCount?: number;
-    /** Total number of results across all pages. */
-    totalResults: number;
+//#region src/hooks/use-pagination.d.ts
+interface UsePaginationProps {
+  /** Current active page number. */
+  currentPage: number;
+  /** Number of results displayed per page. */
+  resultsPerPage: number;
+  /**
+   * Number of sibling pages to show on each side of the current page.
+   * Defaults to 1.
+   */
+  siblingPagesCount?: number;
+  /** Total number of results across all pages. */
+  totalResults: number;
 }
 /** Ellipsis marker used to collapse ranges in pagination output. */
-export declare const ELLIPSIS = "\u2022\u2022\u2022";
+declare const ELLIPSIS = "\u2022\u2022\u2022";
 /**
  * Compute a pagination structure for result sets.
  *
@@ -33,4 +34,11 @@ export declare const ELLIPSIS = "\u2022\u2022\u2022";
  * });
  * ```
  */
-export declare function usePagination({ currentPage, resultsPerPage, siblingPagesCount, totalResults, }: UsePaginationProps): (number | string)[];
+declare function usePagination({
+  currentPage,
+  resultsPerPage,
+  siblingPagesCount,
+  totalResults
+}: UsePaginationProps): (number | string)[];
+//#endregion
+export { ELLIPSIS, UsePaginationProps, usePagination };

package/dist/hooks/use-pagination.js

@@ -1,56 +1,107 @@
 "use client";
 import { useMemo } from "react";
+//#region src/hooks/use-pagination.ts
+/** Ellipsis marker used to collapse ranges in pagination output. */
 const ELLIPSIS = "•••";
-const createRange = (start, end)=>{
-    const length = end - start + 1;
-    return Array.from({
-        length
-    }, (_, index)=>start + index);
+/**
+* Generate a numeric range from start to end inclusive.
+*
+* @param start - Starting number (inclusive).
+* @param end - Ending number (inclusive).
+* @returns Array of numbers from start to end.
+*/
+const createRange = (start, end) => {
+	const length = end - start + 1;
+	return Array.from({ length }, (_, index) => start + index);
 };
+/**
+* Compute a pagination structure for result sets.
+*
+* Returns a mixed array of page numbers and the `ELLIPSIS` marker representing
+* collapsed ranges. The shape adapts to the total pages and the requested
+* sibling window around the current page.
+*
+* @param props - Pagination options. See {@link UsePaginationProps}.
+* @returns Array of page numbers and `ELLIPSIS` representing the pagination model.
+*
+* @example
+* ```tsx
+* const paginationRange = usePagination({
+*   currentPage: 3,
+*   resultsPerPage: 10,
+*   siblingPagesCount: 1,
+*   totalResults: 100
+* });
+* ```
+*/
 function usePagination({ currentPage, resultsPerPage, siblingPagesCount = 1, totalResults }) {
-    return useMemo(()=>{
-        const totalPages = Math.ceil(totalResults / Math.floor(resultsPerPage));
-        if (totalPages <= 0) return [];
-        const visiblePageNumbers = siblingPagesCount + 5;
-        if (visiblePageNumbers >= totalPages) return createRange(1, totalPages);
-        const leftSiblingIndex = Math.max(currentPage - siblingPagesCount, 1);
-        const rightSiblingIndex = Math.min(currentPage + siblingPagesCount, totalPages);
-        const shouldShowLeftEllipsis = leftSiblingIndex > 2;
-        const shouldShowRightEllipsis = rightSiblingIndex < totalPages - 2;
-        const firstPage = 1;
-        const lastPage = totalPages;
-        if (!shouldShowLeftEllipsis && shouldShowRightEllipsis) {
-            const leftRange = createRange(1, 3 + 2 * siblingPagesCount);
-            return [
-                ...leftRange,
-                ELLIPSIS,
-                lastPage
-            ];
-        }
-        if (shouldShowLeftEllipsis && !shouldShowRightEllipsis) {
-            const rightRange = createRange(totalPages - (3 + 2 * siblingPagesCount) + 1, totalPages);
-            return [
-                firstPage,
-                ELLIPSIS,
-                ...rightRange
-            ];
-        }
-        if (shouldShowLeftEllipsis && shouldShowRightEllipsis) {
-            const middleRange = createRange(leftSiblingIndex, rightSiblingIndex);
-            return [
-                firstPage,
-                ELLIPSIS,
-                ...middleRange,
-                ELLIPSIS,
-                lastPage
-            ];
-        }
-        return [];
-    }, [
-        totalResults,
-        resultsPerPage,
-        siblingPagesCount,
-        currentPage
-    ]);
+	return useMemo(() => {
+		const totalPages = Math.ceil(totalResults / Math.floor(resultsPerPage));
+		if (totalPages <= 0) return [];
+		/**
+		* Case 1: If the number of pages is less than or equal to the visible page
+		* numbers, return an array of all page numbers.
+		*/
+		if (siblingPagesCount + 5 >= totalPages) return createRange(1, totalPages);
+		/**
+		* Left sibling boundary (min 1).
+		*/
+		const leftSiblingIndex = Math.max(currentPage - siblingPagesCount, 1);
+		/**
+		* Right sibling boundary (max totalPages).
+		*/
+		const rightSiblingIndex = Math.min(currentPage + siblingPagesCount, totalPages);
+		/**
+		* Whether a left-side ellipsis is needed.
+		*/
+		const shouldShowLeftEllipsis = leftSiblingIndex > 2;
+		/**
+		* Whether a right-side ellipsis is needed.
+		*/
+		const shouldShowRightEllipsis = rightSiblingIndex < totalPages - 2;
+		/** First page number (always 1). */
+		const firstPage = 1;
+		/** Last page number (equals totalPages). */
+		const lastPage = totalPages;
+		/**
+		* Case 2: No left ellipsis, but right ellipsis is necessary.
+		* This occurs when the current page is close to the start of the
+		* pagination range.
+		*/
+		if (!shouldShowLeftEllipsis && shouldShowRightEllipsis) return [
+			...createRange(1, 3 + 2 * siblingPagesCount),
+			ELLIPSIS,
+			lastPage
+		];
+		/**
+		* Case 3: No right ellipsis, but left ellipsis is necessary.
+		* This occurs when the current page is close to the end of the pagination
+		* range.
+		*/
+		if (shouldShowLeftEllipsis && !shouldShowRightEllipsis) return [
+			firstPage,
+			ELLIPSIS,
+			...createRange(totalPages - (3 + 2 * siblingPagesCount) + 1, totalPages)
+		];
+		/**
+		* Case 4: Both left and right ellipsis are necessary.
+		* This occurs when the current page is far enough from both the start and
+		* end of the pagination range.
+		*/
+		if (shouldShowLeftEllipsis && shouldShowRightEllipsis) return [
+			firstPage,
+			ELLIPSIS,
+			...createRange(leftSiblingIndex, rightSiblingIndex),
+			ELLIPSIS,
+			lastPage
+		];
+		return [];
+	}, [
+		totalResults,
+		resultsPerPage,
+		siblingPagesCount,
+		currentPage
+	]);
 }
+//#endregion
 export { ELLIPSIS, usePagination };