feat(hooks): Add useCanExit hook to block transitions from exiting a state

Author: christopherthielen

src/hooks/__tests__/useCanExit.test.tsx

@@ -0,0 +1,126 @@
+import * as React from 'react';
+import { TransitionHookFn } from '@uirouter/core';
+import { makeTestRouter } from '../../__tests__/util';
+import { UIView } from '../../components';
+import { ReactStateDeclaration } from '../../interface';
+import { useCanExit } from '../useCanExit';
+
+const state1 = { name: 'state1', url: '/state1', component: UIView };
+
+function TestComponent({ callback }: { callback: TransitionHookFn }) {
+  useCanExit(callback);
+  return <div />;
+}
+
+describe('useCanExit', () => {
+  let { router, routerGo, mountInRouter } = makeTestRouter([]);
+  beforeEach(() => ({ router, routerGo, mountInRouter } = makeTestRouter([state1])));
+
+  async function registerAndGo(state: ReactStateDeclaration) {
+    router.stateRegistry.register(state);
+    await routerGo(state);
+  }
+
+  it('can block a transition that exits the state it was used in', async () => {
+    const callback = jest.fn(() => false);
+    await registerAndGo({ name: 'state2', component: () => <TestComponent callback={callback} /> });
+    mountInRouter(<UIView />);
+    expect(routerGo('state1')).rejects.toMatchObject({
+      message: 'The transition has been aborted',
+    });
+    expect(callback).toHaveBeenCalled();
+    expect(router.globals.current.name).toBe('state2');
+  });
+
+  it('can block a transition using a Promise that resolves to false', async () => {
+    const callback = jest.fn(() => Promise.resolve(false));
+    await registerAndGo({ name: 'state2', component: () => <TestComponent callback={callback} /> });
+    mountInRouter(<UIView />);
+    expect(routerGo('state1')).rejects.toMatchObject({
+      message: 'The transition has been aborted',
+    });
+    expect(callback).toHaveBeenCalled();
+    expect(router.globals.current.name).toBe('state2');
+  });
+
+  it('can allow a transition using a Promise that resolves to true', async () => {
+    const callback = jest.fn(() => Promise.resolve(true));
+    await registerAndGo({ name: 'state2', component: () => <TestComponent callback={callback} /> });
+    mountInRouter(<UIView />);
+    await routerGo('state1');
+    expect(router.globals.current.name).toBe('state1');
+  });
+
+  it('can allow a transition using a Promise that resolves to undefined', async () => {
+    const callback = jest.fn(() => Promise.resolve(undefined));
+    await registerAndGo({ name: 'state2', component: () => <TestComponent callback={callback} /> });
+    mountInRouter(<UIView />);
+    await routerGo('state1');
+    expect(router.globals.current.name).toBe('state1');
+  });
+
+  it('can allow a transition that exits the state it was used in', async () => {
+    const callback = jest.fn(() => true);
+    await registerAndGo({ name: 'state2', component: () => <TestComponent callback={callback} /> });
+    mountInRouter(<UIView />);
+    await routerGo('state1');
+    expect(callback).toHaveBeenCalled();
+    expect(router.globals.current.name).toBe('state1');
+  });
+
+  it('can block a transition that goes to the parent state', async () => {
+    const callback = jest.fn(() => false);
+    await registerAndGo({ name: 'state1.child', component: () => <TestComponent callback={callback} /> });
+    mountInRouter(<UIView />);
+    expect(routerGo('state1')).rejects.toMatchObject({
+      message: 'The transition has been aborted',
+    });
+    expect(callback).toHaveBeenCalled();
+    expect(router.globals.current.name).toBe('state1.child');
+  });
+
+  it('does not block a transition which retains (does not exit) the state the hook was used in', async () => {
+    const callback = jest.fn(() => false);
+    const state2Component = () => (
+      <>
+        <TestComponent callback={callback} />
+        <UIView />
+      </>
+    );
+
+    // hook used in state2
+    router.stateRegistry.register({ name: 'state2', component: state2Component } as ReactStateDeclaration);
+    router.stateRegistry.register({ name: 'state2.child', component: () => <div /> } as ReactStateDeclaration);
+
+    await routerGo('state2.child');
+    mountInRouter(<UIView />);
+    // exit state2.child but retain state2
+    await routerGo('state2');
+
+    expect(callback).not.toHaveBeenCalled();
+    expect(router.globals.current.name).toBe('state2');
+  });
+
+  describe('implementation detail', () => {
+    it('registers an onBefore transition hook', async () => {
+      const callback = () => true;
+      await registerAndGo({ name: 'state2', component: () => <TestComponent callback={callback} /> });
+      const spy = jest.spyOn(router.transitionService, 'onBefore');
+      mountInRouter(<UIView />);
+      expect(spy).toHaveBeenCalledTimes(1);
+      expect(spy).toHaveBeenCalledWith({ exiting: 'state2' }, expect.any(Function), undefined);
+    });
+
+    it('deregisters the onBefore transition hook when unmounted', async () => {
+      const deregisterSpy = jest.fn();
+      await registerAndGo({ name: 'state2', component: () => <TestComponent callback={() => true} /> });
+      jest.spyOn(router.transitionService, 'onBefore').mockImplementation(() => deregisterSpy);
+      mountInRouter(<UIView />);
+      expect(deregisterSpy).toHaveBeenCalledTimes(0);
+
+      await routerGo('state1');
+      expect(router.globals.current.name).toBe('state1');
+      expect(deregisterSpy).toHaveBeenCalledTimes(1);
+    });
+  });
+});

