Merge branch 'main' into react-dom/FadeIn

.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

.changeset/twenty-rockets-knock.md

@@ -0,0 +1,8 @@
+---
+"@suspensive/jotai": patch
+"@suspensive/react-query-4": patch
+"@suspensive/react-query-5": patch
+"@suspensive/react": patch
+---
+
+fix(*): fix typo in jsdoc

.changeset/wild-days-retire.md

@@ -0,0 +1,8 @@
+---
+'@suspensive/react-query-4': patch
+'@suspensive/react-query-5': patch
+'@suspensive/jotai': patch
+'@suspensive/react': patch
+---
+
+fix(react-query, jotai, react): fix typo in jsdoc

packages/jotai/src/Atom.tsx

@@ -20,10 +20,10 @@ type UseAtomProps<TAtom extends Parameters<typeof useAtom>[0]> = {
 }
 
 /**
- * This hook is wrapping `useAtom` hook from jotai.
+ * This component is wrapping `useAtom` of jotai.
  *
  * The Atom component provides an interface similar to Jotai's `useAtom` hook as props, allowing declarative usage.
- * @see {@link https://suspensive.org/docs/jotai/Atom}
+ * @see {@link https://suspensive.org/docs/jotai/Atom Suspensive Docs}
  * @example
  * ```jsx
  * import { Atom } from '@suspensive/jotai'

packages/jotai/src/AtomValue.tsx

@@ -8,10 +8,10 @@ type UseAtomValueProps<TAtom extends Parameters<typeof useAtomValue>[0]> = {
 }
 
 /**
- * This hook is wrapping `useAtomValue` hook from jotai.
+ * This component is wrapping `useAtomValue` of jotai.
  *
  * The AtomValue component provides an interface similar to Jotai's `useAtomValue` hook as props, allowing declarative usage.
- * @see {@link https://suspensive.org/docs/jotai/AtomValue}
+ * @see {@link https://suspensive.org/docs/jotai/AtomValue Suspensive Docs}
  * @example
  * ```jsx
  * import { AtomValue } from '@suspensive/jotai'

packages/jotai/src/SetAtom.tsx

@@ -8,10 +8,10 @@ type UseSetAtomProps<TAtom> = {
 }
 
 /**
- * This Component is wrapping `useSetAtom` of jotai
+ * This component is wrapping `useSetAtom` of jotai.
  *
  * The SetAtom component provides an interface similar to Jotai's `useSetAtom` hook as props, allowing declarative usage.
- * @see {@link https://suspensive.org/docs/jotai/SetAtom}
+ * @see {@link https://suspensive.org/docs/jotai/SetAtom Suspensive Docs}
  * @example
  * ```jsx
  * import { SetAtom } from '@suspensive/jotai'

packages/react-query-4/src/PrefetchInfiniteQuery.tsx

@@ -2,7 +2,7 @@ import { type FetchInfiniteQueryOptions, type QueryKey } from '@tanstack/react-q
 import { usePrefetchInfiniteQuery } from './usePrefetchInfiniteQuery'
 
 /**
- * A component that allows you to use usePrefetchInfiniteQuery in JSX, avoiding the limitations of React hooks.
+ * A component that allows you to use `usePrefetchInfiniteQuery` in JSX, avoiding the limitations of React hooks.
  * @see {@link https://suspensive.org/en/docs/react-query/PrefetchInfiniteQuery Suspensive Docs}
  * @example
  * ```tsx

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-query-4/src/usePrefetchInfiniteQuery.ts

@@ -1,7 +1,7 @@
 import { type FetchInfiniteQueryOptions, type QueryKey, useQueryClient } from '@tanstack/react-query'
 
 /**
- * The usePrefetchInfiniteQuery does not return anything, it should be used just to fire a prefetch during render, before a suspense boundary that wraps a component that uses useSuspenseInfiniteQuery.
+ * The `usePrefetchInfiniteQuery` does not return anything, it should be used just to fire a prefetch during render, before a suspense boundary that wraps a component that uses `useSuspenseInfiniteQuery`.
  * @see {@link https://suspensive.org/en/docs/react-query/usePrefetchInfiniteQuery Suspensive Docs}
  */
 export function usePrefetchInfiniteQuery<

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

