feat!: clamp sheetInitialDetent value

[kkafar]

Description

In case sheetInitialDetent value is not in range [0, sheetAllowedDetents.length - 1] I decided to clamp it.

Alternatives:

• throw an error,
• clamp it and print warning in dev mode that value has been clamped.

Open for discussion.

Test code and steps to reproduce

Test1649

Checklist

• Included code example that can be used to test this change
• Updated TS types
• Updated documentation:
  • https://github.com/software-mansion/react-native-screens/blob/main/guides/GUIDE_FOR_LIBRARY_AUTHORS.md
  • https://github.com/software-mansion/react-native-screens/blob/main/native-stack/README.md
  • https://github.com/software-mansion/react-native-screens/blob/main/src/types.tsx
  • https://github.com/software-mansion/react-native-screens/blob/main/src/native-stack/types.tsx
• Ensured that CI passes

[alduzy]

Good idea!
Let's remove the out of bounds errors error (edit: let's keep the one for iOS < 16 where the allowedDetents are replaced with system-defined ones) from ios/RNSScreen.mm then.

OR change them to warnings, which will give a clue about the misuse

[kkafar]

@alduzy I think the checks on native side should stay as they are. This causes less coupling (I know we have a ton of assumptions on what our JS code does, but IMHO it should not legitimise us to create more coupling) and in case someone changes JS code in the future, there will be check for this invariant on native side.

[kkafar]

On meeting we decided to go with different way of error handling & different shape of API.