[docs] Create the FormControl page

docs/data/base/components/form-control/UseFormControl.js

@@ -0,0 +1,51 @@
+import * as React from 'react';
+import FormControlUnstyled, {
+  useFormControlUnstyled,
+} from '@mui/base/FormControlUnstyled';
+
+function CustomInput() {
+  const formControlContext = useFormControlUnstyled();
+
+  if (formControlContext === undefined) {
+    return null;
+  }
+
+  const { value, required, onChange, disabled, onFocus, onBlur } =
+    formControlContext;
+
+  return (
+    <input
+      value={value}
+      required={required}
+      onChange={onChange}
+      disabled={disabled}
+      onFocus={onFocus}
+      onBlur={onBlur}
+    />
+  );
+}
+
+function ControlStateDisplay() {
+  const formControlContext = useFormControlUnstyled();
+  if (formControlContext === undefined) {
+    return null;
+  }
+
+  const { filled, focused } = formControlContext;
+
+  return (
+    <p>
+      {filled ? 'filled' : 'empty'}&nbsp;|&nbsp;
+      {focused ? 'focused' : 'not focused'}
+    </p>
+  );
+}
+
+export default function UseFormControl() {
+  return (
+    <FormControlUnstyled defaultValue="" required>
+      <CustomInput />
+      <ControlStateDisplay />
+    </FormControlUnstyled>
+  );
+}

docs/data/base/components/form-control/UseFormControl.tsx

@@ -0,0 +1,51 @@
+import * as React from 'react';
+import FormControlUnstyled, {
+  useFormControlUnstyled,
+} from '@mui/base/FormControlUnstyled';
+
+function CustomInput() {
+  const formControlContext = useFormControlUnstyled();
+
+  if (formControlContext === undefined) {
+    return null;
+  }
+
+  const { value, required, onChange, disabled, onFocus, onBlur } =
+    formControlContext;
+
+  return (
+    <input
+      value={value as string}
+      required={required}
+      onChange={onChange}
+      disabled={disabled}
+      onFocus={onFocus}
+      onBlur={onBlur}
+    />
+  );
+}
+
+function ControlStateDisplay() {
+  const formControlContext = useFormControlUnstyled();
+  if (formControlContext === undefined) {
+    return null;
+  }
+
+  const { filled, focused } = formControlContext;
+
+  return (
+    <p>
+      {filled ? 'filled' : 'empty'}&nbsp;|&nbsp;
+      {focused ? 'focused' : 'not focused'}
+    </p>
+  );
+}
+
+export default function UseFormControl() {
+  return (
+    <FormControlUnstyled defaultValue="" required>
+      <CustomInput />
+      <ControlStateDisplay />
+    </FormControlUnstyled>
+  );
+}

docs/data/base/components/form-control/UseFormControl.tsx.preview

@@ -0,0 +1,4 @@
+<FormControlUnstyled defaultValue="" required>
+  <CustomInput />
+  <ControlStateDisplay />
+</FormControlUnstyled>

docs/data/base/components/form-control/form-control.md

@@ -0,0 +1,58 @@
+---
+product: base
+title: React form control
+components: FormControlUnstyled
+packageName: '@mui/base'
+---
+
+# Unstyled form control
+
+<p class="description">
+  The FormControlUnstyled is a utility that lets you associate a form input with auxillary components,
+  such as labels, error indicators or helper text.
+</p>
+
+{{"component": "modules/components/ComponentLinkHeader.js", "design": false}}
+
+## FormControlUnstyled
+
+FormControlUnstyled wraps an input and other components and enables reflecting the input's state in these other components.
+
+For instance, you may show additional element asking the user to enter a value if the input is empty or display a warning icon when the entered value is incorrect.
+
+The FormControlUnstyled provides a context that can be read by the useFormControl hook.
+
+## useFormControl hook
+
+The useFormControl hook can be used to enable integration between custom form inputs and FormControlUnstyled.
+Additionally, you can read the form control's state and react to its changes in a custom component.
+
+The demo below shows both.
+`CustomInput` is a wrapper around a native HTML `input` that adds FormControlUnstyled integration.
+`ControlStateDisplay` reads the state of the form control and displays it as text.
+
+{{"demo": "UseFormControl.js", "defaultCodeOpen": false}}
+
+Note that even though FormControlUnstyled supports both controlled and uncontrolled-style API
+(i.e. it accepts `value` and `defaultValue` props), `useFormControl` returns only the controlled `value`.
+This way, you don't have to implement both in your custom input - FormControlUnstyled does this for you.
+
+`useFormControl` returns an object with the following fields:
+
+| Name       | Type    | Description                                                                                                                                                            |
+| ---------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `disabled` | boolean | Represents the value of the FormControlUnstyled's `disabled` prop.                                                                                                     |
+| `error`    | boolean | Represents the value of the FormControlUnstyled's `error` prop. Note that it is not calculated automatically (i.e. it's not set when `required: true` and `value: ''`) |
+| `filled`   | boolean | Set to `true` if `value` is not empty.                                                                                                                                 |
+| `focused`  | boolean | Set to `true` if the wrapped input has received focus.                                                                                                                 |
+| `required` | boolean | Represents the value of the FormControlUnstyled's `required` prop.                                                                                                     |
+| `value`    | unknown | The current value of the form control.                                                                                                                                 |
+
+Additionally, the following callbacks are a part of the returned object.
+They are meant to be used when creating custom inputs.
+
+| Name       | Type                      | Description                                                   |
+| ---------- | ------------------------- | ------------------------------------------------------------- |
+| `onChange` | React.ChangeEvent => void | Change handler. Should be forwarded to the inner input.       |
+| `onBlur`   | () => void                | Focus change handler. Should be forwarded to the inner input. |
+| `onFocus`  | () => void                | Focus change handler. Should be forwarded to the inner input. |

