refactor question field

Author: koertho

DECISIONS.md

@@ -200,18 +200,54 @@ einzuführen.
 
 ## D7 – Formularantwort (entschieden)
 
-Die vier Schreibaktionen verwenden einen Frame-lokalen
-Post/Redirect/Get-Flow: POST mutiert ausschließlich über den jeweiligen
-Service und antwortet mit `303 See Other` auf den passenden HTML-Frame-
-Endpunkt. Turbo folgt dem Redirect innerhalb des absendenden Frames; der
-Server rendert anschließend den vollständigen aktuellen Zustand. Das vermeidet
-eine zweite Turbo-Stream-Variantenmatrix für Reader und Bühne und bleibt bei
-deaktiviertem Turbo Drive robust. Fachliche Ablehnungen liefern denselben
-semantischen Frame mit Fehlermeldung und Status `422 Unprocessable Entity`,
-damit Turbo ihn ersetzt. Fehlende Authentifizierung, fehlende
-Steuerberechtigung und CSRF-Abweisungen behalten ihre harten HTTP-Statuscodes.
-
-Alle sechs Routen liegen durch `config/routes.yaml` im Frontend-Scope. Die
+Die vier Schreibaktionen behalten den Post/Redirect/Get-Flow: POST mutiert
+ausschließlich über den jeweiligen Service und antwortet mit `303 See Other`
+auf den passenden GET-Endpunkt. Turbo fordert bei unsicheren Formularrequests
+automatisch `text/vnd.turbo-stream.html` an und behält den Accept-Header beim
+Redirect bei (`public/turbo.es2017-esm.js`, `FormSubmission.prepareRequest()`).
+Die GET-Endpunkte antworten deshalb bei dieser Content-Negotiation mit
+Turbo-Streams, bei normalen Frame-Polls weiterhin mit vollständigem
+HTML-Frame-Markup.
+
+Diese Erweiterung von D7 ist für die Reader-Aufteilung notwendig. Status und
+Frageformular liegen im nicht gepollten Controls-Frame
+`qna-session-<id>-reader`; Fragen und Votes liegen im gepollten Questions-Frame
+`qna-session-<id>-questions`. Das Frageformular zielt per
+`data-turbo-frame` auf den Questions-Frame. Nach erfolgreicher Erstellung
+aktualisiert die Redirect-GET-Antwort die Liste und ersetzt den Controls-Inhalt
+einmalig, wodurch das Feld geleert wird. Nach Vote, Start und Stopp
+aktualisieren Streams nur ihren jeweiligen dynamischen Bereich. Die
+Sortierlinks verwenden dagegen eine normale Frame-Navigation, damit Turbo die
+gewählte URL als neue Frame-`src` übernimmt; das Bundle setzt für diese
+Navigation den vorhandenen Turbo-Morph-Renderer ein, damit der Fokus an der
+stabilen Link-ID erhalten bleibt.
+Da Turbo Stream-Antworten vor einer Frame-Navigation abfängt
+(`StreamObserver.inspectFetchResponse()`), wird der einmalige
+`resetQuestionForm`-Redirect nicht zur dauerhaften `src` des Questions-Frames.
+
+Normale Listen-Polls führen ein statusselektives Stream-Update mit: Nur ein
+Controls-Knoten, dessen `data-qna-state` nicht dem aktuellen Serverstatus
+entspricht, ist Ziel. Bei unverändertem `open` bleibt der bestehende
+Textarea-DOM-Knoten samt Wert, Cursor und Auswahl unangetastet; bei
+`waiting`/`closed` wird der Formularbereich spätestens durch den nächsten
+Listen-Poll ersetzt. Es wird kein Formularzustand in JavaScript gespeichert.
+
+Fachliche Ablehnungen bleiben HTML-Antworten mit `422 Unprocessable Entity`.
+Für eine fehlgeschlagene Frame-Form-Submission lädt Turbo ausdrücklich die
+Antwort in den ursprünglichen Frame statt in das mit `data-turbo-frame`
+angegebene Erfolgsziel (`FrameController.formSubmissionFailedWithResponse()`
+im ausgelieferten Turbo-Modul). Deshalb erscheint eine Fragenvalidierung im
+Controls-Frame; der eingereichte Wert wird serverseitig erneut gerendert.
+Fehlende Authentifizierung, fehlende Steuerberechtigung und CSRF-Abweisungen
+behalten ihre harten HTTP-Statuscodes.
+
+Polling-Reloads der Reader-Liste und der Bühne verwenden Morphing mit stabilen
+IDs. Das Polling-Modul verschiebt außerdem Reloads, während der betreffende
+Frame Fokus enthält oder beschäftigt ist. Dadurch bleiben Vote-Klicks,
+Tastaturfokus und die Bühnen-Sortierumschaltung vor einem zeitgleichen Tausch
+geschützt, ohne das Polling der außerhalb liegenden Frageneingabe anzuhalten.
+
+Alle sieben Routen liegen durch `config/routes.yaml` im Frontend-Scope. Die
 vier Aktionen akzeptieren nur POST und setzen `_token_check = true`; der in
 `vendor/contao/core-bundle/src/EventListener/RequestTokenListener.php`
 verifizierte Listener prüft dadurch bei zustandsbehafteten bzw.

