Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
161 changes: 161 additions & 0 deletions Build/Scripts/codemod-collection-markers.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,161 @@
<?php

declare(strict_types=1);

/**
* Row markers for the Visual Editor in every Content Block template.
*
* Every <f:for> over a Collection field whose body renders exactly one root
* element per entry gets the f:mark.item ViewHelper of Visual Editor
* Enhancements on that root, so the editor can find the entry ("row") on the
* page. Outside edit mode the ViewHelper renders nothing: published pages
* stay byte-identical. The rules live in Classes/Templates/CollectionMarker
* (shared with Tests/Unit/ContentBlockCollectionMarkerTest.php, which is the
* source of truth for the counts); the loops that cannot carry a marker are
* listed with their reasons in CollectionMarkerExceptions.
*
* Usage:
* php Build/Scripts/codemod-collection-markers.php add missing markers
* php Build/Scripts/codemod-collection-markers.php --dry-run show what would change
* php Build/Scripts/codemod-collection-markers.php --check exit 1 on unmarked, unlisted loops
* options: --block=<name> (one Content Block), --path=<dir> (default ContentBlocks/ContentElements)
*
* Idempotent: a second run changes nothing.
*/

use Webconsulting\Desiderio\Templates\CollectionMarker\CollectionLoop;
use Webconsulting\Desiderio\Templates\CollectionMarker\CollectionLoopAnalyzer;
use Webconsulting\Desiderio\Templates\CollectionMarker\CollectionMarkerExceptions;
use Webconsulting\Desiderio\Templates\CollectionMarker\CollectionMarkerRewriter;

$root = dirname(__DIR__, 2);
require $root . '/vendor/autoload.php';

$options = getopt('', ['check', 'dry-run', 'block:', 'path:', 'help']);
if (isset($options['help'])) {
fwrite(STDOUT, "php Build/Scripts/codemod-collection-markers.php [--check|--dry-run] [--block=<name>] [--path=<dir>]\n");
exit(0);
}
$check = isset($options['check']);
$dryRun = isset($options['dry-run']);
$path = is_string($options['path'] ?? null) ? $options['path'] : $root . '/ContentBlocks/ContentElements';
$onlyBlock = is_string($options['block'] ?? null) ? $options['block'] : null;

$directories = glob(rtrim($path, '/') . '/*', GLOB_ONLYDIR) ?: [];
$analyzer = new CollectionLoopAnalyzer();
$exceptions = new CollectionMarkerExceptions();
$rewriter = new CollectionMarkerRewriter();

$counts = ['blocks' => 0, 'loops' => 0, 'nested' => 0, 'marked' => 0, 'exceptions' => 0, 'added' => 0, 'files' => 0];
$rules = [];
$failures = [];
$usedExceptions = [];

foreach ($directories as $directory) {
$block = basename($directory);
if ($onlyBlock !== null && $block !== $onlyBlock) {
continue;
}
if (!is_file($directory . '/config.yaml') || !is_file($directory . '/templates/frontend.html')) {
continue;
}
$analysis = $analyzer->analyzeBlock($directory, $exceptions);
if ($analysis->loops === []) {
continue;
}
++$counts['blocks'];
$template = $directory . '/templates/frontend.html';

if (!$check) {
$result = $rewriter->rewrite($analysis);
foreach ($result['errors'] as $error) {
$failures[] = $block . ': ' . $error;
}
if ($result['edits'] !== []) {
++$counts['files'];
$counts['added'] += count($result['edits']);
fwrite(STDOUT, ($dryRun ? '[dry-run] ' : '') . $block . '/templates/frontend.html: +' . count($result['edits']) . " marker(s)\n");
foreach ($result['edits'] as $note) {
fwrite(STDOUT, ' ' . $note . "\n");
}
if ($dryRun) {
fwrite(STDOUT, lineDiff($analysis->document->source, $result['source']));
} else {
file_put_contents($template, $result['source']);
}
// Re-read what was (or would be) written: the rewrite must leave a
// template the parser reads cleanly and in which every loop passes.
$analysis = $analyzer->analyze($block, $result['source'], $analysis->fields, $exceptions);
}
}

foreach ($analysis->failures() as $failure) {
$failures[] = $block . ': ' . $failure;
}
foreach ($analysis->loops as $loop) {
++$counts['loops'];
if ($loop->field->parent !== null) {
++$counts['nested'];
}
if ($loop->exception !== null) {
++$counts['exceptions'];
$usedExceptions[$loop->key() . '#' . $loop->occurrence] = true;
$usedExceptions[$loop->key()] = true;
continue;
}
if ($loop->isMarked()) {
++$counts['marked'];
foreach ($loop->roots as $rootNode) {
$rule = CollectionLoop::ruleFor($rootNode);
if ($rule === CollectionLoop::RULE_COMPONENT && str_contains((string)$rootNode->attribute('attributes'), 'f:merge(')) {
$rule .= ' (merged)';
}
$rules[$rule] = ($rules[$rule] ?? 0) + 1;
}
}
}
}

