Merge pull request #799 from phpDocumentor/task/improve-menu-items2

!!![TASK] Restructure Menu handling

Author: jaapio

packages/guides-restructured-text/src/RestructuredText/Directives/ContentsDirective.php

@@ -5,7 +5,7 @@
 namespace phpDocumentor\Guides\RestructuredText\Directives;
 
 use phpDocumentor\Guides\Nodes\Menu\ContentMenuNode;
-use phpDocumentor\Guides\Nodes\Menu\MenuDefinitionLineNode;
+use phpDocumentor\Guides\Nodes\Menu\SectionMenuEntryNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolverInterface;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
@@ -39,7 +39,7 @@ public function process(
             $blockContext->getDocumentParserContext()->getContext()->getCurrentFileName(),
         );
 
-        return (new ContentMenuNode([new MenuDefinitionLineNode($absoluteUrl)]))
+        return (new ContentMenuNode([new SectionMenuEntryNode($absoluteUrl)]))
             ->withOptions($this->optionsToArray($options))
             ->withCaption($directive->getDataNode());
     }

packages/guides-restructured-text/src/RestructuredText/Directives/MenuDirective.php

@@ -4,7 +4,7 @@
 
 namespace phpDocumentor\Guides\RestructuredText\Directives;
 
-use phpDocumentor\Guides\Nodes\Menu\MenuDefinitionLineNode;
+use phpDocumentor\Guides\Nodes\Menu\GlobMenuEntryNode;
 use phpDocumentor\Guides\Nodes\Menu\NavMenuNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
@@ -49,7 +49,7 @@ public function process(
             $options,
         );
         if (count($toctreeFiles) === 0) {
-            $toctreeFiles[] = new MenuDefinitionLineNode('/*');
+            $toctreeFiles[] = new GlobMenuEntryNode('/*');
         }
 
         return (new NavMenuNode($toctreeFiles))->withOptions($this->optionsToArray($options));

packages/guides-restructured-text/src/RestructuredText/Parser/Reference/ReferenceData.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\RestructuredText\Parser\Reference;
+
+final class ReferenceData
+{
+    public function __construct(
+        public readonly string $reference,
+        public readonly string|null $text,
+    ) {
+    }
+}

packages/guides-restructured-text/src/RestructuredText/Toc/ToctreeBuilder.php

@@ -4,13 +4,21 @@
 
 namespace phpDocumentor\Guides\RestructuredText\Toc;
 
-use phpDocumentor\Guides\Nodes\Menu\MenuDefinitionLineNode;
+use phpDocumentor\Guides\Nodes\Menu\ExternalMenuEntryNode;
+use phpDocumentor\Guides\Nodes\Menu\GlobMenuEntryNode;
+use phpDocumentor\Guides\Nodes\Menu\InternalMenuEntryNode;
+use phpDocumentor\Guides\Nodes\Menu\MenuEntryNode;
+use phpDocumentor\Guides\Nodes\TitleNode;
 use phpDocumentor\Guides\ParserContext;
 use phpDocumentor\Guides\RestructuredText\Parser\LinesIterator;
 use phpDocumentor\Guides\RestructuredText\Parser\References\EmbeddedReferenceParser;
 
 use function array_filter;
 use function array_map;