README.md

@@ -84,8 +84,9 @@ The bundle contains two content elements and one page controller:
 
 - `qna_session_list` renders published sessions and links to the selected
   reader page through Contao's `ContentUrlGenerator`.
-- `qna_session_reader` renders a cache-neutral lazy Turbo Frame shell for the
-  URL's session alias.
+- `qna_session_reader` renders cache-neutral lazy Turbo Frame shells for the
+  URL's session alias: one stable controls frame and one polling questions
+  frame.
 - page type `qna_stage` renders either the published-session overview or one
   session's operator view. Modern layouts use Contao's Twig-slot
   `ContentComposition`; classic layouts use the documented legacy fallback.
@@ -110,19 +111,30 @@ them.
 
 ## Turbo actions and polling
 
-The reader and stage detail start with a lazy Turbo Frame. Separate GET frame
-routes render current status, questions, vote counts, member vote state,
-forms and CSRF tokens. Question, vote, start and stop forms use POST and a
-Contao `REQUEST_TOKEN`. Successful writes return a frame-local `303 See
-Other`; a business rejection that must remain visible in the frame returns
-`422 Unprocessable Entity`. Missing authentication, failed CSRF validation
-and denied authorization retain their own hard error status.
+The reader starts with two lazy Turbo Frames. Its non-polling controls frame
+contains status, form errors and the question form. Its polling questions
+frame contains questions, vote counts and vote buttons. A status-selective
+Turbo Stream updates the controls only when the server-side session state has
+changed, so normal question polling never replaces text being edited. The
+stage detail uses one polling frame.
+
+Question, vote, start and stop forms use POST and a Contao `REQUEST_TOKEN`.
+Successful writes return a frame-local `303 See Other`; the redirected GET
+uses Turbo Streams to update the affected regions. A created question updates
+the list and resets the form once. A business rejection that must remain
+visible returns `422 Unprocessable Entity` as HTML for the originating frame;
+rejected question text is rendered back into the form. Missing authentication,
+failed CSRF validation and denied authorization retain their own hard error
+status.
 
 Only frames are refreshed; Turbo Drive is not enabled by this bundle. Polling
 pauses while the tab is hidden, removes timers for detached/cached frames,
 avoids duplicate timers and backs off exponentially after transport or frame
-errors, capped at sixteen times the base interval. Sorting by votes or time is
-performed in the database, and the selected sort remains in the frame URL.
+errors, capped at sixteen times the base interval. A polling reload is delayed
+while its frame contains keyboard focus or is processing an action. Polling
+reloads morph elements with stable IDs, protecting vote and sort interactions
+that overlap an already running request. Sorting by votes or time is performed
+in the database, and the selected sort remains in the frame URL.
 
 Every frame and action response uses `Cache-Control: private, no-store`. The
 reader shell and stage detail shell are cache-neutral and contain no member

SPEC.md

@@ -354,6 +354,25 @@ Vote-Button, Kennzeichnung bereits abgegebener Votes.
 **`closed`** — Fragen und Vote-Zahlen bleiben sichtbar, Formular und
 Vote-Buttons entfallen, Hinweis auf das Ende der Fragerunde.
 
+Der Reader trennt den member-spezifischen dynamischen Inhalt strukturell in
+zwei benachbarte Turbo-Frames:
+
+* `qna-session-<id>-reader` enthält ausschließlich Status, Fehlermeldungen und
+  — nur bei `open` und für authentifizierte Mitglieder — das Frageformular.
+  Dieser Controls-Frame wird lazy geladen, aber nicht periodisch gepollt.
+* `qna-session-<id>-questions` enthält ausschließlich die Fragenliste samt
+  Vote-Zahlen und statusabhängigen Vote-Buttons. Nur dieser Frame wird im
+  konfigurierten Intervall gepollt.
+
+Jede Listenantwort enthält zusätzlich ein deklaratives Turbo-Stream-Update für
+den Controls-Inhalt, dessen CSS-Ziel nur bei einem abweichenden Session-Status
+existiert. Normales Polling im unveränderten Zustand `open` ersetzt das
+Formular daher nie; ein Wechsel nach `waiting` oder `closed` entfernt es aber
+spätestens mit dem nächsten Listen-Poll. Beim erfolgreichen Absenden wird der
+Controls-Inhalt einmalig gezielt ersetzt, damit das Formular geleert wird.
+Eine 422-Antwort rendert dagegen den Controls-Frame mit Fehlermeldung und dem
+serverseitig erneut ausgegebenen Fragetext.
+
 ### 5.4 Sortierung Teilnehmeransicht
 
 ```sql
@@ -579,6 +598,19 @@ neu laden — das ist der häufigste Implementierungsfehler in diesem Aufbau.
 Empfohlen: `loading="lazy"` mit neutralem, nicht member-spezifischem
 Initial-Markup, damit die umgebende Seite cachebar bleibt (Abschnitt 8).
 
+Im Reader besteht dieses neutrale Initial-Markup aus zwei lazy Frames. Der
+nicht gepollte Controls-Frame hält Status und Frageformular; der gepollte
+Questions-Frame hält Fragen und Votes. Das Formular zielt mit
+`data-turbo-frame` auf den Questions-Frame. Nach dem POST folgt Turbo dem
+303-Redirect dorthin; bei angefordertem Turbo-Stream-Format aktualisiert die
+GET-Antwort Liste und Controls getrennt. Damit bleiben PRG und eine sofortige
+Listenaktualisierung erhalten, obwohl das Formular außerhalb des Listen-Frames
+liegt.
+
+Reader-Liste und Bühnen-Frame verwenden für Polling-Reloads `refresh="morph"`
+und stabile IDs an interaktiven Elementen. Der Formular-Controls-Frame hat
+weder `data-qna-poll` noch einen Polling-Timer.
+
 ### 7.3 Polling
 
 Turbo pollt nicht von selbst. Die Erweiterung liefert ein **sehr kleines
@@ -599,6 +631,14 @@ Anforderungen:
 * keine doppelten Timer nach Turbo-Visits
 * nur Frames pollen, die im DOM vorhanden sind
 * keine Geschäftslogik im JavaScript
+* kein Polling-Reload, solange der Frame Fokus enthält oder durch eine
+  laufende Frame-/Formaktion als beschäftigt markiert ist
+
+Die letzte Regel betrifft die im gepollten Bereich verbleibenden Vote-Buttons
+und die Sortierumschaltung der Bühne. Das ausgelagerte Fragefeld liegt nicht im
+Polling-Frame: Während dort geschrieben wird, aktualisiert sich die Liste
+weiterhin. Morphing und stabile IDs decken zusätzlich den engen Fall ab, dass
+ein bereits laufender Poll erst während einer beginnenden Interaktion rendert.
 
 **Lastabschätzung gehört ins README:** 2500 ms Intervall × Zuschauerzahl ergibt
 die Requests pro Sekunde auf nicht cachebare Endpunkte. Prüfe, ob die
@@ -630,6 +670,7 @@ Bundle selbst, im eigenen Namensraum:
 
 ```
 contao_qna_reader_frame       GET
+contao_qna_reader_controls    GET
 contao_qna_stage_questions    GET
 contao_qna_question_create    POST
 contao_qna_vote_create        POST
@@ -760,12 +801,19 @@ contao/templates/
 │   ├── qna_session_list.html.twig
 │   └── qna_session_reader.html.twig
 └── qna/
-    ├── reader_frame.html.twig
+    ├── reader_controls.html.twig
+    ├── reader_controls_frame.html.twig
+    ├── reader_controls_update.html.twig
+    ├── reader_questions.html.twig
+    ├── reader_questions_frame.html.twig
+    ├── reader_update.stream.html.twig
     ├── question_list.html.twig
     ├── question.html.twig
     ├── stage_overview.html.twig
     ├── stage_detail.html.twig
-    └── stage_questions.html.twig
+    ├── stage_questions.html.twig
+    ├── stage_content.html.twig
+    └── stage_update.stream.html.twig
 ```
 
 Referenziert wird über die Contao-Hierarchie, nicht über den

contao/templates/content_element/qna_session_reader.html.twig

@@ -11,9 +11,19 @@
             <turbo-frame
                 id="{{ view.frameId }}"
                 class="qna-reader__frame"
-                src="{{ frame_src }}"
+                src="{{ controls_frame_src }}"
                 loading="lazy"
-                data-qna-frame="reader"
+                data-qna-frame="reader-controls"
+            >
+                <p class="qna-reader__loading">{{ 'qna.reader.loading'|trans({}, 'contao_default') }}</p>
+            </turbo-frame>
+            <turbo-frame
+                id="{{ view.questionsFrameId }}"
+                class="qna-reader__questions-frame"
+                src="{{ questions_frame_src }}"
+                loading="lazy"
+                refresh="morph"
+                data-qna-frame="reader-questions"
                 data-qna-poll
                 data-qna-poll-interval="{{ polling_interval }}"
                 data-qna-poll-max-interval="{{ polling_max_interval }}"

contao/templates/qna/question.html.twig

@@ -1,4 +1,4 @@
-<li class="qna-question-list__item">
+<li id="qna-question-{{ question.id }}" class="qna-question-list__item">
     <article class="qna-question" aria-labelledby="qna-question-{{ question.id }}-text">
         <p id="qna-question-{{ question.id }}-text" class="qna-question__text">{{ question.question }}</p>
         <p class="qna-question__votes">
@@ -9,6 +9,7 @@
             <form class="qna-vote-form" action="{{ vote_url }}" method="post">
                 <input type="hidden" name="REQUEST_TOKEN" value="{{ request_token }}">
                 <button
+                    id="qna-question-{{ question.id }}-vote"
                     class="qna-button qna-vote-button{{ question.hasVoted ? ' qna-vote-button--selected' : '' }}"
                     type="submit"
                     aria-label="{{ (question.hasVoted ? 'qna.vote.selected_label' : 'qna.vote.label')|trans([question.question], 'contao_default') }}"

…tao/templates/qna/reader_frame.html.twig …/templates/qna/reader_controls.html.twigcontao/templates/qna/reader_frame.html.twig renamed to contao/templates/qna/reader_controls.html.twig contao/templates/qna/reader_frame.html.twig renamed to contao/templates/qna/reader_controls.html.twig

@@ -1,10 +1,8 @@
-<turbo-frame
-    id="{{ view.frameId }}"
-    class="qna-reader__frame"
-    data-qna-frame="reader"
+<div
+    id="{{ view.controlsContentId }}"
+    class="qna-reader__controls qna-reader__controls--{{ view.state }}"
     data-qna-state="{{ view.state }}"
 >
-    <div data-qna-poll-interval="{{ polling_interval }}">
     {% if error_translation_key %}
         <p class="qna-message qna-message--error" role="alert">
             {{ error_translation_key|trans({}, 'contao_default') }}
@@ -16,7 +14,12 @@
     </p>
 
     {% if view.showQuestionForm %}
-        <form class="qna-question-form" action="{{ question_form_action }}" method="post">
+        <form
+            class="qna-question-form"
+            action="{{ question_form_action }}"
+            method="post"
+            data-turbo-frame="{{ view.questionsFrameId }}"
+        >
             <label class="qna-question-form__label" for="qna-session-{{ view.sessionId }}-question">
                 {{ 'qna.question.label'|trans({}, 'contao_default') }}
             </label>
@@ -26,22 +29,11 @@
                 name="question"
                 maxlength="{{ max_question_length }}"
                 required
-            ></textarea>
+            >{{ question_value }}</textarea>
             <input type="hidden" name="REQUEST_TOKEN" value="{{ request_token }}">
             <button class="qna-button qna-question-form__submit" type="submit">
                 {{ 'qna.question.submit'|trans({}, 'contao_default') }}
             </button>
         </form>
     {% endif %}
-
-    {% if view.showQuestions %}
-        {% include '@Contao/qna/question_list.html.twig' with {
-            questions: questions,
-            frame_id: view.questionsFrameId,
-            show_vote_buttons: view.showVoteButtons,
-            vote_urls: vote_urls,
-            request_token: request_token
-        } only %}
-    {% endif %}
-    </div>
-</turbo-frame>
+</div>

contao/templates/qna/reader_controls_frame.html.twig

@@ -0,0 +1,8 @@
+<turbo-frame
+    id="{{ view.frameId }}"
+    class="qna-reader__frame"
+    data-qna-frame="reader-controls"
+    data-qna-state="{{ view.state }}"
+>
+    {% include '@Contao/qna/reader_controls.html.twig' %}
+</turbo-frame>

contao/templates/qna/reader_controls_update.html.twig

@@ -0,0 +1,12 @@
+<turbo-stream
+    action="replace"
+    {% if reset_question_form %}
+        target="{{ view.controlsContentId }}"
+    {% else %}
+        targets="#{{ view.controlsContentId }}:not([data-qna-state='{{ view.state }}'])"
+    {% endif %}
+>
+    <template>
+        {% include '@Contao/qna/reader_controls.html.twig' %}
+    </template>
+</turbo-stream>

contao/templates/qna/reader_questions.html.twig

@@ -0,0 +1,17 @@
+<div class="qna-reader__questions" data-qna-poll-interval="{{ polling_interval }}" data-qna-state="{{ view.state }}">
+    {% if error_translation_key %}
+        <p class="qna-message qna-message--error" role="alert">
+            {{ error_translation_key|trans({}, 'contao_default') }}
+        </p>
+    {% endif %}
+
+    {% if view.showQuestions %}
+        {% include '@Contao/qna/question_list.html.twig' with {
+            questions: questions,
+            frame_id: view.questionsFrameId ~ '-list',
+            show_vote_buttons: view.showVoteButtons,
+            vote_urls: vote_urls,
+            request_token: request_token
+        } only %}
+    {% endif %}
+</div>

contao/templates/qna/reader_questions_frame.html.twig

@@ -0,0 +1,9 @@
+<turbo-frame
+    id="{{ view.questionsFrameId }}"
+    class="qna-reader__questions-frame"
+    data-qna-frame="reader-questions"
+    data-qna-state="{{ view.state }}"
+>
+    {% include '@Contao/qna/reader_questions.html.twig' %}
+    {% include '@Contao/qna/reader_controls_update.html.twig' with {reset_question_form: false} %}
+</turbo-frame>