[BUGFIX] Fix scrolling behavior for confvals (#975)

And fix permalink display. Add tests for permalinks

Resolves #973

Author: linawolf

Documentation-rendertest/Confval/Index.rst

@@ -6,6 +6,8 @@
 confval
 =======
 
+Permalink to confval: `array of cObjects  <https://docs.typo3.org/permalink/rendertest:confval-case-array>`_.
+
 ..  toctree::
     :glob:
 

Documentation-rendertest/Confval/X.rst

@@ -0,0 +1,28 @@
+..  include:: /Includes.rst.txt
+
+======================
+Confvals with subtrees
+======================
+
+..  confval-menu::
+    :name: x-case-properties
+    :caption: TypoScript Case Properties
+    :display: table
+    :type:
+
+    ..  confval:: array of cObjects
+        :name: x-case-array
+        :type: cObject
+        :searchFacet: TypoScript
+
+        Array of cObjects. Use this to define cObjects for the different
+        values of `cobj-case-key`. If `cobj-case-key` has a certain value,
+        the according cObject will be rendered. The cObjects can have any name, but not
+        the names of the other properties of the cObject CASE.
+
+    ..  confval:: cache
+        :name: x-case-cache
+        :type: cache
+        :searchFacet: TypoScript
+
+        See  for details.

Documentation-rendertest/guides.xml

@@ -4,6 +4,7 @@
         xsi:schemaLocation="https://www.phpdoc.org/guides ../vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
         links-are-relative="true">
     <extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
+               interlink-shortcode="rendertest"
                typo3-core-preferred="stable"
                confval-default="TCA"
     />

packages/typo3-docs-theme/assets/js/scrolling.js

@@ -3,40 +3,29 @@ document.addEventListener("DOMContentLoaded", function () {
     const header = document.querySelector("header");
     const headerHeight = header ? header.offsetHeight : 80; // Default fallback
 
-    document.querySelectorAll(".section").forEach(section => {
+    document.querySelectorAll("[id]").forEach(el => {
       section.style.scrollMarginTop = `${headerHeight + 10}px`; // Extra space for visibility
     });
   }
 
   function scrollToAnchor() {
     const hash = window.location.hash.substring(1); // Get anchor without #
-    if (!hash) return;
+    if (!hash || hash === "top") {
+      window.scrollTo({ top: 0, behavior: "smooth" });
+      return;
+    }
 
     const target = document.getElementById(hash);
     if (target) {
-      // Check if the target is the first main section (h1)
-      const isFirstSection = target.closest(".section")?.querySelector("h1") !== null;
-
-      if (isFirstSection) {
-        window.scrollTo({
-          top: 0,
-          behavior: "smooth"
-        });
-      } else {
-        setTimeout(() => {
-          target.scrollIntoView({ behavior: "smooth", block: "start" });
-        }, 50); // Delay ensures styles apply
-      }
+      setTimeout(() => {
+        target.scrollIntoView({ behavior: "smooth", block: "start" });
+      }, 50); // Delay ensures styles apply
     }
   }
 
-  // Adjust scroll margin on load
   adjustScrollMargin();
-
-  // Handle initial anchor scrolling
   setTimeout(scrollToAnchor, 100); // Slight delay for rendering
 
-  // Handle clicks on internal links
   document.querySelectorAll('a[href^="#"]').forEach(anchor => {
     anchor.addEventListener("click", function (e) {
       e.preventDefault();
@@ -46,6 +35,5 @@ document.addEventListener("DOMContentLoaded", function () {
     });
   });
 
-  // Adjust when resizing (e.g., switching between desktop & mobile)
   window.addEventListener("resize", adjustScrollMargin);
 });

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

@@ -154,10 +154,10 @@
         <div class="caption">{{ node.caption }}</div>
     {%- endif %}
 {% endmacro %}
-
+<a id="{{ node.anchor }}"></a>
 {% import _self as macros %}
 {% if node.display=='list' %}
-<div class="mb-4" id="{{ node.anchor }}">
+<div class="mb-4">
     {{ macros.renderCaption(node) }}
     <ul>
         {% for entry in node.confvals %}
@@ -166,7 +166,7 @@
     </ul>
 </div>
 {% elseif node.display=='tree' %}
-    <div class="directory-tree mb-4" id="{{ node.anchor }}">
+    <div class="directory-tree mb-4">
         {{ macros.renderCaption(node) }}
         <ul>
         {% for entry in node.confvals %}
@@ -175,7 +175,7 @@
         </ul>
     </div>
 {% else %}
-<div class="table-responsive confval-table" id="{{ node.anchor }}">
+<div class="table-responsive confval-table">
     <table class="table table-hover caption-top">
         {%- if node.caption %}<caption>{{ node.caption }}</caption>{% endif %}
         <thead>
@@ -202,9 +202,11 @@
 </div>
 {% endif %}
 {% for child in node.children %}
+    {% do setBackAnchor(node.anchor) %}
     {% if child.isConfval %}
-        {% include "body/directive/confval.html.twig" with  {'node': child, 'backAnchor': node.anchor } %}
+        {% include "body/directive/confval.html.twig" with  {'node': child } %}
     {% else %}
         {{ renderNode(child) }}
     {% endif %}
+    {% do setBackAnchor('') %}
 {% endfor %}

packages/typo3-docs-theme/resources/template/body/directive/confval-menu.html.twig

@@ -1,11 +1,13 @@
+{% set resolvedBackAnchor = backAnchor is defined ? backAnchor : getBackAnchor() %}
 <section data-search-title="{{ node.plainContent }}"
          data-search-id="{{ node.anchor }}"
          data-search-facet="{{ filterAllowedSearchFacets(renderNode(node.additionalOptions.searchFacet)|default(getSettings('confval_default'))) }}"
          class="confval-section"
+         id="{{ node.anchor }}"
 >
     <h3 class="sr-only">{{ node.plainContent }}</h3>
     <dl class="confval">
-        <dt{% if not node.noindex %} id="{{ node.anchor }}"{% endif %}
+        <dt{% if not node.noindex %} {% endif %}
             class="d-flex justify-content-between">
             <div class="confval-header flex-grow-1">
                 <code class="sig-name descname"><span
@@ -15,7 +17,6 @@
                        data-bs-toggle="modal"
                        data-bs-target="#linkReferenceModal"
                        data-id="{{ node.anchor }}"
-                       data-rstCode="{{ getRstCodeForLink(node) }}"
                        title="Reference this configuration value"><i
                             class="fa-solid fa-paragraph"></i></a>
                 {% else %}
@@ -25,8 +26,8 @@
                 {% endif -%}
             </div>
             <div class="confval-back-to-top">
-                {%- if backAnchor %}
-                    <a href="#{{ backAnchor }}" class="backToList"
+                {%- if resolvedBackAnchor %}
+                    <a href="#{{ resolvedBackAnchor }}" class="backToList"
                        title="Back to list"><i
                             class="fa-solid fa-angles-up fa-xs"></i></a>
                 {% else %}

packages/typo3-docs-theme/resources/template/body/directive/confval.html.twig

@@ -0,0 +1,21 @@
+<?php
+
+namespace T3Docs\Typo3DocsTheme\Twig;
+
+final class ContextRegistry
+{
+    /**
+     * @var array<string, string>
+     */
+    private static array $store = [];
+
+    public static function set(string $key, string $value): void
+    {
+        self::$store[$key] = $value;
+    }
+
+    public static function get(string $key): ?string
+    {
+        return self::$store[$key] ?? null;
+    }
+}

packages/typo3-docs-theme/src/Twig/ContextRegistry.php

@@ -102,6 +102,8 @@ public function getFunctions(): array
             new TwigFunction('getPermalink', $this->getPermalink(...), ['is_safe' => ['html'], 'needs_context' => true]),
             new TwigFunction('getSingleHtmlLink', $this->getSingleHtmlLink(...), ['is_safe' => ['html'], 'needs_context' => true]),
             new TwigFunction('getTopPageLink', $this->getTopPageLink(...), ['is_safe' => ['html'], 'needs_context' => true]),
+            new TwigFunction('setBackAnchor', $this->setBackAnchor(...), ['needs_context' => true]),
+            new TwigFunction('getBackAnchor', $this->getBackAnchor(...), ['needs_context' => true]),
         ];
     }
 
@@ -790,5 +792,19 @@ public function isRenderedForDeployment(): bool
 
         return false;
     }
+    /**
+     * @param array{env: RenderContext} $context
+     */
+    public function setBackAnchor(array $context, string $value): void
+    {
+        ContextRegistry::set('backAnchor', $value);
+    }
 
+    /**
+     * @param array{env: RenderContext} $context
+     */
+    public function getBackAnchor(array $context): ?string
+    {
+        return ContextRegistry::get('backAnchor');
+    }
 }