+use function filter_var;
+use function str_contains;
+
+use const FILTER_VALIDATE_URL;
 
 class ToctreeBuilder
 {
@@ -19,7 +27,7 @@ class ToctreeBuilder
     /**
      * @param mixed[] $options
      *
-     * @return MenuDefinitionLineNode[]
+     * @return MenuEntryNode[]
      */
     public function buildToctreeEntries(
         ParserContext $parserContext,
@@ -35,7 +43,7 @@ public function buildToctreeEntries(
         return $toctreeEntries;
     }
 
-    /** @return MenuDefinitionLineNode[] */
+    /** @return MenuEntryNode[] */
     private function parseToctreeEntryLines(LinesIterator $lines): array
     {
         $linesArray =  array_filter(
@@ -46,7 +54,17 @@ private function parseToctreeEntryLines(LinesIterator $lines): array
         $result = [];
         foreach ($linesArray as $line) {
             $referenceData = $this->extractEmbeddedReference($line);
-            $result[] = new MenuDefinitionLineNode($referenceData->reference, $referenceData->text);
+            if (filter_var($referenceData->reference, FILTER_VALIDATE_URL) !== false) {
+                $result[] = new ExternalMenuEntryNode($referenceData->reference, TitleNode::fromString($referenceData->text ?? $referenceData->reference));
+                continue;
+            }
+
+            if (str_contains($referenceData->reference, '*')) {
+                $result[] = new GlobMenuEntryNode($referenceData->reference);
+                continue;
+            }
+
+            $result[] = new InternalMenuEntryNode($referenceData->reference, $referenceData->text === null ? null : TitleNode::fromString($referenceData->text));
         }
 
         return $result;

packages/guides/resources/config/guides.php

@@ -8,6 +8,7 @@
 use phpDocumentor\Guides\Compiler\DocumentNodeTraverser;
 use phpDocumentor\Guides\Compiler\NodeTransformer;
 use phpDocumentor\Guides\Compiler\NodeTransformers\CustomNodeTransformerFactory;
+use phpDocumentor\Guides\Compiler\NodeTransformers\MenuNodeTransformers\InternalMenuEntryNodeTransformer;
 use phpDocumentor\Guides\Compiler\NodeTransformers\NodeTransformerFactory;
 use phpDocumentor\Guides\Interlink\DefaultInventoryLoader;
 use phpDocumentor\Guides\Interlink\DefaultInventoryRepository;
@@ -84,12 +85,20 @@
             'phpDocumentor\\Guides\\Compiler\\NodeTransformers\\',
             '%vendor_dir%/phpdocumentor/guides/src/Compiler/NodeTransformers/*Transformer.php',
         )
+        ->load(
+            'phpDocumentor\\Guides\\Compiler\\NodeTransformers\\MenuNodeTransformers\\',
+            '%vendor_dir%/phpdocumentor/guides/src/Compiler/NodeTransformers/MenuNodeTransformers/*Transformer.php',
+        )
 
         ->load(
             'phpDocumentor\\Guides\\Compiler\\Passes\\',
             '%vendor_dir%/phpdocumentor/guides/src/Compiler/Passes/*Pass.php',
         )
 
+        ->set(InternalMenuEntryNodeTransformer::class)
+        ->tag('phpdoc.guides.compiler.nodeTransformers')
+
+
         ->set(AbsoluteUrlGenerator::class)
         ->set(RelativeUrlGenerator::class)
         ->set(UrlGeneratorInterface::class, ConfigurableUrlGenerator::class)

packages/guides/resources/template/html/body/menu/content-menu.html.twig

@@ -1,8 +1,6 @@
-{% apply spaceless %}
-    <div class="contents">
-        {% if node.caption %}
-        <p class="topic-title">{{ renderNode(node.caption) }}</p>
-        {% endif %}
-        {% include "body/menu/menu-level.html.twig" %}
-    </div>
-{% endapply %}
+<div class="contents">
+    {% if node.caption %}
+    <p class="topic-title">{{ renderNode(node.caption) }}</p>
+    {% endif %}
+    {% include "body/menu/menu-level.html.twig" %}
+</div>

packages/guides/src/Compiler/NodeTransformer.php

@@ -26,5 +26,8 @@ public function leaveNode(Node $node, CompilerContext $compilerContext): Node|nu
     /** @psalm-assert-if-true T $node */
     public function supports(Node $node): bool;
 
+    /**
+     * The higher the priority the earlier the NodeTransformer is executed.
+     */
     public function getPriority(): int;
 }