Enhance docs

docs/guide/upgrading/9.0.md

@@ -175,6 +175,31 @@ And rename old icon names to blade-fontawesome names in your `SharpMenu` :
 ```
 If you were using old fontawesome 4 icons you may need to [rename them](https://docs.fontawesome.com/v5/web/setup/upgrade-from-v4#icon-name-changes-between-version-4-and-5).
 
+### Restore fontawesome icons default behavior *(optional)*
+
+As the default behavior of `blade-icons` (which uses an `svg` tag) differs from the previous behavior of FontAwesome’s `<i/>` tag (which was inline and matched the font size), you may need to adjust the `blade-icons` configuration to replicate the original behavior.
+
+First, publish the FontAwesome blade-icons configuration file:
+```bash
+php artisan vendor:publish --tag=blade-fontawesome-config
+``` 
+
+Then add default attributes for each FontAwesome classes (solid, regular, brands, and optionally pro):
+```php
+// file: config/blade-fontawesome.php
+return [
+    // ...
+    'regular' => [
+      // ...
+      'attributes' => [
+          'width' => '1rem',
+          'height' => '1rem',
+          'style' => 'display: inline;'
+      ],
+    ],
+];
+```
+
 ## No more Bootstrap.css / Font awesome classes
 
 You may be using Custom HTML (entity list row, editor embeds, form HTML field, form Autocomplete item template, page alerts) with CSS classes that was present in Sharp 8.x but that don't exist anymore:
@@ -184,7 +209,7 @@ You may be using Custom HTML (entity list row, editor embeds, form HTML field, f
   - Inject a custom CSS file as described [here](../style-visual-theme.md)
 - If you were using inline Font Awesome icons like `<i class="fas fa-user">`
   - Using [blade-fontawesome](https://github.com/owenvoke/blade-fontawesome) component like : `<x-fas-user style="width: 1rem; height: 1rem" />`. In Sharp 9.x all templates are now Blade.
-  - For `<i class="fas fa-user">` inside a custom transformer of an EntityList field, you must now do `Blade::render('<x-fas-user style="width: 1rem; height: 1rem" />')`
+  - For `<i class="fas fa-user">` inside a custom transformer of an EntityList field, you must now do `Blade::render('<x-fas-user style="width: 1rem; height: 1rem; display:inline;" />')`
 
 ## Page Alerts (aka global messages) are not based on Vue templates anymore
 
@@ -558,12 +583,13 @@ This shouldn’t cause any trouble, as this is a fix, but it could break unortho
 
 ## New validation system (and deprecation of the old one)
 
-The validation system was odd, for legacy reasons.
-In 9.x, it has been rewritten to be in phase with Laravel and to be more consistent:
+The validation system has been revamped in version 9.x to align better with Laravel and improve consistency.
+
+You may now define your validation rules in two ways:
+- implement new `rules()` and `messages()` methods in your `SharpForm` or `Command`; those methods accepts an optional `$formattedData` parameter which represents the... formatted posted data.
+- or make a call to `->validate(array $data, array $rules)`.
 
-- validation rules can now be defined in a `rules()` method of the form / command class,
-- or with a `->validate($data, $rules)` call before update / store.
-- The `$formValidatorClass` property usage, in a `SharpForm`, is now deprecated (you are strongly encouraged to migrate to the `rules()` method instead).
+In consequence, **Form Validators are now deprecated**: the `$formValidatorClass` property in `SharpForm` is deprecated. You are strongly encouraged to switch to the `rules()` method.
 
 This code in 8.x:
 ```php
@@ -623,14 +649,29 @@ class PostForm extends SharpForm
 This version brings two huge benefits (besides the fact that it's clearer):
 
 - the "delayed creation" thing is gone (hooray!): the `{id}` parameter in a `SharpFormUploadField` storageBasePath isn't anymore an issue in creation case as Sharp will no longer call the `update()` method twice.
-- Validation is now called AFTER data formatters, even in `SharpForm` (it was already the case with `Command`).
-
-**Breaking changes**: the 8.x and below validation is still allowed, but deprecated.
-
-If you decide to migrate (and you should), pay attention to:
+- **Validation is now called AFTER data formatters**, even in `SharpForm` (it was already the case with `Command`). This cause a breaking change (see below).
 
+**If you decide to migrate** to this new validation system (and you should), pay attention to:
 - remove special workarounds you may have done to handle the "delayed creation" thing,
-- remove the `.text` suffix you may have added for `SharpFormEditorField` validation rules.
+- remove the `.text` suffix you may have added for `SharpFormEditorField` validation rules,
+- remove the common `.id` suffix you may have added for `SharpFormAutocomplete(Remote|Local)Field` validation rules.
+
+Here's a code example (in which editor is a `SharpFormEditorField` and authors is a `SharpFormAutocompleteLocalField`):
+```diff
+class PostForm extends SharpForm
+{
+    // ...
+    public function rules(): array
+    {
+        return [
+-            'editor.text' => 'required',
++            'editor' => 'required',
+-            'authors.id' => 'required',
++            'authors' => 'required',            
+        ];
+    }
+}
+```
 
 **If you decide not to migrate just now**, you should ensure that the `\Code16\Sharp\Http\Middleware\Api\BindSharpValidationResolver` middleware in added to the `api` group: