Docs(web-twig): Introduce DocsSection and DocsBox components

- New components: `DocsSection`, `DocsBox`. - CSS class `docs-FormFieldGrid` has been dropped. `DocsSection` displays title and automatically provides proper spacing to its content. Before: ```html <section class="docs-Section"> <h2 class="docs-Heading"> Basic Usage <span class="Tag Tag--warning Tag--medium Tag--subtle">Visual demo only</span> </h2> <div class="docs-FormFieldGrid"> <div class="docs-Box">…</div> </div> </section> ``` After: ```twig <DocsSection title="Basic Usage" tag="Visual demo only"> <DocsBox>…</DocsBox> </DocsSection> ```
lmc-eu · Sep 1, 2023 · fcb97dc · fcb97dc
1 parent e9dfab2
commit fcb97dc
Show file tree

Hide file tree

Showing 15 changed files with 159 additions and 8 deletions.
diff --git a/apps/web-twig-demo/config/packages/spirit_web_twig.yaml b/apps/web-twig-demo/config/packages/spirit_web_twig.yaml
@@ -1,4 +1,7 @@
 spirit_web_twig:
+  paths:
+    - '%kernel.project_dir%/../spirit-web-twig-bundle/docs/components'
+    - '%kernel.project_dir%/../spirit-web-twig-bundle/docs/twig-components'
   icons:
     paths:
       - '%kernel.project_dir%/../spirit-web-twig-bundle/static'
diff --git a/apps/web-twig-demo/public/css/demo.css b/apps/web-twig-demo/public/css/demo.css
@@ -32,6 +32,16 @@
   line-height: 1.2;
 }
 
+.docs-Stack {
+  display: grid;
+  row-gap: 1rem;
+  justify-items: start;
+}
+
+.docs-Stack--fluid {
+  justify-items: initial;
+}
+
 .docs-Box {
   min-height: 2rem;
   padding: 1rem;
@@ -48,12 +58,6 @@
   white-space: normal;
 }
 
