docs(grid): Add documentation about grid mutators

docs/SUMMARY.md

@@ -56,6 +56,7 @@
   * [Fields](grid/fields.md)
   * [Filters](grid/filters.md)
   * [Actions](grid/actions.md)
+  * [Mutators](grid/mutators.md)
   * [Advanced configuration](grid/advanced_configuration.md)
   * [Configuration Reference](grid/configuration.md)
 

docs/grid/index.md

@@ -23,5 +23,6 @@ Menu
 * [Fields](fields.md)
 * [Filters](filters.md)
 * [Actions](actions.md)
+* [Mutators](mutators.md)
 * [Advanced configuration](advanced_configuration.md)
 * [Configuration Reference](configuration.md)

docs/grid/mutators.md

@@ -0,0 +1,59 @@
+# Mutators
+
+When using packages that provide built-in grids (such as Sylius E-Commerce or Sylius plugins), you may need to customize their configuration.
+
+Grid mutators allow you to modify an existing grid without overriding its original definition.
+
+## Usage
+
+Let's assume the `app_book` grid already contains a `title` field.
+We want the grid to be sorted by title.
+
+To achieve this, create the following grid mutator:
+
+```php
+<?php
+
+namespace App\Grid\Mutator;
+
+use Sylius\Bundle\GridBundle\Builder\GridBuilderInterface;
+use Sylius\Component\Grid\Attribute\AsGridMutator;
+use Sylius\Component\Grid\Mutator\GridMutatorInterface;
+
+#[AsGridMutator(grid: 'app_book')]
+final class SortByTitleBookGridMutator implements GridMutatorInterface
+{
+    public function __invoke(GridBuilderInterface $gridBuilder): void
+    {
+        $gridBuilder->orderBy('title', 'asc');
+    }
+}
+```
+
+## Priorities
+
+If multiple mutators target the same grid, you can control the order in which they are executed by using the `priority` option.
+
+Mutators with a higher priority are executed before those with a lower priority.
+
+```diff
+<?php
+
+namespace App\Grid\Mutator;
+
+use Sylius\Bundle\GridBundle\Builder\GridBuilderInterface;
+use Sylius\Component\Grid\Attribute\AsGridMutator;
+use Sylius\Component\Grid\Mutator\GridMutatorInterface;
+
+#[AsGridMutator(
+    grid: 'app_book',
++    priority: 20,
+)]
+final class SortByTitleBookGridMutator implements GridMutatorInterface
+{
+    public function __invoke(GridBuilderInterface $gridBuilder): void
+    {
+        $gridBuilder->orderBy('title', 'asc');
+    }
+}
+```