📝 (Canal) update doc for v2

Author: tpucci

README.md

@@ -16,7 +16,7 @@
 
 This repo focuses on grouping screens by business conversion tunnels called **canals**. Why did I call it `react-gondola`? Just because I though of this package when I was visiting Venice... and I kind of hope that using this package will feel like navigating in Venice 📸
 
-**When you use React Gondola**, you define several screens and you have the possibility to control their visibility with YOU're state machine. You define the rules of WHEN some screens should appear; `react-gondola` takes care of the rest.
+**When you use React Gondola**, you define several screens and you have the possibility to control their visibility with YOUR state machine. You define the rules of WHEN some screens should appear; `react-gondola` takes care of the rest.
 
 ## 👍 TLDR; Use this package if:
 

docs/GettingStarted.mdx

@@ -25,68 +25,99 @@ or
 
 ### Create a canal
 
-In order to create a canal, use the `createCanal` function. Pass it your screens in the business order.
+In order to create a canal, use the `Canal` and `Screen` components. Your screens order is important: the order is the elevation order. If two or more screens are visible, last visible in the array is shown.
 
 ```ts
 import React from 'react';
-import { createCanal } from 'react-gondola';
+import { Canal, Screen } from 'react-gondola';
 import { FirstName } from './FirstName';
 import { LastName } from './LastName';
 
-const SignInCanal = createCanal([
-  { name: 'firstName', Component: FirstName },
-  { name: 'lastName', Component: LastName },
-]);
-```
-
-Then, use the canal wherever you want in your app. Specify whether to show/hide a screen by using the screen's name as a prop:
-
-```ts
-import React, { Component } from 'react';
-import { SignInCanal } from './canals/SignIn';
-
-export default class App extends Component {
-  render() {
-    return <SignInCanal firstName={true} lastName={false} />;
-  }
-}
+const SignInCanal = () => (
+  <Canal>
+    <Screen name="firstname" Component={FirstName} visible />
+    <Screen name="lastname" Component={LastName} visible={false} />
+  </Canal>
+);
 ```
 
 That's all !
 
 ### Add a full screen page
 
-If you want to add full screen page, pass the `isFullScreen` flag to the right page when creating a canal. In the following example, `confirm` is a full screen page.
+If you want to add full screen page, pass the `isFullScreen` flag prop to your `Screen` when creating a canal. In the following example, `lastname` is a full screen page.
 
 ```ts
 import React from 'react';
-import { createCanal } from 'react-gondola';
+import { Canal, Screen } from 'react-gondola';
 import { FirstName } from './FirstName';
 import { LastName } from './LastName';
 
-const SignInCanal = createCanal([
-  { name: 'firstName', Component: FirstName },
-  { name: 'lastName', Component: LastName },
-  { name: 'confirm', Component: Confirm, isFullScreen: true },
-]);
+const SignInCanal = () => (
+  <Canal>
+    <Screen name="firstname" Component={FirstName} visible />
+    <Screen name="lastname" Component={LastName} visible={false} isFullScreen />
+  </Canal>
+);
 ```
 
-In order to render the full screen page at the top level in your app, add the `FullScreenPortal` at the top level in your rendering tree.
+In order to render the full screen page, add the `FullScreenPortal` at the top level in your rendering tree.
 
 ```ts
 import React, { Component } from 'react';
-import { SignInCanal } from './canals/SignIn';
+import { MyCanal } from './canals/MyCanal';
 import { FullScreenPortal } from 'react-gondola';
 
 export default class App extends Component {
   render() {
     return (
       <FullScreenPortal>
-        <SignInCanal firstName lastName confirm />
+        <MyCanal />
       </FullScreenPortal>
     );
   }
 }
 ```
 
