Add new hooks used in migrating Fabric components to functional components

.vscode/launch.json

@@ -27,7 +27,7 @@
       "stopOnEntry": false,
       "args": ["-i", "--testPathPattern=\\b${fileBasenameNoExtension}", "--watch"],
       "runtimeExecutable": null,
-      "runtimeArgs": ["--nolazy", "--debug"],
+      "runtimeArgs": ["--nolazy", "--inspect"],
       "env": {
         "NODE_ENV": "development"
       },

change/@uifabric-react-hooks-2020-04-09-17-52-46-functional-hooks.json

@@ -0,0 +1,9 @@
+{
+  "type": "minor",
+  "comment": "Add new hooks used in migrating Fabric components to functional components",
+  "packageName": "@uifabric/react-hooks",
+  "email": "[email protected]",
+  "commit": "42e75e0c956a1d2afb40f0cb0147c31156ea3ae0",
+  "dependentChangeType": "patch",
+  "date": "2020-04-09T17:52:46.940Z"
+}

packages/react-hooks/etc/react-hooks.api.md

@@ -4,6 +4,8 @@
 
 ```ts
 
+import * as React from 'react';
+
 // @public
 export interface IUseBooleanCallbacks {
     setFalse: () => void;
@@ -21,7 +23,18 @@ export function useConst<T>(initialValue: T | (() => T)): T;
 export function useConstCallback<T extends (...args: any[]) => any>(callback: T): T;
 
 // @public
-export function useId(prefix?: string): string;
+export function useControllableValue<TValue, TElement extends HTMLElement>(controlledValue: TValue | undefined, defaultUncontrolledValue: TValue | undefined): Readonly<[TValue | undefined, (newValue: TValue | undefined) => void]>;
+
+// Warning: (ae-forgotten-export) The symbol "ChangeCallback" needs to be exported by the entry point index.d.ts
+//
+// @public (undocumented)
+export function useControllableValue<TValue, TElement extends HTMLElement, TCallback extends ChangeCallback<TElement, TValue> | undefined>(controlledValue: TValue | undefined, defaultUncontrolledValue: TValue | undefined, onChange: TCallback): Readonly<[TValue | undefined, (newValue: TValue | undefined, ev: React.FormEvent<TElement>) => void]>;
+
+// @public
+export function useId(prefix?: string, providedId?: string): string;
+
+// @public
+export function useMergedRefs<T>(...refs: React.Ref<T>[]): (value: T) => void;
 
 
 // (No @packageDocumentation comment for this package)

packages/react-hooks/src/index.ts

@@ -3,3 +3,5 @@ export * from './useBoolean';
 export * from './useConst';
 export * from './useConstCallback';
 export * from './useId';
+export * from './useMergedRefs';
+export * from './useControllableValue';

packages/react-hooks/src/useControllableValue.test.tsx

@@ -0,0 +1,76 @@
+import * as React from 'react';
+import { mount } from 'enzyme';
+import { useControllableValue } from './useControllableValue';
+
+describe('useControllableValue', () => {
+  it('respects controlled value', () => {
+    let resultValue: boolean | undefined;
+    const TestComponent: React.FunctionComponent<{ value?: boolean; defaultValue?: boolean }> = ({
+      value,
+      defaultValue,
+    }) => {
+      [resultValue] = useControllableValue(value, defaultValue);
+      return <div />;
+    };
+
+    const wrapper1 = mount(<TestComponent value={true} />);
+    expect(resultValue!).toBe(true);
+
+    wrapper1.setProps({ value: false });
+    expect(resultValue!).toBe(false);
+
+    const wrapper2 = mount(<TestComponent value={false} defaultValue={true} />);
+    expect(resultValue!).toBe(false);
+
+    wrapper2.setProps({ value: true });
+    expect(resultValue!).toBe(true);
+  });
+
+  it('uses the default value if no controlled value is provided', () => {
+    let resultValue: boolean | undefined;
+    const TestComponent: React.FunctionComponent<{ value?: boolean; defaultValue?: boolean }> = ({
+      value,
+      defaultValue,
+    }) => {
+      [resultValue] = useControllableValue(value, defaultValue);
+      return <div />;
+    };
+
+    mount(<TestComponent defaultValue={true} />);
+    expect(resultValue!).toBe(true);
+  });
+
+  it('uses an updated controlled value over a default value', () => {
+    let resultValue: boolean | undefined;
+    const TestComponent: React.FunctionComponent<{ value?: boolean; defaultValue?: boolean }> = ({
+      value,
+      defaultValue,
+    }) => {
+      [resultValue] = useControllableValue(value, defaultValue);
+      return <div />;
+    };
+
+    const wrapper = mount(<TestComponent defaultValue={true} />);
+    expect(resultValue!).toBe(true);
+
+    wrapper.setProps({ value: false, defaultValue: true });
+    expect(resultValue!).toBe(false);
+  });
+
+  it('does not change value when the default value changes', () => {
+    let resultValue: boolean | undefined;
+    const TestComponent: React.FunctionComponent<{ value?: boolean; defaultValue?: boolean }> = ({
+      value,
+      defaultValue,
+    }) => {
+      [resultValue] = useControllableValue(value, defaultValue);
+      return <div />;
+    };
+
+    const wrapper = mount(<TestComponent defaultValue={true} />);
+    expect(resultValue!).toBe(true);
+
+    wrapper.setProps({ defaultValue: false });
+    expect(resultValue!).toBe(true);
+  });
+});

packages/react-hooks/src/useControllableValue.ts

@@ -0,0 +1,51 @@
+import * as React from 'react';
+
+type ChangeCallback<TElement extends HTMLElement, TValue> = (
+  ev: React.FormEvent<TElement>,
+  newValue: TValue | undefined,
+) => void;
+
+/**
+ * Hook to manage a value that could be either controlled or uncontrolled, such as a checked state or
+ * text box string.
+ * @param controlledValue- The controlled value passed in the props. This value will always be used if provided, and the
+ * internal state will be updated to reflect it.
+ * @param defaultUncontrolledValue- Initial value for the internal state in the uncontrolled case.
+ * @see https://reactjs.org/docs/uncontrolled-components.html
+ */
+export function useControllableValue<TValue, TElement extends HTMLElement>(
+  controlledValue: TValue | undefined,
+  defaultUncontrolledValue: TValue | undefined,
+): Readonly<[TValue | undefined, (newValue: TValue | undefined) => void]>;
+export function useControllableValue<
+  TValue,
+  TElement extends HTMLElement,
+  TCallback extends ChangeCallback<TElement, TValue> | undefined
+>(
+  controlledValue: TValue | undefined,
+  defaultUncontrolledValue: TValue | undefined,
+  onChange: TCallback,
+): Readonly<[TValue | undefined, (newValue: TValue | undefined, ev: React.FormEvent<TElement>) => void]>;
+export function useControllableValue<
+  TValue,
+  TElement extends HTMLElement,
+  TCallback extends ChangeCallback<TElement, TValue> | undefined
+>(controlledValue: TValue | undefined, defaultUncontrolledValue: TValue | undefined, onChange?: TCallback) {
+  const [value, setValue] = React.useState<TValue | undefined>(
+    controlledValue !== undefined ? controlledValue : defaultUncontrolledValue,
+  );
+
+  const setValueOrCallOnChange = React.useCallback(
+    (newValue: TValue | undefined, ev?: React.FormEvent<TElement>) => {
+      if (onChange) {
+        onChange(ev!, newValue);
+      }
+      if (controlledValue === undefined) {
+        setValue(newValue);
+      }
+    },
+    [onChange, controlledValue === undefined],
+  );
+
+  return [controlledValue !== undefined ? controlledValue : value, setValueOrCallOnChange] as const;
+}

packages/react-hooks/src/useId.ts

@@ -5,12 +5,14 @@ import { getId } from '@uifabric/utilities/lib/getId';
  * Hook to generate a unique ID in the global scope (spanning across duplicate copies of the same library).
  *
  * @param prefix - Optional prefix for the ID
+ * @param providedId - Optional id provided by a parent component. Defaults to the provided value if present,
+ *  without conditioning the hook call
  * @returns The ID
  */
-export function useId(prefix?: string): string {
+export function useId(prefix?: string, providedId?: string): string {
   // getId should only be called once since it updates the global constant for the next ID value.
   // (While an extra update isn't likely to cause problems in practice, it's better to avoid it.)
-  const ref = React.useRef<string>();
+  const ref = React.useRef<string | undefined>(providedId);
   if (!ref.current) {
     ref.current = getId(prefix);
   }

packages/react-hooks/src/useMergedRefs.test.tsx

@@ -0,0 +1,65 @@
+import * as React from 'react';
+import { mount } from 'enzyme';
+import { useMergedRefs } from './useMergedRefs';
+
+describe('useMergedRefs', () => {
+  it('updates all provided refs', () => {
+    const refObject: React.RefObject<boolean> = React.createRef<boolean>();
+    let refValue: boolean | null = null;
+    const TestComponent: React.FunctionComponent = () => {
+      const mergedRef = useMergedRefs<boolean>(refObject, val => (refValue = val));
+      mergedRef(true);
+      return null;
+    };
+    mount(<TestComponent />);
+
+    expect(refObject.current).toBe(true);
+    expect(refValue).toBe(true);
+  });
+
+  it('reuses the same ref callback if refs remain stable', () => {
+    const refObject: React.RefObject<boolean> = React.createRef<boolean>();
+
+    // tslint:disable-next-line:no-empty
+    const refValueFunc = (val: boolean) => {};
+
+    let refCallback: Function | undefined = undefined;
+    const TestComponent: React.FunctionComponent = () => {
+      refCallback = useMergedRefs<boolean>(refObject, refValueFunc);
+      return null;
+    };
+
+    const wrapper = mount(<TestComponent />);
+
+    const firstRefCallback = refCallback;
+
+    // Re-render the component
+    wrapper.update();
+
+    expect(refCallback).toBe(firstRefCallback);
+  });
+
+  it('handles changing ref callbacks', () => {
+    const refObject: React.RefObject<boolean> = React.createRef<boolean>();
+
+    let firstRefValue: boolean | null = null;
+    let refValueFunc = (val: boolean) => (firstRefValue = val);
+
+    const TestComponent: React.FunctionComponent = () => {
+      const mergedRef = useMergedRefs<boolean>(refObject, refValueFunc);
+      mergedRef(true);
+      return null;
+    };
+
+    const wrapper = mount(<TestComponent />);
+
+    let secondRefValue: boolean | null = null;
+    refValueFunc = (val: boolean) => (secondRefValue = val);
+
+    // Re-render the component
+    wrapper.setProps({});
+
+    expect(firstRefValue).toBe(true);
+    expect(secondRefValue).toBe(true);
+  });
+});

packages/react-hooks/src/useMergedRefs.ts

@@ -0,0 +1,19 @@
+import * as React from 'react';
+
+/**
+ * React hook to merge multile React refs (either MutableRefObjects or ref callbacks) into a single ref callback that
+ * updates all provided refs
+ * @param refs- Refs to collectively update with one ref value.
+ */
+export function useMergedRefs<T>(...refs: React.Ref<T>[]) {
+  return React.useCallback((value: T) => {
+    refs.forEach(ref => {
+      if (typeof ref === 'function') {
+        ref(value);
+      } else if (ref) {
+        // work around the immutability of the React.Ref type
+        ((ref as unknown) as React.MutableRefObject<T>).current = value;
+      }
+    });
+  }, refs);
+}