From 8bdfc2f285ecae40e52fa042bf4752290177f9ca Mon Sep 17 00:00:00 2001 From: Ferdy Budhidharma Date: Tue, 30 Apr 2019 11:37:58 -0500 Subject: [PATCH] [react-transition-group] add JSDoc usage comments for individual props (#35031) * add JSDoc comments for props * add types * Update TransitionGroup.d.ts * Update Transition.d.ts * Update Transition.d.ts --- .../react-transition-group/CSSTransition.d.ts | 42 +++---- types/react-transition-group/Transition.d.ts | 104 +++++++++++++++++- 2 files changed, 126 insertions(+), 20 deletions(-) diff --git a/types/react-transition-group/CSSTransition.d.ts b/types/react-transition-group/CSSTransition.d.ts index 1192badcea..cb540659b0 100644 --- a/types/react-transition-group/CSSTransition.d.ts +++ b/types/react-transition-group/CSSTransition.d.ts @@ -14,26 +14,30 @@ declare namespace CSSTransition { exitDone?: string; } - /** - * The animation classNames applied to the component as it enters or exits. - * A single name can be provided and it will be suffixed for each stage: e.g. - * - * `classNames="fade"` applies `fade-enter`, `fade-enter-active`, - * `fade-exit`, `fade-exit-active`, `fade-appear`, and `fade-appear-active`. - * Each individual classNames can also be specified independently like: - * - * ```js - * classNames={{ - * appear: 'my-appear', - * appearActive: 'my-active-appear', - * enter: 'my-enter', - * enterActive: 'my-active-enter', - * exit: 'my-exit', - * exitActive: 'my-active-exit', - * }} - * ``` - */ interface CSSTransitionProps extends TransitionProps { + /** + * The animation `classNames` applied to the component as it enters or exits. + * A single name can be provided and it will be suffixed for each stage: e.g. + * + * `classNames="fade"` applies `fade-enter`, `fade-enter-active`, + * `fade-exit`, `fade-exit-active`, `fade-appear`, and `fade-appear-active`. + * + * Each individual classNames can also be specified independently like: + * + * ```js + * classNames={{ + * appear: 'my-appear', + * appearActive: 'my-appear-active', + * appearDone: 'my-appear-done', + * enter: 'my-enter', + * enterActive: 'my-enter-active', + * enterDone: 'my-enter-done', + * exit: 'my-exit', + * exitActive: 'my-exit-active', + * exitDone: 'my-exit-done' + * }} + * ``` + */ classNames?: string | CSSTransitionClassNames; } } diff --git a/types/react-transition-group/Transition.d.ts b/types/react-transition-group/Transition.d.ts index 62c0dada7e..b20d1d2fdb 100644 --- a/types/react-transition-group/Transition.d.ts +++ b/types/react-transition-group/Transition.d.ts @@ -11,8 +11,23 @@ export const ENTERED = 'entered'; export const EXITING = 'exiting'; export interface TransitionActions { + /** + * Normally a component is not transitioned if it is shown when the + * `` component mounts. If you want to transition on the first + * mount set appear to true, and the component will transition in as soon + * as the `` mounts. Note: there are no specific "appear" states. + * appear only adds an additional enter transition. + */ appear?: boolean; + + /** + * Enable or disable enter transitions. + */ enter?: boolean; + + /** + * Enable or disable exit transitions. + */ exit?: boolean; } @@ -24,19 +39,106 @@ export type TransitionStatus = typeof UNMOUNTED; export type TransitionChildren = React.ReactNode | ((status: TransitionStatus) => React.ReactNode); export interface TransitionProps extends TransitionActions { + /** + * Show the component; triggers the enter or exit states + */ in?: boolean; + + /** + * By default the child component is mounted immediately along with the + * parent Transition component. If you want to "lazy mount" the component on + * the first `in={true}` you can set `mountOnEnter`. After the first enter + * transition the component will stay mounted, even on "exited", unless you + * also specify `unmountOnExit`. + */ mountOnEnter?: boolean; + + /** + * By default the child component stays mounted after it reaches the + * 'exited' state. Set `unmountOnExit` if you'd prefer to unmount the + * component after it finishes exiting. + */ unmountOnExit?: boolean; + + /** + * The duration of the transition, in milliseconds. Required unless addEndListener is provided. + * + * You may specify a single timeout for all transitions: + * ```js + * timeout={500} + * ``` + * or individually: + * ```js + * timeout={{ + * appear: 500, + * enter: 300, + * exit: 500, + * }} + * ``` + * - appear defaults to the value of `enter` + * - enter defaults to `0` + * - exit defaults to `0` + */ timeout: number | { enter?: number, exit?: number }; + + /** + * Add a custom transition end trigger. Called with the transitioning DOM + * node and a done callback. Allows for more fine grained transition end + * logic. Note: Timeouts are still used as a fallback if provided. + */ addEndListener?: EndHandler; + + /** + * Callback fired before the "entering" status is applied. An extra + * parameter `isAppearing` is supplied to indicate if the enter stage is + * occurring on the initial mount + */ onEnter?: EnterHandler; + + /** + * Callback fired after the "entering" status is applied. An extra parameter + * isAppearing is supplied to indicate if the enter stage is occurring on + * the initial mount + */ onEntering?: EnterHandler; + + /** + * Callback fired after the "entered" status is applied. An extra parameter + * isAppearing is supplied to indicate if the enter stage is occurring on + * the initial mount + */ onEntered?: EnterHandler; + + /** + * Callback fired before the "exiting" status is applied. + */ onExit?: ExitHandler; + + /** + * Callback fired after the "exiting" status is applied. + */ onExiting?: ExitHandler; + + /** + * Callback fired after the "exited" status is applied. + */ onExited?: ExitHandler; - [prop: string]: any; + + /** + * A function child can be used instead of a React element. This function is + * called with the current transition status ('entering', 'entered', + * 'exiting', 'exited', 'unmounted'), which can be used to apply context + * specific props to a component. + * ```jsx + * + * {state => ( + * + * )} + * + * ``` + */ children?: TransitionChildren; + [ prop: string ]: any; } /**