src/hooks/useCanExit.ts

@@ -0,0 +1,48 @@
+/** @packageDocumentation @reactapi @module react_hooks */
+
+import { HookRegOptions, TransitionHookFn } from '@uirouter/core';
+import { useParentView } from './useParentView';
+import { useTransitionHook } from './useTransitionHook';
+
+/**
+ * A hook that can stop the router from exiting the state the hook is used in.
+ *
+ * This hook can be used to check preconditions before the router is allowed exit the state that the hook was used in.
+ * If the hook returns true/undefined (or a Promise that resolves to true/undefined), the Transition will be allowed to continue.
+ * If the hook returns false (or a Promise that resolves to false), the Transition will be cancelled.
+ *
+ * For example, you may use the hook in an edit screen.
+ * If the user navigates to a different state which would exit the edit screen,
+ * you may check for unsaved data and prompt for confirmation.
+ *
+ * Example:
+ * ```jsx
+ * function EditScreen(props) {
+ *  const [initialValue, setInitialValue] = useState(props.initialValue);
+ *  const [value, setValue] = useState(initialValue);
+ *  const isDirty = useMemo(() => value !== initialValue, [value, initialValue]);
+ *
+ *  async function save() {
+ *    await saveValue(value);
+ *    setInitialValue(value); // reset initial value to current value
+ *  }
+ *
+ *  useCanExit(() => {
+ *    return isDirty ? window.confirm('Input is not saved. Are you sure you want to leave?') : true;
+ *  });
+ *
+ *  return <div> <input type="text" value={value} onChange={setValue} /> <button onClick={save}>Save</button> </div>
+ * }
+ * ```
+ *
+ * Note that this hook adds a transition hook with [[HookMatchCriteria]] of ```{ exiting: thisState }```
+ * where `thisState` is the state that the hook was rendered in.
+ * See also: [[TransitionHookFn]]
+ *
+ * @param canExitCallback a callback that returns true/false, or a Promise for a true/false
+ * @param options transition hook registration options
+ */
+export function useCanExit(canExitCallback: TransitionHookFn, options?: HookRegOptions) {
+  const stateName = useParentView().context.name;
+  useTransitionHook('onBefore', { exiting: stateName }, canExitCallback, options);
+}