feat(react, react-query-4): add missing JSDoc for react and react-que…

…ry-4 (#1365)

# Overview

<!--
    A clear and concise description of what this pr is about.
 -->

I add JSDoc comments to `@suspensive/react` and
`@suspensive/react-query-4`.



## PR Checklist

- [x] I did below actions if need

1. I read the [Contributing
Guide](https://github.com/toss/suspensive/blob/main/CONTRIBUTING.md)
2. I added documents and tests.

---------

Co-authored-by: Jonghyeon Ko <jonghyeon@toss.im>

.changeset/thick-cats-marry.md

@@ -0,0 +1,6 @@
+---
+'@suspensive/react-query-4': patch
+'@suspensive/react': patch
+---
+
+feat(react, react-query-4): add missing JSDoc for react and react-query-4

packages/react-query-4/src/queryOptions.ts

@@ -55,6 +55,12 @@ export type UnSelectedQueryOptions<
   select?: undefined
 }
 
+/**
+ * Creates a reusable query options object that can be used across different query hooks.
+ * Provides better type inference and easier query key management.
+ *
+ * @see {@link https://suspensive.org/en/docs/react-query/queryOptions Suspensive Docs}
+ */
 export function queryOptions<
   TQueryFnData = unknown,
   TError = unknown,

packages/react/src/ClientOnly.tsx

@@ -6,4 +6,8 @@ export interface ClientOnlyProps {
   fallback?: ReactNode
 }
 
+/**
+ * This component ensures its children are only rendered on the client-side.
+ * @see {@link https://suspensive.org/docs/react/ClientOnly Suspensive Docs}
+ */
 export const ClientOnly = ({ children, fallback }: ClientOnlyProps) => <>{useIsClient() ? children : fallback}</>

packages/react/src/DefaultProps.tsx

@@ -2,6 +2,23 @@ import { type ContextType, type PropsWithChildren } from 'react'
 import { DelayDefaultPropsContext, SuspenseDefaultPropsContext } from './contexts'
 import { Message_DefaultProp_delay_ms_should_be_greater_than_0, SuspensiveError } from './models/SuspensiveError'
 
+/**
+ * A class for configuring default props for Suspensive components.
+ *
+ * @example
+ * ```tsx
+ * const defaultProps = new DefaultProps({
+ *   Delay: {
+ *     ms: 1200,
+ *     fallback: <LoadingMessage>Loading additional content...</LoadingMessage>
+ *   },
+ *   Suspense: {
+ *     fallback: <Spinner>Fetching data...</Spinner>,
+ *     clientOnly: false,
+ *   },
+ * })
+ * ```
+ */
 export class DefaultProps {
   Suspense?: ContextType<typeof SuspenseDefaultPropsContext>
   Delay?: ContextType<typeof DelayDefaultPropsContext>
@@ -18,6 +35,35 @@ export class DefaultProps {
 interface DefaultPropsProviderProps extends PropsWithChildren {
   defaultProps: DefaultProps
 }
+
+/**
+ * A provider component that controls the default settings of Suspensive components.
+ * Use this to configure default props for Suspense, Delay, and other Suspensive components globally.
+ *
+ * @example
+ * ```tsx
+ * const defaultProps = new DefaultProps({
+ *   Delay: {
+ *     ms: 1000,
+ *     fallback: <LoadingSpinner />
+ *   },
+ *   Suspense: {
+ *     fallback: <Skeleton />,
+ *     clientOnly: false,
+ *   },
+ * })
+ *
+ * function App() {
+ *   return (
+ *     <DefaultPropsProvider defaultProps={defaultProps}>
+ *       <YourApp />
+ *     </DefaultPropsProvider>
+ *   )
+ * }
+ * ```
+ *
+ * @see {@link https://suspensive.org/en/docs/react/DefaultPropsProvider Suspensive Docs}
+ */
 export const DefaultPropsProvider = ({ defaultProps, children }: DefaultPropsProviderProps) => (
   <DelayDefaultPropsContext.Provider value={defaultProps.Delay ?? {}}>
     <SuspenseDefaultPropsContext.Provider value={defaultProps.Suspense ?? {}}>

packages/react/src/Delay.tsx

@@ -18,6 +18,13 @@ export type DelayProps =
       children?: ReactNode
     }
 
+/**
+ * This component delays the rendering of its children for a specified duration.
+ *
+ * The Delay component provides a way to introduce intentional delays in rendering,
+ * which can be useful for loading states or animations.
+ * @see {@link https://suspensive.org/docs/react/Delay Suspensive Docs}
+ */
 export const Delay = (props: DelayProps) => {
   if (process.env.NODE_ENV === 'development' && typeof props.ms === 'number') {
     SuspensiveError.assert(props.ms >= 0, Message_Delay_ms_prop_should_be_greater_than_or_equal_to_0)

packages/react/src/ErrorBoundary.tsx

@@ -164,8 +164,8 @@ class BaseErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState
 }
 
 /**
- * This component provide a simple and reusable wrapper that you can use to wrap around your components. Any rendering errors in your components hierarchy can then be gracefully handled.
- * @see {@link https://suspensive.org/docs/react/ErrorBoundary}
+ * This component provides a simple and reusable wrapper that you can use to wrap around your components. Any rendering errors in your components hierarchy can then be gracefully handled.
+ * @see {@link https://suspensive.org/docs/react/ErrorBoundary Suspensive Docs}
  */
 export const ErrorBoundary = Object.assign(
   (() => {
@@ -212,6 +212,10 @@ if (process.env.NODE_ENV === 'development') {
   ErrorBoundaryContext.displayName = 'ErrorBoundaryContext'
 }
 
+/**
+ * This hook provides a simple and reusable wrapper that you can use to wrap around your components. Any rendering errors in your components hierarchy can then be gracefully handled.
+ * @see {@link https://suspensive.org/en/docs/react/ErrorBoundary#useerrorboundary Suspensive Docs}
+ */
 // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
 export const useErrorBoundary = <TError extends Error = Error>() => {
   const [state, setState] = useState<ErrorBoundaryState<TError>>({
@@ -236,6 +240,10 @@ export const useErrorBoundary = <TError extends Error = Error>() => {
   )
 }
 
+/**
+ * This hook allows you to access the reset method and error objects without prop drilling.
+ * @see {@link https://suspensive.org/en/docs/react/ErrorBoundary#useerrorboundaryfallbackprops Suspensive Docs}
+ */
 export const useErrorBoundaryFallbackProps = <TError extends Error = Error>(): ErrorBoundaryFallbackProps<TError> => {
   const errorBoundary = useContext(ErrorBoundaryContext)
   SuspensiveError.assert(

packages/react/src/ErrorBoundaryGroup.tsx

@@ -28,8 +28,9 @@ export interface ErrorBoundaryGroupProps extends PropsWithChildren {
 }
 
 /**
- * ErrorBoundaryGroup is Component to manage multiple ErrorBoundaries
- * @see {@link https://suspensive.org/docs/react/ErrorBoundaryGroup}
+ * ErrorBoundaryGroup is a wrapper component that allows you to manage multiple ErrorBoundaries easily.
+ * ErrorBoundaries as children of nested ErrorBoundaryGroup will also be reset by parent ErrorBoundaryGroup.Consumer.
+ * @see {@link https://suspensive.org/docs/react/ErrorBoundaryGroup Suspensive Docs}
  */
 export const ErrorBoundaryGroup = Object.assign(
   (() => {
@@ -63,7 +64,12 @@ export const ErrorBoundaryGroup = Object.assign(
   }
 )
 
-export const useErrorBoundaryGroup = () => {
+/**
+ * This hook provides the reset method for the ErrorBoundaryGroup.
+ * Must be used within an ErrorBoundaryGroup component.
+ * @see {@link https://suspensive.org/docs/react/ErrorBoundaryGroup#useerrorboundarygroup Suspensive Docs}
+ */
+export const useErrorBoundaryGroup = (): { reset: () => void } => {
   const group = useContext(ErrorBoundaryGroupContext)
   SuspensiveError.assert(
     group != null,

packages/react/src/wrap.tsx

@@ -56,6 +56,29 @@ class Wrap {
   }
 }
 
+/**
+ * A utility for wrapping components with Suspensive components (Suspense, ErrorBoundary, ErrorBoundaryGroup, Delay).
+ *
+ * @example
+ * ```tsx
+ * const Page = wrap
+ *   .ErrorBoundaryGroup({ blockOutside: true })
+ *   .ErrorBoundary({
+ *     fallback: ({ error }) => <PageErrorFallback message={error.message} />,
+ *   })
+ *   .Suspense({ fallback: <PageSkeleton /> })
+ *   .on(() => {
+ *     const { data: postList } = useSuspenseQuery({
+ *       queryKey: ['posts'],
+ *       queryFn: () => fetch('/api/posts').then(res => res.json())
+ *     })
+ *
+ *     return <PostList data={postList} />
+ *   })
+ * ```
+ *
+ * @see {@link https://suspensive.org/docs/react/wrap Suspensive Docs}
+ */
 export const wrap = {
   Suspense: (props: OmitKeyof<ComponentProps<typeof Suspense>, 'children'> = {}) => new Wrap([[Suspense, props]]),
   ErrorBoundary: (props: OmitKeyof<ComponentProps<typeof ErrorBoundary>, 'children'>) =>