packages/typo3-docs-theme/src/Twig/TwigExtension.php

@@ -1,22 +1,25 @@
 <!-- content start -->
                 <section class="section" id="confval">
             <h1>Confval<a class="headerlink" href="#confval" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline"><i class="fa-solid fa-paragraph"></i></a></h1>
+
+    <p>Permalink to confval: <a href="#confval-demo">demo</a>.</p>
+
             <section data-search-title="demo"
          data-search-id="confval-demo"
          data-search-facet="Option"
          class="confval-section"
+         id="confval-demo"
 >
     <h3 class="sr-only">demo</h3>
     <dl class="confval">
-        <dt id="confval-demo"            class="d-flex justify-content-between">
+        <dt             class="d-flex justify-content-between">
             <div class="confval-header flex-grow-1">
                 <code class="sig-name descname"><span
                         class="pre">demo</span></code>
                                     <a class="headerlink" href="#confval-demo"
                        data-bs-toggle="modal"
                        data-bs-target="#linkReferenceModal"
                        data-id="confval-demo"
-                       data-rstCode=":ref:`demo &lt;somemanual:confval-demo&gt;`"
                        title="Reference this configuration value"><i
                             class="fa-solid fa-paragraph"></i></a>
                 </div>
@@ -40,24 +43,24 @@ <h3 class="sr-only">demo</h3>
     </dl>
 </section>
 
