Checkpoint: headless JSON architecture documented + cleanup (Stufe 1+2)

Restore point before Stufe 3 (central resolver-service refactoring).

Includes this session's work:
- Success Story (usecase) rebuild: new fields/tabs, UsecaseSerializer,
  thin List/Show renderers, MM relations, inline content elements.
- vitec_columns content block (two-column layout with per-item content)
  incl. unified header section; special-cased JSON resolution.
- Container per-column flex (items[].config align/justify) + gap on parent.
- Unified header section across CEs/plugins/containers; header fields in JSON.
- ISO-style architecture spec: Documentation/Headless-JSON-Architecture.md.
- Cleanup: removed local scratch + verified .bak backups.
- Fixes: B-6 (undefined thumbnail variable in Downloadcardcollection image
  resolver), B-7 (unsatisfiable legacy CType OR branch in Downloadcard/Datasheets).

Rollback: git reset --hard snapshot-2026-07-09-pre-stufe3

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

packages/vitec/ContentBlocks/ContentElements/card/config.yaml

@@ -13,12 +13,27 @@ fields:
     type: Text
     max: 50
 
-  - identifier: header
-    useExistingField: true
-    required: true
+  - identifier: header_section
+    type: Palette
+    label: Header
+    fields:
+      - identifier: header
+        useExistingField: true
+        required: true
+      - type: Linebreak
+      - identifier: header_layout
+        useExistingField: true
+      - identifier: header_position
+        useExistingField: true
+      - identifier: date
+        useExistingField: true
+      - type: Linebreak
+      - identifier: header_link
+        useExistingField: true
+      - type: Linebreak
+      - identifier: subheader
+        useExistingField: true
 
-  - identifier: subheader
-    useExistingField: true
 
   - identifier: bodytext
     useExistingField: true

packages/vitec/ContentBlocks/ContentElements/card/templates/backend-preview.html

@@ -50,7 +50,7 @@
             <f:if condition="{data.header}">
                 <f:then>{data.header}</f:then>
                 <f:else>
-                    <em style="color:#c00;">⚠ Headline fehlt</em>
+                    <em style="color:#c00;">⚠ Headline missing</em>
                 </f:else>
             </f:if>
         </h3>

packages/vitec/ContentBlocks/ContentElements/columns/assets/icon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="32" height="32">
+  <rect x="3" y="6" width="32" height="20" rx="2" fill="none"/>
+  <rect x="3" y="6" width="12" height="20" rx="1.5" fill="#ff6a00"/>
+  <rect x="17" y="6" width="12" height="20" rx="1.5" fill="#0a3d62"/>
+</svg>

packages/vitec/ContentBlocks/ContentElements/columns/config.yaml

@@ -0,0 +1,91 @@
+name: vitec/columns
+group: vitec_custom_components
+prefixFields: true
+prefixType: vendor
+
+fields:
+  - identifier: header_section
+    type: Palette
+    label: Header
+    fields:
+      - identifier: header
+        useExistingField: true
+        required: true
+      - type: Linebreak
+      - identifier: header_layout
+        useExistingField: true
+      - identifier: header_position
+        useExistingField: true
+      - identifier: date
+        useExistingField: true
+      - type: Linebreak
+      - identifier: header_link
+        useExistingField: true
+      - type: Linebreak
+      - identifier: subheader
+        useExistingField: true
+  - identifier: layout
+    type: Select
+    renderType: selectSingle
+    default: cols_50_50
+    items:
+      - label: '50 / 50'
+        value: cols_50_50
+      - label: '66 / 33'
+        value: cols_66_33
+      - label: '33 / 66'
+        value: cols_33_66
+
+  - identifier: items
+    type: Collection
+    label: Items
+    labelField: headline
+    fields:
+      - identifier: column
+        type: Select
+        renderType: selectSingle
+        default: left
+        items:
+          - label: Left column
+            value: left
+          - label: Right column
+            value: right
+      - identifier: item_type
+        type: Select
+        renderType: selectSingle
+        default: text
+        items:
+          - label: Text
+            value: text
+          - label: Image
+            value: image
+          - label: Video
+            value: video
+          - label: CTA / Button
+            value: cta
+      - identifier: headline
+        type: Text
+        max: 255
+      - identifier: text
+        type: Textarea
+        enableRichtext: true
+      - identifier: image
+        type: File
+        minitems: 0
+        maxitems: 1
+        allowed: common-image-types
+      - identifier: video
+        type: File
+        minitems: 0
+        maxitems: 1
+        allowed: mp4,webm,ogv,mov,m4v
+      - identifier: link
+        type: Link
+        allowedTypes:
+          - page
+          - url
+          - file
+          - email
+      - identifier: link_label
+        type: Text
+        max: 60

