feat(hooks): Add hooks: useTransitionHook, useOnStateChanged, useCurrentStateAndParams

RawParams

Author: christopherthielen

src/components/hooks/__tests__/useCurrentStateAndParams.test.tsx

@@ -0,0 +1,74 @@
+import * as React from 'react';
+import { RawParams, StateDeclaration, StateService } from '@uirouter/core';
+import { UIRouterReact } from '../../../core';
+import { defer, makeTestRouter } from '../../__tests__/util';
+import { useCurrentStateAndParams } from '../useCurrentStateAndParams';
+
+const state1 = { name: 'state1', url: '/state1/:param', params: { param: null } };
+const state2 = { name: 'state2', url: '/state2/:param', params: { param: null } };
+
+describe('useCurrentStateAndParams', () => {
+  let router: UIRouterReact;
+  let routerGo: StateService['go'];
+  let mountInRouter;
+  let hookSpy = jest.fn();
+
+  function TestComponent({ spy }: { spy: (state: StateDeclaration, params: RawParams) => void }) {
+    const current = useCurrentStateAndParams();
+    spy(current.state, current.params);
+    return <div />;
+  }
+
+  beforeEach(() => {
+    ({ router, routerGo, mountInRouter } = makeTestRouter([state1, state2]));
+    hookSpy = jest.fn();
+    mountInRouter(<TestComponent spy={hookSpy} />);
+    hookSpy.mockReset();
+  });
+
+  it('returns the current state', async () => {
+    await routerGo('state1');
+    expect(hookSpy).toHaveBeenCalledTimes(1);
+    expect(hookSpy.mock.calls[0][0]).toBe(state1);
+  });
+
+  it('returns the current params', async () => {
+    await routerGo('state1', { param: '123' });
+    expect(hookSpy).toHaveBeenCalledTimes(1);
+    expect(hookSpy.mock.calls[0][1]).toEqual(expect.objectContaining({ param: '123' }));
+  });
+
+  it('returns the previous state until a pending transition is successful', async () => {
+    await routerGo('state1', { param: '123' });
+    expect(hookSpy).toHaveBeenCalledTimes(1);
+    expect(hookSpy).toHaveBeenCalledWith(expect.objectContaining({ name: 'state1' }), expect.anything());
+
+    const { promise, resolve } = defer();
+    router.transitionService.onStart({ to: 'state2' }, transition => promise);
+    const goPromise = routerGo('state2', { param: '456' });
+
+    expect(hookSpy).toHaveBeenCalledTimes(1);
+    resolve();
+    await goPromise;
+    expect(hookSpy).toHaveBeenCalledTimes(2);
+    expect(hookSpy).toHaveBeenCalledWith(expect.objectContaining({ name: 'state2' }), expect.anything());
+  });
+
+  it('returns the previous state if transition is unsuccessful', async () => {
+    await routerGo('state1', { param: '123' });
+    expect(hookSpy).toHaveBeenCalledTimes(1);
+    expect(hookSpy).toHaveBeenCalledWith(expect.objectContaining({ name: 'state1' }), expect.anything());
+
+    const { promise, reject } = defer();
+    router.transitionService.onStart({ to: 'state2' }, transition => promise);
+    const goPromise = routerGo('state2', { param: '456' });
+
+    expect(hookSpy).toHaveBeenCalledTimes(1);
+    try {
+      router.stateService.defaultErrorHandler(() => null);
+      reject();
+      await goPromise;
+    } catch (error) {}
+    expect(hookSpy).toHaveBeenCalledTimes(1);
+  });
+});

src/components/hooks/__tests__/useOnStateChanged.test.tsx