if ($onlyBlock === null) {
foreach (array_keys($exceptions->all()) as $key) {
if (!isset($usedExceptions[$key])) {
$failures[] = 'CollectionMarkerExceptions: "' . $key . '" matches no Collection loop (stale entry)';
}
}
}

ksort($rules);
fwrite(STDOUT, sprintf(
"%d Collection loops in %d Content Blocks (%d over nested Collections): %d marked, %d listed exceptions%s\n",
$counts['loops'],
$counts['blocks'],
$counts['nested'],
$counts['marked'],
$counts['exceptions'],
$check ? '' : sprintf('; %s %d marker(s) in %d file(s)', $dryRun ? 'would add' : 'added', $counts['added'], $counts['files']),
));
foreach ($rules as $rule => $count) {
fwrite(STDOUT, sprintf(" marked roots, %s: %d\n", $rule, $count));
}
if ($failures !== []) {
fwrite(STDERR, count($failures) . " problem(s):\n " . implode("\n ", $failures) . "\n");
exit(1);
}
exit(0);

/**
* The changed lines, "-" before and "+" after (the rewrite never adds or
* removes a line, so lines pair up by number).
*/
function lineDiff(string $before, string $after): string
{
$old = explode("\n", $before);
$new = explode("\n", $after);
$out = '';
foreach ($new as $index => $line) {
if (($old[$index] ?? null) !== $line) {
$out .= sprintf(" %5d - %s\n %5d + %s\n", $index + 1, trim((string)($old[$index] ?? '')), $index + 1, trim($line));
}
}
return $out;
}
93 changes: 93 additions & 0 deletions Build/Scripts/compare-element-renders.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
<?php

declare(strict_types=1);

/**
* Byte comparison of every element preview between two template states — the
* "anonymous render byte-identical" gate for template-wide changes such as
* the collection row markers (Build/Scripts/codemod-collection-markers.php).
*
* php Build/Scripts/compare-element-renders.php capture <urls.json> <dir> [--edit-mode --cookie=<be_typo_user>]
* php Build/Scripts/compare-element-renders.php compare <dirA> <dirB>
*
* <urls.json> is the output of `vendor/bin/typo3 desiderio:library:urls --json`
* (for example in the disposable app of Build/CiApp). Capture the old state,
* flush caches, capture the new one, compare. EXT:form renders a random
* honeypot field and signed form state on every request; those values are
* masked, everything else must match byte for byte. Two captures of the same
* state compare identical, which shows the masking hides no real difference.
*/

$command = $argv[1] ?? '';
if ($command === 'capture' && isset($argv[2], $argv[3])) {
$options = getopt('', ['edit-mode', 'cookie:'], $restIndex);
exit(capture($argv[2], $argv[3], isset($options['edit-mode']), is_string($options['cookie'] ?? null) ? $options['cookie'] : null));
}
if ($command === 'compare' && isset($argv[2], $argv[3])) {
exit(compare($argv[2], $argv[3]));
}
fwrite(STDERR, "usage: capture <urls.json> <dir> [--edit-mode --cookie=<be_typo_user>] | compare <dirA> <dirB>\n");
exit(2);

