[ker0x]

Q	A
Bug fix?	no
New feature?	yes
Deprecations?	no
Documentation?	yes
Issues	#4142
License	MIT

Second step of the RFC in #4142.

In multiple mode, the controller builds the preview of each file in JS, with fixed markup and CSS classes (dropzone-preview-list-item, dropzone-preview-image, ...). An app can only restyle those classes in CSS. It cannot use utility classes, put an icon component in the remove button, or add markup such as the file size.

This adds an optional previewItemTemplate target. When it is present, each preview is a clone of the template's root element, and the controller fills the elements marked with data-dropzone-slot, the root element included:

• image: the image preview, as the src of an <img> or as the background image of any other element. It has the hidden attribute until the preview is loaded, and keeps it for files that are not images.
• filename: the file name, as text.
• remove: removes the file on click, with the same aria-label as the default button.

All slots are optional, and a slot can be on several elements. The template must contain exactly one root element: otherwise the controller does not connect and Stimulus logs the error, before any file is added. To render the template without copying the whole widget, the form theme renders a new, empty dropzone_preview_item_template block inside the container in multiple mode. An app overrides only that block:

{% block dropzone_preview_item_template %}
    <template data-symfony--ux-dropzone--dropzone-target="previewItemTemplate">
        <li class="relative size-20">
            <div data-dropzone-slot="image" class="size-full bg-cover bg-center"></div>
            <span data-dropzone-slot="filename" class="sr-only"></span>
            <button type="button" data-dropzone-slot="remove" class="absolute top-1 right-1">
                {{ ux_icon('lucide:x') }}
            </button>
        </li>
    </template>
{% endblock %}

Without the block override, nothing changes: no <template> is rendered and the JS-built markup stays the default.

Tests: unit tests for the template (slots, slots on the root element, a slot on several elements, escaping of the file name, remove, <img> and background previews, no slots, a template with no or several root elements, and a remove button without type that must not submit the form), and PHPUnit tests that the block is rendered inside the container in multiple mode only. The new unit tests and the multiple mode PHPUnit test fail on the base branch.

[github-actions]

📊 Packages dist files size difference

Thanks for the PR! Here is the difference in size of the packages dist files between the base branch and the PR.
Please review the changes and make sure they are expected.

File	Before (Size / Gzip)	After (Size / Gzip)
Dropzone
controller.d.ts	1.34 kB / 544 B	1.57 kB+17% 📈 / 592 B+9% 📈
controller.js	7.61 kB / 2.18 kB	9.03 kB+19% 📈 / 2.56 kB+17% 📈

[Kocal]

Thank you @ker0x.