+### Go Back
+
+Back events are also managed in a declarative way. Use the `onBack` callback prop on your screen.
+
+```ts
+import React from 'react';
+import { Canal, Screen } from 'react-gondola';
+import { FirstName } from './FirstName';
+import { LastName } from './LastName';
+
+const SignInCanal = () => (
+  <Canal>
+    <Screen name="firstname" Component={FirstName} visible />
+    <Screen
+      name="lastname"
+      Component={LastName}
+      visible={false}
+      onBack={() => {
+        doSomething();
+      }}
+    />
+  </Canal>
+);
+```
+
+import { Info } from 'components/Info';
+import { Warning } from 'components/Warning';
+
+<Warning>
+  You should use a state machine in order to make your canal a controlled component. In fact, your
+  `onBack` callbacks should modify your state in a way it affects the visibility of your screens.
+  See the example in the repo.
+</Warning>
+<Info>
+  If you have nested or multiple canals, here is the priority of `onBack` callbacks:
+  <br/>
+  - Last visible full-screen screen.
+  <br/>
+  - Deepest visible screen.
+</Info>
+
 You are ready to use React-Gondola 🎸.

docs/Welcome.mdx

@@ -11,7 +11,7 @@ React Native declarative and reactive navigation.
 
 This repo focuses on grouping screens by business conversion tunnels called **canals**. Why did I call it `react-gondola`? Just because I though of this package when I was visiting Venice... and I kind of hope that using this package will feel like navigating in Venice 📸
 
-**When you use React Gondola**, you define several screens and you have the possibility to control their visibility with YOU're state machine. You define the rules of WHEN some screens should appear; `react-gondola` takes care of the rest.
+**When you use React Gondola**, you define several screens and you have the possibility to control their visibility with YOUR state machine. You define the rules of WHEN some screens should appear; `react-gondola` takes care of the rest.
 
 ## When to use this package
 

docs/components/Info.tsx

@@ -0,0 +1,20 @@
+import React from 'react';
+import { Text, View } from 'react-native';
+
+export function Info(props: { children: string }) {
+  return (
+    <View
+      style={{
+        padding: 8,
+        backgroundColor: '#eee',
+        borderLeftWidth: 3,
+        borderLeftColor: '#00b0ff',
+        borderRadius: 4,
+        marginBottom: 16,
+      }}
+    >
+      <Text style={{ fontWeight: 'bold', fontSize: 16 }}>ℹ Info</Text>
+      <Text style={{ marginTop: 4 }}>{props.children}</Text>
+    </View>
+  );
+}

docs/components/Warning.tsx

@@ -10,6 +10,7 @@ export function Warning(props: { children: string }) {
         borderLeftWidth: 3,
         borderLeftColor: '#fdcb00',
         borderRadius: 4,
+        marginBottom: 16,
       }}
     >
       <Text style={{ fontWeight: 'bold', fontSize: 16 }}>⚠️ Warning</Text>

docs/guides/Transitions.mdx

@@ -6,21 +6,23 @@ route: /guides/transitions
 
 # Transitions
 
-In order to use transitions between two screens, simply add the `Transitioner` key to your stops.
+In order to use transitions between two screens, simply add the `Transitioner` key to your screens.
 
 ## Basic example
 
 ```ts
-import React from "react";
-import { createCanal } from "react-gondola";
-import { SildeLeft } from "react-gondola/transitions";
-import { FirstName } from "./FirstName";
-import { LastName } from "./LastName";
-
-const SignInCanal = createCanal([
-  { name: "firstName", Component: FirstName },
-  { name: "lastName", Component: LastName, Transitioner: SildeLeft }
-]);
+import React from 'react';
+import { Canal, Screen } from 'react-gondola';
+import { SildeLeft } from 'react-gondola/transitions';
+import { FirstName } from './FirstName';
+import { LastName } from './LastName';
+
+const SignInCanal = () => (
+  <Canal>
+    <Screen name="firstname" Component={FirstName} Transitioner={SlideLeft} />
+    <Screen name="lastname" Component={LastName} Transitioner={SlideLeft} />
+  </Canal>
+);
 ```
 
 ## Available transitioners
