Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Overhaul the Flexbox documentation #8395

Closed
wants to merge 4 commits into from
Closed

Overhaul the Flexbox documentation #8395

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
363491a
lots of flex docs
lacker Jun 24, 2016
142c7cb
fix docs around positioning
lacker Jun 24, 2016
9c9c745
fix a slew of little things
lacker Jun 24, 2016
00d07d5
fix position docs AGAIN
lacker Jun 24, 2016
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
273 changes: 262 additions & 11 deletions Libraries/StyleSheet/LayoutPropTypes.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,63 +20,277 @@ var ReactPropTypes = require('ReactPropTypes');
*
* The implementation in css-layout is slightly different from what the
* Flexbox spec defines - for example, we chose more sensible default
* values. Please refer to the css-layout README for details.
* values. Since our layout docs are generated from the comments in this
* file, please keep a brief comment describing each prop type.
*
* These properties are a subset of our styles that are consumed by the layout
* algorithm and affect the positioning and sizing of views.
*/
var LayoutPropTypes = {
/** `width` sets the width of this component.
*
* It works similarly to `width` in CSS, but in React Native you
* must use logical pixel units, rather than percents, ems, or any of that.
* See http://www.w3schools.com/cssref/pr_dim_width.asp for more details.
*/
width: ReactPropTypes.number,

/** `height` sets the height of this component.
*
* It works similarly to `height` in CSS, but in React Native you
* must use logical pixel units, rather than percents, ems, or any of that.
* See http://www.w3schools.com/cssref/pr_dim_width.asp for more details.
*/
height: ReactPropTypes.number,

/** `top` is the number of logical pixels to offset the top edge of
* this component.
*
* It works similarly to `top` in CSS, but in React Native you must
* use logical pixel units, rather than percents, ems, or any of that.
*
* See https://developer.mozilla.org/en-US/docs/Web/CSS/top
* for more details of how `top` affects layout.
*/
top: ReactPropTypes.number,

/** `left` is the number of logical pixels to offset the left edge of
* this component.
*
* It works similarly to `left` in CSS, but in React Native you must
* use logical pixel units, rather than percents, ems, or any of that.
*
* See https://developer.mozilla.org/en-US/docs/Web/CSS/left
* for more details of how `left` affects layout.
*/
left: ReactPropTypes.number,

/** `right` is the number of logical pixels to offset the right edge of
* this component.
*
* It works similarly to `right` in CSS, but in React Native you must
* use logical pixel units, rather than percents, ems, or any of that.
*
* See https://developer.mozilla.org/en-US/docs/Web/CSS/right
* for more details of how `right` affects layout.
*/
right: ReactPropTypes.number,

/** `bottom` is the number of logical pixels to offset the bottom edge of
* this component.
*
* It works similarly to `bottom` in CSS, but in React Native you must
* use logical pixel units, rather than percents, ems, or any of that.
*
* See https://developer.mozilla.org/en-US/docs/Web/CSS/bottom
* for more details of how `top` affects layout.
*/
bottom: ReactPropTypes.number,

/** `minWidth` is the minimum width for this component, in logical pixels.
*
* It works similarly to `min-width` in CSS, but in React Native you
* must use logical pixel units, rather than percents, ems, or any of that.
*
* See http://www.w3schools.com/cssref/pr_dim_min-width.asp
* for more details.
*/
minWidth: ReactPropTypes.number,

/** `maxWidth` is the maximum width for this component, in logical pixels.
*
* It works similarly to `max-width` in CSS, but in React Native you
* must use logical pixel units, rather than percents, ems, or any of that.
*
* See http://www.w3schools.com/cssref/pr_dim_max-width.asp
* for more details.
*/
maxWidth: ReactPropTypes.number,

/** `minHeight` is the minimum height for this component, in logical pixels.
*
* It works similarly to `min-height` in CSS, but in React Native you
* must use logical pixel units, rather than percents, ems, or any of that.
*
* See http://www.w3schools.com/cssref/pr_dim_min-height.asp
* for more details.
*/
minHeight: ReactPropTypes.number,

/** `maxHeight` is the maximum height for this component, in logical pixels.
*
* It works similarly to `max-height` in CSS, but in React Native you
* must use logical pixel units, rather than percents, ems, or any of that.
*
* See http://www.w3schools.com/cssref/pr_dim_max-height.asp
* for more details.
*/
maxHeight: ReactPropTypes.number,

/** Setting `margin` has the same effect as setting each of
* `marginTop`, `marginLeft`, `marginBottom`, and `marginRight`.
*/
margin: ReactPropTypes.number,

/** Setting `marginVertical` has the same effect as setting both
* `marginTop` and `marginBottom`.
*/
marginVertical: ReactPropTypes.number,

/** Setting `marginHorizontal` has the same effect as setting
* both `marginLeft` and `marginRight`.
*/
marginHorizontal: ReactPropTypes.number,

/** `marginTop` works like `margin-top` in CSS.
* See http://www.w3schools.com/cssref/pr_margin-top.asp
* for more details.
*/
marginTop: ReactPropTypes.number,

/** `marginBottom` works like `margin-bottom` in CSS.
* See http://www.w3schools.com/cssref/pr_margin-bottom.asp
* for more details.
*/
marginBottom: ReactPropTypes.number,

/** `marginLeft` works like `margin-left` in CSS.
* See http://www.w3schools.com/cssref/pr_margin-left.asp
* for more details.
*/
marginLeft: ReactPropTypes.number,

/** `marginRight` works like `margin-right` in CSS.
* See http://www.w3schools.com/cssref/pr_margin-right.asp
* for more details.
*/
marginRight: ReactPropTypes.number,

/** `padding` works like `padding` in CSS.
* It's like setting each of `paddingTop`, `paddingBottom`,
* `paddingLeft`, and `paddingRight` to the same thing.
* See http://www.w3schools.com/css/css_padding.asp
* for more details.
*/
padding: ReactPropTypes.number,

/** Setting `paddingVertical` is like setting both of
* `paddingTop` and `paddingBottom`.
*/
paddingVertical: ReactPropTypes.number,

/** Setting `paddingHorizontal` is like setting both of
* `paddingLeft` and `paddingRight`.
*/
paddingHorizontal: ReactPropTypes.number,

/** `paddingTop` works like `padding-top` in CSS.
* See http://www.w3schools.com/cssref/pr_padding-top.asp
* for more details.
*/
paddingTop: ReactPropTypes.number,

/** `paddingBottom` works like `padding-bottom` in CSS.
* See http://www.w3schools.com/cssref/pr_padding-bottom.asp
* for more details.
*/
paddingBottom: ReactPropTypes.number,

/** `paddingLeft` works like `padding-left` in CSS.
* See http://www.w3schools.com/cssref/pr_padding-left.asp
* for more details.
*/
paddingLeft: ReactPropTypes.number,

/** `paddingRight` works like `padding-right` in CSS.
* See http://www.w3schools.com/cssref/pr_padding-right.asp
* for more details.
*/
paddingRight: ReactPropTypes.number,

/** `borderWidth` works like `border-width` in CSS.
* See http://www.w3schools.com/cssref/pr_border-width.asp
* for more details.
*/
borderWidth: ReactPropTypes.number,

/** `borderTopWidth` works like `border-top-width` in CSS.
* See http://www.w3schools.com/cssref/pr_border-top_width.asp
* for more details.
*/
borderTopWidth: ReactPropTypes.number,

/** `borderRightWidth` works like `border-right-width` in CSS.
* See http://www.w3schools.com/cssref/pr_border-right_width.asp
* for more details.
*/
borderRightWidth: ReactPropTypes.number,

/** `borderBottomWidth` works like `border-bottom-width` in CSS.
* See http://www.w3schools.com/cssref/pr_border-bottom_width.asp
* for more details.
*/
borderBottomWidth: ReactPropTypes.number,

/** `borderLeftWidth` works like `border-left-width` in CSS.
* See http://www.w3schools.com/cssref/pr_border-bottom_width.asp
* for more details.
*/
borderLeftWidth: ReactPropTypes.number,

/** `position` in React Native is similar to regular CSS, but
* everything is set to `relative` by default, so `absolute`
* positioning is always just relative to the parent.
*
* If you want to position a child using specific numbers of logical
* pixels relative to its parent, set the child to have `absolute`
* position.
*
* If you want to position a child relative to something
* that is not its parent, just don't use styles for that. Use the
* component tree.
*
* See https://github.com/facebook/css-layout
* for more details on how `position` differs between React Native
* and CSS.
*/
position: ReactPropTypes.oneOf([
'absolute',
'relative'
]),

// https://developer.mozilla.org/en-US/docs/Web/CSS/flex-direction
/** `flexDirection` controls which directions children of a container go.
* `row` goes left to right, `column` goes top to bottom, and you may
* be able to guess what the other two do. It works like `flex-direction`
* in CSS, except the default is `column`. See
* https://css-tricks.com/almanac/properties/f/flex-direction/
* for more detail.
*/
flexDirection: ReactPropTypes.oneOf([
'row',
'row-reverse',
'column',
'column-reverse'
]),

// https://developer.mozilla.org/en-US/docs/Web/CSS/flex-wrap
/** `flexWrap` controls whether children can wrap around after they
* hit the end of a flex container.
* It works like `flex-wrap` in CSS. See
* https://css-tricks.com/almanac/properties/f/flex-wrap/
* for more detail.
*/
flexWrap: ReactPropTypes.oneOf([
'wrap',
'nowrap'
]),

// How to align children in the main direction
// https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content
/** `justifyContent` aligns children in the main direction.
* For example, if children are flowing vertically, `justifyContent`
* controls how they align vertically.
* It works like `justify-content` in CSS. See
* https://css-tricks.com/almanac/properties/j/justify-content/
* for more detail.
*/
justifyContent: ReactPropTypes.oneOf([
'flex-start',
'flex-end',
Expand All @@ -85,17 +299,27 @@ var LayoutPropTypes = {
'space-around'
]),

// How to align children in the cross direction
// https://developer.mozilla.org/en-US/docs/Web/CSS/align-items
/** `alignItems` aligns children in the cross direction.
* For example, if children are flowing vertically, `alignItems`
* controls how they align horizontally.
* It works like `align-items` in CSS, except the default value
* is `stretch` instead of `flex-start`. See
* https://css-tricks.com/almanac/properties/a/align-items/
* for more detail.
*/
alignItems: ReactPropTypes.oneOf([
'flex-start',
'flex-end',
'center',
'stretch'
]),

// How to align the element in the cross direction
// https://developer.mozilla.org/en-US/docs/Web/CSS/align-items
/** `alignSelf` controls how a child aligns in the cross direction,
* overriding the `alignItems` of the parent. It works like `align-self`
* in CSS. See
* https://css-tricks.com/almanac/properties/a/align-self/
* for more detail.
*/
alignSelf: ReactPropTypes.oneOf([
'auto',
'flex-start',
Expand All @@ -104,10 +328,37 @@ var LayoutPropTypes = {
'stretch'
]),

// https://developer.mozilla.org/en-US/docs/Web/CSS/flex
/** In React Native `flex` does not work the same way that it does in CSS.
* `flex` is a number rather than a string, and it works
* according to the `css-layout` library
* at https://github.com/facebook/css-layout .
*
* When `flex` is a positive number, it makes the component flexible
* and it will be sized proportional to its flex value. So a
* component with `flex` set to 2 will take twice the space as a
* component with `flex` set to 1.
*
* When `flex` is 0, the component is sized according to `width`
* and `height` and it is inflexible.
*
* When `flex` is -1, the component is normally sized according
* `width` and `height`. However, if there's not enough space,
* the component will shrink to its `minWidth` and `minHeight`.
*/
Copy link
Contributor

Choose a reason for hiding this comment

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

It would be nice to say a little bit more about flex but not sure what. Perhaps more about what the positive number means.

flex: ReactPropTypes.number,

// https://developer.mozilla.org/en-US/docs/Web/CSS/z-index
/** `zIndex` controls which components display on top of others.
* Normally, you don't use `zIndex`. Components render according to
* their order in the document tree, so later components draw over
* earlier ones. `zIndex` may be useful if you have animations or custom
* modal interfaces where you don't want this behavior.
*
* It works like the CSS `z-index` property - components with a larger
* `zIndex` will render on top. Think of the z-direction like it's
* pointing from the phone into your eyeball. See
* https://developer.mozilla.org/en-US/docs/Web/CSS/z-index for
* more detail.
*/
zIndex: ReactPropTypes.number,
};

Expand Down
10 changes: 5 additions & 5 deletions docs/Basics-Layout.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
---
id: basics-layout
title: Layout
title: Layout with Flexbox
layout: docs
category: The Basics
permalink: docs/basics-layout.html
permalink: docs/flexbox.html
Copy link
Contributor

Choose a reason for hiding this comment

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

I think we don't need to worry about breaking the bookmarks to that page.
Who would bookmark it?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Google. This page is one of the most visited on the site right now. People search for [react native flexbox] and it's the first link.

Copy link
Contributor

Choose a reason for hiding this comment

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

Oops, we need a redirect then

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I mean that docs/flexbox.html is popular. docs/basics-layout.html doesnt exist yet. Previously docs/flexbox.html was the autogen flexbox doc, now it's this part of "the basics", so the links should just send people here now.

next: basics-component-textinput
---

A component can specify the layout of its children using the flexbox algorithm. Flexbox is designed to provide a consistent layout on different screen sizes.

You will normally use a combination of `flexDirection`, `alignItems`, and `justifyContent` to achieve the right layout.

> Flexbox works the same way in React Native as it does in CSS on the web, with a few exceptions. The most notable one: the defaults are different, with `flexDirection` defaulting to `column` instead of `row`, and `alignItems` defaulting to `stretch` instead of `flex-start`.
> Flexbox works the same way in React Native as it does in CSS on the web, with a few exceptions. The defaults are different, with `flexDirection` defaulting to `column` instead of `row`, and `alignItems` defaulting to `stretch` instead of `flex-start`, and the `flex` parameter only supports a single number.

#### Flex Direction

Expand Down Expand Up @@ -99,6 +99,6 @@ class AlignItemsBasics {
AppRegistry.registerComponent('AwesomeProject', () => AlignItemsBasics);
```

#### API Reference
#### Going Deeper

We've covered the basics, but there are many other styles you may need for layouts. The full list is available [here](./docs/flexbox.html).
We've covered the basics, but there are many other styles you may need for layouts. The full list of props that control layout is documented [here](./docs/layout-props.html).
4 changes: 3 additions & 1 deletion website/server/extractDocs.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,9 @@ function removeExtName(filepath) {
function getNameFromPath(filepath) {
filepath = removeExtName(filepath);
if (filepath === 'LayoutPropTypes') {
return 'Flexbox';
return 'Layout Props';
} else if (filepath == 'ShadowPropTypesIOS') {
return 'Shadow Props';
} else if (filepath === 'TransformPropTypes') {
return 'Transforms';
} else if (filepath === 'TabBarItemIOS') {
Expand Down