function capture(string $urlsFile, string $directory, bool $editMode, ?string $cookie): int
{
$decoded = json_decode((string)file_get_contents($urlsFile), true);
$elements = is_array($decoded) ? ($decoded['elements'] ?? $decoded) : [];
if (!is_dir($directory) && !mkdir($directory, 0777, true)) {
fwrite(STDERR, "cannot create $directory\n");
return 2;
}
$failed = 0;
foreach ($elements as $element) {
$url = (string)$element['url'] . ($editMode ? '&editMode=1' : '');
$handle = curl_init($url);
curl_setopt_array($handle, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 120]);
if ($cookie !== null) {
curl_setopt($handle, CURLOPT_COOKIE, 'be_typo_user=' . $cookie);
}
$body = (string)curl_exec($handle);
$status = curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
if ($status !== 200) {
++$failed;
fwrite(STDERR, $element['cType'] . ": HTTP $status\n");
}
file_put_contents($directory . '/' . $element['cType'] . '-' . $element['uid'] . '.html', $body);
}
fwrite(STDOUT, count($elements) . " previews captured, $failed not HTTP 200\n");
return $failed === 0 ? 0 : 1;
}

function compare(string $left, string $right): int
{
$files = array_map(basename(...), glob($left . '/*.html') ?: []);
$identical = $masked = 0;
$different = [];
foreach ($files as $file) {
$a = (string)file_get_contents($left . '/' . $file);
$b = @file_get_contents($right . '/' . $file);
if ($b === false) {
$different[] = $file . ' (missing)';
} elseif ($a === $b) {
++$identical;
} elseif (maskFormTokens($a) === maskFormTokens($b)) {
++$masked;
} else {
$different[] = $file;
}
}
fwrite(STDOUT, sprintf("%d previews: %d byte-identical, %d identical after masking EXT:form tokens, %d different\n", count($files), $identical, $masked, count($different)));
foreach ($different as $file) {
fwrite(STDOUT, ' ' . $file . "\n");
}
return $different === [] ? 0 : 1;
}

function maskFormTokens(string $html): string
{
if (preg_match_all('/<input aria-hidden="true" data-id="([A-Za-z0-9]+)"/', $html, $matches) > 0) {
foreach ($matches[1] as $index => $honeypot) {
$html = str_replace($honeypot, 'HONEYPOT' . $index, $html);
}
}
return (string)preg_replace('/(name="[^"]*(?:__state|__trustedProperties|__referrer\]\[[^"]*|__session)[^"]*" value=")[^"]*"/', '$1MASKED"', $html);
}
27 changes: 23 additions & 4 deletions Build/Scripts/sync-shadcn-fluid-primitives.php
Original file line number Diff line number Diff line change
Expand Up @@ -554,6 +554,21 @@ function renderAttributesArgument(): string
. '<f:argument name="attributes" type="array" optional="{true}" default="{}" />' . "\n";
}

/**
* The same argument for a component whose markup must not change: the comment
* continues the previous argument's line, so no extra newline is rendered.
*/
function renderBridgedAttributesArgument(): string
{
return "<f:comment>\n"
. " `attributes` carries what a row or control needs beyond the shadcn contract\n"
. " (aria-*, data-* hooks, the Visual Editor's row markers). Keys are\n"
. " template-authored, values are escaped. The comment bridges two lines so\n"
. " the extra argument emits no whitespace.\n"
. "</f:comment>"
. '<f:argument name="attributes" type="array" optional="{true}" default="{}" />' . "\n";
}

