add updates after #1041 fix

src/TwigComponent/doc/index.rst

@@ -1049,10 +1049,9 @@ And in your component template you can access your embedded block
 Anonymous TwigComponent
 -----------------------
 
-Sometimes, reusable elements do not require complex logic or injected service to render what it could be processed
-from one template itself. (e.g. retrieving a customized primary button that could take a different label).
-
-No need for class. Your component matches the namespace of the file you created where components live (see `Twig Template Namespaces`_).
+Sometimes a component is simple enough that it doesn't have any complex logic or injected services.
+In this case, you can skip the class and only create the template. The component name is determined
+by the location of the template (see `Twig Template Namespaces`_):
 
 .. code-block:: html+twig
 
@@ -1062,7 +1061,7 @@ No need for class. Your component matches the namespace of the file you created
         {% endblock %}
     </button>
 
-Then use your component with ``:`` to navigate through the directories:
+Then use your component with ``:`` to navigate through sub-directories (if there are any):
 
 .. code-block:: html+twig
 
@@ -1071,54 +1070,84 @@ Then use your component with ``:`` to navigate through the directories:
     <div>
        <twig:Button:Primary>
            Click Me!
-       </twig:primary>
+       </twig:Button:Primary>
     </div>
 
-Now let's pass props to your button by defining a ``{% props %}`` tag in its view.
-It allows to declare which props are required and which have a default value.
-
-For a required prop "label", and one optional prop "primary":
+Still get all your attributes by rendering the ``attributes`` object in your template:
 
 .. code-block:: html+twig
 
     {# templates/components/Button.html.twig #}
-    {% props label, primary = true %}
-
-    <button class="{{ primary ? 'primary' : 'secondary' }} large rounded">
-        {{ label }}
+    <button {{ attributes }}>
+        {% block content %}
+        {% endblock %}
     </button>
 
-Then use it:
+Then pass any further data to your reusable "button" like so:
 
 .. code-block:: html+twig
 
      {# index.html.twig #}
      ...
     <div>
-       <twig:Button label="Click Me!" />
+        <twig:Button role="button" class="foo">
+            Click Me!
+        </twig:Button>
     </div>
 
-You can also define your component to allow overwriting attributes:
+    {# renders as: #}
+    <button role="button" class="foo">Click Me!</button>
+
+Now let's pass props to your "button" by defining a ``{% props %}`` tag in its view.
+It allows to declare which props are required and which have a default value.
+
+For a required prop "label", and one optional prop "primary":
 
 .. code-block:: html+twig
 
     {# templates/components/Button.html.twig #}
     {% props label, primary = true %}
 
-    <button {{ attributes.defaults({class: primary ? 'primary' : 'secondary'}) }}>
+    <button class="{{ primary ? 'primary' : 'secondary' }} large rounded">
         {{ label }}
     </button>
 
-And use it like so:
+And use it:
 
 .. code-block:: html+twig
 
      {# index.html.twig #}
      ...
     <div>
-        <twig:Button label="Click Me!" :primary="false" />
+       <twig:Button label="Click Me!" />
     </div>
 
+.. note::
+
+    Definining a property in ``{% props %}`` makes it accessible as a variable and not available inside the ``attributes`` object once passed to the component.
+
+    .. code-block:: html+twig
+
+        {# templates/components/Button.html.twig #}
+        {% props label, disabled = false %}
+
+        <button {{ attributes.defaults({class: disabled ? 'disabled' : 'default'}) }}>
+            {{ label }}
+        </button>
+
+    This means that ``disabled`` is used here to set a class name but will not be rendered in HTML attributes:
+
+    .. code-block:: html+twig
+
+         {# index.html.twig #}
+         ...
+        <div>
+            <twig:Button label="Click Me!" :disabled="true" />
+        </div>
+
+        {# renders as: #}
+        <button class="disabled">Click Me!</button>
+
 Test Helpers
 ------------