[TextField] Add onStepperChange optional prop, and support Spinbutton pattern keyboard interactions (#8773)

stefanlegg · web-flow · commit e8c5a2243e8d · 2023-04-13T16:14:27.000-04:00
diff --git a/.changeset/beige-eggs-join.md b/.changeset/beige-eggs-join.md
@@ -0,0 +1,7 @@
+---
+'@shopify/polaris': minor
+---
+
+- Added an optional `onSpinnerChange` prop to`TextField`
+- Added an optional `largeStep` prop to `TextField`
+- Added `TextField` `Spinner` keypress interactions for Home, End, Page Up, Page Down
diff --git a/polaris-react/src/components/TextField/TextField.tsx b/polaris-react/src/components/TextField/TextField.tsx
@@ -122,6 +122,8 @@ interface NonMutuallyExclusiveProps {
   role?: string;
   /** Limit increment value for numeric and date-time inputs */
   step?: number;
+  /** Increment value for numeric and date-time inputs when using Page Up or Page Down */
+  largeStep?: number;
   /** Enable automatic completion by the browser. Set to "off" when you do not want the browser to fill in info */
   autoComplete: string;
   /** Mimics the behavior of the native HTML attribute, limiting the maximum value */
@@ -162,6 +164,8 @@ interface NonMutuallyExclusiveProps {
   onClearButtonClick?(id: string): void;
   /** Callback fired when value is changed */
   onChange?(value: string, id: string): void;
+  /** When provided, callback fired instead of onChange when value is changed via the number step control  */
+  onSpinnerChange?(value: string, id: string): void;
   /** Callback fired when input is focused */
   onFocus?: (event?: React.FocusEvent) => void;
   /** Callback fired when input is blurred */
@@ -207,6 +211,7 @@ export function TextField({
   id: idProp,
   role,
   step,
+  largeStep,
   autoComplete,
   max,
   maxLength,
@@ -229,6 +234,7 @@ export function TextField({
   suggestion,
   onClearButtonClick,
   onChange,
+  onSpinnerChange,
   onFocus,
   onBlur,
   borderless,
@@ -353,8 +359,8 @@ export function TextField({
     ) : null;
 
   const handleNumberChange = useCallback(
-    (steps: number) => {
-      if (onChange == null) {
+    (steps: number, stepAmount = normalizedStep) => {
+      if (onChange == null && onSpinnerChange == null) {
         return;
       }
       // Returns the length of decimal places in a number
@@ -367,16 +373,28 @@ export function TextField({
 
       // Making sure the new value has the same length of decimal places as the
       // step / value has.
-      const decimalPlaces = Math.max(dpl(numericValue), dpl(normalizedStep));
+      const decimalPlaces = Math.max(dpl(numericValue), dpl(stepAmount));
 
       const newValue = Math.min(
         Number(normalizedMax),
-        Math.max(numericValue + steps * normalizedStep, Number(normalizedMin)),
+        Math.max(numericValue + steps * stepAmount, Number(normalizedMin)),
       );
 
-      onChange(String(newValue.toFixed(decimalPlaces)), id);
+      if (onSpinnerChange != null) {
+        onSpinnerChange(String(newValue.toFixed(decimalPlaces)), id);
+      } else if (onChange != null) {
+        onChange(String(newValue.toFixed(decimalPlaces)), id);
+      }
     },
-    [id, normalizedMax, normalizedMin, onChange, normalizedStep, value],
+    [
+      id,
+      normalizedMax,
+      normalizedMin,
+      onChange,
+      onSpinnerChange,
+      normalizedStep,
+      value,
+    ],
   );
 
   const handleButtonRelease = useCallback(() => {
@@ -531,6 +549,7 @@ export function TextField({
     onBlur: handleOnBlur,
     onClick: handleClickChild,
     onKeyPress: handleKeyPress,
+    onKeyDown: handleKeyDown,
     onChange: !suggestion ? handleChange : undefined,
     onInput: suggestion ? handleChange : undefined,
   });
@@ -645,6 +664,40 @@ export function TextField({
     event.preventDefault();
   }
 
+  function handleKeyDown(event: React.KeyboardEvent) {
+    if (type !== 'number') {
+      return;
+    }
+
+    const {key, which} = event;
+    if ((which === Key.Home || key === 'Home') && min !== undefined) {
+      if (onSpinnerChange != null) {
+        onSpinnerChange(String(min), id);
+      } else if (onChange != null) {
+        onChange(String(min), id);
+      }
+    }
+
+    if ((which === Key.End || key === 'End') && max !== undefined) {
+      if (onSpinnerChange != null) {
+        onSpinnerChange(String(max), id);
+      } else if (onChange != null) {
+        onChange(String(max), id);
+      }
+    }
+
+    if ((which === Key.PageUp || key === 'PageUp') && largeStep !== undefined) {
+      handleNumberChange(1, largeStep);
+    }
+
+    if (
+      (which === Key.PageDown || key === 'PageDown') &&
+      largeStep !== undefined
+    ) {
+      handleNumberChange(-1, largeStep);
+    }
+  }
+
   function handleOnBlur(event: React.FocusEvent) {
     setFocus(false);
 
diff --git a/polaris-react/src/components/TextField/tests/TextField.test.tsx b/polaris-react/src/components/TextField/tests/TextField.test.tsx
@@ -9,6 +9,7 @@ import {Tag} from '../../Tag';
 import {Resizer, Spinner} from '../components';
 import {TextField} from '../TextField';
 import styles from '../TextField.scss';
+import {Key} from '../../../types';
 
 describe('<TextField />', () => {
   it('allows specific props to pass through properties on the input', () => {
@@ -1073,6 +1074,200 @@ describe('<TextField />', () => {
         expect(spy).not.toHaveBeenCalled();
       });
 
+      describe('onSpinnerChange()', () => {
+        it('is called with the new value when incrementing by step', () => {
+          const spy = jest.fn();
+          const element = mountWithApp(
+            <TextField
+              id="MyTextField"
+              label="TextField"
+              type="number"
+              value="2"
+              step={4}
+              onSpinnerChange={spy}
+              autoComplete="off"
+            />,
+          );
+
+          element.findAll('div', {role: 'button'})[0].trigger('onClick');
+          expect(spy).toHaveBeenCalledWith('6', 'MyTextField');
+        });
+
+        it('is called with the new value instead of onChange when incrementing by step', () => {
+          const onStepperSpy = jest.fn();
+          const onChangeSpy = jest.fn();
+          const element = mountWithApp(
+            <TextField
+              id="MyTextField"
+              label="TextField"
+              type="number"
+              value="2"
+              step={4}
+              onSpinnerChange={onStepperSpy}
+              onChange={onChangeSpy}
+              autoComplete="off"
+            />,
+          );
+
+          element.findAll('div', {role: 'button'})[0].trigger('onClick');
+          expect(onStepperSpy).toHaveBeenCalledWith('6', 'MyTextField');
+          expect(onChangeSpy).not.toHaveBeenCalled();
+        });
+
+        it('is not called when new values are typed', () => {
+          const onStepperSpy = jest.fn();
+          const onChangeSpy = jest.fn();
+          const element = mountWithApp(
+            <TextField
+              id="MyTextField"
+              label="TextField"
+              type="number"
+              value="2"
+              step={4}
+              onSpinnerChange={onStepperSpy}
+              onChange={onChangeSpy}
+              autoComplete="off"
+            />,
+          );
+
+          element.find('input')!.trigger('onChange', {
+            currentTarget: {
+              value: '6',
+            },
+          });
+          expect(onStepperSpy).not.toHaveBeenCalled();
+          expect(onChangeSpy).toHaveBeenCalledWith('6', 'MyTextField');
+        });
+      });
+
+      describe('keydown events', () => {
+        it('decrements by largeStep when provided and Page Down is pressed', () => {
+          const spy = jest.fn();
+          const textField = mountWithApp(
+            <TextField
+              id="MyTextField"
+              label="TextField"
+              type="number"
+              value="10"
+              step={1}
+              largeStep={4}
+              onChange={spy}
+              autoComplete="off"
+            />,
+          );
+          textField.find('input')!.trigger('onKeyDown', {
+            key: 'PageDown',
+            which: Key.PageDown,
+          });
+          expect(spy).toHaveBeenCalledWith('6', 'MyTextField');
+        });
+
+        it('increments by largeStep when provided and Page Up is pressed', () => {
+          const spy = jest.fn();
+          const textField = mountWithApp(
+            <TextField
+              id="MyTextField"
+              label="TextField"
+              type="number"
+              value="10"
+              step={1}
+              largeStep={4}
+              onChange={spy}
+              autoComplete="off"
+            />,
+          );
+          textField.find('input')!.trigger('onKeyDown', {
+            key: 'PageUp',
+            which: Key.PageUp,
+          });
+          expect(spy).toHaveBeenCalledWith('14', 'MyTextField');
+        });
+
+        it('calls onChange(min) if Home is pressed and min was provided', () => {
+          const spy = jest.fn();
+          const textField = mountWithApp(
+            <TextField
+              id="MyTextField"
+              label="TextField"
+              type="number"
+              value="10"
+              min={1}
+              step={1}
+              onChange={spy}
+              autoComplete="off"
+            />,
+          );
+          textField.find('input')!.trigger('onKeyDown', {
+            key: 'Home',
+            which: Key.Home,
+          });
+          expect(spy).toHaveBeenCalledWith('1', 'MyTextField');
+        });
+
+        it('calls onChange(max) if End is pressed and max was provided', () => {
+          const spy = jest.fn();
+          const textField = mountWithApp(
+            <TextField
+              id="MyTextField"
+              label="TextField"
+              type="number"
+              value="10"
+              max={100}
+              step={1}
+              onChange={spy}
+              autoComplete="off"
+            />,
+          );
+          textField.find('input')!.trigger('onKeyDown', {
+            key: 'End',
+            which: Key.End,
+          });
+          expect(spy).toHaveBeenCalledWith('100', 'MyTextField');
+        });
+
+        it('calls onSpinnerChange(min) if Home is pressed and min was provided', () => {
+          const spy = jest.fn();
+          const textField = mountWithApp(
+            <TextField
+              id="MyTextField"
+              label="TextField"
+              type="number"
+              value="10"
+              min={1}
+              step={1}
+              onSpinnerChange={spy}
+              autoComplete="off"
+            />,
+          );
+          textField.find('input')!.trigger('onKeyDown', {
+            key: 'Home',
+            which: Key.Home,
+          });
+          expect(spy).toHaveBeenCalledWith('1', 'MyTextField');
+        });
+
+        it('calls onSpinnerChange(max) if End is pressed and max was provided', () => {
+          const spy = jest.fn();
+          const textField = mountWithApp(
+            <TextField
+              id="MyTextField"
+              label="TextField"
+              type="number"
+              value="10"
+              max={100}
+              step={1}
+              onSpinnerChange={spy}
+              autoComplete="off"
+            />,
+          );
+          textField.find('input')!.trigger('onKeyDown', {
+            key: 'End',
+            which: Key.End,
+          });
+          expect(spy).toHaveBeenCalledWith('100', 'MyTextField');
+        });
+      });
+
       describe('document events', () => {
         type EventCallback = (mockEventData?: {[key: string]: any}) => void;
 
