Fix null value support in inputs

docs/Form.md

@@ -136,7 +136,9 @@ export const PostCreate = () => {
 
 ## `sanitizeEmptyValues`
 
-In HTML, the value of empty form inputs is the empty string (`''`) by default. React-hook-form doesn't sanitize these values. This leads to unexpected `create` and `update` payloads like:
+In HTML, the value of empty form inputs is the empty string (`''`). React-admin inputs (like `<TextInput>`, `<NumberInput>`, etc.) automatically transform these empty values into `null`.
+
+But for your own input components based on react-hook-form, this is not the default. React-hook-form doesn't transform empty values by default. This leads to unexpected `create` and `update` payloads like:
 
 ```jsx
 {

docs/Inputs.md

@@ -44,11 +44,11 @@ All input components accept the following props:
 | `className`     | Optional | `string`                  | -       | Class name (usually generated by JSS) to customize the look and feel of the field element itself                                                                    |
 | `defaultValue`  | Optional | `any`                     | -       | Default value of the input.                                                                                                                                         |
 | `disabled`      | Optional | `boolean`                 | -       | If true, the input is disabled.                                                                                                                                     |
-| `format`        | Optional | `Function`                | -       | Callback taking the value from the form state, and returning the input value.                                                                                       |
+| `format`        | Optional | `Function`                | `value => value == null ? '' : value` | Callback taking the value from the form state, and returning the input value.                                                                                       |
 | `fullWidth`     | Optional | `boolean`                 | `false` | If `true`, the input will expand to fill the form width                                                                                                             |
 | `helperText`    | Optional | `string`                  | -       | Text to be displayed under the input                                                                                                                                |
 | `label`         | Optional | `string`                  | -       | Input label. In i18n apps, the label is passed to the `translate` function. Defaults to the humanized `source` when omitted. Set `label={false}` to hide the label. |
-| `parse`         | Optional | `Function`                | -       | Callback taking the input value, and returning the value you want stored in the form state.                                                                         |
+| `parse`         | Optional | `Function`                | `value => value === '' ? null : value` | Callback taking the input value, and returning the value you want stored in the form state.                                                                         |
 | `sx`            | Optional | `SxProps`                 | -       | MUI shortcut for defining custom styles                                                                                                                             |
 | `validate`      | Optional | `Function` | `array` | -       | Validation rules for the current property. See the [Validation Documentation](./Validation.md#per-input-validation-built-in-field-validators) for details.          |
 
@@ -142,6 +142,12 @@ form state value --> format --> form input value (string)
 
 `format` often comes in pair with [`parse`](#parse) to transform the input value before storing it in the form state. See the [Transforming Input Value](#transforming-input-value-tofrom-record) section for more details.
 
+**Tip:** By default, react-admin inputs have to following `format` function, which turns any `null` or `undefined` value into an empty string. This is to avoid warnings about controlled/uncontrolled input components:
+
+```js
+const defaultFormat = (value: any) => value == null ? '' : value;
+```
+
 ## `fullWidth`
 
 If `true`, the input will expand to fill the form width.
@@ -215,6 +221,12 @@ form input value (string) ---> parse ---> form state value
 
 `parse` often comes in pair with [`format`](#format) to transform the form value before passing it to the input. See the [Transforming Input Value](#transforming-input-value-tofrom-record) section for more details.
 
+**Tip:** By default, react-admin inputs have to following `parse` function, which transforms any empty string into `null`:
+
+```js
+const defaultParse = (value: string) => value === '' ? null : value;
+```
+
 ## `source`
 
 Specifies the field of the record that the input should edit.
@@ -331,30 +343,13 @@ Mnemonic for the two functions:
 - `parse()`: input -> record
 - `format()`: record -> input
 
-A common usage for this feature is to strip empty strings from the record before saving it to the API. As a reminder, HTML form inputs always return strings, even for numbers and booleans. So the empty value for a text input is the empty string, not `null` or `undefined`. Leveraging `parse` allows you to transform the empty string to `null` before saving the record.
-
-```jsx
-import { TextInput } from 'react-admin';
-
-const TextInputWithNullEmptyValue = props => (
-    <TextInput
-        {...props}
-        parse={v =>  v === '' ? null : v}
-    />
-);
-
-export default TextInputWithNullEmptyValue;
-```
-
-**Tip**: If you need to do that for every input, use [the `sanitizeEmptyValues` prop of the `<Form>` component](./Form.md#sanitizeemptyvalues) instead.
-
-Let's look at another usage example. Say the user would like to input values of 0-100 to a percentage field but your API (hence record) expects 0-1.0. You can use simple `parse()` and `format()` functions to archive the transform:
+Let's look at a simple example. Say the user would like to input values of 0-100 to a percentage field but your API (hence record) expects 0-1.0. You can use simple `parse()` and `format()` functions to archive the transform:
 
 ```jsx
 <NumberInput source="percent" format={v => v * 100} parse={v => parseFloat(v) / 100} label="Formatted number" />
 ```
 
-`<DateInput>` stores and returns a string. If you would like to store a JavaScript Date object in your record instead:
+Another classical use-case is with handling dates. `<DateInput>` stores and returns a string. If you would like to store a JavaScript Date object in your record instead, you can do something like this:
 
 ```jsx
 const dateFormatRegex = /^\d{4}-\d{2}-\d{2}$/;
@@ -393,6 +388,10 @@ const dateParser = value => {
 <DateInput source="isodate" format={dateFormatter} parse={dateParser} defaultValue={new Date()} />
 ```
 
+**Tip:** A common usage for this feature is to deal with empty values. Indeed HTML form inputs always return strings, even for numbers and booleans, however most backends expect a value like `null`. This is why, by default, all react-admin inputs will store the value `null` when the HTML input value is `''`. 
+
+**Tip**: If you need React-admin to completely remove all empty values (that did not change) from the record upon submission, have a look at [the `sanitizeEmptyValues` prop of the `<Form>` component](./Form.md#sanitizeemptyvalues).
+
 ## Linking Two Inputs
 
 Edition forms often contain linked inputs, e.g. country and city (the choices of the latter depending on the value of the former).

docs/SimpleForm.md

@@ -144,7 +144,9 @@ export const PostCreate = () => {
 
 ## `sanitizeEmptyValues`
 
-As a reminder, HTML form inputs always return strings, even for numbers and booleans. So the empty value for a text input is the empty string, not `null` or `undefined`. This means that the data sent to the form handler will contain empty strings:
+In HTML, the value of empty form inputs is the empty string (`''`). React-admin inputs (like `<TextInput>`, `<NumberInput>`, etc.) automatically transform these empty values into `null`.
+
+But for your own input components based on react-hook-form, this is not the default. React-hook-form doesn't transform empty values by default. This leads to unexpected `create` and `update` payloads like:
 
 ```jsx
 {
@@ -156,7 +158,7 @@ As a reminder, HTML form inputs always return strings, even for numbers and bool
 }
 ```
 
-React-hook-form doesn't sanitize these values. If you prefer to omit the keys for empty values, set the `sanitizeEmptyValues` prop to `true`. This will sanitize the form data before passing it to the `dataProvider`, i.e. remove empty strings from the form state, unless the record actually had a value for that field before edition.
+If you prefer to omit the keys for empty values, set the `sanitizeEmptyValues` prop to `true`. This will sanitize the form data before passing it to the `dataProvider`, i.e. remove empty strings from the form state, unless the record actually had a value for that field before edition.
 
 ```jsx
 const PostCreate = () =>  (

docs/TabbedForm.md

@@ -192,7 +192,9 @@ export const PostCreate = () => (
 
 ## `sanitizeEmptyValues`
 
-As a reminder, HTML form inputs always return strings, even for numbers and booleans. So the empty value for a text input is the empty string, not `null` or `undefined`. This means that the data sent to the form handler will contain empty strings:
+In HTML, the value of empty form inputs is the empty string (`''`). React-admin inputs (like `<TextInput>`, `<NumberInput>`, etc.) automatically transform these empty values into `null`.
+
+But for your own input components based on react-hook-form, this is not the default. React-hook-form doesn't transform empty values by default. This leads to unexpected `create` and `update` payloads like:
 
 ```jsx
 {
@@ -204,7 +206,7 @@ As a reminder, HTML form inputs always return strings, even for numbers and bool
 }
 ```
 
-React-hook-form doesn't sanitize these values. If you prefer to omit the keys for empty values, set the `sanitizeEmptyValues` prop to `true`. This will sanitize the form data before passing it to the `dataProvider`, i.e. remove empty strings from the form state, unless the record actually had a value for that field before edition.
+If you prefer to omit the keys for empty values, set the `sanitizeEmptyValues` prop to `true`. This will sanitize the form data before passing it to the `dataProvider`, i.e. remove empty strings from the form state, unless the record actually had a value for that field before edition.
 
 ```jsx
 const PostCreate = () =>  (

packages/ra-core/src/form/getFormInitialValues.ts

@@ -10,12 +10,6 @@ export default function getFormInitialValues(
         getValues(defaultValues, record),
         record
     );
-    // replace null values by empty string to avoid controlled/ uncontrolled input warning
-    Object.keys(finalInitialValues).forEach(key => {
-        if (finalInitialValues[key] === null) {
-            finalInitialValues[key] = '';
-        }
-    });
     return finalInitialValues;
 }
 

packages/ra-core/src/form/sanitizeEmptyValues.ts

@@ -7,7 +7,7 @@
 export const sanitizeEmptyValues = (values: any, record: any = {}): any => {
     const sanitizedValues = {};
     Object.keys(values).forEach(key => {
-        if (values[key] === '') {
+        if (values[key] == null || values[key] === '') {
             if (record.hasOwnProperty(key)) {
                 // user has emptied a field, make the value null
                 sanitizedValues[key] = null;

packages/ra-core/src/form/useApplyInputDefaultValues.ts

@@ -13,13 +13,19 @@ export const useApplyInputDefaultValues = (
 ) => {
     const { defaultValue, source } = props;
     const record = useRecordContext(props);
-    const { getValues, resetField } = useFormContext();
+    const {
+        getValues,
+        resetField,
+        getFieldState,
+        formState,
+    } = useFormContext();
     const recordValue = get(record, source);
     const formValue = get(getValues(), source);
+    const { isDirty } = getFieldState(source, formState);
 
     useEffect(() => {
         if (defaultValue == null) return;
-        if (formValue == null && recordValue == null) {
+        if (formValue == null && recordValue == null && !isDirty) {
             // special case for ArrayInput: since we use get(record, source),
             // if source is like foo.23.bar, this effect will run.
             // but we only want to set the default value for the subfield bar