Merge pull request #994 from phpDocumentor/backport/1.x/pr-993

[1.x] [FEATURE] Introduce directives for bootstrap cards

packages/guides-theme-bootstrap/resources/config/guides-theme-bootstrap.php

@@ -2,6 +2,12 @@
 
 declare(strict_types=1);
 
+use phpDocumentor\Guides\Bootstrap\Directives\CardDirective;
+use phpDocumentor\Guides\Bootstrap\Directives\CardFooterDirective;
+use phpDocumentor\Guides\Bootstrap\Directives\CardGridDirective;
+use phpDocumentor\Guides\Bootstrap\Directives\CardGroupDirective;
+use phpDocumentor\Guides\Bootstrap\Directives\CardHeaderDirective;
+use phpDocumentor\Guides\Bootstrap\Directives\CardImageDirective;
 use phpDocumentor\Guides\Bootstrap\Directives\TabDirective;
 use phpDocumentor\Guides\Bootstrap\Directives\TabsDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\BaseDirective;
@@ -20,6 +26,12 @@
         ->bind('$startingRule', service(DirectiveContentRule::class))
         ->instanceof(BaseDirective::class)
         ->tag('phpdoc.guides.directive')
+        ->set(CardDirective::class)
+        ->set(CardFooterDirective::class)
+        ->set(CardHeaderDirective::class)
+        ->set(CardImageDirective::class)
+        ->set(CardGroupDirective::class)
+        ->set(CardGridDirective::class)
         ->set(TabDirective::class)
         ->set(TabsDirective::class);
 };

packages/guides-theme-bootstrap/resources/template/body/directive/card-grid.html.twig

@@ -0,0 +1,15 @@
+<div class="row card-group
+{%- if node.classes %} {{ node.classesString }}{% endif -%}
+{%- if node.columns > 0 %} row-cols-{{ node.columns }}{% endif -%}
+{%- if node.columnsSm > 0 %} row-cols-sm-{{ node.columnsSm }}{% endif -%}
+{%- if node.columnsMd > 0 %} row-cols-md-{{ node.columnsMd }}{% endif -%}
+{%- if node.columnsLg > 0 %} row-cols-lg-{{ node.columnsLg }}{% endif -%}
+{%- if node.columnsXl > 0 %} row-cols-xl-{{ node.columnsXl }}{% endif -%}
+{%- if node.gap > 0 %} g-{{ node.gap }}{% endif -%}
+">
+    {% for card in node.value -%}
+        <div class="col">
+            {{ renderNode(card) }}
+        </div>
+    {%- endfor %}
+</div>

packages/guides-theme-bootstrap/resources/template/body/directive/card-group.html.twig

@@ -0,0 +1,3 @@
+<div class="card-group {%- if node.classes %} {{ node.classesString }}{% endif %}">
+    {{ renderNode(node.value) }}
+</div>

packages/guides-theme-bootstrap/resources/template/body/directive/card.html.twig

@@ -0,0 +1,34 @@
+<div class="card {%- if node.cardHeight > 0 %} h-{{ node.cardHeight }}{% endif %} {%- if node.classes %} {{ node.classesString }}{% endif %}"  {%- if node.isNoindex == false %} id="{{ node.anchor }}"{% endif %}>
+    {% if node.cardHeader %}
+        <div class="card-header">
+            {% if node.cardHeader.content %}
+                {{ renderNode(node.cardHeader.content) }}
+            {% endif %}
+            {% if node.cardHeader.value %}
+                {{ renderNode(node.cardHeader.value) }}
+            {% endif %}
+        </div>
+    {% endif %}
+    {% if node.cardImage and node.cardImage.position != 'bottom' %}
+        {% include "body/directive/card/card-image.html.twig" %}
+    {% endif %}
+    <div class="card-body">
+        {{ renderNode(node.title) }}
+        <div class="card-text">
+            {{ renderNode(node.value) }}
+        </div>
+    </div>
+    {% if node.cardImage and node.cardImage.position == 'bottom' %}
+        {% include "body/directive/card/card-image.html.twig" %}
+    {% endif %}
+    {% if node.cardFooter %}
+        <div class="card-footer">
+            {% if node.cardFooter.content %}
+                {{ renderNode(node.cardFooter.content) }}
+            {% endif %}
+            {% if node.cardFooter.value %}
+                {{ renderNode(node.cardFooter.value) }}
+            {% endif %}
+        </div>
+    {% endif %}
+</div>

