[docs] Add section for useFormControl (#25927)

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

@@ -111,10 +111,10 @@ otherwise you will notice duplicate headers.
 
 ## `useAutocomplete`
 
-For advanced customization use cases, we expose a headless `useAutocomplete()` hook.
+For advanced customization use cases, a headless `useAutocomplete()` hook is exposed.
 It accepts almost the same options as the Autocomplete component minus all the props
 related to the rendering of JSX.
-The Autocomplete component uses this hook internally.
+The Autocomplete component is built on this hook.
 
 ```jsx
 import useAutocomplete from '@material-ui/core/useAutocomplete';

docs/src/pages/components/pagination/pagination.md

@@ -48,10 +48,10 @@ You can specify how many digits to display either side of current page with the
 
 ## `usePagination`
 
-For advanced customization use cases, we expose a headless `usePagination()` hook.
+For advanced customization use cases, a headless `usePagination()` hook is exposed.
 It accepts almost the same options as the Pagination component minus all the props
 related to the rendering of JSX.
-The Pagination component uses this hook internally.
+The Pagination component is built on this hook.
 
 ```jsx
 import { usePagination } from '@material-ui/core/Pagination';

docs/src/pages/components/text-fields/UseFormControl.js

@@ -0,0 +1,30 @@
+import * as React from 'react';
+import FormControl, { useFormControl } from '@material-ui/core/FormControl';
+import OutlinedInput from '@material-ui/core/OutlinedInput';
+import Box from '@material-ui/core/Box';
+import FormHelperText from '@material-ui/core/FormHelperText';
+
+function MyFormHelperText() {
+  const { focused } = useFormControl() || {};
+
+  const helperText = React.useMemo(() => {
+    if (focused) {
+      return 'This field is being focused';
+    }
+
+    return 'Helper text';
+  }, [focused]);
+
+  return <FormHelperText>{helperText}</FormHelperText>;
+}
+
+export default function UseFormControl() {
+  return (
+    <Box component="form" noValidate autoComplete="off">
+      <FormControl sx={{ width: '25ch' }}>
+        <OutlinedInput placeholder="Please enter text" />
+        <MyFormHelperText />
+      </FormControl>
+    </Box>
+  );
+}

docs/src/pages/components/text-fields/UseFormControl.tsx

@@ -0,0 +1,30 @@
+import * as React from 'react';
+import FormControl, { useFormControl } from '@material-ui/core/FormControl';
+import OutlinedInput from '@material-ui/core/OutlinedInput';
+import Box from '@material-ui/core/Box';
+import FormHelperText from '@material-ui/core/FormHelperText';
+
+function MyFormHelperText() {
+  const { focused } = useFormControl() || {};
+
+  const helperText = React.useMemo(() => {
+    if (focused) {
+      return 'This field is being focused';
+    }
+
+    return 'Helper text';
+  }, [focused]);
+
+  return <FormHelperText>{helperText}</FormHelperText>;
+}
+
+export default function UseFormControl() {
+  return (
+    <Box component="form" noValidate autoComplete="off">
+      <FormControl sx={{ width: '25ch' }}>
+        <OutlinedInput placeholder="Please enter text" />
+        <MyFormHelperText />
+      </FormControl>
+    </Box>
+  );
+}

docs/src/pages/components/text-fields/text-fields.md

@@ -135,6 +135,42 @@ Below is an example using the [`InputBase`](/api/input-base/) component, inspire
 
 🎨 If you are looking for inspiration, you can check [MUI Treasury's customization examples](https://mui-treasury.com/styles/text-field).
 
+## `useFormControl`
+
+For advanced customization use cases, a `useFormControl()` hook is exposed.
+This hook returns the context value of the parent `FormControl` component.
+
+**API**
+
+```jsx
+import { useFormControl } from '@material-ui/core/FormControl';
+```
+
+**Returns**
+
+`value` (_object_):
+
+- `value.adornedStart` (_bool_): Indicate whether the child `Input` or `Select` component has a start adornment.
+- `value.setAdornedStart` (_func_): Setter function for `adornedStart` state value.
+- `value.color` (_string_): The theme color is being used, inherited from `FormControl` `color` prop .
+- `value.disabled` (_bool_): Indicate whether the component is being displayed in a disabled state, inherited from `FormControl` `disabled` prop.
+- `value.error` (_bool_): Indicate whether the component is being displayed in an error state, inherited from `FormControl` `error` prop
+- `value.filled` (_bool_): Indicate whether input is filled
+- `value.focused` (_bool_): Indicate whether the component and its children are being displayed in a focused state
+- `value.fullWidth` (_bool_): Indicate whether the component is taking up the full width of its container, inherited from `FormControl` `fullWidth` prop
+- `value.hiddenLabel` (_bool_): Indicate whether the label is being hidden, inherited from `FormControl` `hiddenLabel` prop
+- `value.required` (_bool_): Indicate whether the label is indicating that the input is required input, inherited from the `FormControl` `required` prop
+- `value.size` (_string_): The size of the component, inherited from the `FormControl` `size` prop
+- `value.variant` (_string_): The variant is being used by the `FormControl` component and its children, inherited from `FormControl` `variant` prop
+- `value.onBlur` (_func_): Should be called when the input is blurred
+- `value.onFocus` (_func_): Should be called when the input is focused
+- `value.onEmpty` (_func_): Should be called when the input is emptied
+- `value.onFilled` (_func_): Should be called when the input is filled
+
+**Example**
+
+{{"demo": "pages/components/text-fields/UseFormControl.js"}}
+
 ## Limitations
 
 ### Shrink

docs/src/pages/guides/api/api.md

@@ -132,7 +132,7 @@ For example, let's take a button that has different types. Each option has its p
   This API is more verbose:
   `<Button>`, `<Button variant="contained">`, `<Button variant="fab">`.
 
-  However it prevents an invalid combination from being used,
+  However, it prevents an invalid combination from being used,
   bounds the number of props exposed,
   and can easily support new values in the future.