packages/vitec/ContentBlocks/ContentElements/columns/language/labels.xlf

@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xliff version="1.2">
+  <file source-language="en" datatype="plaintext" original="messages">
+    <body>
+      <trans-unit id="title">
+        <source>VITEC · Columns</source>
+      </trans-unit>
+      <trans-unit id="description">
+        <source>Two-column layout (50/50, 66/33, 33/66). Add items and assign each to the left or right column.</source>
+      </trans-unit>
+
+      <trans-unit id="layout.label">
+        <source>Layout</source>
+      </trans-unit>
+
+      <trans-unit id="items.label">
+        <source>Items</source>
+      </trans-unit>
+      <trans-unit id="items.column.label">
+        <source>Column</source>
+      </trans-unit>
+      <trans-unit id="items.item_type.label">
+        <source>Type</source>
+      </trans-unit>
+      <trans-unit id="items.headline.label">
+        <source>Headline</source>
+      </trans-unit>
+      <trans-unit id="items.text.label">
+        <source>Text</source>
+      </trans-unit>
+      <trans-unit id="items.image.label">
+        <source>Image</source>
+      </trans-unit>
+      <trans-unit id="items.video.label">
+        <source>Video</source>
+      </trans-unit>
+      <trans-unit id="items.link.label">
+        <source>Link</source>
+      </trans-unit>
+      <trans-unit id="items.link_label.label">
+        <source>Link Label</source>
+      </trans-unit>
+    </body>
+  </file>
+</xliff>

packages/vitec/ContentBlocks/ContentElements/columns/templates/backend-preview.html

@@ -0,0 +1,19 @@
+<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers" data-namespace-typo3-fluid="true">
+<f:layout name="Preview"/>
+<f:section name="Content">
+
+<f:asset.css identifier="vitec-backend-preview" href="EXT:vitec/Resources/Public/Css/backend-preview.css"/>
+
+<div class="vitec-preview">
+    <div class="vitec-preview__thumb-placeholder">▦</div>
+    <div class="vitec-preview__body">
+        <div class="vitec-preview__label">VITEC · Columns</div>
+        <h3 class="vitec-preview__headline">Two-column layout — {data.layout}</h3>
+    </div>
+    <div class="vitec-preview__settings">
+        <span class="vitec-badge">{data.layout}</span>
+    </div>
+</div>
+
+</f:section>
+</html>

packages/vitec/ContentBlocks/ContentElements/columns/templates/frontend.html

@@ -0,0 +1,3 @@
+<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers" data-namespace-typo3-fluid="true">
+<!-- Headless mode: JSON is built by the VITEC UsecaseSerializer / nb-headless-content-blocks -->
+</html>

packages/vitec/ContentBlocks/ContentElements/cta-banner/config.yaml

@@ -4,9 +4,26 @@ prefixFields: true
 prefixType: vendor
 
 fields:
-  - identifier: header
-    useExistingField: true
-    required: true
+  - identifier: header_section
+    type: Palette
+    label: Header
+    fields:
+      - identifier: header
+        useExistingField: true
+        required: true
+      - type: Linebreak
+      - identifier: header_layout
+        useExistingField: true
+      - identifier: header_position
+        useExistingField: true
+      - identifier: date
+        useExistingField: true
+      - type: Linebreak
+      - identifier: header_link
+        useExistingField: true
+      - type: Linebreak
+      - identifier: subheader
+        useExistingField: true
 
   - identifier: bodytext
     useExistingField: true

packages/vitec/ContentBlocks/ContentElements/cta-banner/language/labels.xlf

@@ -6,7 +6,7 @@
         <source>VITEC · CTA Banner</source>
       </trans-unit>
       <trans-unit id="description">
-        <source>Call-to-Action Banner mit optionalem zweiten Button und Background-Varianten</source>
+        <source>Call-to-action banner with optional secondary button and background variants</source>
       </trans-unit>
 
       <trans-unit id="primary_cta.label">
@@ -35,7 +35,7 @@
         <source>Background Image (optional)</source>
       </trans-unit>
       <trans-unit id="background_image.description">
-        <source>Optionales Hintergrundbild — überlagert die Background-Variant-Farbe</source>
+        <source>Optional background image — overlays the background variant colour</source>
       </trans-unit>
     </body>
   </file>