packages/guides-theme-bootstrap/resources/template/body/directive/card/card-image.html.twig

@@ -0,0 +1,8 @@
+<img src="{{ asset(node.cardImage.plainContent) }}" class="card-img-{{ node.cardImage.position }}" alt="{{ node.cardImage.alt }}">
+{% if node.cardImage.value %}
+    <div class="card-img-overlay">
+        <div class="card-text">
+            {{ renderNode(node.cardImage.value) }}
+        </div>
+    </div>
+{% endif %}

packages/guides-theme-bootstrap/src/Bootstrap/Directives/CardDirective.php

@@ -0,0 +1,97 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link https://phpdoc.org
+ */
+
+namespace phpDocumentor\Guides\Bootstrap\Directives;
+
+use phpDocumentor\Guides\Bootstrap\Nodes\Card\CardFooterNode;
+use phpDocumentor\Guides\Bootstrap\Nodes\Card\CardHeaderNode;
+use phpDocumentor\Guides\Bootstrap\Nodes\Card\CardImageNode;
+use phpDocumentor\Guides\Bootstrap\Nodes\CardNode;
+use phpDocumentor\Guides\Nodes\CollectionNode;
+use phpDocumentor\Guides\Nodes\InlineCompoundNode;
+use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\Nodes\TitleNode;
+use phpDocumentor\Guides\ReferenceResolvers\AnchorNormalizer;
+use phpDocumentor\Guides\RestructuredText\Directives\SubDirective;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
+use phpDocumentor\Guides\RestructuredText\Parser\Directive;
+use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
+use phpDocumentor\Guides\RestructuredText\TextRoles\GenericLinkProvider;
+
+class CardDirective extends SubDirective
+{
+    public const NAME = 'card';
+
+    public function __construct(
+        protected Rule $startingRule,
+        GenericLinkProvider $genericLinkProvider,
+        private readonly AnchorNormalizer $anchorReducer,
+    ) {
+        parent::__construct($startingRule);
+
+        $genericLinkProvider->addGenericLink(self::NAME, CardNode::LINK_TYPE, CardNode::LINK_PREFIX);
+    }
+
+    public function getName(): string
+    {
+        return self::NAME;
+    }
+
+    protected function processSub(
+        BlockContext $blockContext,
+        CollectionNode $collectionNode,
+        Directive $directive,
+    ): Node|null {
+        $title = null;
+        if ($directive->getDataNode() !== null) {
+            $title = new TitleNode($directive->getDataNode(), 3, $this->getName());
+            $title->setClasses(['card-title']);
+        }
+
+        $originalChildren = $collectionNode->getChildren();
+        $children = [];
+        $header = null;
+        $image = null;
+        $footer = null;
+        foreach ($originalChildren as $child) {
+            if ($child instanceof CardHeaderNode) {
+                $header = $child;
+            } elseif ($child instanceof CardImageNode) {
+                $image = $child;
+            } elseif ($child instanceof CardFooterNode) {
+                $footer = $child;
+            } else {
+                $children[] = $child;
+            }
+        }
+
+        $id = '';
+        if ($directive->hasOption('name')) {
+            $id = $directive->getOption('name')->toString();
+        }
+
+        $id = $this->anchorReducer->reduceAnchor($id);
+
+        return new CardNode(
+            $this->getName(),
+            $directive->getData(),
+            $directive->getDataNode() ?? new InlineCompoundNode(),
+            $title,
+            $children,
+            $header,
+            $image,
+            $footer,
+            $id,
+        );
+    }
+}

packages/guides-theme-bootstrap/src/Bootstrap/Directives/CardFooterDirective.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link https://phpdoc.org
+ */
+
+namespace phpDocumentor\Guides\Bootstrap\Directives;
+
+use phpDocumentor\Guides\Bootstrap\Nodes\Card\CardFooterNode;
+use phpDocumentor\Guides\Nodes\CollectionNode;
+use phpDocumentor\Guides\Nodes\InlineCompoundNode;
+use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\RestructuredText\Directives\SubDirective;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
+use phpDocumentor\Guides\RestructuredText\Parser\Directive;
+
+class CardFooterDirective extends SubDirective
+{
+    public function getName(): string
+    {
+        return 'card-footer';
+    }
+
+    protected function processSub(
+        BlockContext $blockContext,
+        CollectionNode $collectionNode,
+        Directive $directive,
+    ): Node|null {
+        return new CardFooterNode(
+            $this->getName(),
+            $directive->getData(),
+            $directive->getDataNode() ?? new InlineCompoundNode(),
+        );
+    }
+}