-    <p>See also <a href="#confval-demo">demo</a> or <a href="#confval-demo">demo</a>.</p>
+    <p>See also <a href="https://docs.typo3.org/permalink/test:confval-demo"></a> or <a href="#confval-demo">demo</a>.</p>
 
             <section data-search-title="demo"
          data-search-id="confval-some-other-demo"
          data-search-facet="Option"
          class="confval-section"
+         id="confval-some-other-demo"
 >
     <h3 class="sr-only">demo</h3>
     <dl class="confval">
-        <dt id="confval-some-other-demo"            class="d-flex justify-content-between">
+        <dt             class="d-flex justify-content-between">
             <div class="confval-header flex-grow-1">
                 <code class="sig-name descname"><span
                         class="pre">demo</span></code>
                                     <a class="headerlink" href="#confval-some-other-demo"
                        data-bs-toggle="modal"
                        data-bs-target="#linkReferenceModal"
                        data-id="confval-some-other-demo"
-                       data-rstCode=":ref:`demo &lt;somemanual:confval-some-other-demo&gt;`"
                        title="Reference this configuration value"><i
                             class="fa-solid fa-paragraph"></i></a>
                 </div>

tests/Integration/tests/confval/confval-basic/expected/index.html

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<guides xmlns="https://www.phpdoc.org/guides"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="https://www.phpdoc.org/guides vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
+    links-are-relative="true"
+    theme="typo3docs"
+>
+
+    <extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
+        interlink-shortcode="test"
+    />
+    <extension
+        class="\T3Docs\GuidesExtension\DependencyInjection\Typo3GuidesExtension"/>
+    <output-format>interlink</output-format>
+    <output-format>html</output-format>
+    <output-format>singlepage</output-format>
+</guides>

tests/Integration/tests/confval/confval-basic/input/guides.xml

@@ -2,6 +2,8 @@
 Confval
 =======
 
+Permalink to confval: `demo  <https://docs.typo3.org/permalink/test:confval-demo>`_.
+
 ..  confval:: demo
     :type: string
     :default: ``"Hello World"``

tests/Integration/tests/confval/confval-basic/input/index.rst