packages/vitec/ContentBlocks/ContentElements/cta-banner/templates/backend-preview.html

@@ -6,7 +6,7 @@
 
 <div class="vitec-preview vitec-preview--{data.background_variant}">
 
-    <f:comment>Thumbnail (Background Image oder Farb-Placeholder)</f:comment>
+    <f:comment>Thumbnail (background image or colour placeholder)</f:comment>
     <f:if condition="{data.background_image.0}">
         <f:then>
             <f:image image="{data.background_image.0}"
@@ -37,7 +37,7 @@
             <f:if condition="{data.header}">
                 <f:then>{data.header}</f:then>
                 <f:else>
-                    <em style="color:#c00;">⚠ Headline fehlt</em>
+                    <em style="color:#c00;">⚠ Headline missing</em>
                 </f:else>
             </f:if>
         </h3>
@@ -75,7 +75,7 @@
             </f:switch>
         </span>
 
-        <f:comment>Layout Variant Badge mit Icon</f:comment>
+        <f:comment>Layout variant badge with icon</f:comment>
         <span class="vitec-badge">
             <f:switch expression="{data.layout_variant}">
                 <f:case value="centered">◎ Centered</f:case>
@@ -85,9 +85,9 @@
             </f:switch>
         </span>
 
-        <f:comment>Warnung wenn Primary-CTA-Link fehlt</f:comment>
+        <f:comment>Warning when primary CTA link is missing</f:comment>
         <f:if condition="{data.primary_cta.url} == ''">
-            <span class="vitec-badge vitec-badge--warning">⚠ Kein Primary-Link</span>
+            <span class="vitec-badge vitec-badge--warning">⚠ Primary link missing</span>
         </f:if>
     </div>
 

packages/vitec/ContentBlocks/ContentElements/faq/assets/icon.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16">
+  <rect x="1.5" y="2" width="13" height="3.4" rx="0.8" fill="#000" opacity="0.55"/>
+  <polygon points="12.2,3.2 13.6,3.2 12.9,4.4" fill="#fff"/>
+  <rect x="1.5" y="6.3" width="13" height="3.4" rx="0.8" fill="none" stroke="#000" stroke-width="1" opacity="0.6"/>
+  <polygon points="12.4,7.2 12.4,8.6 13.4,7.9" fill="#000" opacity="0.6"/>
+  <rect x="1.5" y="10.6" width="13" height="3.4" rx="0.8" fill="none" stroke="#000" stroke-width="1" opacity="0.6"/>
+  <polygon points="12.4,11.5 12.4,12.9 13.4,12.2" fill="#000" opacity="0.6"/>
+</svg>

packages/vitec/ContentBlocks/ContentElements/faq/config.yaml

@@ -0,0 +1,56 @@
+name: vitec/faq
+group: vitec_custom_components
+prefixFields: true
+prefixType: vendor
+
+fields:
+  - identifier: header_section
+    type: Palette
+    label: Header
+    fields:
+      - identifier: header
+        useExistingField: true
+        required: true
+      - type: Linebreak
+      - identifier: header_layout
+        useExistingField: true
+      - identifier: header_position
+        useExistingField: true
+      - identifier: date
+        useExistingField: true
+      - type: Linebreak
+      - identifier: header_link
+        useExistingField: true
+      - type: Linebreak
+      - identifier: subheader
+        useExistingField: true
+
+
+
+
+
+  - identifier: faq_items
+    type: Collection
+    labelField: question
+    minitems: 1
+    fields:
+      - identifier: question
+        type: Text
+        required: true
+        max: 255
+
+      - identifier: answer
+        type: Textarea
+        enableRichtext: true
+
+  - identifier: first_item_open
+    type: Checkbox
+    default: 1
+
+  - identifier: allow_multiple_open
+    type: Checkbox
+    default: 0
+
+  - identifier: debug
+    type: Checkbox
+    default: 0

packages/vitec/ContentBlocks/ContentElements/faq/language/labels.xlf

