[FEATURE] Introduce composer text role (#604)

Making it possible to link to packagist and display more information
about the package. Warn if package not found.


![image](https://github.com/TYPO3-Documentation/render-guides/assets/48202465/40f47ec2-678f-403e-b461-b080513138aa)


![image](https://github.com/TYPO3-Documentation/render-guides/assets/48202465/02dbbab6-0986-4e87-a889-dd70e8bd29b5)

![image](https://github.com/TYPO3-Documentation/render-guides/assets/48202465/b82524f0-a596-4edc-b0b4-9e3a3cf8d6f9)


If JavaScript is not active they are simple links to packagist from
where users can get all other information.

Author: linawolf

packages/typo3-docs-theme/assets/js/composer-modal.js

@@ -0,0 +1,81 @@
+(() => {
+  const SELECTOR_MODAL = '#generalModal';
+  const SELECTOR_COPY_BUTTON = '.copy-button';
+  const SELECTOR_ALERT_SUCCESS = '#general-alert-success';
+
+  function handleCopyButtons(generalModal) {
+    const alertSuccessDiv = generalModal.querySelector(SELECTOR_ALERT_SUCCESS);
+    const copyButtons = generalModal.querySelectorAll(SELECTOR_COPY_BUTTON);
+    if (!navigator.clipboard || !navigator.clipboard.writeText) {
+      console.info('"navigator.clipboard.writeText" is not available. Update to a modern browser to copy code to the system\'s clipboard');
+      copyButtons.forEach(button => button.disabled = true);
+    } else {
+      copyButtons.forEach(button => {
+        button.addEventListener('click', function() {
+          const targetId = this.getAttribute('data-target');
+          const targetElement = generalModal.querySelector(`#${targetId}`);
+          if (!targetElement) {
+            console.warn('Cannot copy link as no input is available!');
+            return;
+          }
+          alertSuccessDiv.classList.remove('d-none');
+          alertSuccessDiv.innerHTML = `Snippet <code>${htmlEscape(targetElement.value)}</code> was copied to your clipboard.`;
+          navigator.clipboard.writeText(targetElement.value);
+        });
+      });
+    }
+  }
+
+  function htmlEscape(text) {
+    const div = document.createElement('div');
+    div.textContent = text;
+    return div.innerHTML;
+  }
+
+  const generalModal = document.querySelector(SELECTOR_MODAL);
+  generalModal.addEventListener('show.bs.modal', function (event) {
+    const item = event.relatedTarget;
+    if (!item.dataset.composername) {
+      return;
+    }
+    const generalModalLabel = generalModal.querySelector('#generalModalLabel');
+    const content = generalModal.querySelector('#generalModalContent');
+    generalModalLabel.innerText = item.dataset.composername;
+    handleCopyButtons(generalModal);
+    content.innerHTML = `
+        <p>${item.dataset.description}</p>
+        <p>Install the package using Composer: </p>
+        <div class="input-group">
+            <textarea class="form-control code" id="composer-command" readonly>${item.dataset.composercommand}</textarea>
+            <button type="button" class="btn btn-outline-secondary copy-button" data-target="composer-command"><i class="far fa-clone"></i></button>
+        </div>
+  `;
+    const generalModalCustomButtons = generalModal.querySelector('#generalModalCustomButtons');
+
+    // Add more buttons to the modal footer
+    generalModalCustomButtons.innerHTML = `
+          <a href="${item.href}" class="btn btn-default"><i class="fa-solid fa-arrow-right"></i>&nbsp;Packagist</a>
+      `;
+    if(item.dataset.documentation) {
+      const url = new URL(item.dataset.documentation);
+      const isExternal = url.hostname !== 'docs.typo3.org';
+      generalModalCustomButtons.innerHTML += `
+            <a href="${item.dataset.documentation}" class="btn btn-default">
+                <i class="fa-solid fa-book"></i>&nbsp;Documentation ${isExternal ? '(external)' : ''}
+            </a>
+        `;
+    }
+    if(item.dataset.homepage) {
+      const url = new URL(item.dataset.homepage);
+      const isTER = url.hostname === 'extensions.typo3.org';
+      if (isTER) {
+        generalModalCustomButtons.innerHTML += `
+            <a href="${item.dataset.homepage}" class="btn btn-default">
+                <i class="fa-brands fa-typo3"></i>&nbsp;TER
+            </a>
+        `;
+      }
+    }
+    handleCopyButtons(generalModal);
+  });
+})();

packages/typo3-docs-theme/assets/sass/components/_textroles.scss

@@ -1,15 +1,21 @@
 
-/**
- * Keyboard Shortcuts, text role :kbd:
- */
-kbd {
-    @include inline-box;
-}
+article {
+    /**
+     * Keyboard Shortcuts, text role :kbd:
+     */
+    kbd {
+        @include inline-box;
+    }
+
+    /**
+     * GUI-Label
+     */
+    .guilabel {
+        font-size: 75%;
+        @include inline-box($info);
+    }
 
-/**
- * GUI-Label
- */
-.guilabel {
-    font-size: 75%;
-    @include inline-box($info);
+    a.composer-link {
+        text-decoration: underline dotted;
+    }
 }

packages/typo3-docs-theme/composer.json

@@ -10,6 +10,7 @@
         }
     },
     "require": {
+        "ext-curl": "*",
         "brotkrueml/twig-codehighlight": "^0.1.1",
         "phpdocumentor/guides-graphs": "^1.0",
         "phpdocumentor/guides-theme-bootstrap": "^1.0",

packages/typo3-docs-theme/resources/config/typo3-docs-theme.php

@@ -28,11 +28,13 @@
 use T3Docs\Typo3DocsTheme\EventListeners\IgnoreLocalizationsFolders;
 use T3Docs\Typo3DocsTheme\EventListeners\TestingModeActivator;
 use T3Docs\Typo3DocsTheme\Inventory\Typo3InventoryRepository;
+use T3Docs\Typo3DocsTheme\Packagist\PackagistService;
 use T3Docs\Typo3DocsTheme\Inventory\Typo3VersionService;
 use T3Docs\Typo3DocsTheme\Parser\ExtendedInterlinkParser;
 use T3Docs\Typo3DocsTheme\Parser\Productions\FieldList\EditOnGitHubFieldListItemRule;
 use T3Docs\Typo3DocsTheme\Parser\Productions\FieldList\TemplateFieldListItemRule;
 use T3Docs\Typo3DocsTheme\Renderer\DecoratingPlantumlRenderer;
+use T3Docs\Typo3DocsTheme\TextRoles\ComposerTextRole;
 use T3Docs\Typo3DocsTheme\TextRoles\FluidTextTextRole;
 use T3Docs\Typo3DocsTheme\TextRoles\HtmlTextTextRole;
 use T3Docs\Typo3DocsTheme\TextRoles\InputTextTextRole;
@@ -74,6 +76,8 @@
         ->set(InventoryRepository::class, Typo3InventoryRepository::class)
         ->arg('$inventoryConfigs', param('phpdoc.guides.inventories'))
         ->set(InterlinkParser::class, ExtendedInterlinkParser::class)
+        ->set(ComposerTextRole::class)
+        ->tag('phpdoc.guides.parser.rst.text_role')
         ->set(FluidTextTextRole::class)
         ->tag('phpdoc.guides.parser.rst.text_role')
         ->set(HtmlTextTextRole::class)
@@ -134,6 +138,7 @@
         ->tag('twig.extension')
         ->autowire()
 
+        ->set(PackagistService::class)
         ->set(Typo3VersionService::class)
 
         // Register Event Listeners

packages/typo3-docs-theme/resources/public/css/theme.css

@@ -24698,10 +24698,15 @@ article *:hover > a.headerlink:after, article *:hover > a.permalink:after, artic
   margin: 0;
 }
 
-/**
- * Keyboard Shortcuts, text role :kbd:
- */
-kbd {
+article {
+  /**
+   * Keyboard Shortcuts, text role :kbd:
+   */
+  /**
+   * GUI-Label
+   */
+}
+article kbd {
   display: inline-block;
   padding: 0.25em 0.5em;
   box-shadow: 0 2px 4px 0 rgba(0, 0, 0, 0.2), inset 0 0 0 2px #ffffff;
@@ -24710,11 +24715,7 @@ kbd {
   border-radius: 0.375rem;
   border: 1px solid #f2f2f2;
 }
-
-/**
- * GUI-Label
- */
-.guilabel {
+article .guilabel {
   font-size: 75%;
   display: inline-block;
   padding: 0.25em 0.5em;
@@ -24724,6 +24725,9 @@ kbd {
   border-radius: 0.375rem;
   border: 1px solid #319fc0;
 }
+article a.composer-link {
+  text-decoration: underline dotted;
+}
 
 /**
  * Bignums
@@ -24922,11 +24926,11 @@ ul[class*=horizbuttons-][class*=-attention-] > li:hover, ul[class*=horizbuttons-
   background-color: #f2f2f2;
   outline: 2px solid #333333;
 }
-ul[class*=horizbuttons-][class*=-note-] > li, ul[class*=horizbuttons-][class*=-tip-] > li, ul[class*=horizbuttons-][class*=-default-] > li {
+ul[class*=horizbuttons-][class*=-note-] > li, ul[class*=horizbuttons-][class*=-tip-] > li, ul[class*=horizbuttons-][class*=-default-] > li, ul[class*=horizbuttons-][class*=-light-] > li {
   color: #000000;
   background-color: #f2f2f2;
 }
-ul[class*=horizbuttons-][class*=-note-] > li:hover, ul[class*=horizbuttons-][class*=-tip-] > li:hover, ul[class*=horizbuttons-][class*=-default-] > li:hover {
+ul[class*=horizbuttons-][class*=-note-] > li:hover, ul[class*=horizbuttons-][class*=-tip-] > li:hover, ul[class*=horizbuttons-][class*=-default-] > li:hover, ul[class*=horizbuttons-][class*=-light-] > li:hover {
   color: #333333;
   background-color: #f2f2f2;
   outline: 2px solid #333333;

packages/typo3-docs-theme/resources/public/js/theme.min.js

@@ -0,0 +1,15 @@
+<a class="composer-link"
+   href="{{ node.package.packagistLink }}"
+   title="Packagist information"
+   data-bs-toggle="modal"
+   data-bs-target="#generalModal"
+   data-description="{{ node.package.description }}"
+   data-composername="{{ node.composerName }}"
+   data-composercommand="{{ node.package.composerCommand }}"
+   data-homepage="{{ node.package.homepage }}"
+   data-documentation="{{ node.package.documentation }}"
+   data-issues="{{ node.package.issues }}"
+   data-source="{{ node.package.source }}"
+>
+    {{ node.composerName }}
+</a>

packages/typo3-docs-theme/resources/template/inline/textroles/composer.html.twig

@@ -57,6 +57,7 @@
     </main>
 
     {% include "structure/layoutParts/linkReferenceModal.html.twig" %}
+    {% include "structure/layoutParts/generalModal.html.twig" %}
 </div>
 
 {% include "structure/layoutParts/footer.html.twig" %}

packages/typo3-docs-theme/resources/template/structure/layout.html.twig

@@ -0,0 +1,22 @@
+{%- set interlinkShortcode = getSettings('interlink_shortcode') -%}
+<div class="modal fade" id="generalModal" tabindex="-1" aria-labelledby="linkReferenceModalLabel"
+    aria-hidden="true" data-current-filename="{{ getCurrentFilename() }}"
+>
+    <div class="modal-dialog">
+        <div class="modal-content">
+            <div class="modal-header">
+                <h5 class="modal-title" id="generalModalLabel"></h5>
+                <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
+            </div>
+            <div class="modal-body">
+                <div class="alert alert-success d-none" id="general-alert-success" role="alert"></div>
+                <div id="generalModalContent">
+                </div>
+            </div>
+            <div class="modal-footer justify-content-between">
+                <div id="generalModalCustomButtons"></div>
+                <button type="button" class="btn btn-secondary" data-bs-dismiss="modal"><i class="fa-regular fa-circle-xmark"></i>&nbsp;Close</button>
+            </div>
+        </div>
+    </div>
+</div>

packages/typo3-docs-theme/resources/template/structure/layoutParts/generalModal.html.twig

@@ -14,6 +14,7 @@
 use Symfony\Component\DependencyInjection\Loader\PhpFileLoader;
 use Symfony\Component\DependencyInjection\Reference;
 use T3Docs\Typo3DocsTheme\Nodes\Inline\CodeInlineNode;
+use T3Docs\Typo3DocsTheme\Nodes\Inline\ComposerInlineNode;
 use T3Docs\Typo3DocsTheme\Nodes\YoutubeNode;
 use T3Docs\Typo3DocsTheme\Settings\Typo3DocsInputSettings;
 use T3Docs\Typo3DocsTheme\Settings\Typo3DocsThemeSettings;
@@ -99,6 +100,7 @@ public function prepend(ContainerBuilder $container): void
 
             'templates' => [
                 template(CodeInlineNode::class, 'inline/textroles/code.html.twig'),
+                template(ComposerInlineNode::class, 'inline/textroles/composer.html.twig'),
             ],
         ]);
     }

packages/typo3-docs-theme/src/DependencyInjection/Typo3DocsThemeExtension.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace T3Docs\Typo3DocsTheme\Nodes\Inline;
+
+use phpDocumentor\Guides\Nodes\Inline\InlineNode;
+use T3Docs\Typo3DocsTheme\Packagist\ComposerPackage;
+
+final class ComposerInlineNode extends InlineNode
+{
+    public const TYPE = 'code';
+
+    public function __construct(
+        private string $composerName,
+        private ComposerPackage $package,
+    ) {
+        parent::__construct(self::TYPE, $composerName);
+    }
+
+    public function getComposerName(): string
+    {
+        return $this->composerName;
+    }
+
+    public function getPackage(): ComposerPackage
+    {
+        return $this->package;
+    }
+}

packages/typo3-docs-theme/src/Nodes/Inline/ComposerInlineNode.php

@@ -0,0 +1,69 @@
+<?php
+
+namespace T3Docs\Typo3DocsTheme\Packagist;
+
+class ComposerPackage
+{
+    public function __construct(
+        private readonly string $composerName,
+        private readonly string $composerCommand,
+        private readonly string $packagistStatus,
+        private readonly string $packagistLink = '',
+        private readonly string $description = '',
+        private readonly string $homepage = '',
+        private readonly string $documentation = '',
+        private readonly string $issues = '',
+        private readonly string $source = '',
+        private readonly bool $development = false,
+    ) {}
+
+    public function getComposerName(): string
+    {
+        return $this->composerName;
+    }
+
+    public function getComposerCommand(): string
+    {
+        return $this->composerCommand;
+    }
+
+    public function getPackagistLink(): string
+    {
+        return $this->packagistLink;
+    }
+
+    public function getDescription(): string
+    {
+        return $this->description;
+    }
+
+    public function getHomepage(): string
+    {
+        return $this->homepage;
+    }
+
+    public function getDocumentation(): string
+    {
+        return $this->documentation;
+    }
+
+    public function getIssues(): string
+    {
+        return $this->issues;
+    }
+
+    public function getSource(): string
+    {
+        return $this->source;
+    }
+
+    public function getPackagistStatus(): string
+    {
+        return $this->packagistStatus;
+    }
+
+    public function isDevelopment(): bool
+    {
+        return $this->development;
+    }
+}