From 816d7531e313a16721cf9d478317fbedf869643e Mon Sep 17 00:00:00 2001 From: Sam Li Date: Wed, 12 Apr 2017 11:59:51 -0700 Subject: [PATCH] Migrate flexbox layout guide to a custom page (#114) --- GUIDE.md | 1244 ++++++++++++++++++++++++++++++++++++++++++++++++++++ bower.json | 3 + 2 files changed, 1247 insertions(+) create mode 100644 GUIDE.md diff --git a/GUIDE.md b/GUIDE.md new file mode 100644 index 0000000..e82ea6e --- /dev/null +++ b/GUIDE.md @@ -0,0 +1,1244 @@ +## Overview + +The `iron-flex-layout` component provides simple ways to use [CSS flexible box layout](https://developer.mozilla.org/en-US/docs/Web/Guide/CSS/Flexible_boxes), also known as _flexbox_. This component provides two different ways to use flexbox: + +* Layout classes. The layout class stylesheet provides a simple set of class-based flexbox rules. Layout classes + let you specify layout properties directly in markup. + +* Custom CSS mixins. The mixin stylesheet includes custom CSS mixins that can be applied + inside a CSS rule using the `@apply` function. + +Using the classes or CSS mixins is largely a matter of preference. The following sections discuss +how to use the each of the stylesheets. + +> Note: Before using either of these stylesheets, it's helpful to be familiar with the basics +of flexbox layout. Chris Coyier's [A Complete Guide to Flexbox](https://css-tricks.com/snippets/css/a-guide-to-flexbox/) is a +good primer. + +### Using layout classes + +To use layout classes import the `iron-flex-layout-classes` file. You +must do this in any element that uses any of the `iron-flex-layout` styles. +```html + +``` + +Then include the module(s) that you need: +```html + + + + + + +
+
One
+
Two
+
Three
+
+ + +``` +**Example: using classes in a Polymer element** +```html + + + ... + + + + + + + + + + + +``` + +It's important to note that unlike the previous layout class stylesheets +(found in `/classes/iron-flex-layout.html`), the new version does not use the `/deep/` +combinator: it does not work across local DOM boundaries, +and the modules must be imported into each scope where they're used. + +### Using layout mixins + +Custom mixins can be applied inside a Polymer +custom element's stylesheet, **or** inside a `custom-style` stylesheet to apply styles to the +main document. (They cannot be applied in the main document without a `custom-style` stylesheet.) + +**Example: using mixins in the main document** +```html + + + ... + + + + ... + + + + + + + +
+
One
+
Two
+
Three
+
+ + +``` +**Example: using mixins in a Polymer element** +```html + + + ... + + + + + + + + + + + +``` + +In general the mixins require a little more code to use, but they can be preferable if you +don't want to use the classes, or if you want to switch layouts based on a media query. + +Custom CSS properties and mixins are features provided by the Polymer library. +See [Cross-scope styling](https://www.polymer-project.org/1.0/docs/devguide/styling.html#xscope-styling) +in the Polymer developer guide. + +## Horizontal and vertical layout + +Create a flex container that lays out its children vertically or horizontally. + +Class | Mixin | Result +:-|:-|:- +layout horizontal| --layout-horizontal | Horizontal layout container. +layout vertical | --layout-vertical | Vertical layout container. + +The classes listed here are included in the `iron-flex` module of the `iron-flex-layout-classes` file. + +**Example: classes** +```html +
+
One
+
Two
+
Three
+
+``` + +**Example: mixins** + +```html + + +
+
One
+
Two
+
Three
+
+``` + +### Flexible children + +Children of a flex container can use flex to control their own sizing. + +Class | Mixin | Result +:-|:-|:- +flex| --layout-flex | Expand the child to fill available space in the main axis. +flex-ratio| --layout-flex-ratio | Assign a flex ratio of 1 to 12. +flex-none| --layout-flex-none | Don't flex the child. +flex-auto| --layout-flex-auto | Sets flex `flex-basis` to `auto` and `flex-grow` and `flex-shrink` to 1. + +The classes listed here are included in the `iron-flex` module of the `iron-flex-layout-classes` file. + +**Example: classes** +```html +
+
Alpha
+
Beta (flex)
+
Gamma
+
+``` + +**Example: mixins** + +```html + + +
+
Alpha
+
Beta (flex)
+
Gamma
+
+``` + +#### Flexible children in vertical layouts + +The same rules can be used for children in vertical layouts. + +**Example: classes** +```html +
+
Alpha
+
Beta (flex)
+
Gamma
+
+``` + +**Example: mixins** + +```html + + +
+
One
+
Two
+
Three
+
+``` + +> **Note**: for vertical layouts, the container needs to have a height for the +children to flex correctly. + +#### Flex ratios + +Children elements can be told to take up more space by including a "flex ratio" +from 1 to 12. This is equivalent to specifying the CSS `flex-grow` property. + +For example, the following examples make "Gamma" 2x larger than "Beta" and "Alpha" 3x larger, use +`flex-2` and `flex-3`, respectively. + +The classes listed here are included in the `iron-flex-factors` module of the `iron-flex-layout-classes` file. + +**Example: classes** +```html +
+
Alpha
+
Beta
+
Gamma
+
+``` + +**Example: mixins** + +```html + + +
+
One
+
Two
+
Three
+
+``` + +### Cross-axis alignment + +By default, children stretch to fit the cross-axis (e.g. _vertical_ stretching in a _horizontal_ layout). + + +```html +
+
Stretch Fill
+
+``` + +Center _across_ the main axis (e.g. _vertical_ centering elements in a _horizontal_ layout) +by adding the `center` class or applying the `--layout-center` mixin. + +**Example: classes, cross-axis center** + +```html +
+
Center
+
+``` + +**Example: mixins, cross-axis center** + +```html + + +
+
Center
+
+``` + +You can also position at the top/bottom (or left/right in `vertical` layouts) using the `start` or `end` +classes, or by applying the `--layout-start` or `--layout-end` mixins. + + +**Example: classes, cross-axis start** + +```html +
+
start
+
+``` + +**Example: mixins, cross-axis start** + +```html + + +
+
start
+
+``` + +**Example: classes, cross-axis end** + +```html +
+
end
+
+``` + +**Example: mixins, cross-axis end** + +```html + + +
+
end
+
+``` + +### Justification + +Justifying aligns contents along the **main axis**. Justify the layout +by specifying one of the following. + + +Class | Mixin | Result +:-|:-|:- +`start-justified`| --layout-start-justified | Aligns contents at the start of the main axis. +`center-justified` | --layout-center-justified | Centers contents along the main axis. +`end-justified` | --layout-end-justified | Aligns contents to the end of the main axis. +`justified` | --layout-justified | Aligns contents with equal spaces between children. +`around-justified` | --layout-around-justified | Aligns contents with equal spaces arround children. + +The classes listed here are included in the `iron-flex-alignment` module of the `iron-flex-layout-classes` file. + +**Example: classes, start justified** + +```html +
+
start-justified
+
+``` + +**Example: mixins, center justified** + +```html + + +
+
center-justified
+
+``` + +**Example: classes, end justified** + +```html +
+
end-justified
+
+``` + +**Example: mixins, equal space between elements** + +```html + + +
+
justified
+
justified
+
justified
+
+``` + +**Example: classes, equal space around each element** + +```html +
+
around-justified
+
around-justified
+
+``` + +## Self alignment + +Alignment can also be set per-child (instead of using the layout container's rules). + +Class | Mixin | Result +:-|:-|:- +`self-start`| --layout-self-start | Aligns the child at the start of the cross-axis. +`self-center` | --layout-self-center | Centers the child along the cross-axis. +`self-end` | --layout-self-end | Aligns the child at the end of the cross-axis. +`self-stretch` | --layout-self-stretch | Stretches the child to fit the cross-axis. + +**Example: classes** + +```html +
+
Alpha
+
Beta
+
Gamma
+
Delta
+
+``` + +**Example: mixins** + +```html + +
+
Alpha
+
Beta
+
Gamma
+
Delta
+
+``` + +> Note: The flex class +(and --layout-flex mixin) shown in these examples is +added for the demo and not required for self-alignment. + + +## Wrapping + +Wrapped layouts can be enabled with the `wrap` class or `--layout-wrap` mixin. + +**Example: classes** + +```html +
+
Alpha
+
Beta
+
Gamma
+
Delta
+
+``` + +## Reversed layouts + +Layout direction can be mirrored using the following rules: + +Class | Mixin | Result +:-|:-|:- +layout horizontal-reverse| --layout-horizontal-reverse | Horizontal layout with children laid out in reverse order (last-to-first). +layout vertical-reverse | --layout-vertical-reverse | Vertical layout with children laid out in reverse order. +layout wrap-reverse | --layout-wrap-reverse | Wrap layout with wrapped rows placed in the reverse order (for example, in a vertical layout, the second row is placed above the first row, instead of below). + +The classes listed here are included in the `iron-flex-reverse` module of the `iron-flex-layout-classes` file. + +**Example: mixins** + +```html + + +
+
Alpha
+
Beta
+
Gamma
+
Delta
+
+``` + +## Full bleed <body> + +It's common to want the entire `` to fit to the viewport. By themselves, Polymer's layout features on +`` don't achieve the result. You can make `` take up the entire viewport by adding the `fullbleed` class: + +```html + +
Fitting a fullbleed body.
+ +``` + +This removes its margins and maximizes its height to the viewport. There is no equivalent mixin, but the same result can +be achieved in CSS very simply: +```css +body { + margin: 0; + height: 100vh; +} +``` + +This class is included in the `iron-positioning` module of the `iron-flex-layout-classes` file. + +Note that the `fullbleed` class **only works on the `` tag.** This is the only rule in the +stylesheet that is scoped to a particular tag. + + +## General purpose rules + +Polymer also includes other general purpose rules for basic positioning: + +Class | Mixin | Result +:-|:-|:- +`block`| `--layout-block` | Assigns `display: block` +`invisible` | `--layout-invisible` | Assigns `visibility: hidden` +`relative` | `--layout-relative` | Assigns `position: relative` +`fit` | `--layout-fit` | Sets `position: absolute` and sets `top:0;right:0;bottom:0;left:0;` (aka "trbl fitting"). + +The classes listed here are included in the `iron-positioning` module of the `iron-flex-layout-classes` file. + +> Note:When using `fit` layout, the element must have an ancestor with fixed size and `position: relative` layout +to fit inside of. + + +**Example: classes** + +```html +
Before [A Span] After
+
Before [A Block Span] After
+
Before invisible span After invisible span
+
+
Fit
+
+``` diff --git a/bower.json b/bower.json index 30c6afe..daf0bd9 100644 --- a/bower.json +++ b/bower.json @@ -27,5 +27,8 @@ "webcomponentsjs": "webcomponents/webcomponentsjs#^0.7.0", "web-component-tester": "^4.0.0" }, + "pages": { + "Flexbox layout guide": "GUIDE.md" + }, "ignore": [] }