RFC: deprecate some a11y queries

[mdjastrzebski]

Problem

Some of our a11y queries are underwhelming:

• getByA11yState({ disabled: true }) - does not give any control over which control we are trying to find. Can be problematic if there are 2+ controls with matching state, we also might accidentally match another disabled control leading to false negative result.
• getByA11yValue({ min: 100 }) - similar issues

Note: these queries have no counterpart in RTL.

Other queries are somewhat more useful, but still less powerful than getByRole:

• getByLabelText
• getByHintText

Users are generally better server by using getByRole with name and state props like disabled, selected, etc.

Note: this queries have counterpart in the RTL world (LabelText) or have similar semantic (HintText).

Proposed solution

1. Add a11y value & hint props support to getByRole in order to make it more versatile
2. Deprecate *ByA11yState and *ByA11yValue queries, and display message to use getByRole with appropriate parameters.
3. Keep *ByLabelText and *ByHintText text as lightweight queries, but mention in the docs that we rather suggest using getByRole with proper additional attributes.

Impact

Soft deprecating, i.e. displaying deprecating warning to console, is not a breaking change, so we might do with minor/feature update.

We then should remove *ByA11yState and *ByA11yValue in the next or next^2 release.

[pierrezimmermannbam]

I think this is a really good idea ! However I wonder if the byLabelText and byA11yValue make sense on their own. It makes sense to keep them if they have a counterpart in RTL, but I'm not sure about keeping queries, not mark them as deprecated and only indicate in documentation that we recommend using getByRole. Most users won't read the documentation so if we really think that using byRole queries is better (which I'm not sure of but I'm not an expert when it comes to accessibility), I wonder if these queries shouldn't be deprecated as well

[thymikee]

If we want to discourage usage, a good start would be to leverage that most of the users use TS, and use the deprecated comment.

To further improve adoption we could create a codemod, ideally applicable through npx so it's a one-liner.

[mdjastrzebski]

@thymikee I think there might be problem with both ideas:

1. @deprecated annotation would be easy for explicit function definitions but we have makeQueries and also do query binding to root instance, hence all function information is inferred.
2. Codemode will not be possible, as user will have to figure out relevant role values for each affected query.

That leaves use with deprecating warning, similar to the one we used in the past, so displaying warning only one per query. I would not worry too much about this queries as they seem to be rather niche and limited, due to their predicates, which is also the reason why I suggested deprecating them.

[AugustinLF]

I agree with the whole train of thought, getByRole. We should also update the doc of those given queries, advising people to go to *ByRole, and not limit ourselves with just the overall doc on query preference.

[mdjastrzebski]

Resolved by #1269