chore: rootlayout, code sharing and touchups

NathanWalker · NathanWalker · commit abc5f8d7874e · 2021-03-29T22:30:02.000-07:00
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,4 @@
+.DS_Store
 .vitepress/dist
 node_modules
 package-lock.json
diff --git a/.vitepress/config.js b/.vitepress/config.js
@@ -117,6 +117,10 @@ function getSidebar() {
 			text: 'Performance',
 			children: [{ text: 'Performance', link: '/performance' }],
 		},
+		{
+			text: 'Scalability',
+			children: [{ text: 'Code Sharing', link: '/code-sharing/index' }],
+		},
 		{
 			text: 'Advanced Concepts',
 			children: [
diff --git a/best-practices/index.md b/best-practices/index.md
@@ -4,10 +4,12 @@ title: Best Practices
 
 ## NativeScript Best Practices
 
+### The story of 😢 or 😊
+
 Over the years several distinct best practices have emerged when working with NativeScript and we'd like to outline a few here for you in hopes that you can enjoy NativeScripting as much as we do. More importantly though, that your end product gives you all the right _feels_ you expect.
 
-We are providing a sample "vanilla" NativeScript app which shows some of the good vs. bad practices for you to run and see for yourself.
-Using vanilla NativeScript is a great way to see the raw examples of why these are good and bad practices and are applicable to any frontend framework integration. Each framework integration effectively utilitizes these same practices for it's own various cases.
+We are providing a sample "vanilla" NativeScript app which shows some of the bad vs. good practices for you to run and see for yourself.
+Using vanilla NativeScript is a great way to see the raw examples of why these are bad and good practices which are applicable to any frontend framework integration. Each framework integration effectively utilitizes these same practices for it's own various cases.
 
 Clone and see for yourself: https://github.com/NativeScript/examples-best-practices
 
diff --git a/code-sharing/index.md b/code-sharing/index.md
@@ -2,6 +2,12 @@
 title: Code Sharing
 ---
 
+JavaScript provides opportunities of immense scalability if architectured properly.
+
+One key word that often comes up in this department is **"code sharing"**.
+
+Over the years, several lessons have emerged around scalability with JavaScript in lieu of NativeScript in particular.
+
 **The NativeScript TSC's 5 fundamental lessons about good code sharing**
 
 1. If you can share your code easily with other paradigms, other disciplines, other runtimes even, then you have a good code sharing approach that will continue to provide you and your team joy. No developer or team willingly gets into code sharing hoping to find themselves in a corner later. You always want to share now to more easily maintain and scale the code later.
@@ -22,46 +28,60 @@ If a "code sharing solution" is maintained by a framework that can often mean th
 
 ## Recommendations and Solutions
 
-- [Nx with xplat](https://nstudio.io/xplat)
+### [Nrwl Nx DevTools with @nativescript/nx](https://github.com/NativeScript/nx)
+
+**Pros:**
+
+- It's centered around JavaScript/TypeScript (lesson 1 and 5 above)
+- Uses standard build tooling like typescript or webpack to build code (lesson 2 above)
+- No custom file extensions to deal with (lesson 3 above)
+- Nx splits up "apps" and "libs" clearly identifying deployment/distribution targets "apps" that consume shared code "libs" (lesson 4 above)
+
+**Cons:**
+
+- Learning curve if not used to Nx practices in general
+
+### [Nrwl Nx DevTools with @nstudio/xplat](https://nstudio.io/xplat)
 
-  **Pros:**
+**Pros:**
 
-  - It's centered around JavaScript/TypeScript (lesson 1 and 5 above)
-  - Uses standard build tooling like typescript or webpack to build code (lesson 2 above)
-  - No custom file extensions to deal with (lesson 3 above)
-  - Nx splits up "apps" and "libs" clearly identifying deployment/distribution targets "apps" that consume shared code "libs" (lesson 4 above)
-  - Opinionated architecture is provided via xplat which helps to avoid common pitfalls from hard lessons learned in real world developments with cross platform mixtures
+- It's centered around JavaScript/TypeScript (lesson 1 and 5 above)
+- Uses standard build tooling like typescript or webpack to build code (lesson 2 above)
+- No custom file extensions to deal with (lesson 3 above)
+- Nx splits up "apps" and "libs" clearly identifying deployment/distribution targets "apps" that consume shared code "libs" (lesson 4 above)
+- It builds upon @nativescript/nx to further scale it across more paradigms so it's a natural extension when needed if already working in Nx with @nativescript/nx
+- Opinionated architecture is provided via xplat which helps to avoid common pitfalls from hard lessons learned in real world developments with cross platform mixtures
 
-  **Cons:**
+**Cons:**
 
-  - Learning curve if not used to Nx practices in general
-  - Learning curve if you have not developed applications in large codebases before
-  - Understanding the [basic fundamentals](https://nstudio.io/xplat/fundamentals/architecture) of the provided architecture
+- Learning curve if not used to Nx practices in general
+- Learning curve if you have not developed applications in large codebases before
+- Understanding the [basic fundamentals](https://nstudio.io/xplat/fundamentals/architecture) of the provided architecture
 
-- [Yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/)
+### [Yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/)
 
-  **Pros:**
+**Pros:**
 
-  - It's centered around JavaScript/TypeScript (lesson 1 and 5 above)
-  - Uses standard build tooling like typescript or webpack to build code (lesson 2 above)
-  - No custom file extensions to deal with (lesson 3 above)
-  - Can link/share dependencies
+- It's centered around JavaScript/TypeScript (lesson 1 and 5 above)
+- Uses standard build tooling like typescript or webpack to build code (lesson 2 above)
+- No custom file extensions to deal with (lesson 3 above)
+- Can link/share dependencies
 
-  **Cons:**
+**Cons:**
 
-  - You are on your own with organizational structure which can lead to common pitfalls with cross platform mixtures
-  - No out of the box deployment/distribution target setup to identify app targets vs. shared code
+- You are on your own with organizational structure which can lead to common pitfalls with cross platform mixtures
+- No out of the box deployment/distribution target setup to identify app targets vs. shared code
 
-- [Lerna](https://github.com/lerna/lerna)
+### [Lerna](https://github.com/lerna/lerna)
 
-  **Pros:**
+**Pros:**
 
-  - It's centered around JavaScript/TypeScript (lesson 1 and 5 above)
-  - Uses standard build tooling like typescript or webpack to build code (lesson 2 above)
-  - No custom file extensions to deal with (lesson 3 above)
+- It's centered around JavaScript/TypeScript (lesson 1 and 5 above)
+- Uses standard build tooling like typescript or webpack to build code (lesson 2 above)
+- No custom file extensions to deal with (lesson 3 above)
 
-  **Cons:**
+**Cons:**
 
-  - You are on your own with organizational structure which can lead to common pitfalls with cross platform mixtures
-  - No out of the box deployment/distribution target setup to identify app targets vs. shared code
-  - It's generally geared towards open source library management so no extra helpful tooling for "workspace management" in general
+- You are on your own with organizational structure which can lead to common pitfalls with cross platform mixtures
+- No out of the box deployment/distribution target setup to identify app targets vs. shared code
+- It's generally geared towards open source library management so no extra helpful tooling for "workspace management" in general
diff --git a/index.md b/index.md
@@ -19,8 +19,21 @@ actionLink: /introduction
 # footer: Copyright © 2021
 ---
 
-<div style="text-align:center;margin: 0 auto;">
-  <img src="/assets/images/mobile.gif">
+<div style="float:left; max-width:275px;">
+  <img src="/assets/images/ns-docs.gif">
 </div>
 
-<a href="/introduction">Read the docs</a>
+<div style="float:left">
+  <h3 id="table-of-contents"><a class="header-anchor" href="#table-of-contents" aria-hidden="true">#</a> Table of Contents</h3>
+
+  <ul style="list-style-type:none">
+  <li><a href="/introduction">Introduction</a></li>
+  <li><a href="/ui-and-styling">UI &amp; Styling</a></li>
+  <li><a href="/networking">Networking</a></li>
+  <li><a href="/performance">Performance</a></li>
+  <li><a href="/code-sharing/index">Scalability</a></li>
+  <li><a href="/advanced-concepts">Advanced Concepts</a></li>
+  <li><a href="/releasing">Distribution</a></li>
+  <li><a href="/troubleshooting">Troubleshooting</a></li>
+  </ul>
+</div>
diff --git a/public/assets/images/ns-docs.gif b/public/assets/images/ns-docs.gif
diff --git a/ui-and-styling.md b/ui-and-styling.md
@@ -489,6 +489,122 @@ The following example creates a diagonal stack of items with responsive sizes. I
 
 None.
 
+### RootLayout
+
+`<RootLayout>` is a layout container designed to be used as the primary root layout container for your app with a built in api to easily control dynamic view layers. It extends a GridLayout so has all the features of a grid but enhanced with additional apis.
+
+It's api can be observed here:
+
+```ts
+export class RootLayout extends GridLayout {
+  open(view: View, options?: RootLayoutOptions): Promise<void>
+  close(view: View, exitTo?: TransitionAnimation): Promise<void>
+  bringToFront(view: View, animated?: boolean): Promise<void>
+  closeAll(): Promise<void>
+  getShadeCover(): View
+}
+
+export function getRootLayout(): RootLayout
+
+export interface RootLayoutOptions {
+  shadeCover?: ShadeCoverOptions
+  animation?: {
+    enterFrom?: TransitionAnimation
+    exitTo?: TransitionAnimation
+  }
+}
+
+export interface ShadeCoverOptions {
+  opacity?: number
+  color?: string
+  tapToClose?: boolean
+  animation?: {
+    enterFrom?: TransitionAnimation // only applied if first one to be opened
+    exitTo?: TransitionAnimation // only applied if last one to be closed
+  }
+  ignoreShadeRestore?: boolean
+}
+
+export interface TransitionAnimation {
+  translateX?: number
+  translateY?: number
+  scaleX?: number
+  scaleY?: number
+  rotate?: number // in degrees
+  opacity?: number
+  duration?: number // in milliseconds
+  curve?: any // CoreTypes.AnimationCurve (string, cubicBezier, etc.)
+}
+```
+
+You can use `getRootLayout()` to get a reference to the root layout in your app from anywhere.
+
+#### Example: RootLayout setup
+
+Sample layout:
+
+```html
+<RootLayout height="100%" width="100%">
+  <GridLayout height="100%">
+    <label
+      verticalAlignment="center"
+      textAlignment="center"
+      text="MAIN CONTENT AREA"
+    ></label>
+  </GridLayout>
+</RootLayout>
+```
+
+Sample api usage:
+
+```ts
+// Open a dynamic popup
+const view = this.getPopup('#EA5936', 110, -30)
+getRootLayout()
+  .open(view, {
+    shadeCover: {
+      color: '#000',
+      opacity: 0.7,
+      tapToClose: true
+    },
+    animation: {
+      enterFrom: {
+        opacity: 0,
+        translateY: 500,
+        duration: 500
+      },
+      exitTo: {
+        opacity: 0,
+        duration: 300
+      }
+    }
+  })
+  .catch(ex => console.error(ex))
+
+// Close the dynamic popup
+getRootLayout()
+  .close(view, {
+    opacity: 0,
+    translate: { x: 0, y: -500 }
+  })
+  .catch(ex => console.error(ex))
+
+function getPopup(color: string, size: number, offset: number): View {
+  const layout = new StackLayout()
+  layout.height = size
+  layout.width = size
+  layout.marginTop = offset
+  layout.marginLeft = offset
+  layout.backgroundColor = color
+  layout.borderRadius = 10
+  return layout
+}
+```
+
+You can play with [the toolbox app here](https://github.com/NativeScript/NativeScript/tree/master/apps/toolbox/src/pages/root-layout.ts)
+
+You can also find a more [thorough example in this sample repo](https://github.com/williamjuan027/nativescript-rootlayout-demo)
+
 ### WrapLayout
 
 `<WrapLayout>` is a layout container that lets you position items in rows or columns, based on the `orientation` property. When the space is filled, the container automatically wraps items onto a new row or column.

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+.DS_Store`
`1`	`2`	`.vitepress/dist`
`2`	`3`	`node_modules`
`3`	`4`	`package-lock.json`