[Autocomplete] Clarify value and inputValue link

Author: oliviertassinari

docs/src/pages/components/autocomplete/autocomplete.md

@@ -32,6 +32,15 @@ Choose one of the 248 countries.
 
 {{"demo": "pages/components/autocomplete/CountrySelect.js"}}
 
+### Controllable states
+
+The component has two states that can be controlled:
+
+1. the "value" state with the `value`/`onChange` props combination.
+2. the "input value" state with the `inputValue`/`onInputChange` props combination.
+
+> ⚠️ These two state are isolated, they should be controlled independently.
+
 ## Free solo
 
 Set `freeSolo` to true so the textbox can contain any arbitrary value. The prop is designed to cover the primary use case of a search box with suggestions, e.g. Google search.

packages/material-ui-lab/src/Autocomplete/Autocomplete.test.js

@@ -1101,13 +1101,6 @@ describe('<Autocomplete />', () => {
   });
 
   describe('controlled', () => {
-    beforeEach(() => {
-      consoleWarnMock.spy();
-    });
-
-    afterEach(() => {
-      consoleWarnMock.reset();
-    });
     it('controls the input value', () => {
       const handleChange = spy();
       function MyComponent() {
@@ -1151,49 +1144,6 @@ describe('<Autocomplete />', () => {
       fireEvent.keyDown(document.activeElement, { key: 'Enter' });
       expect(handleInputChange.calledBefore(handleChange)).to.equal(true);
     });
-
-    it('should log warning if undefined passed as input value', () => {
-      function MyComponent() {
-        const [value, setInputValue] = React.useState('foo');
-        const handleInputChange = () => {
-          setInputValue(undefined);
-        };
-        return (
-          <Autocomplete
-            {...defaultProps}
-            inputValue={value}
-            onInputChange={handleInputChange}
-            renderInput={(params) => <TextField {...params} autoFocus />}
-          />
-        );
-      }
-      render(<MyComponent />);
-      expect(
-        consoleWarnMock
-          .getSpy()
-          .calledWithExactly(
-            'inputValue provided was null, defaulting to empty string. Check that the inputValue property gets passed a valid string value',
-          ),
-      ).to.equal(true);
-    });
-    it('should treat undefined as empty string when passed in as input value', () => {
-      function MyComponent() {
-        const [value, setInputValue] = React.useState('foo');
-        const handleInputChange = () => {
-          setInputValue(undefined);
-        };
-        return (
-          <Autocomplete
-            {...defaultProps}
-            inputValue={value}
-            onInputChange={handleInputChange}
-            renderInput={(params) => <TextField {...params} autoFocus />}
-          />
-        );
-      }
-      render(<MyComponent />);
-      expect(document.activeElement.value).to.equal('');
-    });
   });
 
   describe('prop: filterOptions', () => {

packages/material-ui-lab/src/Pagination/usePagination.js

@@ -25,6 +25,7 @@ export default function usePagination(props = {}) {
     controlled: pageProp,
     default: defaultPage,
     name: componentName,
+    state: 'page',
   });
 
   const handleClick = (event, value) => {

packages/material-ui-lab/src/TreeView/TreeView.js

@@ -67,12 +67,14 @@ const TreeView = React.forwardRef(function TreeView(props, ref) {
     controlled: expandedProp,
     default: defaultExpanded,
     name: 'TreeView',
+    state: 'expanded',
   });
 
   const [selected, setSelectedState] = useControlled({
     controlled: selectedProp,
     default: defaultSelected,
     name: 'TreeView',
+    state: 'selected',
   });
 
   /*

packages/material-ui-lab/src/TreeView/TreeView.test.js

@@ -46,7 +46,7 @@ describe('<TreeView />', () => {
 
       setProps({ expanded: undefined });
       expect(consoleErrorMock.messages()[0]).to.include(
-        'A component is changing a controlled TreeView to be uncontrolled',
+        'Material-UI: a component is changing the controlled expanded state of TreeView to be uncontrolled.',
       );
     });
 
@@ -59,7 +59,7 @@ describe('<TreeView />', () => {
 
       setProps({ selected: undefined });
       expect(consoleErrorMock.messages()[0]).to.include(
-        'A component is changing a controlled TreeView to be uncontrolled',
+        'Material-UI: a component is changing the controlled selected state of TreeView to be uncontrolled.',
       );
     });
   });

packages/material-ui-lab/src/useAutocomplete/useAutocomplete.js

@@ -67,15 +67,6 @@ const defaultFilterOptions = createFilterOptions();
 // Number of options to jump in list box when pageup and pagedown keys are used.
 const pageSize = 5;
 
-const getInputValue = (inputValue) => {
-  if (inputValue == null) {
-    console.warn(
-      'inputValue provided was null, defaulting to empty string. Check that the inputValue property gets passed a valid string value',
-    );
-    return '';
-  }
-  return inputValue;
-};
 export default function useAutocomplete(props) {
   const {
     autoComplete = false,
@@ -195,10 +186,12 @@ export default function useAutocomplete(props) {
     default: defaultValue,
     name: componentName,
   });
-
-  const { current: isInputValueControlled } = React.useRef(inputValueProp != null);
-  const [inputValueState, setInputValue] = React.useState('');
-  const inputValue = isInputValueControlled ? getInputValue(inputValueProp) : inputValueState;
+  const [inputValue, setInputValue] = useControlled({
+    controlled: inputValueProp,
+    default: '',
+    name: componentName,
+    state: 'inputValue',
+  });
 
   const [focused, setFocused] = React.useState(false);
 

packages/material-ui/src/ExpansionPanel/ExpansionPanel.js

@@ -99,6 +99,7 @@ const ExpansionPanel = React.forwardRef(function ExpansionPanel(props, ref) {
     controlled: expandedProp,
     default: defaultExpanded,
     name: 'ExpansionPanel',
+    state: 'expanded',
   });
 
   const handleChange = React.useCallback(

packages/material-ui/src/ExpansionPanel/ExpansionPanel.test.js

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import PropTypes from 'prop-types';
-import { assert } from 'chai';
+import { assert, expect } from 'chai';
 import { spy } from 'sinon';
 import { createMount, getClasses, findOutermostIntrinsic } from '@material-ui/core/test-utils';
 import describeConformance from '../test-utils/describeConformance';
@@ -193,9 +193,8 @@ describe('<ExpansionPanel />', () => {
       const wrapper = mount(<ExpansionPanel expanded>{minimalChildren}</ExpansionPanel>);
 
       wrapper.setProps({ expanded: undefined });
-      assert.include(
-        consoleErrorMock.messages()[0],
-        'A component is changing a controlled ExpansionPanel to be uncontrolled.',
+      expect(consoleErrorMock.messages()[0]).to.include(
+        'Material-UI: a component is changing the controlled expanded state of ExpansionPanel to be uncontrolled.',
       );
     });
 
@@ -205,7 +204,7 @@ describe('<ExpansionPanel />', () => {
       wrapper.setProps({ expanded: true });
       assert.include(
         consoleErrorMock.messages()[0],
-        'A component is changing an uncontrolled ExpansionPanel to be controlled.',
+        'Material-UI: a component is changing the uncontrolled expanded state of ExpansionPanel to be controlled.',
       );
     });
   });

packages/material-ui/src/RadioGroup/RadioGroup.test.js

@@ -348,9 +348,8 @@ describe('<RadioGroup />', () => {
       );
 
       wrapper.setProps({ value: undefined });
-      assert.include(
-        consoleErrorMock.messages()[0],
-        'A component is changing a controlled RadioGroup to be uncontrolled.',
+      expect(consoleErrorMock.messages()[0]).to.include(
+        'Material-UI: a component is changing the controlled value state of RadioGroup to be uncontrolled.',
       );
     });
 
@@ -362,9 +361,8 @@ describe('<RadioGroup />', () => {
       );
 
       wrapper.setProps({ value: 'foo' });
-      assert.include(
-        consoleErrorMock.messages()[0],
-        'A component is changing an uncontrolled RadioGroup to be controlled.',
+      expect(consoleErrorMock.messages()[0]).to.include(
+        'Material-UI: a component is changing the uncontrolled value state of RadioGroup to be controlled.',
       );
     });
   });

packages/material-ui/src/Slider/Slider.test.js

@@ -515,7 +515,7 @@ describe('<Slider />', () => {
 
       setProps({ value: undefined });
       expect(consoleErrorMock.messages()[0]).to.include(
-        'A component is changing a controlled Slider to be uncontrolled.',
+        'Material-UI: a component is changing the controlled value state of Slider to be uncontrolled.',
       );
     });
 
@@ -524,7 +524,7 @@ describe('<Slider />', () => {
 
       setProps({ value: [20, 50] });
       expect(consoleErrorMock.messages()[0]).to.include(
-        'A component is changing an uncontrolled Slider to be controlled.',
+        'Material-UI: a component is changing the uncontrolled value state of Slider to be controlled.',
       );
     });
   });