add JSDoc

Author: theKashey

src/assignRef.ts

@@ -1,5 +1,18 @@
 import { ReactRef } from './types';
 
+/**
+ * Assigns a value for a given ref, no matter of the ref format
+ * @param {RefObject} ref - a callback function or ref object
+ * @param value - a new value
+ *
+ * @see https://github.com/theKashey/use-callback-ref#assignref
+ * @example
+ * const refObject = useRef();
+ * const refFn = (ref) => {....}
+ *
+ * assignRef(refObject, "refValue");
+ * assignRef(refFn, "refValue");
+ */
 export function assignRef<T>(ref: ReactRef<T>, value: T | null): ReactRef<T> {
   if (typeof ref === 'function') {
     ref(value);

src/createRef.ts

@@ -1,5 +1,13 @@
-import { RefObject, useImperativeHandle } from 'react';
+import { RefObject } from 'react';
 
+/**
+ * creates a Ref object with on change callback
+ * @param callback
+ * @returns {RefObject}
+ *
+ * @see {@link useCallbackRef}
+ * @see https://reactjs.org/docs/refs-and-the-dom.html#creating-refs
+ */
 export function createCallbackRef<T>(
   callback: (newValue: T | null, lastValue: T | null) => any
 ): RefObject<T> {

src/mergeRef.ts

@@ -1,11 +1,24 @@
-import * as React from 'react';
-import { createCallbackRef } from './createRef';
-import { assignRef } from './assignRef';
-import { ReactRef } from './types';
+import {MutableRefObject} from 'react';
+import {createCallbackRef} from './createRef';
+import {assignRef} from './assignRef';
+import {ReactRef} from './types';
 
+/**
+ * Merges two or more refs together providing a single interface to set their value
+ * @param {RefObject|Ref} refs
+ * @returns {MutableRefObject} - a new ref, which translates all changes to {refs}
+ *
+ * @see {@link useMergeRefs} to be used in ReactComponents
+ * @example
+ * const Component = React.forwardRef((props, ref) => {
+ *   const ownRef = useRef();
+ *   const domRef = mergeRefs([ref, ownRef]); // 👈 merge together
+ *   return <div ref={domRef}>...</div>
+ * }
+ */
 export function mergeRefs<T>(
   refs: ReactRef<T>[]
-): React.MutableRefObject<T | null> {
+): MutableRefObject<T | null> {
   return createCallbackRef<T>(newValue =>
     refs.forEach(ref => assignRef(ref, newValue))
   );

src/refToCallback.ts

@@ -1,6 +1,10 @@
 import {ReactRef, RefCallback} from './types';
-import {useRef, useState} from 'react';
 
+/**
+ * Unmemoized version of {@link useRefToCallback}
+ * @see {@link useRefToCallback}
+ * @param ref
+ */
 export function refToCallback<T>(ref: ReactRef<T>): RefCallback<T> {
   return newValue => {
     if (typeof ref === 'function') {
@@ -25,6 +29,22 @@ const weakMemoize = (ref: ReactRef<any>) => {
   return cb;
 };
 
+/**
+ * Transforms a given `ref` into `callback`.
+ *
+ * To transform `callback` into ref use {@link useCallbackRef|useCallbackRef(undefined, callback)}
+ *
+ * @param {ReactRef} ref
+ * @returns {Function}
+ *
+ * @see https://github.com/theKashey/use-callback-ref#reftocallback
+ *
+ * @example
+ * const ref = useRef(0);
+ * const setRef = useRefToCallback(ref);
+ * 👉 setRef(10);
+ * ✅ ref.current === 10
+ */
 export function useRefToCallback<T>(ref: ReactRef<T>): RefCallback<T> {
   return weakMemoize(ref);
 }

src/useMergeRef.ts

@@ -3,6 +3,20 @@ import { useCallbackRef } from './useRef';
 import { assignRef } from './assignRef';
 import { ReactRef } from './types';
 
+/**
+ * Merges two or more refs together providing a single interface to set their value
+ * @param {RefObject|Ref} refs
+ * @returns {MutableRefObject} - a new ref, which translates all changes to {refs}
+ *
+ * @see {@link mergeRefs} a version without buit-in memoization
+ * @see https://github.com/theKashey/use-callback-ref#usemergerefs
+ * @example
+ * const Component = React.forwardRef((props, ref) => {
+ *   const ownRef = useRef();
+ *   const domRef = useMergeRefs([ref, ownRef]); // 👈 merge together
+ *   return <div ref={domRef}>...</div>
+ * }
+ */
 export function useMergeRefs<T>(
   refs: ReactRef<T>[],
   defaultValue?: T

src/useRef.ts

@@ -1,5 +1,19 @@
 import { MutableRefObject, useState } from 'react';
 
+/**
+ * creates a MutableRef with ref change callback
+ * @param initialValue - initial ref value
+ * @param {Function} callback - a callback to run when value changes
+ *
+ * @example
+ * const ref = useCallbackRef(0, (newValue, oldValue) => console.log(oldValue, '->', newValue);
+ * ref.current = 1;
+ * // prints 0 -> 1
+ *
+ * @see https://reactjs.org/docs/hooks-reference.html#useref
+ * @see https://github.com/theKashey/use-callback-ref#usecallbackref---to-replace-reactuseref
+ * @returns {MutableRefObject}
+ */
 export function useCallbackRef<T>(
   initialValue: T | null,
   callback: (newValue: T | null, lastValue: T | null) => void

src/useTransformRef.ts

@@ -2,6 +2,19 @@ import { ReactRef, RefObject } from './types';
 import { useCallbackRef } from './useRef';
 import { assignRef } from './assignRef';
 
+/**
+ * Create a _lense_ on Ref, making it possible to transform ref value
+ * @param {ReactRef} ref
+ * @param {Function} transformer. 👉 Ref would be __NOT updated__ on `transformer` update.
+ * @returns {RefObject}
+ *
+ * @see https://github.com/theKashey/use-callback-ref#usetransformref-to-replace-reactuseimperativehandle
+ * @example
+ *
+ * const ResizableWithRef = forwardRef((props, ref) =>
+ *  <Resizable {...props} ref={useTransformRef(ref, i => i ? i.resizable : null)}/>
+ * );
+ */
 export function useTransformRef<T, K>(
   ref: ReactRef<K>,
   transformer: (original: T) => K

tsconfig.json

@@ -10,7 +10,6 @@
     "noImplicitReturns": true,
     "noFallthroughCasesInSwitch": true,
     "noImplicitAny": true,
-    "removeComments": true,
     "importHelpers": true,
     "target": "es2015",
     "lib": [