Provide a way to deprecate form API array value keys

Does something for this need to be added to the core BC policy too?

Once it exists we should add to the 'how to deprecate' page. For me this is a nicety that doesn't change the BC policy for forms though - there are plenty of form changes that would not be able to use this and we don't want to preclude ourselves from doing them. I also don't think we'd bother using this on obscure admin forms either.

I agree with catch. Adding tag and item to the remaining tasks about updating the 'how to'.

Another thing to consider whether it's worth covering for the deprecation: Some form submit methods use $form_state->getValues(), then reference a specific key on the array, e.g. $form_state->getValues()['confirm']; or $values = $form_state->getValues(); $confirm = $values['confirm'];.

MR is ready.

Can't trigger deprecations for usages ofgetValues() after all, so focusing strictly on getValue().

CR: https://www.drupal.org/node/3521264 →

Updated deprecation version to 11.3 and refactored the test a little.

This looks great - just had one question about some extra coverage for subform state which this code will run for, but we don't have any tests for in the MR yet

Rebased for the merge conflict.
Subform state should be accounted for now, and some logic issues fixed, with additional test coverage.