RFC: readability vs RTL compatibility in API naming

RNTL is modelled after RTL, as one of our unstated goals we strive to reimplement RTL for React Native platform, expose familiar features and APIs while accounting for platform differences.

So far we have been reasonably successful with this approach as it delivered familiar and well thought out API. However recently, when we started to implement A11y-related features I’ve found that some of them are somewhat confusingly named:

• isInaccessible - which checks if the element is hidden from accessibility, which is a different concept that being accessibility element as indicated by accessible prop. Values of accessibility prop and results of isInaccessible are independent and all four combinations (true/false) are allowed.
• hidden query option - this option controls whether we include elements hidden from accessibility in our queries. However, it is unintuitive whether hidden: true or hidden: false includes the hidden elements and I have to refer to the documentation to check that.

I think readability of our code could be improved by renaming these in a following way:

• isInaccessible -> isHiddenFromAccessibility
• hidden option -> includeHidden

Note: the change is only about the naming, the arguments or behaviour do not change.

Such renaming would however break our naming compatibility with RTL.

I see couple of options how we could approach that:

1. Keep RTL naming
2. Rename them
3. Expose both names: promote the readable name as primary, while allowing RTL-compatible name as a secondary option.

I think we should consider using 3rd option, as it gives us both more explicit and readable code while catering for people with RTL background.

@thymikee @AugustinLF @pierrezimmermannbam @MattAgn What do you think?

[AugustinLF]

IMO the length of the param shouldn’t necessarily be a problem. Ideally you want to enable that as a global settings, and only change it when needed, which hopefully should be almost never.

[AugustinLF]

I vote for the third solution. Or even better, suggest RTL to change 😃 I agree that we need better name, and RTL’s naming shouldn’t be the lowest denominator. However having the same names is very important

• for people working with both web and native, this’ll lead to painful times where you end up using the wrong variable name
• at Klarna we have a wrapper library to be able to write our tests once and run on both platforms (branching to RTL or RNTL), so consistent API is important, especially for things like parameters, or properties on object returned (queries for instance). What I mean is that it’s easy enough for us to alias isInaccessible through an export, but aliasing hidden is kind of ugly, we need to create a wrapper function, it’ll pollute stack traces, etc.