@@ -1,7 +1,7 @@
 import { type FetchQueryOptions, type QueryKey, useQueryClient } from '@tanstack/react-query'
 
 /**
- * The usePrefetchQuery does not return anything, it should be used just to fire a prefetch during render, before a suspense boundary that wraps a component that uses useSuspenseQuery.
+ * The `usePrefetchQuery` does not return anything, it should be used just to fire a prefetch during render, before a suspense boundary that wraps a component that uses `useSuspenseQuery`.
  * @see {@link https://suspensive.org/en/docs/react-query/usePrefetchQuery Suspensive Docs}
  */
 export function usePrefetchQuery<

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

@@ -27,7 +27,7 @@ export type UseSuspenseInfiniteQueryOptions<
 >
 
 /**
- * This hook is wrapping useInfiniteQuery of `@tanstack/react-query` v4 with default suspense option.
+ * This hook is wrapping `useInfiniteQuery` of `@tanstack/react-query` v4 with default suspense option.
  * @see {@link https://suspensive.org/en/docs/react-query/useSuspenseInfiniteQuery Suspensive Docs}
  */
 export function useSuspenseInfiniteQuery<

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

@@ -110,7 +110,7 @@ export type SuspenseQueriesResults<
             Array<UseSuspenseQueryResult>
 
 /**
- * This hook is wrapping useQueries of `@tanstack/react-query` v4 with default suspense option.
+ * This hook is wrapping `useQueries` of `@tanstack/react-query` v4 with default suspense option.
  * @see {@link https://suspensive.org/en/docs/react-query/useSuspenseQueries Suspensive Docs}
  */
 export function useSuspenseQueries<T extends any[]>({

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

@@ -18,7 +18,7 @@ export type UseSuspenseQueryOptions<
 >
 
 /**
- * This hook is wrapping useQuery of `@tanstack/react-query` v4 with default suspense option.
+ * This hook is wrapping `useQuery` of `@tanstack/react-query` v4 with default suspense option.
  * @see {@link https://suspensive.org/en/docs/react-query/useSuspenseQuery Suspensive Docs}
  */
 export function useSuspenseQuery<

packages/react-query-5/src/QueryErrorBoundary.tsx

@@ -3,7 +3,7 @@ import { useQueryErrorResetBoundary } from '@tanstack/react-query'
 import { type ComponentPropsWithoutRef, type ComponentRef, forwardRef } from 'react'
 
 /**
- * This component wrapping QueryErrorResetBoundary of `@tanstack/react-query` with `@suspensive/react`'s ErrorBoundary. So you must install `@suspensive/react` first, then use it. with this component, You don't have to make unnecessary repetitive implementation to combine ErrorBoundary with QueryErrorResetBoundary
+ * This component is wrapping QueryErrorResetBoundary of `@tanstack/react-query` with `@suspensive/react`'s ErrorBoundary. So you must install `@suspensive/react` first, then use it. with this component, You don't have to make unnecessary repetitive implementation to combine ErrorBoundary with QueryErrorResetBoundary
  * @deprecated this interface will be removed in the next major version. Please make this component yourself by combining ErrorBoundary of `@suspensive/react` and useQueryErrorResetBoundary of `@tanstack/react-query`
  * @example
  * ```tsx

packages/react-query-5/src/SuspenseQuery.tsx

@@ -15,12 +15,12 @@ import type { ReactNode } from 'react'
  * ```tsx
  * import { SuspenseQuery } from '@suspensive/react-query'
  *
- * // You can use QueryOptions as props.
+ * // You can use queryOptions as props.
  * <SuspenseQuery {...queryOptions()}>
- *   {({ data, isLoading }) => {
+ *   {({ data }) => {
  *     return <></>
- *   }
- * </SuspenseQuery/>
+ *   }}
+ * </SuspenseQuery>
  */
 export const SuspenseQuery = <
   TQueryFnData = 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/Suspense.tsx

@@ -23,7 +23,7 @@ export interface SuspenseProps
 
 /**
  * This component is just wrapping React's Suspense. to use Suspense easily in Server-side rendering environment like Next.js
- * @see {@link https://suspensive.org/docs/react/Suspense}
+ * @see {@link https://suspensive.org/docs/react/Suspense Suspensive Docs}
  */
 export const Suspense = ({ clientOnly, children, fallback }: SuspenseProps) => {
   const defaultProps = useContext(SuspenseDefaultPropsContext)

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'>) =>