@@ -29,6 +31,7 @@ const SignInCanal = createCanal([
 | :-------------------------------------------------------------------: | ---------------------------------------------------------- | :--------------------------------------------------: |
 |                              `SildeLeft`                              | `import { SildeLeft } from "react-gondola/transitions";`   |   ![Slide Left transition](./assets/slideLeft.gif)   |
 |                               `SildeUp`                               | `import { SildeUp } from "react-gondola/transitions";`     |     ![Slide Up transition](./assets/slideUp.gif)     |
+|                              `ConvexUp`                               | `import { ConvexUp } from "react-gondola/transitions";`    |                                                      |
 | `RotateCrazy` (⚠️ experimental: this might be removed without notice) | `import { RotateCrazy } from "react-gondola/transitions";` | ![Rotate Crazy transition](./assets/rotateCrazy.gif) |
 
 ## Create your own transitioner
@@ -44,16 +47,16 @@ You can create your own transitioner if the one availables does not fit your nee
 ```js
 // in your jest setup file, use the following
 
-jest.mock("react-native-reanimated/src/ReanimatedEventEmitter");
-jest.mock("react-native-reanimated/src/ReanimatedModule", () => ({
+jest.mock('react-native-reanimated/src/ReanimatedEventEmitter');
+jest.mock('react-native-reanimated/src/ReanimatedModule', () => ({
   configureNativeProps: () => {},
   connectNodes: () => {},
   disconnectNodes: () => {},
   createNode: () => {},
   configureProps: () => {},
   getValue: () => {},
-  dropNode: () => {}
+  dropNode: () => {},
 }));
-jest.mock("react-native-reanimated/src/derived/evaluateOnce");
-jest.mock("react-native-reanimated/src/core/AnimatedProps");
+jest.mock('react-native-reanimated/src/derived/evaluateOnce');
+jest.mock('react-native-reanimated/src/core/AnimatedProps');
 ```

docs/mocks/react-native-reanimated.js

@@ -10,7 +10,7 @@ module.exports = {
     'Example',
     'Contribute',
     'Roadmap',
-    { name: 'API', menu: ['createCanal', 'FullScreenPortal'] },
+    { name: 'API', menu: ['Screen', 'FullScreenPortal'] },
   ],
   modifyBundlerConfig: config => {
     // Combine the default docz aliases with our custom aliases.
@@ -19,6 +19,7 @@ module.exports = {
       'react-native$': 'react-native-web',
       'react-gondola$': path.resolve(__dirname, 'src/index.ts'), // eslint-disable-line
       'react-gondola/transitions$': path.resolve(__dirname, 'src/transitions/index.ts'), // eslint-disable-line
+      'react-native-reanimated$': path.resolve(__dirname, 'docs/mocks/react-native-reanimated'), // eslint-disable-line
     });
     return config;
   },

doczrc.js

@@ -0,0 +1,24 @@
+---
+name: Screen
+menu: API
+route: /api/screen
+---
+
+import { Props } from 'docz';
+import { Screen } from 'react-gondola';
+
+# Screen
+
+`type: React.Component`
+
+## Props
+
+|    Prop name    | Required | Default     | Usage                                                                                                                                                                                     |
+| :-------------: | :------: | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `isFullScreen`  | `false`  | `false`     | Specifies if the screen should be render in the `FullScreenPortal`.                                                                                                                       |
+|    `onBack`     | `false`  | `undefined` | Function to call when a back event occurs. Use this prop and `visible` to control your Canal.                                                                                             |
+|     `name`      |  `true`  | `undefined` | Unique identifier of the screen.                                                                                                                                                          |
+|   `Component`   |  `true`  | `undefined` | Component to render. This is your page.                                                                                                                                                   |
+|     `props`     | `false`  | `undefined` | Props to pass to the Component. Those props are transition-safe. This means while a transition occurs, those props are frozen. When the transition completes, the props flow is released. |
+| `Transtitioner` | `false`  | `None`      | Transition to apply to the screen when it appears or disappears.                                                                                                                          |
+|    `visible`    |  `true`  | `false`     | Visibility of your screen. Use this prop and `onBack` to control your Canal.                                                                                                              |