function extraAttributes(): string
{
return '<f:for each="{attributes}" as="attributeValue" key="attributeName"> {attributeName}="{attributeValue}"</f:for>';
Expand Down Expand Up @@ -1121,7 +1136,9 @@ function renderTabsTrigger(array $recipe, string $header): string
. '<f:argument name="id" type="string" />' . "\n"
. '<f:argument name="controls" type="string" />' . "\n"
. '<f:argument name="active" type="bool" optional="{true}" default="{false}" />' . "\n"
. '<f:argument name="class" type="string" optional="{true}" default="" />' . "\n\n"
. '<f:argument name="class" type="string" optional="{true}" default="" />'
. renderBridgedAttributesArgument()
. "\n"
. '<button' . "\n"
. ' type="button"' . "\n"
. ' role="tab"' . "\n"
Expand All @@ -1133,7 +1150,7 @@ function renderTabsTrigger(array $recipe, string $header): string
. sprintf(' class="%s {class}"', attr($recipe['trigger'])) . "\n"
. ' data-slot="tabs-trigger"' . "\n"
. ' data-d-tabs-trigger' . "\n"
. ' data-value="{value}"' . "\n"
. ' data-value="{value}"' . extraAttributes() . "\n"
. ' {f:if(condition: active, then: \'data-active\')}' . "\n"
. '>' . "\n"
. ' <f:slot />' . "\n"
Expand All @@ -1147,7 +1164,9 @@ function renderTabsContent(array $recipe, string $header): string
. '<f:argument name="id" type="string" />' . "\n"
. '<f:argument name="labelledBy" type="string" />' . "\n"
. '<f:argument name="active" type="bool" optional="{true}" default="{false}" />' . "\n"
. '<f:argument name="class" type="string" optional="{true}" default="" />' . "\n\n"
. '<f:argument name="class" type="string" optional="{true}" default="" />'
. renderBridgedAttributesArgument()
. "\n"
. '<div' . "\n"
. ' role="tabpanel"' . "\n"
. ' id="{id}"' . "\n"
Expand All @@ -1158,7 +1177,7 @@ function renderTabsContent(array $recipe, string $header): string
. sprintf(' class="%s {class}"', attr($recipe['content'])) . "\n"
. ' data-slot="tabs-content"' . "\n"
. ' data-d-tabs-content' . "\n"
. ' data-value="{value}"' . "\n"
. ' data-value="{value}"' . extraAttributes() . "\n"
. '>' . "\n"
. ' <f:slot />' . "\n"
. '</div>' . "\n";
Expand Down
11 changes: 11 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,17 @@ All notable changes to **webconsulting/desiderio** are documented in this
file. The format follows [Keep a Changelog](https://keepachangelog.com/)
and the project adheres to [Semantic Versioning](https://semver.org/).

## [4.36.0] — unreleased

### Added

- Collection row markers for the Visual Editor: every `<f:for>` over a Content Block Collection marks each entry's root element with `f:mark.item` (Visual Editor Enhancements 1.6+), so the editor highlights, dims and — from Visual Editor Enhancements 1.7 — offers row controls on the page. 185 of 189 collection loops in 156 elements carry markers (149 HTML roots, 39 component roots, 2 of them merged with existing `attributes`), including the 13 loops over nested Collections; 4 loops without one element per entry are listed exceptions with reasons (chart, chart-contribution and chart-donut computation/JSON loops, the gallery's featured view). Outside edit mode the marker renders nothing: all 263 element previews render byte-identical to 4.34.1 (checked before this branch was rebased onto 4.35.0).
- `Build/Scripts/codemod-collection-markers.php` adds missing markers (`--dry-run`, `--check`; idempotent) with the rules in `Classes/Templates/CollectionMarker`; `ContentBlockCollectionMarkerTest` gates every loop. Guide: Developer → Collection row markers.
- `CheckedListItem`, `TableRow`, `TableCell`, `FeatureItem`, `TabsTrigger` and `TabsContent` accept an `attributes` argument and spread it onto their root tag, like `Card`.

### Changed

- Requires `webconsulting/visual-editor-enhancements` `^1.6` (was `^0.8 || ^1.0`). Where that extension is not loaded, desiderio registers a stand-in `f:mark.item` that renders nothing, so templates never meet an unknown ViewHelper.
## [4.35.0] — 2026-11-08

### Added
Expand Down
6 changes: 6 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,12 @@ Desiderio targets **TYPO3 14.3.6+ and PHP 8.4–8.5**. Use the
Collection must not keep its own `fields:` (they are inert). The audit gates
all of this; the [collection guide](Documentation/Developer/CollectionTableConsolidation.rst)
explains the shared models and upgrade procedure.
- Every `<f:for>` over a Content Block `Collection` marks each entry's root
element with `f:mark.item` (the Visual Editor's row marker, invisible
outside edit mode). Run `php Build/Scripts/codemod-collection-markers.php`
after template changes; `--check` and `ContentBlockCollectionMarkerTest`
fail on unmarked loops that are not listed exceptions. See the
[row marker guide](Documentation/Developer/CollectionRowMarkers.rst).
- Content Block image fields render through `<f:image>` or `f:uri.image()`.
Pass custom `data-*` attributes through structured Fluid arguments such as
`data="{d-gallery-main: 'true'}"`; do not hand-write literal `<img>` tags for
Expand Down
Loading