@codefast/ui 0.3.16-canary.1 → 0.3.16-canary.3

package/src/hooks/use-copy-to-clipboard.ts

@@ -0,0 +1,63 @@
+"use client";
+
+import { useState } from "react";
+
+/**
+ * Provide clipboard copy capability with a transient copied state.
+ *
+ * Internally uses the Clipboard API when available and sets a temporary
+ * `isCopied` flag for UI feedback. A custom callback may be invoked upon copy.
+ *
+ * @param options - Configuration options.
+ *   - onCopy: Callback invoked after a successful copy.
+ *   - timeout: Duration in milliseconds to keep `isCopied` true. Defaults to 2000.
+ * @returns An object with a `copyToClipboard` function and an `isCopied` flag.
+ *
+ * @example
+ * ```tsx
+ * const { copyToClipboard, isCopied } = useCopyToClipboard({ timeout: 1500 });
+ * <button onClick={() => copyToClipboard("Hello")}>{isCopied ? "Copied" : "Copy"}</button>
+ * ```
+ *
+ * @since 0.3.16-canary.0
+ */
+export function useCopyToClipboard({
+  onCopy,
+  timeout = 2000,
+}: { onCopy?: () => void; timeout?: number } = {}): {
+  copyToClipboard: (value: string) => Promise<void>;
+  isCopied: boolean;
+} {
+  const [isCopied, setIsCopied] = useState(false);
+
+  const copyToClipboard = async (value: string): Promise<void> => {
+    if (
+      typeof window === "undefined" ||
+      !("clipboard" in navigator) ||
+      typeof navigator.clipboard.writeText !== "function"
+    ) {
+      return;
+    }
+
+    if (!value) {
+      return;
+    }
+
+    try {
+      await navigator.clipboard.writeText(value);
+      setIsCopied(true);
+
+      if (onCopy) {
+        onCopy();
+      }
+
+      setTimeout(() => {
+        setIsCopied(false);
+      }, timeout);
+    } catch (error) {
+      console.error(error);
+    }
+  };
+
+  return { copyToClipboard, isCopied };
+}

package/src/hooks/use-is-mobile.ts

@@ -0,0 +1,27 @@
+"use client";
+
+import { useMediaQuery } from "#/hooks/use-media-query";
+
+/**
+ * Determine whether the current viewport should be treated as mobile.
+ *
+ * Uses {@link useMediaQuery} to evaluate a max-width media query derived from the
+ * provided breakpoint. By default, widths below 768px are considered mobile.
+ *
+ * @param mobileBreakpoint - Pixel width used as the mobile breakpoint. Values strictly
+ * less than this breakpoint are treated as mobile. Defaults to 768.
+ * @returns true when the viewport width is less than the given breakpoint; otherwise false.
+ *
+ * @example
+ * ```tsx
+ * const isMobile = useIsMobile();
+ * if (isMobile) {
+ *   // Render compact layout
+ * }
+ * ```
+ *
+ * @since 0.3.16-canary.0
+ */
+export function useIsMobile(mobileBreakpoint = 768): boolean {
+  return useMediaQuery(`(max-width: ${(mobileBreakpoint - 1).toString()}px)`);
+}

package/src/hooks/use-media-query.ts

@@ -0,0 +1,71 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/**
+ * Event handler for MediaQueryList changes.
+ *
+ * @param event - Media query change event providing the updated match status.
+ */
+type MediaQueryChangeHandler = (event: MediaQueryListEvent) => void;
+
+/**
+ * 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)");
+ * ```
+ *
+ * @since 0.3.16-canary.0
+ */
+export function useMediaQuery(query: string): boolean {
+  /**
+   * State to store whether the query matches.
+   * The initial value is calculated based on the current window state.
+   */
+  const [matches, setMatches] = useState<boolean>(() => {
+    // Ensure initial state matches current media query status
+    if (typeof window !== "undefined" && typeof window.matchMedia === "function") {
+      return window.matchMedia(query).matches;
+    }
+
+    return false;
+  });
+
+  useEffect(() => {
+    // Only run in a browser environment where matchMedia is available
+    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: MediaQueryChangeHandler = (event): void => {
+      setMatches(event.matches);
+    };
+
+    mediaQueryList.addEventListener("change", onChange);
+
+    /**
+     * Remove the event listener on unmount or when the query changes.
+     */
+    return (): void => {
+      mediaQueryList.removeEventListener("change", onChange);
+    };
+  }, [query]);
+
+  return matches;
+}

package/src/hooks/use-mutation-observer.ts

@@ -0,0 +1,54 @@
+"use client";
+
+import type { RefObject } from "react";
+
+import { useEffect } from "react";
+
+/**
+ * Default options for MutationObserver observing common mutation types.
+ */
+const defaultOptions: MutationObserverInit = {
+  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)
+ *
+ * @since 0.3.16-canary.0
+ */
+export function useMutationObserver(
+  ref: RefObject<HTMLElement | null>,
+  callback: MutationCallback,
+  options: MutationObserverInit = defaultOptions,
+): void {
+  useEffect(() => {
+    // Abort if ref is not attached
+    if (!ref.current) {
+      return;
+    }
+
+    // Create observer
+    const observer = new MutationObserver(callback);
+
+    // Observe with provided options
+    observer.observe(ref.current, options);
+
+    // Cleanup on unmount or when deps change
+    return (): void => {
+      observer.disconnect();
+    };
+  }, [ref, callback, options]);
+}

package/src/hooks/use-pagination.ts

@@ -0,0 +1,166 @@
+"use client";
+
+import { useMemo } from "react";
+
+/**
+ * @since 0.3.16-canary.0
+ */
+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;
+}
+
+/**
+ * Ellipsis marker used to collapse ranges in pagination output.
+ *
+ * @since 0.3.16-canary.0
+ */
+export const ELLIPSIS = "•••";
+
+/**
+ * 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: number, end: number): Array<number> => {
+  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
+ * });
+ * ```
+ *
+ * @since 0.3.16-canary.0
+ */
+export function usePagination({
+  currentPage,
+  resultsPerPage,
+  siblingPagesCount = 1,
+  totalResults,
+}: UsePaginationProps): Array<number | string> {
+  return useMemo<Array<number | string>>(() => {
+    // Total pages derived from results and page size
+    const totalPages = Math.ceil(totalResults / Math.floor(resultsPerPage));
+
+    // Return an empty array if there are no pages to display
+    if (totalPages <= 0) {
+      return [];
+    }
+
+    /**
+     * Total visible items including: first, last, current, siblings, and two ellipses.
+     */
+    const visiblePageNumbers = siblingPagesCount + 5;
+
+    /**
+     * 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 (visiblePageNumbers >= 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) {
+      // Range starting from page 1 through the right sibling window
+      const leftRange = createRange(1, 3 + 2 * siblingPagesCount);
+
+      return [...leftRange, 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) {
+      // Range ending at last page through the left sibling window
+      const rightRange = createRange(totalPages - (3 + 2 * siblingPagesCount) + 1, totalPages);
+
+      return [firstPage, ELLIPSIS, ...rightRange];
+    }
+
+    /**
+     * 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) {
+      // Middle window from left to right siblings
+      const middleRange = createRange(leftSiblingIndex, rightSiblingIndex);
+
+      return [firstPage, ELLIPSIS, ...middleRange, ELLIPSIS, lastPage];
+    }
+
+    return [];
+  }, [totalResults, resultsPerPage, siblingPagesCount, currentPage]);
+}