Allow adding custom suggestions from the render array

Problem/Motivation

Pretty often in the output we have similar elements that can use the same Twig template for rendering. The theme suggestions provided by the module work great for general use, but do not cover the case when we need to theme only a group of specific fields.

Steps to reproduce

Let's get as an example a feedback form with fields: first_name, middle_name, last_name, company_name, topic, message, email.

I want to create a custom Twig template for only all name-related fields: first_name, middle_name, last_name.

The suggestion by the field type "textfield" does not suit, because the "company_name" and "topic" has the "textfield" type too.

The suggestion by the form id - too, because I need to cover only specific fields.

The suggestions per field name too - because I have three different field names.

For now, seems there are several workarounds to achieve this:

1. Create a single Twig template, and symlinks to it for each field name like this:

name-fields-group--my-form.html.twig
first-name--my-form.html.twig » symlink to name-fields-group--my-form.html.twig
middle-name--my-form.html.twig » symlink to name-fields-group--my-form.html.twig
last-name--my-form.html.twig » symlink to name-fields-group--my-form.html.twig

This should work, but looks like a trick with symlinks that is not good.

2. Create several templates and include a general template from them:

name-fields-group--my-form.html.twig
first-name--my-form.html.twig » "{{ include "name-fields-group--my-form.html.twig" }}"
middle-name--my-form.html.twig » "{{ include "name-fields-group--my-form.html.twig" }}"
last-name--my-form.html.twig » "{{ include "name-fields-group--my-form.html.twig" }}"

This looks a bit better, because doesn't use the symlink magic, but not good for performance, because we introduce "proxy" templates.

3. Create a general Twig template for all form fields form-element--form-id--[form-id].html.twig and build the "if" condition in it for each required field name, and include a fallback template for other fields.

This also works but requires hardcoding the "if" condition and will give problems if we need to cover several groups of fields.

Proposed resolution

The proposed solution for this issue is to allow passing the theme suggestions directly from the render element, something like this:

    $form['first_name'] = [
      '#type' => 'textfield',
      '#theme_suggestions' => ['name_fields_group'],
      '#title' => $this->t('Your First Name'),
    ];
    $form['middle_name'] = [
      '#type' => 'textfield',
      '#theme_suggestions' => ['name_fields_group'],
      '#title' => $this->t('Your Middle Name'),
    ];
    $form['last_name'] = [
      '#type' => 'textfield',
      '#theme_suggestions' => ['name_fields_group'],
      '#title' => $this->t('Your Last Name'),
    ];

This #theme_suggestions key will add a suggestion to all these form fields as form-element--name-fields-group--my-form.html.twig and I can theme these files using a single clear Twig file.

What do you think about this suggestion?
And maybe you have better ideas on how to implement this?

Remaining tasks

User interface changes

API changes

Data model changes