From 36d4169a7ea43c922a15972ea6001eb539d2a4f8 Mon Sep 17 00:00:00 2001
From: Panayot Cankov <Panayot.Cankov@telerik.com>
Date: Mon, 24 Oct 2016 17:34:26 +0300
Subject: [PATCH] Add flexbox-layout.md

---
 tests/app/ui/layouts/flexbox-layout-page.xml | 47 ++++++++++++++
 tests/app/ui/layouts/flexbox-layout-tests.ts | 22 ++++++-
 tests/app/ui/layouts/flexbox-layout.md       | 66 ++++++++++++++++++++
 3 files changed, 132 insertions(+), 3 deletions(-)
 create mode 100644 tests/app/ui/layouts/flexbox-layout-page.xml
 create mode 100644 tests/app/ui/layouts/flexbox-layout.md

diff --git a/tests/app/ui/layouts/flexbox-layout-page.xml b/tests/app/ui/layouts/flexbox-layout-page.xml
new file mode 100644
index 000000000..fd0ca570d
--- /dev/null
+++ b/tests/app/ui/layouts/flexbox-layout-page.xml
@@ -0,0 +1,47 @@
+<!-- >> flexbox-layout-page -->
+<Page xmlns="http://schemas.nativescript.org/tns.xsd">
+    <FlexboxLayout flexDirection="column">
+        <!-- Reverse the natural flow of items -->
+        <FlexboxLayout height="22" flexDirection="row-reverse">
+            <!-- Use even flexGrow to achieve uniform grid -->
+            <Label text="1" backgroundColor="#EEEEEE" flexGrow="1" id="one" />
+            <Label text="2" backgroundColor="#DDDDDD" flexGrow="1" />
+            <Label text="3" backgroundColor="#CCCCCC" flexGrow="1" />
+            <Label text="4" backgroundColor="#BBBBBB" flexGrow="1" />
+            <Label text="5" backgroundColor="#AAAAAA" flexGrow="1" />
+            <Label text="6" backgroundColor="#999999" flexGrow="1" id="six" />
+        </FlexboxLayout>
+
+        <!-- Set flexGrow to accomodate into any extra space -->
+        <ScrollView flexGrow="1" id="scrollview">
+
+            <!-- Wrap excessive items on new lines -->
+            <FlexboxLayout flexWrap="wrap" alignContent="flex-start">
+
+                <Label textWrap="wrap" text="Sed aliquet diam sed augue vestibulum scelerisque." id="title" />
+
+                <!-- Use flexWrapBefore to control explicit line wrapping -->
+                <Label text="Gihub issue labels:" flexWrapBefore="true" fontSize="11" />
+
+                <Label text="S: High" flexWrapBefore="true" borderRadius="5" backgroundColor="red" margin="2" id="firstlabel" />
+                <Label text="T: Feature" borderRadius="5" backgroundColor="green" margin="2"/>
+                <Label text="3 - In Progress" borderRadius="5" backgroundColor="gray" margin="2"/>
+                <Label text="S: Ullamcorper" borderRadius="5" backgroundColor="red" margin="2" />
+                <Label text="T: Vulputate" borderRadius="5" backgroundColor="green" margin="2"/>
+                <Label text="2 - Egestas magna" borderRadius="5" backgroundColor="gray" margin="2"/>
+                <Label text="S: High" borderRadius="5" backgroundColor="red" margin="2" />
+                <Label text="T: Phasellus" borderRadius="5" backgroundColor="green" margin="2"/>
+                <Label text="Nullam" borderRadius="5" backgroundColor="gray" margin="2"/>
+
+                <Label flexWrapBefore="true" textWrap="wrap" text="Pellentesque molestie nibh et leo facilisis gravida ac porttitor eros. Etiam tempus diam nulla, ut fermentum mauris aliquet quis. Cras finibus vitae magna in bibendum." id="description" />
+            </FlexboxLayout>
+        </ScrollView>
+        <FlexboxLayout>
+            <Button text="&lt;" width="50" backgroundColor="gray" />
+            <!-- Set flexGrow to 1 accomodate into any extra space -->
+            <Button text="reactions" flexGrow="1" backgroundColor="darkgray" />
+            <Button text="&gt;" width="50" backgroundColor="gray" />
+        </FlexboxLayout>
+    </FlexboxLayout>
+</Page>
+<!-- << flexbox-layout-page -->
diff --git a/tests/app/ui/layouts/flexbox-layout-tests.ts b/tests/app/ui/layouts/flexbox-layout-tests.ts
index 05c6f58f6..fd8dff6b2 100644
--- a/tests/app/ui/layouts/flexbox-layout-tests.ts
+++ b/tests/app/ui/layouts/flexbox-layout-tests.ts
@@ -1,12 +1,15 @@
+// >> flexbox-layout-require
 import {
     FlexboxLayout,
+    FlexDirection,
     FlexWrap,
+    JustifyContent,
     AlignItems,
     AlignContent,
-    AlignSelf,
-    FlexDirection,
-    JustifyContent
+    AlignSelf
 } from "ui/layouts/flexbox-layout";
+// << flexbox-layout-require
+
 import {View} from "ui/core/view";
 import {Label} from "ui/label";
 import TKUnit = require("../../TKUnit");
@@ -14,6 +17,8 @@ import helper = require("../helper");
 import {layout} from "utils/utils";
 import {parse} from "ui/builder";
 