@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xliff version="1.2">
+  <file source-language="en" datatype="plaintext" original="messages">
+    <body>
+      <trans-unit id="title">
+        <source>VITEC · FAQ</source>
+      </trans-unit>
+      <trans-unit id="description">
+        <source>Accordion with repeatable question/answer items. First item can start expanded.</source>
+      </trans-unit>
+
+      <trans-unit id="faq_items.label">
+        <source>FAQ Entries</source>
+      </trans-unit>
+      <trans-unit id="faq_items.question.label">
+        <source>Question</source>
+      </trans-unit>
+      <trans-unit id="faq_items.answer.label">
+        <source>Answer</source>
+      </trans-unit>
+
+      <trans-unit id="first_item_open.label">
+        <source>Open first item by default</source>
+      </trans-unit>
+      <trans-unit id="allow_multiple_open.label">
+        <source>Allow multiple items open at once</source>
+      </trans-unit>
+      <trans-unit id="debug.label">
+        <source>Allow Debug Output</source>
+      </trans-unit>
+    </body>
+  </file>
+</xliff>

packages/vitec/ContentBlocks/ContentElements/faq/templates/backend-preview.html

@@ -0,0 +1,66 @@
+<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers" data-namespace-typo3-fluid="true">
+<f:layout name="Preview"/>
+<f:section name="Content">
+
+<f:asset.css identifier="vitec-backend-preview" href="EXT:vitec/Resources/Public/Css/backend-preview.css"/>
+
+<div class="vitec-preview">
+
+    <div class="vitec-preview__thumb-placeholder">?</div>
+
+    <div class="vitec-preview__body">
+        <div class="vitec-preview__label">VITEC · FAQ</div>
+
+        <h3 class="vitec-preview__headline">
+            <f:if condition="{data.header}">
+                <f:then>{data.header}</f:then>
+                <f:else>
+                    <em style="color:#c00;">⚠ Headline missing</em>
+                </f:else>
+            </f:if>
+        </h3>
+
+        <f:if condition="{data.subheader}">
+            <div class="vitec-preview__subline">{data.subheader}</div>
+        </f:if>
+
+        <f:if condition="{data.faq_items}">
+            <f:then>
+                <div class="vitec-preview__body-text">
+                    <f:for each="{data.faq_items}" as="item" iteration="i">
+                        <f:if condition="{i.index} < 3">▸ {item.question}<br/></f:if>
+                    </f:for>
+                </div>
+            </f:then>
+            <f:else>
+                <div class="vitec-preview__body-text">
+                    <em style="color:#c00;">⚠ No FAQ entries</em>
+                </div>
+            </f:else>
+        </f:if>
+    </div>
+
+    <div class="vitec-preview__settings">
+
+        <span class="vitec-badge">
+            ❓ <f:count subject="{data.faq_items}"/> entries
+        </span>
+
+        <f:if condition="{data.first_item_open}">
+            <span class="vitec-badge">▽ First item open</span>
+        </f:if>
+
+        <f:if condition="{data.allow_multiple_open}">
+            <span class="vitec-badge">≡ Multiple open allowed</span>
+        </f:if>
+
+        <f:if condition="{data.debug}">
+            <span class="vitec-badge vitec-badge--warning">⚙ Debug ON</span>
+        </f:if>
+
+    </div>
+
+</div>
+
+</f:section>
+</html>

packages/vitec/ContentBlocks/ContentElements/faq/templates/frontend.html

@@ -0,0 +1,3 @@
+<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers" data-namespace-typo3-fluid="true">
+<!-- Headless mode: JSON is built by nb-headless-content-blocks -->
+</html>

packages/vitec/ContentBlocks/ContentElements/hero-section/config.yaml

@@ -8,21 +8,30 @@ fields:
     type: Text
     max: 50
 
-  - identifier: header
-    useExistingField: true
-    required: true
+  - identifier: header_section
+    type: Palette
+    label: Header
+    fields:
+      - identifier: header
+        useExistingField: true
+        required: true
+      - type: Linebreak
+      - identifier: header_layout
+        useExistingField: true
+      - identifier: header_position
+        useExistingField: true
+      - identifier: date
+        useExistingField: true
+      - type: Linebreak
+      - identifier: header_link
+        useExistingField: true
+      - type: Linebreak
+      - identifier: subheader
+        useExistingField: true
 
-  - identifier: header_layout
-    useExistingField: true
 
-  - identifier: header_position
-    useExistingField: true
 
-  - identifier: header_link
-    useExistingField: true
 
-  - identifier: subheader
-    useExistingField: true
 
   - identifier: bodytext
     useExistingField: true

packages/vitec/ContentBlocks/ContentElements/hero-section/templates/backend-preview.html

@@ -31,7 +31,7 @@
             <f:if condition="{data.header}">
                 <f:then>{data.header}</f:then>
                 <f:else>
-                    <em style="color:#c00;">⚠ Headline fehlt</em>
+                    <em style="color:#c00;">⚠ Headline missing</em>
                 </f:else>
             </f:if>
         </h3>
