[bpacholek]

What this changes

A field's help in adminata is one small grey line under the control (adm-help, 12px). In recomaty-panel the device settings form (recomaty/recomaty-panel#682) needed more: long explanations and lists of template placeholders read better as a lighter box under the field, in the form's own text size. The panel's prototype drew that box with a form theme and a stylesheet of its own. @bpacholek asked for it to be a setting of adminata, so that the panel needs no override. This PR adds that setting.

• 5bc570570 The help_style option (Form\Extension\HelpStyleTypeExtension, new, extends FormType; service adminata.admin.form.extension.help_style):
  • Values: plain (the default, today's look) or box; the option itself defaults to null.
  • It is inherited. A form or field without a style of its own takes its parent's, so an admin sets it once for its whole form in configureFormOptions() ($formOptions['help_style'] = 'box';). Its fields, sub-forms and collection entries follow, the collection prototype too. A single field can still pick the other style.
  • A form at the top that names no style takes the new adminata.options.help_style (default plain). Setting it to box turns the box on for every form of an application.
  • The resolved style is the view variable help_style. AdminataExtension passes the option to the extension as its default.
• Markup (Form/form_admin_fields.html.twig, form_help): with box, the help's class adm-help becomes adm-help-box. adminata-field-help, help-text, the help's id, help_class and the help's place (under the control and its errors) stay as they are. With plain the output is byte for byte what it was, and the existing layout tests and the demo's JS fixtures pass unchanged.
  • f09b04785: the first commit's comment in form_help trimmed the whitespace around it ({#- … -#}). That shifted the help's <div> left in every form, and JsFixtureDumperTest caught it (the product-create fixture). It is now a plain {# … #}, like the comment it replaced.
• CSS (components/misc.css):
  • @utility adm-help-box: margin 0.5rem; padding 0.75rem 1rem; a gray-100 border with the control's radius; a gray-50 background; gray-600 text at --text-theme-sm (the label's and the control's 14px). In the dark theme: a gray-800 border, white at 5% over the 3% card, gray-400 text.
  • In @layer components: the markup of help_html inside the box (h3/h4, paragraphs, ul/ol with their markers, b/strong, code), which the preflight leaves unstyled.
  • app.css is rebuilt; safelist.css and contract.json are regenerated (one new selector, .adm-help-box).
• Docs: a "Help in a box" section in reference/action_create_edit.rst, the configuration reference, and UPGRADE-1.0's table of new nodes. CHANGELOG: one entry under [Unreleased] → ### Added.

Contract

• Additive only: a new form option, a new config node (options.help_style, default plain), a new service id, a new adm-* utility, and a new view variable. No template, block, hook, registry key or existing node changed meaning. The default rendering is unchanged.
• tests-adminata/Contract/config-reference/adminata.yaml has the new node (3 lines), as ConfigContractTest requires.
• No Bootstrap/AdminLTE class, no jQuery, no inline script. make check-names: clean.
• The demo application does not use the box, so no screenshot baseline or JS fixture changes. The box was looked at in the panel's device settings screen against this branch (light and dark, at 1920×1080); see recomaty/recomaty-panel#684.

Tests

• tests/Form/Extension/HelpStyleTypeExtensionTest.php (new):
  • With no option anywhere, every view has the extension's default (plain, or box when constructed so).
  • A top form's box reaches its field, a sub-form's field, a collection entry and the collection's prototype.
  • A field or sub-form naming the other style keeps it and passes it on, in both directions.
  • An unknown value is refused, as an option and as the default.
• tests/Form/AdminLayoutTest.php:
  • testHelpInABox: adm-help-box adminata-field-help help-text on the help.
  • testAFormsBoxReachesItsFieldsRows: a field with no style of its own, rendered as a row, takes its form's box. help_html stays markup and a row's help_class is kept. A field without help gets no box.
• ConfigurationTest: the default is plain, box is accepted, and side is refused with the path in the message. AdminataExtensionTest: the service, its tag and its argument from the option.
• The option-shape arrays of AdminataConfigurationTest, RenderElementRuntimeTest and RenderElementExtensionTest have the new key.

Gates (local)

• npm ci, then npm run build: only app.css, safelist.css and contract.json change. Stylelint (misc.css), css:layers, Prettier, css:contract (139 selectors) and size (app.css 70.27 kB of 120 kB): all OK.
• php-cs-fixer (dist config) on every changed PHP file: clean. lint:twig (Form), lint:container, check-names: OK.
• PHPStan on the changed files: one error, assertEmpty() in ConfigurationTest::testDashboardWithoutRoles, which is on main already. None from this change.
• PHPUnit admin + adminata-unit: 2377 tests, no failures. 3 errors, all three in DoctrineODMQuerySourceIteratorTest, because this machine has no MongoDB server. adminata-contract: 191 tests, OK.
• Not run here: Rector and the Playwright/Panther suites. The demo's rendering is unchanged, so CI has the say there.

CI (f09b047)

• Green:
  • Visual (screenshots, axe, html-validate)
  • Test on PHP 8.4 lowest, PHP 8.5 highest, PHP 8.5 + Symfony 7.4 and PHP 8.5 + Symfony 8.1
  • Front end (Node 24, 26)
  • Lint, PHP-CS-Fixer, Symfony lint (container, Twig, XLIFF, YAML), Composer, Sphinx
• Red, with nothing from this change:
  • "PHP 8.4 + highest" and the MongoDB fork's unit suite failed before any test ran. Their mongo:8 service container does not start on the runner ("MongoDB cannot start: Linux kernel versions 6.19 and newer has a known incompatibility", SERVER-121912). main's latest MongoDB fork run at 078d2b1 fails the same way. On 5bc5705 the MongoDB fork suite was green and "PHP 8.4 + highest" failed only on the fixture whitespace that f09b047 fixes. Both need a re-run once the runner's MongoDB starts again.
  • PHPStan ×2: the same errors as main's latest Quality assurance run at 078d2b1; the error lists match message for message.
  • Rector ×2: the same 5 files as on main (the ConfigurationTest finding moved down 15 lines with the new test).

Part of recomaty/recomaty-panel#682. The panel's draft PR, recomaty/recomaty-panel#684, moves its composer.lock to this branch's commit, so the change can be seen there before this one is merged. It turns the box on for the device settings form alone and drops its own form theme and stylesheet. After the merge, the panel's lock moves to the merge commit.

Bober's change for recomaty/recomaty-panel#682, made at Bartosz's request.

🦫 ~Bober