@@ -0,0 +1,70 @@
+import * as React from 'react';
+import { RawParams, StateDeclaration } from '@uirouter/core';
+import { defer, makeTestRouter } from '../../__tests__/util';
+import { useOnStateChanged } from '../useOnStateChanged';
+
+const state1 = { name: 'state1', url: '/state1/:param', params: { param: null } };
+const state2 = { name: 'state2', url: '/state2/:param', params: { param: null } };
+
+describe('useOnStateChanged', () => {
+  let { router, routerGo, mountInRouter } = makeTestRouter([]);
+  beforeEach(() => ({ router, routerGo, mountInRouter } = makeTestRouter([state1, state2])));
+  let hookSpy = jest.fn();
+
+  function TestComponent({ spy }: { spy: (state: StateDeclaration, params: RawParams) => void }) {
+    useOnStateChanged(spy);
+    return <div />;
+  }
+
+  beforeEach(() => {
+    hookSpy = jest.fn();
+    mountInRouter(<TestComponent spy={hookSpy} />);
+    hookSpy.mockReset();
+  });
+
+  it('returns the current state', async () => {
+    await router.stateService.go('state1');
+    expect(hookSpy).toHaveBeenCalledTimes(1);
+    expect(hookSpy.mock.calls[0][0]).toBe(state1);
+  });
+
+  it('returns the current params', async () => {
+    await router.stateService.go('state1', { param: '123' });
+    expect(hookSpy).toHaveBeenCalledTimes(1);
+    expect(hookSpy.mock.calls[0][1]).toEqual(expect.objectContaining({ param: '123' }));
+  });
+
+  it('returns the previous state until a pending transition is successful', async () => {
+    await router.stateService.go('state1', { param: '123' });
+    expect(hookSpy).toHaveBeenCalledTimes(1);
+    expect(hookSpy).toHaveBeenCalledWith(expect.objectContaining({ name: 'state1' }), expect.anything());
+
+    const { promise, resolve } = defer();
+    router.transitionService.onStart({ to: 'state2' }, transition => promise);
+    const goPromise = router.stateService.go('state2', { param: '456' });
+
+    expect(hookSpy).toHaveBeenCalledTimes(1);
+    resolve();
+    await goPromise;
+    expect(hookSpy).toHaveBeenCalledTimes(2);
+    expect(hookSpy).toHaveBeenCalledWith(expect.objectContaining({ name: 'state2' }), expect.anything());
+  });
+
+  it('returns the previous state if transition is unsuccessful', async () => {
+    await router.stateService.go('state1', { param: '123' });
+    expect(hookSpy).toHaveBeenCalledTimes(1);
+    expect(hookSpy).toHaveBeenCalledWith(expect.objectContaining({ name: 'state1' }), expect.anything());
+
+    const { promise, reject } = defer();
+    router.transitionService.onStart({ to: 'state2' }, transition => promise);
+    const goPromise = router.stateService.go('state2', { param: '456' });
+
+    expect(hookSpy).toHaveBeenCalledTimes(1);
+    try {
+      router.stateService.defaultErrorHandler(() => null);
+      reject();
+      await goPromise;
+    } catch (error) {}
+    expect(hookSpy).toHaveBeenCalledTimes(1);
+  });
+});

src/components/hooks/__tests__/useUiSref.test.tsx renamed to src/components/hooks/__tests__/useSref.test.tsx