-.docs-FormFieldGrid {
-  display: grid;
-  grid-template-columns: 25rem;
-  gap: 1.5rem;
-}
-
 @media (min-width: 768px) {
   .docs-TileLink {
     padding: 1.5rem;

diff --git a/packages/web-twig/docs/components/DocsBox/DocsBox.twig b/packages/web-twig/docs/components/DocsBox/DocsBox.twig
@@ -0,0 +1,19 @@
+{# API #}
+{%- set props = props | default([]) -%}
+{%- set _size = props.size | default('medium') -%}
+
+{# Class names #}
+{%- set _rootClassName = 'docs-Box' -%}
+{%- set _rootSizeClassName = 'docs-Box--' ~ _size -%}
+
+{# Miscellaneous #}
+{%- set _styleProps = useStyleProps(props) -%}
+{%- set _rootClassNames = [_rootClassName, _rootSizeClassName, _styleProps.className] -%}
+
+<div
+    {{ mainProps(props) }}
+    {{ styleProp(_styleProps) }}
+    {{ classProp(_rootClassNames) }}
+>
+    {% block content %}{% endblock %}
+</div>
diff --git a/packages/web-twig/docs/components/DocsBox/__tests__/DocsBoxSnapshotTest.php b/packages/web-twig/docs/components/DocsBox/__tests__/DocsBoxSnapshotTest.php
@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Lmc\SpiritWebTwigBundle\Resources\components\DocsBox;
+
+use Lmc\SpiritWebTwigBundle\AbstractComponentSnapshotTest;
+
+class DocsBoxSnapshotTest extends AbstractComponentSnapshotTest
+{
+}
diff --git a/packages/web-twig/docs/components/DocsBox/__tests__/__fixtures__/docsBoxDefault.twig b/packages/web-twig/docs/components/DocsBox/__tests__/__fixtures__/docsBoxDefault.twig
@@ -0,0 +1,7 @@
+<DocsBox />
+
+<!-- Render with content -->
+<DocsBox>my content</DocsBox>
+
+<!-- Render with all props -->
+<DocsBox size="small">my content</DocsBox>
diff --git a/...es/web-twig/docs/components/DocsBox/__tests__/__snapshots__/docsBoxDefault.twig.snap.html b/...es/web-twig/docs/components/DocsBox/__tests__/__snapshots__/docsBoxDefault.twig.snap.html
@@ -0,0 +1,21 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <title>
+    </title>
+  </head>
+  <body>
+    <div class="docs-Box docs-Box--medium">
+    </div>
+    <!-- Render with content -->
+
+    <div class="docs-Box docs-Box--medium">
+      my content
+    </div>
+    <!-- Render with all props -->
+
+    <div class="docs-Box docs-Box--small">
+      my content
+    </div>
+  </body>
+</html>
diff --git a/packages/web-twig/docs/components/DocsSection/DocsSection.twig b/packages/web-twig/docs/components/DocsSection/DocsSection.twig
@@ -0,0 +1,32 @@
+{# API #}
+{%- set props = props | default([]) -%}
+{%- set _hasFluidLayout = props.hasFluidLayout | default(false) -%}
+{%- set _tag = props.tag | default(null) -%}
+{%- set _title = props.title -%}
+
+{# Class names #}
+{%- set _rootClassName = 'docs-Section' -%}
+{%- set _headingClassName = 'docs-Heading' -%}
+{%- set _stackClassName = 'docs-Stack' -%}
+{%- set _stackFluidClassName = _hasFluidLayout ? 'docs-Stack--fluid' : null -%}
+
+{# Miscellaneous #}
+{%- set _styleProps = useStyleProps(props) -%}
+{%- set _rootClassNames = [_rootClassName, _styleProps.className] -%}
+{%- set _stackClassNames = [_stackClassName, _stackFluidClassName] -%}
+
+<section
+    {{ mainProps(props) }}
+    {{ styleProp(_styleProps) }}
+    {{ classProp(_rootClassNames) }}
+>
+    <h2 class="{{ _headingClassName }}">
+        {{ _title }}
+        {% if _tag %}
+            <Tag color="warning" isSubtle>{{ _tag }}</Tag>
+        {% endif %}
+    </h2>
+    <div {{ classProp(_stackClassNames) }}>
+        {% block content %}{% endblock %}
+    </div>
+</section>
diff --git a/packages/web-twig/docs/components/DocsSection/__tests__/DocsSectionSnapshotTest.php b/packages/web-twig/docs/components/DocsSection/__tests__/DocsSectionSnapshotTest.php
@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Lmc\SpiritWebTwigBundle\Resources\components\DocsSection;
+
+use Lmc\SpiritWebTwigBundle\AbstractComponentSnapshotTest;
+
+class DocsSectionSnapshotTest extends AbstractComponentSnapshotTest
+{
+}
diff --git a/packages/web-twig/docs/components/DocsSection/__tests__/__fixtures__/docsSectionDefault.twig b/packages/web-twig/docs/components/DocsSection/__tests__/__fixtures__/docsSectionDefault.twig
@@ -0,0 +1,4 @@
+<DocsSection title="My Title" />
+
+<!-- Render with all props -->
+<DocsSection tag="My tag" title="My Title">my content</DocsSection>
diff --git a/...wig/docs/components/DocsSection/__tests__/__snapshots__/docsSectionDefault.twig.snap.html b/...wig/docs/components/DocsSection/__tests__/__snapshots__/docsSectionDefault.twig.snap.html
@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <title>
+    </title>
+  </head>
+  <body>
+    <section class="docs-Section">
+      <h2 class="docs-Heading">
+        My Title
+      </h2>
+
+      <div class="docs-Stack">
+      </div>
+    </section>
+    <!-- Render with all props -->
+
+    <section class="docs-Section">
+      <h2 class="docs-Heading">
+        My Title <span class="Tag Tag--warning Tag--medium Tag--subtle">My tag</span>
+      </h2>
+
+      <div class="docs-Stack">
+        my content
+      </div>
+    </section>
+  </body>
+</html>
diff --git a/packages/web-twig/docs/twig-components/docsBox.twig b/packages/web-twig/docs/twig-components/docsBox.twig
@@ -0,0 +1 @@
+{% extends '@spirit/DocsBox/DocsBox.twig' %}
diff --git a/packages/web-twig/docs/twig-components/docsSection.twig b/packages/web-twig/docs/twig-components/docsSection.twig
@@ -0,0 +1 @@
+{% extends '@spirit/DocsSection/DocsSection.twig' %}
diff --git a/packages/web-twig/phpunit.xml.dist b/packages/web-twig/phpunit.xml.dist
@@ -27,6 +27,7 @@
             <!-- Tests defined by directory are run in serial mode. Mind the order! -->
             <!-- Solves the problem of AbstractComponentSnapshotTest vs ComponentTest where Twig namespace differs from each other -->
             <!-- @see: https://stackoverflow.com/questions/10228/run-phpunit-tests-in-certain-order -->
+            <directory suffix="Test.php">docs/components/**/__tests__/</directory>
             <directory suffix="Test.php">src/Resources/components/**/__tests__/</directory>
             <directory suffix="Test.php">tests/</directory>
         </testsuite>

diff --git a/packages/web-twig/src/Resources/components/Pill/__tests__/PillSnapshotTest.php b/packages/web-twig/src/Resources/components/Pill/__tests__/PillSnapshotTest.php
@@ -6,6 +6,6 @@
 
 use Lmc\SpiritWebTwigBundle\AbstractComponentSnapshotTest;
 
-class PillwSnapshotTest extends AbstractComponentSnapshotTest
+class PillSnapshotTest extends AbstractComponentSnapshotTest
 {
 }
diff --git a/packages/web-twig/tests/Helper/TwigHelper.php b/packages/web-twig/tests/Helper/TwigHelper.php
@@ -25,7 +25,15 @@ public static function setup(
         array $extendedComponentsPath = []
     ): Environment {
         $loader = new FilesystemLoader($defaultTemplatePath);
-        $paths = array_merge($extendedComponentsPath, [SpiritWebTwigExtension::DEFAULT_TWIG_COMPONENTS_PATH, SpiritWebTwigExtension::DEFAULT_COMPONENTS_PATH]);
+        $paths = array_merge(
+            $extendedComponentsPath,
+            [
+                SpiritWebTwigExtension::DEFAULT_TWIG_COMPONENTS_PATH,
+                SpiritWebTwigExtension::DEFAULT_COMPONENTS_PATH,
+                __DIR__ . '/../../docs/components',
+                __DIR__ . '/../../docs/twig-components',
+            ]
+        );
 
         foreach ($paths as $path) {
             $loader->addPath($path, $defaultAlias);