@@ -53,7 +53,7 @@
         </f:if>
     </div>
 
-    <f:comment>Settings Sidebar (ohne Partial)</f:comment>
+    <f:comment>Settings sidebar (without partial)</f:comment>
     <div class="vitec-preview__settings">
         <span class="vitec-badge">
             <span class="vitec-badge__dot vitec-badge__dot--{data.background_variant}"></span>
@@ -65,7 +65,7 @@
         </f:if>
 
         <f:if condition="{data.hero_image.0} == ''">
-            <span class="vitec-badge vitec-badge--warning">⚠ Kein Bild</span>
+            <span class="vitec-badge vitec-badge--warning">⚠ No image</span>
         </f:if>
     </div>
 

packages/vitec/ContentBlocks/ContentElements/intro-paragraph/config.yaml

@@ -4,21 +4,30 @@ prefixFields: true
 prefixType: vendor
 
 fields:
-  - identifier: header
-    useExistingField: true
-    required: true
+  - identifier: header_section
+    type: Palette
+    label: Header
+    fields:
+      - identifier: header
+        useExistingField: true
+        required: true
+      - type: Linebreak
+      - identifier: header_layout
+        useExistingField: true
+      - identifier: header_position
+        useExistingField: true
+      - identifier: date
+        useExistingField: true
+      - type: Linebreak
+      - identifier: header_link
+        useExistingField: true
+      - type: Linebreak
+      - identifier: subheader
+        useExistingField: true
 
-  - identifier: header_layout
-    useExistingField: true
 
-  - identifier: header_position
-    useExistingField: true
 
-  - identifier: header_link
-    useExistingField: true
 
-  - identifier: subheader
-    useExistingField: true
 
   - identifier: bodytext
     useExistingField: true

packages/vitec/ContentBlocks/ContentElements/intro-paragraph/templates/backend-preview.html

@@ -12,7 +12,7 @@
             <f:if condition="{data.header}">
                 <f:then>{data.header}</f:then>
                 <f:else>
-                    <em style="color:#c00;">⚠ Headline fehlt</em>
+                    <em style="color:#c00;">⚠ Headline missing</em>
                 </f:else>
             </f:if>
         </h3>
@@ -61,7 +61,7 @@
         </f:if>
 
         <f:if condition="{data.button_text} && {data.button_link.url} == ''">
-            <span class="vitec-badge vitec-badge--warning">⚠ Button-Text ohne Link</span>
+            <span class="vitec-badge vitec-badge--warning">⚠ Button text without link</span>
         </f:if>
 
         <f:if condition="{data.debug}">

packages/vitec/ContentBlocks/ContentElements/video/config.yaml

@@ -4,21 +4,30 @@ prefixFields: true
 prefixType: vendor
 
 fields:
-  - identifier: header
-    useExistingField: true
-    required: true
+  - identifier: header_section
+    type: Palette
+    label: Header
+    fields:
+      - identifier: header
+        useExistingField: true
+        required: true
+      - type: Linebreak
+      - identifier: header_layout
+        useExistingField: true
+      - identifier: header_position
+        useExistingField: true
+      - identifier: date
+        useExistingField: true
+      - type: Linebreak
+      - identifier: header_link
+        useExistingField: true
+      - type: Linebreak
+      - identifier: subheader
+        useExistingField: true
 
-  - identifier: header_layout
-    useExistingField: true
 
-  - identifier: header_position
-    useExistingField: true
 
-  - identifier: header_link
-    useExistingField: true
 
-  - identifier: subheader
-    useExistingField: true
 
   - identifier: youtube_code
     type: Text

packages/vitec/ContentBlocks/ContentElements/video/templates/backend-preview.html

@@ -27,7 +27,7 @@
             <f:if condition="{data.header}">
                 <f:then>{data.header}</f:then>
                 <f:else>
-                    <em style="color:#c00;">⚠ Headline fehlt</em>
+                    <em style="color:#c00;">⚠ Headline missing</em>
                 </f:else>
             </f:if>
         </h3>
@@ -59,7 +59,7 @@
         </f:if>
 
         <f:if condition="!{data.youtube_code} && !{data.custom_video.0}">
-            <span class="vitec-badge vitec-badge--warning">⚠ Kein Video-Source</span>
+            <span class="vitec-badge vitec-badge--warning">⚠ No video source</span>
         </f:if>
         <f:if condition="{data.hide_controls}">
             <span class="vitec-badge">⏸ Controls hidden</span>