Skip to content

Add documentation for StyleSheet API #520

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 31, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions reason-react-native/src/apis/Style.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ the last style in the array has precedence, so you can use this to mix & inherit
styles.

⚠️ _Note that when a component grows in complexity, it is often cleaner to use
[`StyleSheet.create`](/bs-react-native/en/docs/apis/StyleSheet/) to define
several styles in one place_.
[`StyleSheet.create`](../StyleSheet/#create) to define several styles in one
place_.

We have made different style constructors because React Native have various
components that accept different styles props. For example `View` doesn't accept
Expand Down
113 changes: 101 additions & 12 deletions reason-react-native/src/apis/StyleSheet.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,109 @@
---
id: apis/StyleSheet
title: StyleSheet
wip: true
officialDoc: https://facebook.github.io/react-native/docs/stylesheet
---

`StyleSheet` mainly has a method to [create](#create) an object containing many
styles, similar to a CSS StyleSheet. This is helpful to keep style definitions
at fewer locations, away from the render function. Separating concerns in your
code in this manner should help readability. Named styles might also help
differentiate between your components. Finally, allowing components to refer to
styles by ID, it also reduces the amount of data transferred over the JS bridge.

There is also a [`flatten`](#flatten) method to merge multiple styles into a single style
and several [constants](#constants) for commonly used style definitions.

## Methods

### `create`

Takes and returns `Js.t('a)` objects, with `string` keys and `Style.t` values.
Individual styles can be accessed using `##`, followed by the name specified as
the key.

Note that using `Style.array` or `Style.list` to pass `array(Style.t)` or
`list(Style.t)` is illegal within a `StyleSheet`, even those are valid `style`
props for components. You may, howevever, use the [`flatten`](#flatten) method
to convert `array(Style.t)` into a valid `Style.t` object.

```reason
create: Js.t('a) => Js.t('a)
```
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps we revisit this issue later, but I don't think there is a way to exclude array(Style.t) without a lot of pain elsewhere.


### `flatten`

Takes an array of styles (of type `Style.t`) and returns a single style (also of
type `Style.t`). Creates a `Style.t` object which is valid in a `StyleSheet`.

```reason
flatten: array(Style.t) => Style.t
```

## Constants

### `hairlineWidth`

To ensure the resulting line will look sharp, this specifies an integer number
of pixels which should approximate the standard thickness of a thin line on the
platform given the screen density.

```reason
hairlineWidth: float
```

### `absoluteFill`

This is the style

```
{
position: 'absolute',
left: 0,
right: 0,
top: 0,
bottom: 0
}
```

which is frequently used to create overlays. A common use is to add these props
to a style using the spread operator (`...`), but as ReasonML does not allow the
operator when fields are not explicitly set, you may use the `flatten` method
instead.

```reason
[@bs.module "react-native"] [@bs.scope "StyleSheet"]
external hairlineWidth: float = "";
[@bs.module "react-native"] [@bs.scope "StyleSheet"]
external absoluteFill: Style.t = "";
[@bs.module "react-native"] [@bs.scope "StyleSheet"]
external absoluteFillObject: Style.t = "";

[@bs.module "react-native"] [@bs.scope "StyleSheet"]
external create: Js.t('a) => Js.t('a) = "";
[@bs.module "react-native"] [@bs.scope "StyleSheet"]
external flatten: array(Style.t) => Style.t = "";
absoluteFill: Style.t
```

### `absoluteFillObject`

This is identical to `absoluteFill` when used with pure functions.

```reason
absoluteFillObject: Style.t
```

## Example

Please also see the [example](../Style/#style-example) in documentation of the
`Style` API.

```reason
open ReactNative;

let borderStyle = Style.(style(~borderWidth=StyleSheet.hairlineWidth, ()));

let styles =
Style.(
StyleSheet.create({
// style may be defined inline
"container": style(~flex=1., ~flexDirection=`column, ()),
"screen": style(~width=pt(windowWidth), ()),
// or already defined elsewhere
"borderStyle": borderStyle,
"overlay": StyleSheet.absoluteFill,
})
);

let flatStyle = StyleSheet.flatten([|styles##container, styles##screen|]);
```