From 89c1cd9028bbdf092cdda24254a56afd003c941f Mon Sep 17 00:00:00 2001 From: Juhyeok Kang Date: Wed, 20 Nov 2024 11:32:13 +0900 Subject: [PATCH] feat(react, react-query-4): add missing JSDoc for react and react-query-4 (#1365) # Overview 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 --- .changeset/thick-cats-marry.md | 6 +++ packages/react-query-4/src/queryOptions.ts | 6 +++ packages/react/src/ClientOnly.tsx | 4 ++ packages/react/src/DefaultProps.tsx | 46 ++++++++++++++++++++++ packages/react/src/Delay.tsx | 7 ++++ packages/react/src/ErrorBoundary.tsx | 12 +++++- packages/react/src/ErrorBoundaryGroup.tsx | 12 ++++-- packages/react/src/wrap.tsx | 23 +++++++++++ 8 files changed, 111 insertions(+), 5 deletions(-) create mode 100644 .changeset/thick-cats-marry.md diff --git a/.changeset/thick-cats-marry.md b/.changeset/thick-cats-marry.md new file mode 100644 index 000000000..3a42f2c40 --- /dev/null +++ b/.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 diff --git a/packages/react-query-4/src/queryOptions.ts b/packages/react-query-4/src/queryOptions.ts index eaf5cef57..15472e924 100644 --- a/packages/react-query-4/src/queryOptions.ts +++ b/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, diff --git a/packages/react/src/ClientOnly.tsx b/packages/react/src/ClientOnly.tsx index 95d3182c5..df716788e 100644 --- a/packages/react/src/ClientOnly.tsx +++ b/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} diff --git a/packages/react/src/DefaultProps.tsx b/packages/react/src/DefaultProps.tsx index e16bdf398..3cc5e7aa2 100644 --- a/packages/react/src/DefaultProps.tsx +++ b/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: Loading additional content... + * }, + * Suspense: { + * fallback: Fetching data..., + * clientOnly: false, + * }, + * }) + * ``` + */ export class DefaultProps { Suspense?: ContextType Delay?: ContextType @@ -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: + * }, + * Suspense: { + * fallback: , + * clientOnly: false, + * }, + * }) + * + * function App() { + * return ( + * + * + * + * ) + * } + * ``` + * + * @see {@link https://suspensive.org/en/docs/react/DefaultPropsProvider Suspensive Docs} + */ export const DefaultPropsProvider = ({ defaultProps, children }: DefaultPropsProviderProps) => ( diff --git a/packages/react/src/Delay.tsx b/packages/react/src/Delay.tsx index 414f52b40..54c23661d 100644 --- a/packages/react/src/Delay.tsx +++ b/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) diff --git a/packages/react/src/ErrorBoundary.tsx b/packages/react/src/ErrorBoundary.tsx index e21ef3f5f..55fffe1b8 100644 --- a/packages/react/src/ErrorBoundary.tsx +++ b/packages/react/src/ErrorBoundary.tsx @@ -164,8 +164,8 @@ class BaseErrorBoundary extends Component { @@ -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 = () => { const [state, setState] = useState>({ @@ -236,6 +240,10 @@ export const useErrorBoundary = () => { ) } +/** + * 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 = (): ErrorBoundaryFallbackProps => { const errorBoundary = useContext(ErrorBoundaryContext) SuspensiveError.assert( diff --git a/packages/react/src/ErrorBoundaryGroup.tsx b/packages/react/src/ErrorBoundaryGroup.tsx index 42fd77aab..9dde42f7c 100644 --- a/packages/react/src/ErrorBoundaryGroup.tsx +++ b/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, diff --git a/packages/react/src/wrap.tsx b/packages/react/src/wrap.tsx index 640c4f8f7..de8619779 100644 --- a/packages/react/src/wrap.tsx +++ b/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 }) => , + * }) + * .Suspense({ fallback: }) + * .on(() => { + * const { data: postList } = useSuspenseQuery({ + * queryKey: ['posts'], + * queryFn: () => fetch('/api/posts').then(res => res.json()) + * }) + * + * return + * }) + * ``` + * + * @see {@link https://suspensive.org/docs/react/wrap Suspensive Docs} + */ export const wrap = { Suspense: (props: OmitKeyof, 'children'> = {}) => new Wrap([[Suspense, props]]), ErrorBoundary: (props: OmitKeyof, 'children'>) =>