|
| 1 | +# Contributing |
| 2 | + |
| 3 | +Thanks for your help! |
| 4 | + |
| 5 | +This document describes the philosophy behind the bs-react-native-next bindings. |
| 6 | + |
| 7 | +## Zero Cost |
| 8 | + |
| 9 | +Following the spirit of the new hooks-based reason-react 0.7.0, we aim for the |
| 10 | +bindings to be as close to the ideal of zero cost as possible. |
| 11 | + |
| 12 | +This means that, as far as possible, we strive to avoid any bundle size increase |
| 13 | +or performance penalty caused by the usage of these bindings. |
| 14 | + |
| 15 | +Sometimes, this can come at the cost of usability. For example, a variant might |
| 16 | +provide a nicer interface than inlined string constants because it enables |
| 17 | +exhaustiveness checks on pattern matching. But as converting to and from the |
| 18 | +variant comes with extra cost, we will stay with the inlined string constants. |
| 19 | + |
| 20 | +After all, any abstractions on top of our bindings may still be added in user |
| 21 | +code if required. |
| 22 | + |
| 23 | +## JS Objects Passed as Props |
| 24 | + |
| 25 | +We use `[@bs.obj]` to model JS objects passed as props to components or as |
| 26 | +parameters to api functions. This enables us to: |
| 27 | + |
| 28 | +- have optional fields |
| 29 | +- use `[@bs.string]` to map polymorphic variants to strings without extra cost |
| 30 | +- use `[@bs.int]` to map polymorphic variants to strings without extra cost |
| 31 | + |
| 32 | +Example (`Alert` options): |
| 33 | + |
| 34 | +```re |
| 35 | +[@bs.obj] |
| 36 | +external options: |
| 37 | + (~cancelable: bool=?, ~onDismiss: unit => unit=?, unit) => options = |
| 38 | + ""; |
| 39 | +``` |
| 40 | + |
| 41 | +## JS Objects Returned in Callbacks |
| 42 | + |
| 43 | +We model JS objects returned in callbacks or promises as some `Js.t` type, e.g. |
| 44 | + |
| 45 | +```re |
| 46 | +type t = { |
| 47 | + . |
| 48 | + "width": int, |
| 49 | + "height": int, |
| 50 | + "scale": float, |
| 51 | + "fontScale": float, |
| 52 | +}; |
| 53 | + |
| 54 | +[@bs.module "react-native"] [@bs.scope "Dimensions"] |
| 55 | +external get: ([@bs.string] [ | `window | `screen]) => t = ""; |
| 56 | +``` |
| 57 | + |
| 58 | +This way, the fields of the returned `dimensions` object can be easily accessed |
| 59 | +as `dimensions##width` etc. (whereas using e.g. `[@bs.deriving abstract]` would |
| 60 | +require the user to use a getter function like `dimensions->Dimensions.width`). |
0 commit comments