React-native-windows: RN docs about "direction" property are incorrect

Created on 23 Apr 2020 · 4Comments · Source: microsoft/react-native-windows

I noticed that facebook’s docs are wrong, in multiple places. For example:
https://reactnative.dev/docs/layout-props#marginstart
The doc says:
“When direction is ltr, marginStart is equivalent to marginLeft. When direction is rtl, marginStart is equivalent to marginRight”
This is making it sound like marginStart flips depending on direction, but marginLeft dow not. However this is not how it actually works. marginStart and marginLeft both behave the same way (ie if direction == ‘rtl’ marginStart/marginLeft are both applied to the right side).

I asked on Discord why it works this way, as it’s clearly not what the docs say. I got this response from Eli White:
“I believe this is the known behavior. RN has always flipped left and right in RTL mode. To enable people to have proper RTL support the start and end properties were introduced, but we've never found a good way to migrate the ecosystem to get the left/right properties to not flip anymore. There is a command I18nManager.swapLeftAndRightInRTL(false) that can disable that flipping. Eventually that should be the default, but it is such a big breaking change we have punted on it for 3 years (timing based on some internal documents I've found)”

Ideally we would document the whole story, which is, essentially two things:
1) All of the start/end properties I linked to above flip with direction
2) For each of those start/end properties, their equivalent left/right properties flip with direction, unless you call I18nManager.swapLeftAndRightInRTL(false), in which case left/right properties will not flip with direction anymore.
I feel strongly we should fix #1 as it’s confusing and just plain wrong. We could debate how to document #2 as it’s a complicated story to tell for each property.

bug

Source