docs/data/base/pages.ts

@@ -35,6 +35,7 @@ const pages = [
         subheader: 'utils',
         children: [
           { pathname: '/base/react-click-away-listener', title: 'Click-away listener' },
+          { pathname: '/base/react-form-control', title: 'Form control' },
           { pathname: '/base/react-modal', title: 'Modal' },
           { pathname: '/base/react-no-ssr', title: 'No SSR' },
           { pathname: '/base/react-popper', title: 'Popper' },

docs/data/material/components/text-fields/text-fields.md

@@ -1,7 +1,7 @@
 ---
 product: material-ui
 title: Text Field React component
-components: FilledInput, FormControl, FormControlUnstyled, FormHelperText, Input, InputAdornment, InputBase, InputLabel, OutlinedInput, TextField
+components: FilledInput, FormControl, FormHelperText, Input, InputAdornment, InputBase, InputLabel, OutlinedInput, TextField
 githubLabel: 'component: text field'
 materialDesign: https://material.io/components/text-fields
 unstyled: /base/react-input/

docs/pages/api-docs/form-control-unstyled.json

@@ -18,6 +18,6 @@
   "forwardsRefTo": "HTMLDivElement",
   "filename": "/packages/mui-base/src/FormControlUnstyled/FormControlUnstyled.tsx",
   "inheritance": null,
-  "demos": "<ul><li><a href=\"/components/text-fields/\">Text Fields</a></li></ul>",
+  "demos": "<ul><li><a href=\"/components/form-control/\">Form Control</a></li>\n<li><a href=\"/components/text-fields/\">Text Fields</a></li></ul>",
   "cssComponent": false
 }

docs/pages/base/api/form-control-unstyled.json

@@ -18,6 +18,6 @@
   "forwardsRefTo": "HTMLDivElement",
   "filename": "/packages/mui-base/src/FormControlUnstyled/FormControlUnstyled.tsx",
   "inheritance": null,
-  "demos": "<ul><li><a href=\"/material-ui/react-text-field/\">Text Fields</a></li></ul>",
+  "demos": "<ul><li><a href=\"/base/components/form-control/\">Form Control</a></li></ul>",
   "cssComponent": false
 }

docs/pages/base/react-form-control.js

@@ -0,0 +1,11 @@
+import * as React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import {
+  demos,
+  docs,
+  demoComponents,
+} from 'docs/data/base/components/form-control/form-control.md?@mui/markdown';
+
+export default function Page() {
+  return <MarkdownDocs demos={demos} docs={docs} demoComponents={demoComponents} />;
+}

packages/mui-base/src/FormControlUnstyled/FormControlUnstyled.tsx

@@ -52,6 +52,7 @@ export type FormControlUnstyledOwnerState = Omit<
  *
  * Demos:
  *
+ * - [Form Control](https://mui.com/components/form-control/)
  * - [Text Fields](https://mui.com/components/text-fields/)
  *
  * API:

packages/mui-base/src/FormControlUnstyled/FormControlUnstyledProps.ts

@@ -36,11 +36,6 @@ export interface FormControlUnstyledOwnProps {
    * @default false
    */
   error?: boolean;
-  /**
-   * Extra properties to be placed on the FormControlContext.
-   * @default {}
-   */
-  extraContextProperties?: object;
   /**
    * If `true`, the component is displayed in focused state.
    * @default false