+// TODO: Test the flexbox-layout-page.xml can be loaded and displayed
+
 import dipToDp = layout.toDevicePixels;
 
 const EPS = 1;
@@ -164,6 +169,17 @@ function isAbove(view1: View, view2: View) {
     TKUnit.assert(bounds1.bottom <= bounds2.top, `${view1}.bottom: ${bounds1.bottom} is not above ${view2}.top: ${bounds2.top}`);
 }
 
+export function testFlexboxPage() {
+    let page = helper.navigateWithEntry({ moduleName: "ui/layouts/flexbox-layout-page" });
+    function view(id: string) {
+        return page.getViewById(id);
+    }
+    isLeftOf(view("six"), view("one"));
+    isAbove(view("one"), view("scrollview"));
+    isAbove(view("title"), view("firstlabel"));
+    isAbove(view("firstlabel"), view("description"));
+}
+
 const noop = () => {
     // no operation
 };
diff --git a/tests/app/ui/layouts/flexbox-layout.md b/tests/app/ui/layouts/flexbox-layout.md
new file mode 100644
index 000000000..d177201d0
--- /dev/null
+++ b/tests/app/ui/layouts/flexbox-layout.md
@@ -0,0 +1,66 @@
+---
+nav-title: "flexbox-layout How-To"
+title: "flexbox-layout"
+environment: nativescript
+description: "Examples for using flexbox-layout"
+---
+# FlexboxLayout
+Using a FlexboxLayout requires the FlexboxLayout module.
+{%snippet flexbox-layout-require%}
+
+Using the flexbox layout in the NativeScript framework requires the FleboxLayout view with children.
+The FlexboxLayout will automatically serve as if it were a *div* with `{ display: flex; }`.
+
+[Here is a good guide on using flexbox](https://css-tricks.com/snippets/css/a-guide-to-flexbox/).
+
+The FlexboxLayout implementation is based on existing Apache-2 licensed flexbox implementation hosted on
+[github.com/google/flexbox-layout](https://github.com/google/flexbox-layout).
+
+## Properties
+The flexbox properties supported at the moment can be set in JavaScript or the NativeScript markup.
+Support for flexbox properties in CSS is yet missing.
+
+The supported properties on the FlexboxLayout container are:
+ - ~~**display:**~~ This works as if set to `flex` by default on the *FlexboxLayout*
+ - **flex-direction:**
+    - Set in JavaScript using the property - `fb.flexDirection = FlexDirection.ROW`
+    - Set in XML using the attribute - `<FleboxLayout flexDirection="row">`
+ - **flex-wrap:** Use the property - `flexWrap`
+    - Set in JavaScript using the property - `fb.flexWrap = FlexWrap`
+    - Set in XML using the attribute - `<FleboxLayout flexWrap="wrap">`
+ - ~~**flex-flow:**~~ the shorthand property has no alternative, set the flex properties one by one
+ - **justify-content:** Use the property - `justifyContent`
+    - Set in JavaScript using the property - `fb.justifyContent = JustifyContent.SPACE_BETWEEN`
+    - Set in XML using the attribute - `<FleboxLayout justifyContent = "space-between">`
+ - **align-items:** Use the property - `alignItems`
+    - Set in JavaScript using the property - `fb.alignItems = AlignItems.STRETCH`
+    - Set in XML using the attribute - `<FleboxLayout alignItems = "stretch">`
+ - **align-content:** Use the property - `alignContent`
+    - Set in JavaScript using the property - `fb.alignContent = AlignContent.SPACE_BETWEEN`
+    - Set in XML using the attribute - `<FleboxLayout alignContent = "space-between">`
+
+> **NOTE:** There is a limitation for `align-items` in **iOS**, the `baseline` option can **not** be used.
+
+The supported flexbox properties on child elements are as follow:
+ - **order:**
+    - Set in JavaScript using the method `flexbox.FlexboxLayout.setOrder(child, 1)`
+    - Set in XML using the attribute `order="1"`
+ - **flex-grow:**
+    - Set in JavaScript using the method `flexbox.FlexboxLayout.setFlexGrow(child, 1)`
+    - Set in XML using the attribute `flexGrow="1"`
+ - **flex-shrink:**
+    - Set in JavaScript using the method `flexbox.FlexboxLayout.setFlexShrink(child, 1)`
+    - Set in XML using the attribute `flexShrink="1"`
+ - ~~**flex-basis:**~~ The NativeScript layout supports setting width or height as fixed values or percent, use them instead
+ - ~~**flex:**~~ the shorthand proeprty has no alternative, set the `flex-grow`, `flex-shrink`, `width` or `height` instead
+ - **align-self:**
+    - Set in JavaScript using the method `flexbox.FlexboxLayout.setAlignSelf(child, AlignSelf.STRETCH)`
+    - Set in XML using the attribute `<FlexboxLayout><Button alignSelf="stretch" /></FlexboxLayout>`
+ - **flex-wrap-before:** Non-spec property controlling item wrapping, setting to *true* on flexbox child will force it to wrap on a new line
+    - Set in JavaScript using the method `flexbox.FlexboxLayout.setFlexWrapBefore(child, true)`
+    - Set in XML using the attribute `<FlexboxLayout><Button flexWrapBefore="true" /></FlexboxLayout>`
+
+> **NOTE:** There is a limitation for `align-self` in **iOS**, the `baseline` option can **not** be used.
+
+## Use in XML layout
+{%snippet flexbox-layout-page%}