@@ -0,0 +1,59 @@
+import * as React from 'react';
+import { mount } from 'enzyme';
+import { useStableCallback } from '../useStableCallback';
+
+describe('useStableCallback', () => {
+  function TestComponent({ prop = 'prop', spy }: { prop?: any; spy: any }) {
+    const unstableCallback = () => prop;
+    const stableCallback = useStableCallback(unstableCallback);
+    spy(unstableCallback, stableCallback);
+    return <div />;
+  }
+
+  it('returns the same stable callback reference over multiple renders', async () => {
+    const spy = jest.fn();
+    const wrapper = mount(<TestComponent spy={spy} />);
+    wrapper.setProps({ prop: 'newvalue' });
+    wrapper.setProps({ prop: 'nextvalue' });
+    expect(spy).toHaveBeenCalledTimes(3);
+
+    const stableArg1 = spy.mock.calls[0][1];
+    const stableArg2 = spy.mock.calls[1][1];
+    const stableArg3 = spy.mock.calls[2][1];
+
+    expect(stableArg1).toBe(stableArg2);
+    expect(stableArg1).toBe(stableArg3);
+    expect(stableArg2).toBe(stableArg3);
+  });
+
+  it('returns the most recent unstable callback reference over multiple renders', async () => {
+    const spy = jest.fn();
+    const wrapper = mount(<TestComponent spy={spy} />);
+    wrapper.setProps({ prop: 'newvalue' });
+    wrapper.setProps({ prop: 'nextvalue' });
+    expect(spy).toHaveBeenCalledTimes(3);
+
+    const stableArg1 = spy.mock.calls[0][0];
+    const stableArg2 = spy.mock.calls[1][0];
+    const stableArg3 = spy.mock.calls[2][0];
+
+    expect(stableArg1.name).toBe('unstableCallback');
+    expect(stableArg2.name).toBe('unstableCallback');
+    expect(stableArg3.name).toBe('unstableCallback');
+
+    expect(stableArg1).not.toBe(stableArg2);
+    expect(stableArg1).not.toBe(stableArg3);
+    expect(stableArg2).not.toBe(stableArg3);
+  });
+
+  it('allows a stable callback reference to access the latest render closure values', async () => {
+    const spy = jest.fn();
+    const wrapper = mount(<TestComponent spy={spy} />);
+    wrapper.setProps({ prop: 'newvalue' });
+    wrapper.setProps({ prop: 'nextvalue' });
+    expect(spy).toHaveBeenCalledTimes(3);
+
+    const stableArg3 = spy.mock.calls[2][0];
+    expect(stableArg3()).toBe('nextvalue');
+  });
+});

src/components/hooks/__tests__/useStableCallback.test.tsx

@@ -0,0 +1,35 @@
+import * as React from 'react';
+import { makeTestRouter } from '../../__tests__/util';
+import { useTransitionHook } from '../useTransitionHook';
+
+describe('useRouterHook', () => {
+  let { router, routerGo, mountInRouter } = makeTestRouter([]);
+  beforeEach(() => ({ router, routerGo, mountInRouter } = makeTestRouter([])));
+
+  it('registers with the correct transitionService hook on mount', async () => {
+    function TestComponent() {
+      useTransitionHook('onBefore', {}, () => null);
+      return <div />;
+    }
+
+    jest.spyOn(router.transitionService, 'onBefore');
+    mountInRouter(<TestComponent />);
+    expect(router.transitionService.onBefore).toHaveBeenCalledTimes(1);
+  });
+
+  it('de-registers the hook on unmount', async () => {
+    function TestComponent() {
+      useTransitionHook('onBefore', {}, () => null);
+      return <div />;
+    }
+
+    const deregisterSpy = jest.fn();
+    jest.spyOn(router.transitionService, 'onBefore').mockImplementation(() => deregisterSpy);
+    const wrapper = mountInRouter(<TestComponent />);
+    expect(router.transitionService.onBefore).toHaveBeenCalledTimes(1);
+    expect(deregisterSpy).not.toHaveBeenCalled();
+
+    wrapper.unmount();
+    expect(deregisterSpy).toHaveBeenCalled();
+  });
+});

src/components/hooks/__tests__/useTransitionHook.test.tsx

@@ -1,3 +1,6 @@
 export * from './useCurrentStateAndParams';
+export * from './useOnStateChanged';
 export * from './useRouter';
 export * from './useSref';
+export * from './useStableCallback';
+export * from './useTransitionHook';

src/components/hooks/index.ts

@@ -1,20 +1,17 @@
-import { StateParams } from '@uirouter/core';
-import { useEffect, useState } from 'react';
+import { useState } from 'react';
+import { RawParams, StateDeclaration } from '@uirouter/core';
+import { useOnStateChanged } from './useOnStateChanged';
 import { useRouter } from './useRouter';
 
