From 52c673261bc9b79f29e685e02df5b4ab7bf86d94 Mon Sep 17 00:00:00 2001 From: "codegen-sh[bot]" <131295404+codegen-sh[bot]@users.noreply.github.com> Date: Fri, 28 Mar 2025 02:37:32 +0000 Subject: [PATCH] Add JSDoc to hooks in app/hooks directory (#8819) * Add JSDoc to hooks in app/hooks directory * lint --------- Co-authored-by: codegen-sh[bot] <131295404+codegen-sh[bot]@users.noreply.github.com> Co-authored-by: Tom Moor --- app/hooks/useDictionary.ts | 5 +++++ app/hooks/useMaxHeight.ts | 9 +++++++++ app/hooks/useMediaQuery.ts | 6 ++++++ app/hooks/useMobile.ts | 5 +++++ app/hooks/useQuery.ts | 5 +++++ app/hooks/useStores.ts | 5 +++++ app/hooks/useUnmount.ts | 5 +++++ app/hooks/useViewportHeight.ts | 6 ++++++ app/hooks/useWindowScrollPosition.ts | 7 +++++++ 9 files changed, 53 insertions(+) diff --git a/app/hooks/useDictionary.ts b/app/hooks/useDictionary.ts index 5b16343526..4c325a93db 100644 --- a/app/hooks/useDictionary.ts +++ b/app/hooks/useDictionary.ts @@ -1,6 +1,11 @@ import * as React from "react"; import { useTranslation } from "react-i18next"; +/** + * Hook that provides a dictionary of translated UI strings. + * + * @returns An object containing all translated UI strings used throughout the application + */ export default function useDictionary() { const { t } = useTranslation(); diff --git a/app/hooks/useMaxHeight.ts b/app/hooks/useMaxHeight.ts index c3f5e0a922..6e8300f4b7 100644 --- a/app/hooks/useMaxHeight.ts +++ b/app/hooks/useMaxHeight.ts @@ -1,6 +1,15 @@ import * as React from "react"; import useWindowSize from "./useWindowSize"; +/** + * Hook to calculate the maximum height for an element based on its position and viewport size. + * + * @param options Configuration options + * @param options.elementRef A ref pointing to the element to calculate max height for + * @param options.maxViewportPercentage The maximum height of the element as a percentage of the viewport + * @param options.margin The margin to apply to the positioning + * @returns Object containing the calculated maxHeight and a function to recalculate it + */ const useMaxHeight = ({ elementRef, maxViewportPercentage = 90, diff --git a/app/hooks/useMediaQuery.ts b/app/hooks/useMediaQuery.ts index ccf8d90590..79234ad0bb 100644 --- a/app/hooks/useMediaQuery.ts +++ b/app/hooks/useMediaQuery.ts @@ -1,5 +1,11 @@ import { useState, useEffect } from "react"; +/** + * Hook to check if a media query matches the current viewport. + * + * @param query The CSS media query to check against + * @returns boolean indicating whether the media query matches + */ export default function useMediaQuery(query: string): boolean { const [matches, setMatches] = useState(false); diff --git a/app/hooks/useMobile.ts b/app/hooks/useMobile.ts index d703dcdde7..abed58e124 100644 --- a/app/hooks/useMobile.ts +++ b/app/hooks/useMobile.ts @@ -1,6 +1,11 @@ import { breakpoints } from "@shared/styles"; import useMediaQuery from "~/hooks/useMediaQuery"; +/** + * Hook to detect if the current viewport is mobile-sized. + * + * @returns boolean indicating whether the current viewport is mobile-sized + */ export default function useMobile(): boolean { return useMediaQuery(`(max-width: ${breakpoints.tablet - 1}px)`); } diff --git a/app/hooks/useQuery.ts b/app/hooks/useQuery.ts index 02405e1afc..960c8afce9 100644 --- a/app/hooks/useQuery.ts +++ b/app/hooks/useQuery.ts @@ -1,6 +1,11 @@ import React from "react"; import { useLocation } from "react-router-dom"; +/** + * Hook to access URL query parameters from the current location. + * + * @returns URLSearchParams object containing the current URL query parameters + */ export default function useQuery() { const location = useLocation(); diff --git a/app/hooks/useStores.ts b/app/hooks/useStores.ts index e77130ebf9..9bea4b422d 100644 --- a/app/hooks/useStores.ts +++ b/app/hooks/useStores.ts @@ -2,6 +2,11 @@ import { MobXProviderContext } from "mobx-react"; import * as React from "react"; import RootStore from "~/stores"; +/** + * Hook to access the MobX stores from the React context. + * + * @returns The root store containing all application stores + */ export default function useStores() { return React.useContext(MobXProviderContext) as typeof RootStore; } diff --git a/app/hooks/useUnmount.ts b/app/hooks/useUnmount.ts index 5be355e00c..2cdcb0f105 100644 --- a/app/hooks/useUnmount.ts +++ b/app/hooks/useUnmount.ts @@ -1,5 +1,10 @@ import * as React from "react"; +/** + * Hook that executes a callback when the component unmounts. + * + * @param callback Function to be called on component unmount + */ const useUnmount = (callback: (...args: Array) => any) => { const ref = React.useRef(callback); ref.current = callback; diff --git a/app/hooks/useViewportHeight.ts b/app/hooks/useViewportHeight.ts index 6175f314c3..3915de50a6 100644 --- a/app/hooks/useViewportHeight.ts +++ b/app/hooks/useViewportHeight.ts @@ -1,5 +1,11 @@ import { useLayoutEffect, useState } from "react"; +/** + * Hook to get the current viewport height, accounting for mobile virtual keyboards. + * Uses the VisualViewport API when available, falling back to window.innerHeight. + * + * @returns The current viewport height in pixels + */ export default function useViewportHeight(): number | void { // https://developer.mozilla.org/en-US/docs/Web/API/VisualViewport#browser_compatibility // Note: No support in Firefox at time of writing, however this mainly exists diff --git a/app/hooks/useWindowScrollPosition.ts b/app/hooks/useWindowScrollPosition.ts index 4f3cf2b333..10713d58f1 100644 --- a/app/hooks/useWindowScrollPosition.ts +++ b/app/hooks/useWindowScrollPosition.ts @@ -13,6 +13,13 @@ const defaultOptions = { throttle: 100, }; +/** + * Hook to track the window's scroll position. + * + * @param options Configuration options + * @param options.throttle Time in milliseconds to throttle the scroll event + * @returns Object containing the current scroll position (x, y coordinates) + */ export default function useWindowScrollPosition(options: { throttle: number; }): {