add docs

Author: kbond

src/TwigComponent/src/Resources/doc/index.rst

@@ -415,6 +415,135 @@ you can store its result on a private property:
           }
       }
 
+Component Attributes
+--------------------
+
+A common need for components is to configure/render attributes for the
+root node. You can enable this feature by having your component use
+the ``HasAttributesTrait``.  Attributes are any data passed to ``component()``
+that cannot be mounted on the component itself. This extra data is added
+to a ``ComponentAttributes`` object that lives as a public property on your
+component (available as ``attributes`` in your component's template).
+
+To use, add the HasAttributesTrait to your component:
+
+    use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;
+    use Symfony\UX\TwigComponent\HasAttributesTrait;
+
+    #[AsTwigComponent('my_component')]
+    class MyComponent
+    {
+        use HasAttributesTrait;
+    }
+
+.. code-block:: twig
+
+    {# templates/components/my_component.html.twig #}
+
+    <div{{ attributes }}>
+      My Component!
+    </div>
+
+When rendering the component, you can pass an array of html attributes to add:
+
+.. code-block:: twig
+
+    {{ component('my_component', { class: 'foo', style: 'color:red' }) }}
+
+    {# renders as: #}
+    <div class="foo" style="color:red">
+      My Component!
+    </div>
+
+Defaults
+~~~~~~~~
+
+Set default attributes that can be fully overridden by passed attributes:
+
+.. code-block:: twig
+
+    {# templates/components/my_component.html.twig #}
+
+    <div{{ attributes.defaults({ class: 'bar' }) }}>
+      My Component!
+    </div>
+
+    {# render component #}
+    {{ component('my_component', { style: 'color:red' }) }}
+    {{ component('my_component', { class: 'foo', style: 'color:red' }) }}
+
+    {# renders as: #}
+    <div class="bar" style="color:red">
+      My Component!
+    </div>
+    <div class="foo" style="color:red">
+      My Component!
+    </div>
+
+Merging Defaults
+~~~~~~~~~~~~~~~~
+
+Set defaults but allow them to be appended to by passing these values to
+the ``component()`` function:
+
+.. code-block:: twig
+
+    {# templates/components/my_component.html.twig #}
+
+    <div{{ attributes.merge({ class: 'bar' }) }}>
+      My Component!
+    </div>
+
+    {# render component #}
+    {{ component('my_component', { class: 'foo', style: 'color:red' }) }}
+
+    {# renders as: #}
+    <div class="bar foo" style="color:red">
+      My Component!
+    </div>
+
+Only
+~~~~
+
+Extract specific attributes and discard the rest:
+
+.. code-block:: twig
+
+    {# templates/components/my_component.html.twig #}
+
+    <div{{ attributes.only('class') }}>
+      My Component!
+    </div>
+
+    {# render component #}
+    {{ component('my_component', { class: 'foo', style: 'color:red' }) }}
+
+    {# renders as: #}
+    <div class="foo">
+      My Component!
+    </div>
+
+Without
+~~~~~~~
+
+Exclude specific attributes:
+
+.. code-block:: twig
+
+    {# templates/components/my_component.html.twig #}
+
+    <div{{ attributes.without('class') }}>
+      My Component!
+    </div>
+
+    {# render component #}
+    {{ component('my_component', { class: 'foo', style: 'color:red' }) }}
+
+    {# renders as: #}
+    <div style="color:red">
+      My Component!
+    </div>
+
 Embedded Components
 -------------------