docs(hooks): Add basic docs and examples for the new hooks api

Author: christopherthielen

src/hooks/index.ts

@@ -1,3 +1,11 @@
+/**
+ * ## UI-Router React Hooks
+ *
+ * This is a collection of [react hooks](https://reactjs.org/docs/hooks-intro.html)
+ * that can be used in functional components.
+ *
+ * @packageDocumentation @preferred @module react_hooks
+ */
 export { useCurrentStateAndParams } from './useCurrentStateAndParams';
 export { useOnStateChanged } from './useOnStateChanged';
 export { useRouter } from './useRouter';

src/hooks/useCurrentStateAndParams.ts

@@ -1,12 +1,21 @@
+/** @packageDocumentation @reactapi @module react_hooks */
 import { useState } from 'react';
 import { RawParams, StateDeclaration } from '@uirouter/core';
 import { useOnStateChanged } from './useOnStateChanged';
 import { useRouter } from './useRouter';
 
 /**
- * Returns the current state and parameter values.
+ * A hook that returns the current state and parameter values.
  *
  * Each time the current state or parameter values change, the component will re-render with the new values.
+ *
+ * Example:
+ * ```jsx
+ * function CurrentState() {
+ *   const { state, params } = useCurrentStateAndParams();
+ *   return <span>{state.name} ({JSON.stringify(params)})</span>;
+ * }
+ * ```
  */
 export function useCurrentStateAndParams(): { state: StateDeclaration; params: RawParams } {
   const globals = useRouter().globals;

src/hooks/useDeepObjectDiff.ts

@@ -1,3 +1,4 @@
+/** @packageDocumentation @internalapi @module react_hooks */
 import { equals } from '@uirouter/core';
 import { useRef } from 'react';
 

src/hooks/useIsActive.ts

@@ -1,3 +1,5 @@
+/** @packageDocumentation @reactapi @module react_hooks */
+
 import { StateDeclaration } from '@uirouter/core';
 import { useEffect, useMemo, useState } from 'react';
 import { UIRouterReact } from '../core';
@@ -6,6 +8,7 @@ import { useOnStateChanged } from './useOnStateChanged';
 import { useRouter } from './useRouter';
 import { useViewContextState } from './useViewContextState';
 
+/** @hidden */
 function checkIfActive(
   router: UIRouterReact,
   stateName: string,
@@ -18,6 +21,32 @@ function checkIfActive(
     : router.stateService.includes(stateName, params, { relative });
 }
 
+/**
+ * A hook that returns true if a given state is active.
+ *
+ * Example:
+ * ```jsx
+ * function ContactsLabel() {
+ *  const isActive = useIsActive('contacts');
+ *  return <span className={isActive ? 'active' : 'inactive'}>Contacts></span>
+ * }
+ * ```
+ *
+ * Example:
+ * ```jsx
+ * function JoeLabel() {
+ *  const isActive = useIsActive('contacts.contact', { contactId: 'joe' });
+ *  return <span className={isActive ? 'active' : 'inactive'}>Joe></span>
+ * }
+ * ```
+ *
+ * @param stateName the name of the state to check.
+ *        Relative state names such as '.child' are supported.
+ *        Relative states are resolved relative to the state that rendered the hook.
+ * @param params if present, the hook will only return true if all the provided parameter values match.
+ * @param exact when true, the hook returns true only when the state matches exactly.
+ *        when false, returns true if the state matches, or any child state matches.
+ */
 export function useIsActive(stateName: string, params = null, exact = false) {
   const router = useRouter();
   const relative = useViewContextState(router);

src/hooks/useOnStateChanged.ts

@@ -1,6 +1,24 @@
+/** @packageDocumentation @reactapi @module react_hooks */
+
 import { RawParams, StateDeclaration } from '@uirouter/core';
 import { useTransitionHook } from './useTransitionHook';
 
+/**
+ * A hook that invokes the provided callback whenever the current state changes.
+ *
+ * The callback receives the [[StateDeclaration]] and parameter values of the new current state.
+ *
+ * Example:
+ * ```jsx
+ * function ShowCurrentState() {
+ *   const [routerState, setRouterState] = useState('');
+ *   useOnStateChanged((state) => setState(state.name);
+ *   return <span>{routerState ? `state changed to ${routerState}` : null}</span>
+ * }
+ * ```
+ *
+ * @param onStateChangedCallback a callback that receives the new current state and parameter values
+ */
 export function useOnStateChanged(onStateChangedCallback: (state: StateDeclaration, params: RawParams) => void) {
   useTransitionHook('onSuccess', {}, trans => onStateChangedCallback(trans.to(), trans.params('to')));
 }

src/hooks/useRouter.ts

@@ -1,11 +1,30 @@
+/** @packageDocumentation @reactapi @module react_hooks */
+
 import { useContext } from 'react';
 import { UIRouterReact } from '../core';
 import { UIRouterContext } from '../components/UIRouter';
 
 /** @hidden */
 export const UIRouterInstanceUndefinedError = `UIRouter instance is undefined. Did you forget to include the <UIRouter> as root component?`;
 
-/** Returns the UIRouter object from React Context */
+/**
+ * A hook that returns the UIRouter instance
+ *
+ * Example:
+ * ```jsx
+ * const FormSubmit() {
+ *   const router = useRouter();
+ *   const form = useContext(FormFromContext);
+ *   function submit() {
+ *     validateForm(form)
+ *       .then(submitForm)
+ *       .then(() => router.stateService.go('home'));
+ *   }
+ *
+ *   return <button onClick={submit}>Submit form</button>;
+ * }
+ * ```
+ */
 export function useRouter(): UIRouterReact {
   const router = useContext(UIRouterContext);
   if (!router) {

src/hooks/useSref.ts

@@ -1,3 +1,5 @@
+/** @packageDocumentation @reactapi @module react_hooks */
+
 import * as React from 'react';
 import { useCallback, useContext, useEffect, useMemo, useState } from 'react';
 import { isString, StateDeclaration, TransitionOptions } from '@uirouter/core';
@@ -15,15 +17,15 @@ export interface LinkProps {
 /** @hidden */
 export const IncorrectStateNameTypeError = `The state name passed to useSref must be a string.`;
 
-/** Gets all StateDeclarations that are registered in the StateRegistry. */
+/** @hidden Gets all StateDeclarations that are registered in the StateRegistry. */
 function useListOfAllStates(router: UIRouterReact) {
   const initial = useMemo(() => router.stateRegistry.get(), []);
   const [states, setStates] = useState(initial);
   useEffect(() => router.stateRegistry.onStatesChanged(() => setStates(router.stateRegistry.get())), []);
   return states;
 }
 
-/** Gets the StateDeclaration that this sref targets */
+/** @hidden Gets the StateDeclaration that this sref targets */
 function useTargetState(router: UIRouterReact, stateName: string, context: StateDeclaration): StateDeclaration {
   // Whenever any states are added/removed from the registry, get the target state again
   const allStates = useListOfAllStates(router);
@@ -33,13 +35,35 @@ function useTargetState(router: UIRouterReact, stateName: string, context: State
 }
 
 /**
- * A hook that helps create link to a state.
+ * A hook to create a link to a state.
+ *
+ * This hook returns link (anchor tag) props for a given state reference.
+ * The resulting props can be spread onto an anchor tag.
+ *
+ * The props returned from this hook are:
+ *
+ * - `href`: the browser URL of the referenced state
+ * - `onClick`: a mouse event handler that will active the referenced state
+ *
+ * Example:
+ * ```jsx
+ * function HomeLink() {
+ *   const sref = useSref('home');
+ *   return <a {...sref}>Home</a>
+ * }
+ * ```
  *
- * This hook returns data for an sref (short for state reference)
+ * Example:
+ * ```jsx
+ * function UserLink({ userId, username }) {
+ *   const sref = useSref('users.user', { userId: userId });
+ *   return <a {...sref}>{username}</a>
+ * }
+ * ```
  *
  * @param stateName The name of the state to link to
  * @param params Any parameter values
- * @param options Transition options
+ * @param options Transition options used when the onClick handler fires.
  */
 export function useSref(stateName: string, params: object = {}, options: TransitionOptions = {}): LinkProps {
   if (!isString(stateName)) {

src/hooks/useSrefActive.ts

@@ -1,3 +1,5 @@
+/** @packageDocumentation @reactapi @module react_hooks */
+
 import { TransitionOptions } from '@uirouter/core';
 import { LinkProps, useSref } from './useSref';
 import { useIsActive } from './useIsActive';
@@ -7,26 +9,40 @@ interface ActiveLinkProps extends LinkProps {
 }
 
 /**
- * A hook that helps create link to a state and tracks if that state is active.
+ * A hook to create a link to a state and track its active status.
  *
- * This hook returns an object the following properties of an sref (short for state reference).
+ * This hook returns link (anchor tag) props for a given state reference.
+ * The resulting props can be spread onto an anchor tag.
+ * If the referenced state (and params) is active, then the activeClass is returned as the `className` prop.
  *
- * - href: the browser URL of the referenced state
- * - onClick: a mouse event handler that will active the referenced state
- * - className: the activeClass parameter when the state or any child state is active, otherwise an empty string
+ * The props returned from this hook are:
  *
- * Example
- * ```
- * function LinkToHome() {
- *   const sref = useSrefActive('home', null, 'active');
+ * - `href`: the browser URL of the referenced state
+ * - `onClick`: a mouse event handler that will active the referenced state
+ * - `className`: the activeClass parameter when the state (or any child state) is active, otherwise an empty string
+ *
+ * Example:
+ * ```jsx
+ * function HomeLink() {
+ *   const sref = useSref('home', null, 'active');
  *   return <a {...sref}>Home</a>
  * }
  * ```
  *
+ * Example:
+ * ```jsx
+ * function UserLink({ userId, username }) {
+ *   const sref = useSref('users.user', { userId: userId }, 'active');
+ *   return <a {...sref}>{username}</a>
+ * }
+ * ```
+ *
+ * This hook is a variation of the [[useSref]] hook.
+ *
  * @param stateName The name of the state to link to
  * @param params Any parameter values
  * @param activeClass A css class string to use when the state is active
- * @param options Transition options
+ * @param options Transition options used when the onClick handler fires.
  */
 export function useSrefActive(
   stateName: string,

src/hooks/useSrefActiveExact.ts

@@ -1,3 +1,5 @@
+/** @packageDocumentation @reactapi @module react_hooks */
+
 import { TransitionOptions } from '@uirouter/core';
 import { LinkProps, useSref } from './useSref';
 import { useIsActive } from './useIsActive';
@@ -7,26 +9,41 @@ interface ActiveLinkProps extends LinkProps {
 }
 
 /**
- * A hook that helps create link to a state and tracks if that state is active.
+ * A hook to create a link to a state and track its active status.
  *
- * This hook returns an object the following properties of an sref (short for state reference).
+ * This hook returns link (anchor tag) props for a given state reference.
+ * The resulting props can be spread onto an anchor tag.
+ * If the referenced state (and params) is active, then the activeClass is returned as the `className` prop.
  *
- * - href: the browser URL of the referenced state
- * - onClick: a mouse event handler that will active the referenced state
- * - className: the activeClass parameter when the state is active, otherwise an empty string
+ * The props returned from this hook are:
  *
- * Example
- * ```
- * function LinkToHome() {
- *   const sref = useSrefActive('home', null, 'active');
+ * - `href`: the browser URL of the referenced state
+ * - `onClick`: a mouse event handler that will active the referenced state
+ * - `className`: the activeClass parameter when the state is active, otherwise an empty string
+ *
+ * Example:
+ * ```jsx
+ * function HomeLink() {
+ *   const sref = useSref('home', null, 'active');
  *   return <a {...sref}>Home</a>
  * }
  * ```
  *
+ * Example:
+ * ```jsx
+ * function UserLink({ userId, username }) {
+ *   const sref = useSref('users.user', { userId: userId }, 'active');
+ *   return <a {...sref}>{username}</a>
+ * }
+ * ```
+ *
+ * This hook is a variation of the [[useSrefActive]] hook.
+ * This variation does not render the `activeClass` if a child state is active.
+ *
  * @param stateName The name of the state to link to
  * @param params Any parameter values
  * @param activeClass A css class string to use when the state is active
- * @param options Transition options
+ * @param options Transition options used when the onClick handler fires.
  */
 export function useSrefActiveExact(
   stateName: string,

src/hooks/useStableCallback.ts

@@ -1,3 +1,5 @@
+/** @packageDocumentation @internalapi @module react_hooks */
+
 import { useCallback, useRef } from 'react';
 
 /**
@@ -7,7 +9,7 @@ import { useCallback, useRef } from 'react';
  * This can be useful if the callback is being stored long term, such as in the Transition Hook registry.
  *
  * Example:
- * ```
+ * ```jsx
  * const latestValueFromProps = props.value
  * const transitionHook = useStableCallback(() => console.log(latestValueFromProps));
  * useEffect(() => {