Skip to content
This repository was archived by the owner on Nov 3, 2025. It is now read-only.

Commit 4546108

Browse files
tpuccitpucci
committed
📝 (API) Write basic API references and usage
1 parent 9ef0862 commit 4546108

12 files changed

Lines changed: 416 additions & 9 deletions

‎README.md‎

Lines changed: 41 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,44 @@
22

33
# React Gondola
44

5-
React Native declarative navigation
5+
React Native declarative and reactive navigation.
6+
7+
## Philosophy
8+
9+
This repo focuses on grouping pages by business conversion tunnels called **canals**. When navigating in Venice, you can not teleport yourself from the beginning of a canal to the end of it. You are forced to either go ahead or go back; and doing so you might discover another canal. **When you use React Gondola**, define several gondoliers and hhow they are authorize to move accross their canals.
10+
11+
## 👍 TLDR; Use this package if:
12+
13+
- you want to group pages by **business** conversion tunnels rather than transition.
14+
- you want to control your navigation state with a **state machine**.
15+
- you want you navigation to **react** to your store changes.
16+
17+
## 👎 Do not use this repo if:
18+
19+
- you want to navigate imperatively.
20+
- you need to use Native navigation (react-gondola's navigation is powered by JS code only).
21+
22+
## Docs
23+
24+
The docs are here: https://react-gondola.netlify.com/
25+
26+
## Contribute
27+
28+
- Clone this repository.
29+
- Run `yarn` in the root directory.
30+
- Run `yarn` in the `example` directory.
31+
- Add your code and its test in the `<rootDir>/src` directory.
32+
- Add your example code and its test in the `<rootDir>/example` directory.
33+
- Open a pull request !
34+
35+
## Run the example project
36+
37+
- Clone this repository.
38+
- Run `yarn` in the root directory.
39+
- Run `yarn` in the `example` directory.
40+
- In the `example` directory, run either `react-native run-ios` or `react-native run-android`.
41+
42+
## Compare
43+
44+
- [React Navigation](https://reactnavigation.org/)
45+
- [React Native Navigation](https://github.com/wix/react-native-navigation)

‎docs/Contribute.mdx‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
name: Contribute
3+
---
4+
5+
# Contribute
6+
7+
- Clone this repository.
8+
- Run `yarn` in the root directory.
9+
- Run `yarn` in the `example` directory.
10+
- Add your code and its test in the `<rootDir>/src` directory.
11+
- Add your example code and its test in the `<rootDir>/example` directory.
12+
- Open a pull request !

‎docs/GettingStarted.mdx‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
name: Getting Started
3+
---
4+
5+
# Getting Started
6+
7+
## Installation
8+
9+
React-gondola needs the following dependencies; if you do not have those installed, you need to install them with the correspondig command:
10+
11+
| Dependencie name | Yarn Installation command | NPM Installation command |
12+
| :--------------: | :-----------------------: | :----------------------: |
13+
| `mobx` | `yarn add mobx` | `npm i mobx` |
14+
| `rxjs` | `yarn add rxjs` | `npm i rxjs` |
15+
16+
Then, install React-Gondola with:
17+
18+
`yarn add react-gondola`
19+
20+
or
21+
22+
`npm i react-gondola`
23+
24+
## Basic Usage
25+
26+
### Create a canal
27+
28+
In order to create a canal, use the `createCanal` function. Pass it your screens in the business order.
29+
30+
```ts
31+
import React from "react";
32+
import { createCanal } from "react-gondola";
33+
import { FirstName } from "./FirstName";
34+
import { LastName } from "./LastName";
35+
36+
const SignInCanal = createCanal([
37+
{ name: "firstName", Component: FirstName },
38+
{ name: "lastName", Component: LastName }
39+
]);
40+
```
41+
42+
Then, use the canal wherever you want in your app. Specify wether to show/hide a screen by using the screen's name as a prop:
43+
44+
```ts
45+
import React, { Component } from "react";
46+
import { SignInCanal } from "./canals/SignIn";
47+
48+
export default class App extends Component {
49+
render() {
50+
return <SignInCanal firstName />;
51+
}
52+
}
53+
```
54+
55+
That's all !
56+
57+
### Add some full screen page
58+
59+
If you want to add full screen page, pass the `isFullScreen` flag when creating a canal. In the following example, `confirm` is a full screen page.
60+
61+
```ts
62+
import React from "react";
63+
import { createCanal } from "react-gondola";
64+
import { FirstName } from "./FirstName";
65+
import { LastName } from "./LastName";
66+
67+
const SignInCanal = createCanal([
68+
{ name: "firstName", Component: FirstName },
69+
{ name: "lastName", Component: LastName },
70+
{ name: "confirm", Component: Confirm, isFullScreen: true }
71+
]);
72+
```
73+
74+
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.
75+
76+
```ts
77+
import React, { Component } from "react";
78+
import { SignInCanal } from "./canals/SignIn";
79+
import { FullScreenPortal } from "react-gondola";
80+
81+
export default class App extends Component {
82+
render() {
83+
return (
84+
<FullScreenPortal>
85+
<SignInCanal firstName lastName confirm />
86+
</FullScreenPortal>
87+
);
88+
}
89+
}
90+
```
91+
92+
You are ready to use React-Gondola

‎docs/Roadmap.mdx‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
name: Roadmap
3+
---
4+
5+
# Roadmap
6+
7+
If there is a real interest on `react-gondola` and its phylosophy, I might add support for the following features:
8+
9+
- transitions
10+
- navigation gestures
11+
12+
Tweet me some encouragements 😁
13+
14+
My twitter: [@Thomas_Pucci](https://twitter.com/Thomas_Pucci)

‎docs/Welcome.mdx‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
name: Welcome
3+
---
4+
5+
# React Gondola
6+
7+
React Native declarative and reactive navigation.
8+
9+
## Philosophy
10+
11+
This repo focuses on grouping pages by business conversion tunnels called **canals**. When navigating in Venice, you can not teleport yourself from the beginning of a canal to the end of it. You are forced to either go ahead or go back; and doing so you might discover another canal. **When you use React Gondola**, define several gondoliers and hhow they are authorize to move accross their canals.
12+
13+
## When to use this package
14+
15+
### 👍 TLDR; Use this package if:
16+
17+
- you want to group pages by **business** conversion tunnels rather than transition.
18+
- you want to control your navigation state with a **state machine**.
19+
- you want you navigation to **react** to your store changes.
20+
21+
### 👎 Do not use this repo if:
22+
23+
- you want to navigate imperatively.
24+
- you need to use Native navigation (react-gondola's navigation is powered by JS code only).
25+
26+
## Compare
27+
28+
- [React Navigation](https://reactnavigation.org/)
29+
- [React Native Navigation](https://github.com/wix/react-native-navigation)

‎doczrc.js‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
import path from 'path';
2+
3+
module.exports = {
4+
native: true,
5+
typescript: true,
6+
menu: [
7+
'Welcome',
8+
'Getting Started',
9+
'Example',
10+
'Contribute',
11+
'Roadmap',
12+
{ name: 'API', menu: ['createCanal', 'FullScreenPortal'] },
13+
],
14+
modifyBundlerConfig: config => {
15+
// Combine the default docz aliases with our custom aliases.
16+
config.resolve.alias = Object.assign({}, config.resolve.alias, {
17+
'react-native$': 'react-native-web',
18+
'react-gondola$': path.resolve(__dirname, 'src/index.ts'),
19+
});
20+
return config;
21+
},
22+
};

‎example/README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Run the example project
2+
3+
- Clone this repository.
4+
- Run `yarn` in the root (`cd ..`) directory.
5+
- Run `yarn` in this `example` directory.
6+
- In this `example` directory, run either `react-native run-ios` or `react-native run-android`.

‎example/src/Exemple.mdx‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
name: Example
3+
---
4+
5+
# Example
6+
7+
The following example runs with `react-native-web` 🎉
8+
9+
import { Playground } from "docz";
10+
import { View } from "react-native";
11+
import App from "./App";
12+
13+
<Playground>
14+
<View style={{ alignItems: "center" }}>
15+
<View style={{ width: 320, height: 568 }}>
16+
<App />
17+
</View>
18+
</View>
19+
</Playground>
20+
21+
## Run the example project
22+
23+
- Clone this repository.
24+
- Run `yarn` in the root directory.
25+
- Run `yarn` in the `example` directory.
26+
- In the `example` directory, run either `react-native run-ios` or `react-native run-android`.

‎package.json‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -20,13 +20,14 @@
2020
"react-native": "*"
2121
},
2222
"scripts": {
23+
"doc:build": "docz build",
24+
"release": "release-it",
25+
"test:ci": "yarn test:lint && yarn test:unit:ci && yarn test:type",
2326
"test:lint": "tslint src/**/*.ts{,x}",
24-
"test:unit": "jest",
25-
"test:unit:ci": "jest --runInBand",
2627
"test:type": "tsc --noEmit",
27-
"test": "yarn test:lint && yarn test:unit && yarn test:type",
28-
"test:ci": "yarn test:lint && yarn test:unit:ci && yarn test:type",
29-
"release": "release-it"
28+
"test:unit:ci": "jest --runInBand",
29+
"test:unit": "jest",
30+
"test": "yarn test:lint && yarn test:unit && yarn test:type"
3031
},
3132
"devDependencies": {
3233
"@babel/core": "^7.4.3",
@@ -51,6 +52,7 @@
5152
"react": "16.8.6",
5253
"react-dom": "16.8.6",
5354
"react-native": "0.59.5",
55+
"react-native-web": "^0.11.4",
5456
"react-test-renderer": "^16.8.6",
5557
"release-it": "^12.0.1",
5658
"rxjs": "^6.4.0",

‎src/FullScreenPortal.mdx‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
name: FullScreenPortal
3+
menu: API
4+
---
5+
6+
# FullScreenPortal
7+
8+
`type: React.Component`
9+
10+
## Props
11+
12+
| Prop name | Required | Default | Usage |
13+
| :--------: | :------: | ----------- | ---------------------------------------------------------------------------------------------------------- |
14+
| `children` | `true` | `undefined` | Children are wrapped in a `React.Fragment`. All full screen Stops are rendered in front of those children. |
15+
16+
## Properties
17+
18+
### `fullScreenStack: IStreamListener<IStop[]>`
19+
20+
MobX Strem Listener of list of React Gondola full screen Stops. This stream is observed by MobX and fires the rendering of the full screen stack in the `FullScreenPortal.render` method.
21+
22+
## Basic usage
23+
24+
Wrap your application main canal with `FullScreenPortal`. `FullScreenPortal` must appear at the top of your tree in order to render full screen pages.
25+
26+
```tsx
27+
import React, { Component } from "react";
28+
import { FullScreenPortal } from "react-gondola";
29+
30+
import { MainCanal } from "./canals/MainCanal";
31+
32+
export default class App extends Component {
33+
render() {
34+
return (
35+
<FullScreenPortal>
36+
<MainCanal />
37+
</FullScreenPortal>
38+
);
39+
}
40+
}
41+
```

0 commit comments

Comments
 (0)