@@ -5,18 +5,18 @@ <h1>Confval in another domain<a class="headerlink" href="#confval-in-another-dom
          data-search-id="confval-another-demo"
          data-search-facet="Option"
          class="confval-section"
+         id="confval-another-demo"
 >
     <h3 class="sr-only">demo</h3>
     <dl class="confval">
-        <dt id="confval-another-demo"            class="d-flex justify-content-between">
+        <dt             class="d-flex justify-content-between">
             <div class="confval-header flex-grow-1">
                 <code class="sig-name descname"><span
                         class="pre">demo</span></code>
                                     <a class="headerlink" href="#confval-another-demo"
                        data-bs-toggle="modal"
                        data-bs-target="#linkReferenceModal"
                        data-id="confval-another-demo"
-                       data-rstCode=":ref:`demo &lt;somemanual:confval-another-demo&gt;`"
                        title="Reference this configuration value"><i
                             class="fa-solid fa-paragraph"></i></a>
                 </div>

tests/Integration/tests/confval/confval-duplicate-with-name/expected/anotherDomain.html

@@ -5,18 +5,18 @@ <h1>Confval<a class="headerlink" href="#confval" data-bs-toggle="modal" data-bs-
          data-search-id="confval-demo"
          data-search-facet="Option"
          class="confval-section"
+         id="confval-demo"
 >
     <h3 class="sr-only">demo</h3>
     <dl class="confval">
-        <dt id="confval-demo"            class="d-flex justify-content-between">
+        <dt             class="d-flex justify-content-between">
             <div class="confval-header flex-grow-1">
                 <code class="sig-name descname"><span
                         class="pre">demo</span></code>
                                     <a class="headerlink" href="#confval-demo"
                        data-bs-toggle="modal"
                        data-bs-target="#linkReferenceModal"
                        data-id="confval-demo"
-                       data-rstCode=":ref:`demo &lt;somemanual:confval-demo&gt;`"
                        title="Reference this configuration value"><i
                             class="fa-solid fa-paragraph"></i></a>
                 </div>

tests/Integration/tests/confval/confval-duplicate-with-name/expected/index.html

@@ -5,18 +5,18 @@ <h1>Confval in another domain<a class="headerlink" href="#confval-in-another-dom
          data-search-id="confval-demo"
          data-search-facet="Option"
          class="confval-section"
+         id="confval-demo"
 >
     <h3 class="sr-only">demo</h3>
     <dl class="confval">
-        <dt id="confval-demo"            class="d-flex justify-content-between">
+        <dt             class="d-flex justify-content-between">
             <div class="confval-header flex-grow-1">
                 <code class="sig-name descname"><span
                         class="pre">demo</span></code>
                                     <a class="headerlink" href="#confval-demo"
                        data-bs-toggle="modal"
                        data-bs-target="#linkReferenceModal"
                        data-id="confval-demo"
-                       data-rstCode=":ref:`demo &lt;somemanual:confval-demo&gt;`"
                        title="Reference this configuration value"><i
                             class="fa-solid fa-paragraph"></i></a>
                 </div>

tests/Integration/tests/confval/confval-duplicate/expected/anotherDomain.html

@@ -5,18 +5,18 @@ <h1>Confval<a class="headerlink" href="#confval" data-bs-toggle="modal" data-bs-
          data-search-id="confval-demo"
          data-search-facet="Option"
          class="confval-section"
+         id="confval-demo"
 >
     <h3 class="sr-only">demo</h3>
     <dl class="confval">
-        <dt id="confval-demo"            class="d-flex justify-content-between">
+        <dt             class="d-flex justify-content-between">
             <div class="confval-header flex-grow-1">
                 <code class="sig-name descname"><span
                         class="pre">demo</span></code>
                                     <a class="headerlink" href="#confval-demo"
                        data-bs-toggle="modal"
                        data-bs-target="#linkReferenceModal"
                        data-id="confval-demo"
-                       data-rstCode=":ref:`demo &lt;somemanual:confval-demo&gt;`"
                        title="Reference this configuration value"><i
                             class="fa-solid fa-paragraph"></i></a>
                 </div>