packages/guides-theme-bootstrap/src/Bootstrap/Directives/CardGridDirective.php

@@ -0,0 +1,76 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link https://phpdoc.org
+ */
+
+namespace phpDocumentor\Guides\Bootstrap\Directives;
+
+use phpDocumentor\Guides\Bootstrap\Nodes\CardGridNode;
+use phpDocumentor\Guides\Bootstrap\Nodes\CardNode;
+use phpDocumentor\Guides\Nodes\CollectionNode;
+use phpDocumentor\Guides\Nodes\InlineCompoundNode;
+use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\RestructuredText\Directives\SubDirective;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
+use phpDocumentor\Guides\RestructuredText\Parser\Directive;
+use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
+use Psr\Log\LoggerInterface;
+
+use function intval;
+
+class CardGridDirective extends SubDirective
+{
+    public function __construct(
+        protected Rule $startingRule,
+        private readonly LoggerInterface $logger,
+    ) {
+        parent::__construct($startingRule);
+    }
+
+    public function getName(): string
+    {
+        return 'card-grid';
+    }
+
+    protected function processSub(
+        BlockContext $blockContext,
+        CollectionNode $collectionNode,
+        Directive $directive,
+    ): Node|null {
+        $title = null;
+        $originalChildren = $collectionNode->getChildren();
+        $children = [];
+        $cardHeight = intval($directive->getOption('card-height')->getValue());
+        foreach ($originalChildren as $child) {
+            if ($child instanceof CardNode) {
+                $children[] = $child;
+                if ($cardHeight > 0) {
+                    $child->setCardHeight($cardHeight);
+                }
+            } else {
+                $this->logger->warning('A card-grid may only contain cards. ', $blockContext->getLoggerInformation());
+            }
+        }
+
+        return new CardGridNode(
+            $this->getName(),
+            $directive->getData(),
+            $directive->getDataNode() ?? new InlineCompoundNode(),
+            $children,
+            intval($directive->getOption('columns')->getValue() ?? 0),
+            intval($directive->getOption('columns-sm')->getValue() ?? 0),
+            intval($directive->getOption('columns-md')->getValue() ?? 0),
+            intval($directive->getOption('columns-lg')->getValue() ?? 0),
+            intval($directive->getOption('columns-xl')->getValue() ?? 0),
+            intval($directive->getOption('gap')->getValue() ?? 0),
+        );
+    }
+}

packages/guides-theme-bootstrap/src/Bootstrap/Directives/CardGroupDirective.php

@@ -0,0 +1,64 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link https://phpdoc.org
+ */
+
+namespace phpDocumentor\Guides\Bootstrap\Directives;
+
+use phpDocumentor\Guides\Bootstrap\Nodes\CardGroupNode;
+use phpDocumentor\Guides\Bootstrap\Nodes\CardNode;
+use phpDocumentor\Guides\Nodes\CollectionNode;
+use phpDocumentor\Guides\Nodes\InlineCompoundNode;
+use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\RestructuredText\Directives\SubDirective;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
+use phpDocumentor\Guides\RestructuredText\Parser\Directive;
+use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
+use Psr\Log\LoggerInterface;
+
+class CardGroupDirective extends SubDirective
+{
+    public function __construct(
+        protected Rule $startingRule,
+        private readonly LoggerInterface $logger,
+    ) {
+        parent::__construct($startingRule);
+    }
+
+    public function getName(): string
+    {
+        return 'card-group';
+    }
+
+    protected function processSub(
+        BlockContext $blockContext,
+        CollectionNode $collectionNode,
+        Directive $directive,
+    ): Node|null {
+        $title = null;
+        $originalChildren = $collectionNode->getChildren();
+        $children = [];
+        foreach ($originalChildren as $child) {
+            if ($child instanceof CardNode) {
+                $children[] = $child;
+            } else {
+                $this->logger->warning('A card-group may only contain cards. ', $blockContext->getLoggerInformation());
+            }
+        }
+
+        return new CardGroupNode(
+            $this->getName(),
+            $directive->getData(),
+            $directive->getDataNode() ?? new InlineCompoundNode(),
+            $children,
+        );
+    }
+}