[TwigComponent] Document high-order components

Author: Kocal

src/TwigComponent/doc/index.rst

@@ -1266,6 +1266,46 @@ The nesting is recursive so you could potentially do something like this:
         row:widget:class="ui-form-widget"
     />
 
+Higher-Order Components (Component Wrappers)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can create a component that wraps another component while adding its own
+default attributes. This is useful for creating component variants without
+duplicating code.
+
+For example, create a base ``Button`` component:
+
+.. code-block:: html+twig
+
+    {# templates/components/Button.html.twig #}
+    <button{{ attributes.defaults({type: 'button', class: 'btn'}) }}>
+        {% block content %}{% endblock %}
+    </button>
+
+Then create a ``Button:Primary`` variant that wraps it:
+
+.. code-block:: html+twig
+
+    {# templates/components/Button/Primary.html.twig #}
+    <twig:Button {{ ...attributes.defaults({class: 'btn-primary'}) }}>
+        {{ block(outerBlocks.content) }}
+    </twig:Button>
+
+Usage:
+
+.. code-block:: html+twig
+
+    <twig:Button:Primary>Save</twig:Button:Primary>
+    {# <button type="button" class="btn btn-primary">Save</button> #}
+
+    <twig:Button:Primary class="btn-lg">Save</twig:Button:Primary>
+    {# <button type="button" class="btn btn-primary btn-lg">Save</button> #}
+
+The key parts are:
+
+- **Spread operator** ``{{ ...attributes.defaults() }}`` - passes attributes to wrapped component
+- **``outerBlocks``** - forwards content blocks to the wrapped component
+
 Component with Complex Variants (CVA)
 -------------------------------------
 

src/TwigComponent/tests/Fixtures/templates/components/SimpleButton.html.twig

@@ -0,0 +1,3 @@
+<button{{ attributes.defaults({type: 'button', class: 'btn'}) }}>
+    {% block content %}{% endblock %}
+</button>

src/TwigComponent/tests/Fixtures/templates/components/SimpleButton/Primary.html.twig

@@ -0,0 +1,3 @@
+<twig:SimpleButton {{ ...attributes.defaults({class: 'btn-primary'}) }}>
+    {{ block(outerBlocks.content) }}
+</twig:SimpleButton>

src/TwigComponent/tests/Fixtures/templates/higher_order_component.html.twig

@@ -0,0 +1,11 @@
+{# Test base SimpleButton component #}
+<twig:SimpleButton>Click me</twig:SimpleButton>
+
+{# Test SimpleButton:Primary wrapper component #}
+<twig:SimpleButton:Primary>Save</twig:SimpleButton:Primary>
+
+{# Test SimpleButton:Primary with custom class #}
+<twig:SimpleButton:Primary class="btn-lg">Save</twig:SimpleButton:Primary>
+
+{# Test SimpleButton:Primary with other attributes #}
+<twig:SimpleButton:Primary data-action="delete">Delete</twig:SimpleButton:Primary>

src/TwigComponent/tests/Integration/ComponentExtensionTest.php

@@ -488,6 +488,23 @@ public function testAnonymousComponentWithPropsOverwriteParentsProps()
         $this->assertStringNotContainsString('I am md', $output);
     }
 
+    public function testHigherOrderComponentWithAttributeDefaults()
+    {
+        $output = self::getContainer()->get(Environment::class)->render('higher_order_component.html.twig');
+
+        // Test base SimpleButton component
+        $this->assertStringContainsString('<button type="button" class="btn">Click me</button>', $output);
+
+        // Test SimpleButton:Primary wrapper component - should merge btn and btn-primary classes
+        $this->assertStringContainsString('<button type="button" class="btn btn-primary">Save</button>', $output);
+
+        // Test SimpleButton:Primary with custom class - should merge all three classes
+        $this->assertStringContainsString('<button type="button" class="btn btn-primary btn-lg">Save</button>', $output);
+
+        // Test SimpleButton:Primary with data attribute
+        $this->assertStringContainsString('<button type="button" class="btn btn-primary" data-action="delete">Delete</button>', $output);
+    }
+
     private function renderComponent(string $name, array $data = []): string
     {
         return self::getContainer()->get(Environment::class)->render('render_component.html.twig', [