Release preparations (#20)

* use twig-ux-components in dev and suggest ux packages * fix hardcoded menu add basic usage doc add hints on experimental state of bundle * cs fixer * Update README.md Co-authored-by: Benjamin Schultz <[email protected]> --------- Co-authored-by: Benjamin Schultz <[email protected]>
qossmic · Apr 4, 2024 · 2488b65 · 2488b65
1 parent 23adb72
commit 2488b65
Show file tree

Hide file tree

Showing 9 changed files with 114 additions and 67 deletions.
diff --git a/README.md b/README.md
@@ -2,19 +2,27 @@
 
 [![Image](docs/resources/images/qossmic.png)](https://qossmic.com) Brought to you by qossmic! 
 
-1. [Installation](#installation)
-2. Configuration
+1. [Ye be warned!](#experimental-package)
+2. [Installation](#installation)
+3. Configuration
    1. [Bundle Configuration](docs/BundleConfiguration.md)
    2. [Component Configuration](docs/ComponentConfiguration.md)
-3. [Routing](#routing)
-4. [Customization](#customizing-the-design)
-5. [Usage](docs/Usage.md)
+4. [Routing](#routing)
+5. [Customization](#customizing-the-design)
+6. [Usage](docs/Usage.md)
 
 ---
 
+## Experimental Package
 > **Important**: This is an experimental version and might change drastically. 
 > Therefore, you might encounter breaking changes when updating until we release a stable version. 
 
+- bad templates: due to the lack of frontend capacities, the templates are very "basic"
+  - but as in every Symfony bundle, you can easily overwrite them and create your own :-)
+- incomplete documentation
+- no translations (yet)
+
+###
 Allows you to create an overview for your Twig Components, be it either [UX-Components](https://symfony.com/bundles/ux-twig-component/current/index.html), [UX-Live-Components](https://symfony.com/bundles/ux-live-component/current/index.html) or simple snippet templates.
 
 Components will be grouped in categories and optional sub-categories.

diff --git a/composer.json b/composer.json
@@ -27,6 +27,11 @@
     "symfony/browser-kit": "^6.4|^7.0",
     "symfony/css-selector": "^6.4|^7.0",
     "symfony/dom-crawler": "^6.4|^7.0",
-    "friendsofphp/php-cs-fixer": "^3.51"
+    "friendsofphp/php-cs-fixer": "^3.51",
+    "symfony/ux-twig-component": "^2.16.0"
+  },
+  "suggest": {
+    "symfony/ux-twig-component": "Create native UX components with twig and document them with this bundle",
+    "symfony/ux-live-component": "Create truly reactive frontend components and document them with this bundle"
   }
 }
diff --git a/docs/Usage.md b/docs/Usage.md
@@ -1,5 +1,13 @@
 ## Usage
 
-TODO
-- screenshots of UI
-- searching
+The bundle provides two routes:
+
+- component overview (twig_doc_home, /twig/doc): here are all components listed
+- component view (twig_doc_component_view, /twig/doc/component-view): this route is used to render a component into an iframe
+
+### Overview
+
+This is how a component will look like on the overview page:
+![image](resources/images/overview.png)
+
+As the components are rendered into an iframe, you can view the behaviour of the component for different screen-sizes by simply changing its width.
diff --git a/docs/resources/images/overview.png b/docs/resources/images/overview.png
diff --git a/src/Twig/TwigDocExtension.php b/src/Twig/TwigDocExtension.php
@@ -35,9 +35,13 @@ public function getFunctions(): array
             new TwigFunction('filterComponents', [$this, 'filterComponents']),
             new TwigFunction('getInvalidComponents', [$this, 'getInvalidComponents']),
             new TwigFunction('getSubCategories', [$this, 'getSubCategories']),
+            new TwigFunction('getComponentCategories', [$this, 'getCategories']),
         ];
     }
 
+    /**
+     * @codeCoverageIgnore
+     */
     public function filterComponents(string $filterQuery, ?string $type = null): ComponentItemList
     {
         return $this->componentService->filter($filterQuery, $type);
@@ -86,4 +90,14 @@ private function renderFallback(ComponentItem $item, array $params): string
     {
         return $this->twig->render($item->getRenderPath(), $params);
     }
+
+    /**
+     * @return ComponentCategory[]
+     *
+     * @codeCoverageIgnore
+     */
+    public function getCategories(): array
+    {
+        return $this->categoryService->getCategories();
+    }
 }
diff --git a/templates/blocks/page_blocks.html.twig b/templates/blocks/page_blocks.html.twig
@@ -1,38 +1,66 @@
 {% block head %}
-{% block stylesheets %}
-    <style>
-        {{ include('@TwigDoc/style/style.css.twig') }}
-    </style>
-{% endblock %}
+    {% block stylesheets %}
+        <style>
+            {{ include('@TwigDoc/style/style.css.twig') }}
+        </style>
+    {% endblock %}
     <title>{% block title %}Twig Component Documentation{% endblock %}</title>
-{% block javascripts %}
-    <script type="application/javascript">
-        window.addEventListener('load', () => {
-            document.querySelectorAll('.twig-doc-variation h5').forEach(
-                function (element) {
-                    element.addEventListener('click', function () {
-                        console.log(element);
-                        let variation = element.getAttribute('data-variation');
-                        element.parentNode.querySelectorAll('.twig-doc-variation-body, h5').forEach(
-                            function (e) {
-                                e.classList.remove('active');
-                            });
-                        element.classList.add('active');
-                        element.parentNode.querySelector(`.twig-doc-variation-body[data-variation="${variation}"]`).classList.add('active');
-                    })
-                }
-            )
-            const observer = new ResizeObserver((entries) => {
-                for (const entry of entries) {
-                    entry.target.closest('.twig-doc-variation-body').querySelector('.twig-doc-viewport-width-value').innerText = entry.contentRect.width;
-                }
-            })
-            document.querySelectorAll('.twig-doc-viewport').forEach((e) => {
-                observer.observe(e);
-            })
-        });
-    </script>
+    {% block javascripts %}
+        <script type="application/javascript">
+            window.addEventListener('load', () => {
+                document.querySelectorAll('.twig-doc-variation h5').forEach(
+                    function (element) {
+                        element.addEventListener('click', function () {
+                            let variation = element.getAttribute('data-variation');
+                            element.parentNode.querySelectorAll('.twig-doc-variation-body, h5').forEach(
+                                function (e) {
+                                    e.classList.remove('active');
+                                });
+                            element.classList.add('active');
+                            element.parentNode.querySelector(`.twig-doc-variation-body[data-variation="${variation}"]`).classList.add('active');
+                        })
+                    }
+                )
+                const observer = new ResizeObserver((entries) => {
+                    for (const entry of entries) {
+                        entry.target.closest('.twig-doc-variation-body').querySelector('.twig-doc-viewport-width-value').innerText = entry.contentRect.width;
+                    }
+                })
+                document.querySelectorAll('.twig-doc-viewport').forEach((e) => {
+                    observer.observe(e);
+                })
+            });
+        </script>
+    {% endblock %}
 {% endblock %}
+
+{% block navigation %}
+    <div class="twig-doc-navigation">
+        {% for category in getComponentCategories() %}
+            {% if loop.first %}
+                <ul>
+            {% endif %}
+            <li>
+                <a href="{{ path('twig_doc_home', {filterQuery: category.name, filterType: 'category'}) }}">{{ category.name }}</a>
+                {% for subCategory in getSubCategories(category.name) %}
+                    {% if loop.first %}
+                        <ul>
+                    {% endif %}
+                    <li>
+                        <a href="{{ path('twig_doc_home', {filterQuery: subCategory.name, filterType: 'subCategory'}) }}">
+                            {{ subCategory.name }}
+                        </a>
+                    </li>
+                    {% if loop.last %}
+                        </ul>
+                    {% endif %}
+                {% endfor %}
+            </li>
+            {% if loop.last %}
+                </ul>
+            {% endif %}
+        {% endfor %}
+    </div>
 {% endblock %}
 
 {% block body %}
@@ -45,23 +73,6 @@
             </div>
         {% endif %}
         <div class="twig-doc-body">
-
-            <div class="navigation">
-                <ul>
-                    <li>
-                        <a href="?filterQuery=Atoms&filterType=category">Atoms</a>
-                        <ul>
-                            <li><a href="?filterQuery=Buttons&filterType=sub_category">Buttons</a></li>
-                            <li><a href="?filterQuery=Typography&filterType=sub_category">Typography</a></li>
-                        </ul>
-                    </li>
-                    <li><a href="?filterQuery=Commons&filterType=category">Commons</a></li>
-                    <li><a href="?filterQuery=Snippets&filterType=category">Snippets</a></li>
-                    <li><a href="?filterQuery=Blocks&filterType=category">Blocks</a></li>
-                    <li><a href="?filterQuery=Templates&filterType=category">Templates</a></li>
-                </ul>
-            </div>
-
             {% for component in components %}
                 {% include '@TwigDoc/component/_item.html.twig' with { component: component } %}
             {% endfor %}

diff --git a/templates/documentation.html.twig b/templates/documentation.html.twig
@@ -5,6 +5,7 @@
     {{ block('head') }}
 </head>
 <body>
+    {{ block('navigation') }}
     {{ block('body') }}
 </body>
 </html>
diff --git a/templates/style/style.css.twig b/templates/style/style.css.twig
@@ -1,5 +1,5 @@
 #twig-doc-container {
-    margin-top: 50px;
+    margin-top: 60px;
 }
 #twig-doc-container .breakpoints {
     position: fixed;
@@ -26,7 +26,7 @@
     flex-grow: 1;
 }
 
-#twig-doc-container .navigation {
+.twig-doc-navigation {
     position: fixed;
     left: 0;
     top: 0;
@@ -37,28 +37,28 @@
     z-index: 100;
 }
 
-#twig-doc-container .navigation ul {
+.twig-doc-navigation ul {
     display: flex;
     position: relative;
     flex-direction: row;
 {# margin-bottom: 25px; #}
 }
 
-#twig-doc-container .navigation ul ul {
+.twig-doc-navigation ul ul {
     display: none;
     position: absolute;
 }
 
-#twig-doc-container .navigation li {
+.twig-doc-navigation li {
     list-style: none;
 }
 
-#twig-doc-container .navigation li a {
+.twig-doc-navigation li a {
     padding: 5px 15px;
 }
 
 
-#twig-doc-container .navigation li:hover ul {
+.twig-doc-navigation li:hover ul {
     display: flex;
 }
 
@@ -169,4 +169,4 @@
     width: 100%;
     flex-grow: 1;
     border: 0;
-}
+}
diff --git a/tests/Functional/Twig/TwigDocExtensionTest.php b/tests/Functional/Twig/TwigDocExtensionTest.php
@@ -34,7 +34,7 @@ public function testGetFunctions(): void
         $extension = static::getContainer()->get(TwigDocExtension::class);
         $functions = $extension->getFunctions();
 
-        static::assertCount(4, $functions);
+        static::assertCount(5, $functions);
 
         foreach ($functions as $function) {
             static::assertInstanceOf(TwigFunction::class, $function);