-export function useCurrentStateAndParams() {
-  const uiRouter = useRouter();
-  const { globals } = uiRouter;
-  const [stateData, setStateData] = useState({ state: globals.current, params: globals.params });
-
-  useEffect(() => {
-    const deregister = uiRouter.transitionService.onSuccess({}, transition => {
-      const state = transition.to();
-      const params = transition.params('to') as StateParams;
-      setStateData({ state, params });
-    });
-    return () => deregister();
-  }, [uiRouter]);
+/**
+ * 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.
+ */
+export function useCurrentStateAndParams(): { state: StateDeclaration; params: RawParams } {
+  const globals = useRouter().globals;
+  const [stateData, setStateData] = useState({ state: globals.current, params: globals.params as RawParams });
+  useOnStateChanged((state, params) => setStateData({ state, params }));
 
   return stateData;
 }

src/components/hooks/useCurrentStateAndParams.ts

@@ -0,0 +1,6 @@
+import { RawParams, StateDeclaration } from '@uirouter/core';
+import { useTransitionHook } from './useTransitionHook';
+
+export function useOnStateChanged(onStateChangedCallback: (state: StateDeclaration, params: RawParams) => void) {
+  useTransitionHook('onSuccess', {}, trans => onStateChangedCallback(trans.to(), trans.params('to')));
+}

src/components/hooks/useOnStateChanged.ts

@@ -0,0 +1,26 @@
+import { useCallback, useRef } from 'react';
+
+/**
+ * Returns a stabilized callback reference which delegates to the most recent unstable callback
+ *
+ * This is similar to useCallback, but allows unstableCallback to access the most recent values from the closure.
+ * This can be useful if the callback is being stored long term, such as in the Transition Hook registry.
+ *
+ * Example:
+ * ```
+ * const latestValueFromProps = props.value
+ * const transitionHook = useStableCallback(() => console.log(latestValueFromProps));
+ * useEffect(() => {
+ *   const deregister = transitionService.onBefore({ exiting: 'someState' }, transitionHook);
+ *   return () => deregister();
+ * }, []);
+ * ```
+ */
+
+export function useStableCallback<T extends Function>(unstableCallback: T): T {
+  const ref = useRef<T>(unstableCallback);
+  const callback = useCallback(function() {
+    return ref.current && ref.current.apply(this, arguments);
+  }, []);
+  return (callback as unknown) as T;
+}

src/components/hooks/useStableCallback.ts

@@ -0,0 +1,32 @@
+import { curry, HookFn, StateParams, TransitionService, TransitionStateHookFn } from '@uirouter/core';
+import { HookMatchCriteria, HookRegOptions, TransitionHookFn } from '@uirouter/core/lib/transition/interface';
+import { useEffect, useState } from 'react';
+import { useRouter } from './useRouter';
+
+type HookName = 'onBefore' | 'onStart' | 'onSuccess' | 'onError' | 'onSuccess' | 'onFinish';
+type StateHookName = 'onEnter' | 'onRetain' | 'onExit';
+
+export function useTransitionHook(
+  hookName: HookName,
+  criteria: HookMatchCriteria,
+  callback: TransitionHookFn,
+  options?: HookRegOptions
+);
+export function useTransitionHook(
+  hookName: StateHookName,
+  criteria: HookMatchCriteria,
+  callback: TransitionStateHookFn,
+  options?: HookRegOptions
+);
+export function useTransitionHook(
+  hookRegistrationFn: HookName | StateHookName,
+  criteria: HookMatchCriteria,
+  callback: TransitionHookFn | TransitionStateHookFn,
+  options?: HookRegOptions
+) {
+  const { transitionService } = useRouter();
+  useEffect(() => {
+    const deregister = transitionService[hookRegistrationFn](criteria, callback as any, options);
+    return () => deregister();
+  }, [transitionService, hookRegistrationFn]);
+}