Enterprise Level Business System Frontend Framework
6 |
7 | - [Documents](https://nautil.js.org)
8 | - [中文文档](https://www.tangshuang.net/7273.html)
9 |
10 | ## What is all the Nautil?
11 |
12 | Nautil\[ˈnɔːtɪl] is a modern javascript frontend framework which helps you to build enterprise level business system by using familiar React syntax.
13 |
14 | The purpose of Nautil is to make complex business system development more systematic, easy and efficient.
15 |
16 | Nautil is built on React and is a framework, not a UI library. Developers can use React components in Nautil applications directly as possible. *Nautil is absolutely React, however, Nautil is more than React.* As a framework, it provides MVC architecture, router, state management, model management, event stream management, internationalization and ability of cross-platform.
17 |
18 | Without importing all the ecosystem of React, without complex redux, without any more choice of third part libraries, you will begin and build your application quickly with Nautil. Feel happy and relaxing when you writing with Nautil. It will work as what you think. You do not need to learn more than react. The only thing you need to know is some feature level api. There is no syntax level or higher knowledge to learn. Try it, I belive, you will fall in love with Nautil in 5 minutes.
19 |
20 | ## Ready for More?
21 |
22 | We've briefly introduced the most basic features of nautil.js core - the rest of this document will cover them and other advanced features with much finer details, so make sure to read through it all!
23 |
--------------------------------------------------------------------------------
/docs/api/animation.md:
--------------------------------------------------------------------------------
1 | # Animation
2 |
3 | ```js
4 | import { Animation } from 'nautil'
5 |
6 |
7 | ...
8 |
9 | ```
10 |
11 | ## props
12 |
13 | - show: Boolean,
14 | - enter: String,
15 | - leave: String,
16 | - loop: ifexist(Boolean), // when you pass loop=true, you should pass $show instead
17 | - onEnterStart
18 | - onEnterUpdate
19 | - onEnterStop
20 | - onLeaveStart
21 | - onLeaveUpdate
22 | - onLeaveStop
23 |
24 |
25 | `enter` and `leave` is a description for enter animation `...effect:params duration ease`.
26 |
27 | - fade:(from)/(to): in,out,
28 | - move:(from)/(to): left,right,top,bottom,(x,y)/(x,y)
29 | - rotate:(from)deg/(to)deg
30 | - scale:(from)/(to)
--------------------------------------------------------------------------------
/docs/api/create-async-component.md:
--------------------------------------------------------------------------------
1 | # createAsyncComponent
2 |
3 | ```js
4 | import { createAsyncComponent } from 'nautil'
5 |
6 | const Home = createAsyncComponent(() => import('./home.jsx'))
7 | const Detail = createAsyncComponent(() => import('./detail.jsx'))
8 | ```
9 |
10 | The imported file should export component as default.
11 |
--------------------------------------------------------------------------------
/docs/api/create-two-way-binding.md:
--------------------------------------------------------------------------------
1 | # createTwoWayBinding
2 |
3 | ```typescript
4 | declare function createTwoWayBinding(
5 | // object to convert to be two-way-binding
6 | data: object,
7 | // function to invoke when two-way-binding changed
8 | updator: (value: any, keyPath: string[], data: object) => void,
9 | // whether to generate formalized two-way-binding like [value, update]
10 | formalized?: boolean,
11 | ): Proxy
12 | ```
13 |
14 |
15 | ```js
16 | import { createTwoWayBinding, Component } from 'nautil'
17 |
18 | const $state = createTwoWayBinding(
19 | // data
20 | { show: false },
21 | // updator
22 | (value, keyPath, data) => {
23 | assign(data, keyPath, value)
24 | },
25 | // formalized
26 | true,
27 | )
28 |
29 | // $state.show -> [false, (value, key) => data[key] = value]
30 |
31 |
32 | ```
33 |
--------------------------------------------------------------------------------
/docs/api/storage.md:
--------------------------------------------------------------------------------
1 | # Storage
2 |
3 | ```js
4 | import { Storage } from 'nautil'
5 |
6 | await Storage.getItem(key)
7 | await Storage.setItem(key, value)
8 | await Storage.delItem(key)
9 | await Storage.clear()
10 | ```
11 |
--------------------------------------------------------------------------------
/docs/assets/nautil-lifecircle.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/tangshuang/nautil/1cdd52330d481aef417b7560796c9e68d3a42167/docs/assets/nautil-lifecircle.jpg
--------------------------------------------------------------------------------
/docs/assets/nautil-logo.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/tangshuang/nautil/1cdd52330d481aef417b7560796c9e68d3a42167/docs/assets/nautil-logo.png
--------------------------------------------------------------------------------
/docs/beginning/install.md:
--------------------------------------------------------------------------------
1 | # Install
2 |
3 | ```
4 | npm i nautil
5 | ```
6 |
--------------------------------------------------------------------------------
/docs/beginning/package-usage.md:
--------------------------------------------------------------------------------
1 | # Package Usage
2 |
3 | ```js
4 | import { Component } from 'nautil'
5 | ```
6 |
7 | We recommand use `nautil-cli` to build even though it is not nessesary.
8 | Your building tool should must support rewrite `process.env.NODE_ENV` to real env vars.
9 |
10 | Nautil is using ES6 `Proxy` to implement reactive system, so your building targets should must support `Proxy`.
11 | This means nautil does not support low version browsers such as IE, earlier chrome or firefox.
12 | Here is a browserslist:
13 |
14 | ```browserslist
15 | chrome 49
16 | firefox 18
17 | edge 12
18 | safari 10
19 | opera 36
20 | ```
21 |
22 | To render Nautil components, you should import renderer from different platform exports:
23 |
24 | ```js
25 | import { mount, update, unmount } from 'nautil/dom'
26 | ```
27 |
28 | Nautil is based on react@^16.8 and use react@17.x inside, if your project are using higher version (i.e. react@18.x), you should use inner React to render nautil components:
29 |
30 | ```js
31 | import { React } from 'nautil'
32 | ```
33 |
34 | And `tyshemo` is a inner driver, if you need full APIs of tyshemo, you can import like:
35 |
36 | ```js
37 | import { TySheMo } from 'nautil'
38 |
39 | const { shouldmatch, String8 } = TySheMo
40 | ```
41 |
--------------------------------------------------------------------------------
/docs/cli/command.md:
--------------------------------------------------------------------------------
1 | # Nautil-CLI Command
2 |
3 | Nautil CLI is a high-level scaffolding tool. If you use nautil-cli, your project will follow the pattern of it. To clearify, you should think about whether to use it (without nautil-cli is ok to use nautil).
4 |
5 | You can call `nautil` as alias of `nautil-cli`, so I will use only `nautil` instead of `nautil-cli` in the following.
6 |
7 | ## init
8 |
9 | ```
10 | nautil init [--verbose]
11 | ```
12 |
13 | Initialize a new project or override an exisiting project.
14 |
15 | You should run `nautil init` in an empty directory or an exisiting project directory.
16 |
17 | ## build
18 |
19 | ```
20 | nautil build
21 | ```
22 |
23 | Build a app, `app` stands for a dir name in `src/apps` dir. The dest dir is `dist/`.
24 |
25 | Notice, `NODE_ENV` makes sense. For example:
26 |
27 | ```
28 | NODE_ENV=development nautil build dom
29 | ```
30 |
31 | This will make your code without minified.
32 |
33 | ## dev
34 |
35 | ```
36 | nautil dev
37 | ```
38 |
39 | Setup a devserver / watching task to help you develop and preview.
40 |
41 | ## install
42 |
43 | ```
44 | nautil install [pkg@version] [pkg@version] ...
45 | nautil i -g [pkg@version] ...
46 | nautil i -f
47 | ```
48 |
49 | Install some dependencies:
50 |
51 | - pkg: the package you want to install
52 | - -g, --global: install dependencies into nautil-cli inside, for globally installed nautil-cli
53 | - -f, --force: pkg and --global will be ignore, all required dependencies will be reinstalled
54 |
55 | ## run
56 |
57 | ```
58 | nautil run
59 | ```
60 |
61 | `io` can be `android` `ios` `electron`.
62 |
63 | ```
64 | nautil run my-app ios
65 | ```
66 |
67 | This will serve up a metro building to preview an ios app.
68 |
69 | ## pack
70 |
71 | ```
72 | nautil pack
73 | ```
74 |
--------------------------------------------------------------------------------
/docs/cli/env-vars.md:
--------------------------------------------------------------------------------
1 | # Env Vars
2 |
3 | You can use `process.env.NODE_ENV` in your code and it will be replaced with given env vars.
4 |
5 | There are 3 way to give env vars:
6 |
7 | **.env**
8 |
9 | Create a `.env` file into your project root dir.
10 |
11 | It should follow [dotenv](https://www.npmjs.com/package/dotenv) rules.
12 |
13 | You will find a `.env_sample` file in your project dir after init.
14 |
15 | **export**
16 |
17 | Give export in CLI directly:
18 |
19 | ```
20 | NODE_ENV=development nautil build dom
21 | ```
22 |
23 | **define**
24 |
25 | Provide `define` filed in [cli-config.json](./config.md)
26 |
--------------------------------------------------------------------------------
/docs/cli/install.md:
--------------------------------------------------------------------------------
1 | # Nautil-CLI Install
2 |
3 | To install globally, so that you can use it again quickly:
4 |
5 | ```
6 | npm i -g nautil-cli
7 | ```
8 |
9 | To generate project only once:
10 |
11 | ```
12 | npx nautil-cli init
13 | ```
14 |
15 | This will install nautil-cli in your project as a devDependency.
16 |
17 | To use locally in your project:
18 |
19 | ```
20 | npm i -D nautil-cli
21 | ```
22 |
23 | With this, you should must use nautil-cli in npm scripts.
24 |
--------------------------------------------------------------------------------
/docs/cli/ts.md:
--------------------------------------------------------------------------------
1 | # TypeScript
2 |
3 | It is easy to support typescript with Nautil-CLI.
4 |
5 | First of all, you should enable typescript supporting in `.nautil/cli-config.json`.
6 |
7 | After you enable this config, and run `nautil dev `, it will install typescript dependencies for you automaticly.
8 |
9 | Then modify `tsconfig.json` in the project root directory to match your project requirement.
10 |
11 | Next create .ts files to export modules in src dir.
12 | Notice that, index.js should Must be .js file, it is entry file, you should write less code (no logic code) in it, and import .ts files in it.
13 | Nauti-CLI support .ts, .tsx files.
14 |
15 | Finally run `nautil build ` or `nautil dev ` to check whether it works.
16 | Build task will emit error and break out when checking fail.
17 | Dev task will only emit error in CLI and not emit error in browser, so you should must read error infomation in your commander when you developing.
18 |
--------------------------------------------------------------------------------
/docs/component/attrs.md:
--------------------------------------------------------------------------------
1 | # Attrs
2 |
3 | There is a `attrs` property on the component instance.
4 |
5 | ```js
6 | class SomeComponent extends Component {
7 | render() {
8 | const { some } = this.attrs
9 | }
10 | }
11 | ```
12 |
13 | It is a sub-set of `props`. It is from `props` but not the same. It contains:
14 |
15 | ```
16 |
17 |
18 | +---------------+--------------+
19 | | props | attrs |
20 | +---------------+--------------+
21 | | | |
22 | | one ----> one |
23 | | | |
24 | | $two ----> two |
25 | | | |
26 | | onSee | x |
27 | | | |
28 | +---------------+--------------+
29 | ```
30 |
31 | In the `Some` component, we can read `this.attrs.one` and `this.attrs.two`, `onSee` and `$two` are invisible. `this.attrs.two` is the real value of `this.props.$two[0]`.
32 |
33 | And a `this.$attrs` is availiable, it can be changed to trigger two way binding updator.
34 |
35 | ```js
36 | class SomeComponent extends Component {
37 | render() {
38 | return
39 | }
40 | }
41 | ```
42 |
43 | ```js
44 | const $two = useState(0)
45 |
46 | ```
47 |
48 | `$attrs` is a Proxy, you can read value from it, however objects are not equal to origin data.
49 |
--------------------------------------------------------------------------------
/docs/component/class-or-function.md:
--------------------------------------------------------------------------------
1 | # Class or Function?
2 |
3 | > Should we use class components? Can we use functional components?
4 |
5 | Although we are try to support react completely, we had some difficulty to face. Remember the following rules:
6 |
7 | **1. Class components is much more strong than functional components!**
8 |
9 | **2. Two way binding only works for class components.**
10 |
11 | You should must create a class component to receive two way binding props, function components have no ability of nautil.
12 |
13 | ```js
14 | // bad
15 | function MyComponent(props) {
16 | return
17 | }
18 |
19 | // good
20 | class MyComponent extends Component {
21 | static props = {
22 | $age: Number,
23 | }
24 |
25 | render() {
26 | const { age } = this.attrs
27 | return
28 | }
29 | }
30 | ```
31 |
32 | **3. `stylesheet`, `props`, `defaultStylesheet` and event-stream only works for class component.**
33 |
34 | ```js
35 | // bad
36 | function A() {
37 | return
xxx
38 | }
39 | A.props = {}
40 | A.defaultStylesheet = []
41 |
42 | // ok
43 | function A() {
44 | return xxx
45 | }
46 | // bad
47 | A.props = {}
48 | A.defaultStylesheet = []
49 |
50 | // good
51 | class A extends Component {
52 | static props = {}
53 | static defaultStylesheet = []
54 |
55 | render() {
56 | return xxx
57 | }
58 | }
59 | ```
60 |
61 | ## Use hooks in Class component.
62 |
63 | To use hooks functions in class component, you should must set `Render` method then `render`.
64 |
65 | ```js
66 | class Some extends Component {
67 | Render(props) {
68 | // use hooks directly here
69 | const [value, setState] = useState('')
70 | return
71 | }
72 | }
73 | ```
74 |
--------------------------------------------------------------------------------
/docs/component/lifecircle.md:
--------------------------------------------------------------------------------
1 | # Lifecircle
2 |
3 | A little different from react, Nautil has its own lifecircle:
4 |
5 | - ===== mount: =======
6 | - init
7 | - onDigested
8 | - onInit
9 | - render
10 | - onRender
11 | - shouldAffect
12 | - onAffect
13 | - onMounted
14 | - onAffected
15 | - ====== update: =======
16 | - shouldUpdate
17 | - onNotUpdate
18 | - onUpdate
19 | - onDigested
20 | - render
21 | - onRender
22 | - shouldAffect
23 | - onAffect
24 | - onUpdated
25 | - onAffected
26 | - ====== unmount: =======
27 | - onUnmount
28 | - ====== error: =======
29 | - onCatch
30 |
31 | Details:
32 |
33 | - init: when `constructor` run, use `init` so that you do not need to call `super` in `constructor`
34 | - onDigested: after this.attrs, this.className, this.style, this.context... generated, during onDigested, `onParseProps` is triggered, you can use it to transform props to generate different this.attrs, this.className and this.style
35 | - onInit: after onDigested immediately when mount
36 | - shouldUpdate: determine whether to rerender, should return boolean or an array, if return an array means affect when the array is shallow equal to previous, if not equal, to rerender
37 | - onRender: you have the chance to change the VDOM here, should return new VDOM
38 | - shouldAffect: detect whether to affect, should must return an array or `true`, if `true` means going to affect, if return an array means affect when the array is shallow equal to previous
39 | - onAffect: will be invoked before onMounted/onUpdated
40 | - onAffected: be invoked after onAffect and onMounted/onUpdated
41 |
42 | 
43 |
44 | Nautil lifecircle functions should not use together with react component life circle functions (except getDerivedStateFromProps and getSnapshotBeforeUpdate).
45 |
46 | For Nautil components, they will run a `digest` task to generate derived properties such as `attrs` `style` `className` and so on. After this task, before `render`, a `onDigested` lifecircle function will be called.
47 |
--------------------------------------------------------------------------------
/docs/component/props-type.md:
--------------------------------------------------------------------------------
1 | # Props-Type
2 |
3 | This paper will tell you how to set props type. As default, you can use react prop-types as what you did in your react application.
4 | However, we developed this, based on [tyshemo](http://github.com/tangshuang/tyshemo), we can check the data structure of props.
5 | ## Declare props type
6 |
7 | As you learned, we have 3 types of props in nautil: normal, two-way-binding and event-stream. How to declare each type?
8 |
9 | ```js
10 | import { Component } from 'nautil'
11 |
12 | export default class SomeComponent extends Component {
13 | static props = {
14 | // normal
15 | name: String,
16 | // tow-way-binding
17 | $show: Boolean,
18 | // event stream handler, only pass `true` to make it work
19 | onHit: true,
20 | }
21 | }
22 | ```
23 |
24 | ## Define props type
25 |
26 | Props-type system support deep nested object checking.
27 |
28 | ```js
29 | import { Component } from 'nautil'
30 |
31 | export default class SomeComponent extends Component {
32 | static props = {
33 | some: {
34 | name: String,
35 | age: Number,
36 | },
37 | }
38 | }
39 | ```
40 |
41 | Some logic can be inject:
42 |
43 | ```js
44 | import { Component } from 'nautil'
45 | import { ifexist } from 'tyshemo'
46 |
47 | export default class SomeComponent extends Component {
48 | static props = {
49 | some: {
50 | name: ifexist(String),
51 | age: Number,
52 | },
53 | }
54 | }
55 | ```
56 |
57 | Read [more](https://tyshemo.js.org) for type checking.
58 |
59 | ## Optimization
60 |
61 | `props` static property only works in development mode, when you run CLI in production mode, props checking will be dropped, and the `props` static property will be removed from source code by Nautil-CLI.
62 |
63 | ## Async Checking
64 |
65 | If you give `props` as a function, props type checking will run asyncly.
66 |
67 | ```js
68 | class SomeComponent extends Component {
69 | static props = () => ({
70 | name: String,
71 | age: Number,
72 | })
73 | }
74 | ```
75 |
--------------------------------------------------------------------------------
/docs/component/props.md:
--------------------------------------------------------------------------------
1 | # Props
2 |
3 | You can define a static property in Nautil Component class called `props` to declare the received props and their types.
4 |
5 | ```js
6 | import { Component } from 'nautil'
7 |
8 | export class MyComponent extends Component {
9 | static props = {
10 | // normal prop
11 | some: String,
12 |
13 | // object prop
14 | any: {
15 | name: String,
16 | age: Number,
17 | },
18 |
19 | // two-way-binding prop
20 | $show: Boolean,
21 |
22 | // event stream prop, there is no need to declare the real type, only pass `true`
23 | onClick: true,
24 | }
25 | }
26 | ```
27 |
28 | Type checking is following [tyshemo](https://github.com/tangshuang/tyshemo) which is a data schema system in runtime. We will learn more about props type [here](props-type.md).
29 |
30 | You can declare 3 kinds of prop:
31 |
32 | - normal prop
33 | - `$` beginning which is two-way-binding prop
34 | - `on` beginning which is event stream prop
35 |
36 | After you declare the props, you can use `defaultProps` to give the default values.
37 |
--------------------------------------------------------------------------------
/docs/component/stylesheet.md:
--------------------------------------------------------------------------------
1 | # Stylesheet
2 |
3 | In nautil.js, we praise css module, which is easy to implement cross-platform.
4 |
5 | ```js
6 | import { Section, Text, Component } from 'nautil'
7 | import * as Styles from './my-component.css'
8 |
9 | export default class MyComponent extends Component {
10 | render() {
11 | return (
12 |
13 | xxx
14 | xxx
15 |
16 | )
17 | }
18 | static defaultStylesheet = [
19 | 'some-classname',
20 | { color: 'red' },
21 | ]
22 | }
23 | ```
24 |
25 | Read the previous code, you can understand it very easily. You will notice points:
26 |
27 | - import .css as CSS Module
28 | - use a `stylesheet` prop
29 | - mixing style object and className in an array
30 | - this.className
31 | - this.style
32 | - this.css
33 | - static defaultStylesheet
34 | - static css
35 |
36 | **CSS Modules**
37 |
38 | In nautil, we praise CSS Module, and recommend to use CSS Module at the first.
39 | It is not recommended to use style object in react. So use styles in css file.
40 |
41 | **stylesheet**
42 |
43 | A Nautil Class Component can receive a stylesheet prop. The value will be parse automaticly, it can receive all kinds of style expression in web.
44 |
45 | - string: as className
46 | - object:
47 | - boolean: as className
48 | - normal: as style rules
49 | - array: mixing
50 |
51 | When you pass an object, it dependents on the value of each property. When the value is a boolean, it means you want to toggle this className.
52 |
53 | ```js
54 |
55 | ```
56 |
57 | **this.className**
58 |
59 | Get current component's `styesheet` parsed classNames to be a string.
60 |
61 | **this.style**
62 |
63 | Get current component's `stylesheet` parsed style object.
64 |
65 | **static defaultStylesheet**
66 |
67 | Prefix stylesheet for current component before render.
68 |
69 | **static css & this.css**
70 |
71 | A component has this.css inside which is generated based on `static css`.
72 |
73 | ```js
74 | class MyComponent extends Component {
75 | static css = {
76 | a: '__a',
77 | b: '__b',
78 | c: { width: 100, height: 90 },
79 | }
80 |
81 | render() {
82 | return (
83 |
84 | ...
85 |
86 | )
87 | }
88 | }
89 | ```
90 |
91 | To generate this.css dynamicly, you can pass `css` as a function:
92 |
93 | ```js
94 | class MyComponent extends Component {
95 | static css = ({ attrs, style, className }) => ({
96 | a: attrs.a ? '__a' : undefined,
97 | b: '__b',
98 | c: { width: 100, height: 90 },
99 | })
100 | }
101 | ```
102 |
103 | `css` is always used with CSS Modules together:
104 |
105 | ```js
106 | import * as SomeCss from 'some.css'
107 |
108 | class MyComponent extends Component {
109 | static css = SomeCss
110 | }
111 | ```
112 |
113 | This help us to generate cross-platform styles by only one css file.
114 |
--------------------------------------------------------------------------------
/docs/components/async.md:
--------------------------------------------------------------------------------
1 | # Async
2 |
3 | ```js
4 | new Promise(...)}
6 | then={data => {data.text}}
7 | catch={e => {e.message}}
8 | pending={}
9 | />
10 | ```
11 |
--------------------------------------------------------------------------------
/docs/components/each.md:
--------------------------------------------------------------------------------
1 | # Each
2 |
3 | ```js
4 |
5 | {key}: {value}
6 | } />
7 | ```
8 |
--------------------------------------------------------------------------------
/docs/components/for.md:
--------------------------------------------------------------------------------
1 | # For
2 |
3 | ```js
4 |
5 | {i}
6 | } />
7 | ```
8 |
9 | Notice that, the range contains `end`.
10 |
--------------------------------------------------------------------------------
/docs/components/if-else.md:
--------------------------------------------------------------------------------
1 | # If/ElseIf/Else
2 |
3 | Render by given condition.
4 |
5 | ## If
6 |
7 | Render when `is` prop is true.
8 |
9 | ```js
10 |
11 | ```
12 |
13 | or
14 |
15 | ```js
16 |
17 | {Function}
18 |
19 | ```
20 |
21 | The `render` function, should return a Nautil Element. It is like `render` method of Nautil component.
22 |
23 | ## ElseIf
24 |
25 | It is a sub component of `If` component. You should use it inside `If`.
26 |
27 | ```js
28 |
29 |
30 |
31 | ```
32 |
33 | ## Else
34 |
35 | The same as `ElseIf` only without `is` prop.
36 |
37 | ```js
38 |
39 |
40 |
41 |
42 | ```
43 |
--------------------------------------------------------------------------------
/docs/components/observer.md:
--------------------------------------------------------------------------------
1 | # Observer
2 |
3 | This component is very important in Nautil.
4 | It is the power to make observer pattern work in your application.
5 |
6 | **props**
7 |
8 | - subscribe
9 | - unsubscribe
10 | - dispatch
11 | - render|children function
12 |
13 | ```js
14 | store.subscribe(dispatch)}
16 | unsubscribe={dispatch => store.unsubscribe(dispatch)}
17 | dispatch={this.update}
18 | >
19 | {() => {store.state.some}}
20 |
21 | ```
22 |
23 | Notice the `dispatch` function which passed into `subscribe`/`unsubscribe` prop. In fact, it is really the function you passed into `dispatch` prop.
24 |
--------------------------------------------------------------------------------
/docs/components/prepare.md:
--------------------------------------------------------------------------------
1 | # Prepare
2 |
3 | ```js
4 | loading} render={() =>
5 | loaded
6 | } />
7 | ```
8 |
--------------------------------------------------------------------------------
/docs/components/static.md:
--------------------------------------------------------------------------------
1 | # Static
2 |
3 | ```js
4 |
5 | {Date.now()}
6 | } />
7 | ```
8 |
9 | When `shouldUpdate` is `false`, the render result will not change. If change to `true`, the render will change.
10 |
11 | `shouldUpdate` can be:
12 |
13 | - boolean: true to update, false to keep static
14 | - array: if the passed array items are equal, to update, or to keep static, like `detectEffect`
15 | - function: function to return true or false, true to update
16 |
--------------------------------------------------------------------------------
/docs/components/switch-case.md:
--------------------------------------------------------------------------------
1 | # Switch/Case
2 |
3 | Render by given condition.
4 |
5 | ## Switch
6 |
7 | ```js
8 |
9 |
10 |
11 | ```
12 |
13 | When the value of `Case.is` equals `Switch.of`, use the `render` function to render.
14 |
15 | ## Case
16 |
17 | ```js
18 |
19 | ```
20 |
21 | - is: when equals `Switch.of`, render it
22 | - default: if all previous not match, use this render
23 | - break: if match, render this, and stop going down
24 |
25 | ```js
26 |
27 |
28 |
29 |
30 | ```
31 |
32 | Let's look this to learn about `break`. When `index%3 === 1`, it will **only** render first branch, or it will render the **both** branch
33 |
--------------------------------------------------------------------------------
/docs/concepts/css-module.md:
--------------------------------------------------------------------------------
1 | # CSS Module
2 |
3 | You'd better use [CSS Module](https://css-tricks.com/css-modules-part-1-need/) in Nautil. According to the [repo](https://github.com/css-modules/css-modules), CSS modules are:
4 |
5 | > CSS files in which all class names and animation names are scoped locally by default.
6 |
7 | Why should you use CSS Module in Nautil?
8 | It is much easier to find out from which css file the rules come. Another reason is becuase of cross-platform. It is very easy to load css rules as objects by using building tools, if you do not use CSS Module, there is no way to cross platform with one code.
9 |
10 | If you use nautil-cli, it is automaticly to import a css file as CSS Module:
11 |
12 | ```js
13 | import * as Css from './some.css' // -> CSS Module
14 | import './any.css' // -> global css import
15 | ```
16 |
--------------------------------------------------------------------------------
/docs/concepts/data-type-system.md:
--------------------------------------------------------------------------------
1 | # Data Type System
2 |
3 | To check type and structure of a data, Nautil uses [tyshemo](https://github.com/tangshuang/tyshemo). You can give a `props` static property to a class component so that props will be checked.
4 |
5 | ```js
6 | import BookType from '../types/book.type.js'
7 |
8 | class MyComponent extends Component {
9 | static props = {
10 | data: {
11 | name: String,
12 | age: Number,
13 | books: [BookType],
14 | },
15 | }
16 | }
17 | ```
18 |
19 | As you seen, it is very similar to real data structure, other developers can understand your props structure easily.
20 |
--------------------------------------------------------------------------------
/docs/concepts/observer-pattern.md:
--------------------------------------------------------------------------------
1 | # Observer Pattern
2 |
3 | [Observer Pattern](https://en.wikipedia.org/wiki/Observer_pattern) is the most important concepts you should keep in mind when you use Nautil. It is so important that already all abilities are built on it.
4 |
5 | > The observer pattern is a software design pattern in which an object, called the **subject**, maintains a list of its dependents, called **observers**, and notifies them automatically of any state changes, usually by calling one of their methods.
6 |
7 | Normally, we create a subject and pass a function into it, this function is a method of an observer. When the subject changes, the method will be called, so that the observer will change too.
8 |
9 | Let's look a simple example:
10 |
11 | ```js
12 | store.on('*', dispatch)}
15 | unsubscribe={dispatch => store.off('*', dispatch)}
16 | >
17 | {store.get('some')}
18 |
19 | ```
20 |
21 | In Nautil, we use `Observer` component as an *observer*, here `store` is a subject. `Observer` component receive a `dispatch` prop to define its *method*. The `subscribe` prop is the action to give the *method* to the *subject*. After `Observer` component mounted, the subscribe function will be called, so that the *subject* `store` will put the *method* `dispatch` in the dependents' notifies list. When `store` changes, `dispatch` which equals `this.update` will be called. Then the UI will be rerendered.
22 |
--------------------------------------------------------------------------------
/docs/concepts/stream.md:
--------------------------------------------------------------------------------
1 | # Stream
2 |
3 | [Rxjs](https://github.com/ReactiveX/RxJS) is used in Nautil to handle event streams. But what is a stream? A stream is data points separated by time. Read [this article](https://javascript.tutorialhorizon.com/2017/04/28/rxjs-tutorial-getting-started-with-rxjs-and-streams/) to know what and [this page](https://rxjs.dev/guide/operators) to know how.
4 |
5 | When you handle an event, you can pass a callback function, or, the deep usage, a stream pipe-chain and execution.
6 |
7 | ```
8 | [operator1, operator2, ...operators, execution]
9 | ```
10 |
11 | ```js
12 | import { map } from 'rxjs'
13 |
14 | e.target.value),
19 | map(value => value ++),
20 |
21 | // subscriber
22 | value => console.log(value)
23 | ]}
24 | />
25 | ```
26 |
27 | If you pass an array, the last item should must be a function which pass into `stream$.subscribe`.
28 |
29 | ```js
30 | import { Stream } from 'nautil'
31 |
32 | const change$ = new Stream()
33 | change$.pipe(
34 | map(e => e.target.value),
35 | map(value => value ++),
36 | ).subscribe(
37 | value => console.log(value)
38 | )
39 |
40 |
44 | ```
45 |
46 | By supporting this pattern, you will be able to seperate your event stream from UX handlers.
47 |
--------------------------------------------------------------------------------
/docs/concepts/two-way-binding.md:
--------------------------------------------------------------------------------
1 | # Two-Way-Binding
2 |
3 | There is no strict defination of **Two Way Binding**. In short, it is about a reactive proposal between view and model, which describes [when changing model changes the view and changing the view changes the model](https://medium.com/front-end-weekly/what-is-2-way-data-binding-44dd8082e48e).
4 |
5 | In react, data only goes one way, from parent component to child component by passing props. And the main voice in community is immutable data. However, it is not comfortable when we are going to build a intertwined application. In fact, redux is not good enough to solve the problem, it is to complex to write many non-business codes. We want an easy way.
6 |
7 | In Nautil, we can use Two Way Binding. Let's have a look:
8 |
9 | ```js
10 | const $some = useState(some)
11 |
12 | ```
13 |
14 | The previous code is very simple, however it is very powerful. You do not need to care about what it will do inside `Input`. It will give you right UI response when value of input changed. In the document of Two Way Binding, I will introduce the whole face of it.
15 |
16 | Relate APIs:
17 |
18 | - createTwoWayBinding(data, updator, formalized)
19 | - useTwoWayBinding(data, updator, formalized)
20 | - useTwoWayBindingAttrs(props)
21 | - useTwoWayBindingState(initState)
22 |
--------------------------------------------------------------------------------
/docs/controller/controller.md:
--------------------------------------------------------------------------------
1 | # Controller
2 |
3 | What is Controller in Nautil? It is in fact a type of special model, which controls view's data and reactive (event handlers). In Nautil, a controller orient a business scenes.
4 |
5 | In many business scenes, we have a same controller, but should act different views. The Controller is the way to keep the business logic same in one system, and be used in different views. For example, you have a payment module in your system, and have PC and App clients, however, business logic should must be same on both client sides. Here, you should create a controller which contains the same business logic, and use it on both client side views.
6 |
7 | ## Usage
8 |
9 | ```js
10 | import { Controller, Model, Service } from 'nautil'
11 |
12 | class SomeModel extends Model {}
13 |
14 | class SomeService extends Service {}
15 |
16 | class SomeController extends Controller {
17 | static someModel = SomeModel
18 | static someService = SomeService
19 |
20 | static increase$(stream) {
21 | stream.subscribe(() => {
22 | this.someModel.some = 'xxx'
23 | })
24 | }
25 |
26 | handleRemove() {
27 | ...
28 | }
29 | }
30 | ```
31 |
32 | `Controller` is a helpfull tool in nautil, it is designed to control a business area in one place.
33 | In a controller, you can define Model, Service, Events, Components and scoped handlers.
34 | The exported components from a controller can be used in other components in Nautil, the exported components are treated as business components but with small code size.
35 |
36 | When define a Controller, you should `extends` from `Controller` class, and given static properties. For example:
37 |
38 | ```js
39 | class SomeController extends Controller {
40 | static someModel = SomeModel // Model -> this.someModel
41 | static someDataService = SomeDataService // DataService -> this.someDataService
42 | static someService = SomeService // Service -> this.someService (single instance)
43 | static count$(stream$) { // stream$() -> this.count$
44 | // here you can use this point to Controller instance
45 | stream$.pipe(...).subscribe(...)
46 | }
47 | static store = Store // Store -> this.store, used as state helper
48 |
49 | // after Controller initialized
50 | init() {}
51 |
52 | // provide an API method
53 | decreaseCount() {
54 | this.count$.next(...)
55 | }
56 | }
57 | ```
58 |
59 | **You should never operate UI in controller.** A controller is an API set to provide to views, so you should keep in mind that it is an independent system from UI operation. And this is the way to seperate business logic from React components, make business logic management as an independent job.
60 |
61 | ## API
62 |
63 | ### observe(observer: Model | Store | Function) -> { start, stop }
64 |
65 | Observe other observable objects which are not put inside controller, for example:
66 |
67 | ```js
68 | controller.observe((dispatch) => {
69 | const timer = setInterval(dispatch, 5000)
70 | return () => clearInterval(timer)
71 | })
72 | ```
73 |
74 | After this, controller will react each 5s.
75 |
--------------------------------------------------------------------------------
/docs/decorators/decorate.md:
--------------------------------------------------------------------------------
1 | # decorate
2 |
3 | ```js
4 | function H(props) {
5 | const {
6 | render,
7 | } = props
8 | const state = 1
9 | const data = 2
10 | return render(state, data)
11 | }
12 |
13 | function C(props) {
14 | const { state, data } = props
15 | return null
16 | }
17 |
18 | export default decorate(H, ['state', 'data'], 'render')(C) // ->
19 | /**
20 | * function Wrapped(props) {
21 | * return
22 | *
23 | * } />
24 | * }
25 | */
26 | ```
27 |
28 | sign:
29 |
30 | ```
31 | function decorate(HOC: ComponentType, params: string[], renderProp: string): ComponentType
32 | ```
33 |
34 | - HOC: the higher order component to wrapper inner component
35 | - params: names which read from render function's params and patch to inner component's props, the values is provided by HOC
36 | - renderProp: the prop name of HOC render function, if renderProp is not passed, `children` should be a function to receive
37 |
38 |
39 | For example, `Consumer`'s render function is`(value) => ...`, you should pass `['value']` to params, and the inner component will receive `const { value } = props`.
40 |
--------------------------------------------------------------------------------
/docs/decorators/evolve.md:
--------------------------------------------------------------------------------
1 | # evolve
2 |
3 |
4 | ```js
5 | import { evolve } from 'nautil'
6 |
7 | const EvolutionComponent = evolve((props) => {
8 | const { a, b } = props
9 | return { a, b }
10 | })(OriginalComponent)
11 | ```
12 |
13 | In the previous code block, EvolutionComponent will only rerender when the { a, b } is different from previous { a, b }.
14 |
--------------------------------------------------------------------------------
/docs/decorators/initialize.md:
--------------------------------------------------------------------------------
1 | # initialize
2 |
3 | ```js
4 | import { initialize } from 'nautil'
5 |
6 | const WrappedComponent = initialize('some', Some)(OriginalComponent)
7 | ```
--------------------------------------------------------------------------------
/docs/decorators/inject.md:
--------------------------------------------------------------------------------
1 | # inject
2 |
3 | ```js
4 | import { inject } from 'nautil'
5 |
6 | const WrappedComponent = inject('now', () => Date.now())(OriginalComponent)
7 | ```
--------------------------------------------------------------------------------
/docs/decorators/nest.md:
--------------------------------------------------------------------------------
1 | # nest
2 |
3 | ```js
4 | import { nest } from 'nautil'
5 |
6 | const WrappedComponent = nest([
7 | [Provider, { store }],
8 | [Language, { i18n }],
9 | ])(OriginalComponent)
10 | ```
11 |
12 | => output:
13 |
14 | ```js
15 |
16 |
17 |
18 |
19 |
20 | ```
21 |
22 | - options:
23 | - Component
24 | - props: object or function to return object
25 |
26 | ```js
27 | import { nest } from 'nautil'
28 |
29 | const WrappedComponent = nest([
30 | [Provider, (props) => ({ store })],
31 | [Language, (props) => ({ i18n })],
32 | ])(OriginalComponent)
33 | ```
34 |
--------------------------------------------------------------------------------
/docs/decorators/observe.md:
--------------------------------------------------------------------------------
1 | # observe
2 |
3 | ```js
4 | import { observe } from 'nautil'
5 |
6 | const WrappedComponent = observe(
7 | dispatch => store.subscribe(dispatch),
8 | dispatch => store.unsubscribe(dispatch),
9 | )(OriginalComponent)
10 | ```
--------------------------------------------------------------------------------
/docs/decorators/pipe.md:
--------------------------------------------------------------------------------
1 | # pipe
2 |
3 | ```js
4 | import { pipe, observe, initialize } from 'nautil'
5 |
6 | const operate = pipe([
7 | observe(subscribe, unsubscribe),
8 | initialize('i18n', I18nController, { i18n }),
9 | ])
10 |
11 | const WrappedComponent = operate(OriginalComponent)
12 | ```
13 |
--------------------------------------------------------------------------------
/docs/elements/audio.md:
--------------------------------------------------------------------------------
1 | # Audio
2 |
3 | ```js
4 | import { Audio } from 'nautil'
5 |
6 |
7 | ```
8 |
9 | ## props
10 |
11 | - source: enumerate([String, Object]),
12 | - width: Unit,
13 | - height: Unit,
14 | - onPlay
15 | - onPause
16 | - onStop
17 | - onDrag
18 | - onResume
19 | - onReload
20 | - onLoad
21 | - onTick
22 | - onVolume
--------------------------------------------------------------------------------
/docs/elements/button.md:
--------------------------------------------------------------------------------
1 | # Button
2 |
3 | ```js
4 | import { Button } from 'nautil'
5 |
6 |
7 | ```
8 |
9 | ## props
10 |
11 | - onHit
12 | - onHitStart
13 | - onHitEnd
--------------------------------------------------------------------------------
/docs/elements/checkbox.md:
--------------------------------------------------------------------------------
1 | # Checkbox
2 |
3 | ```js
4 | import { Checkbox } from 'nautil'
5 |
6 |
7 | ```
8 |
9 | ## props
10 |
11 | - checked: Boolean
12 | - onCheck
13 | - onUncheck
14 | - onChange
15 |
16 | `Checkbox` supports two-way-binding:
17 |
18 | ```js
19 |
20 | ```
--------------------------------------------------------------------------------
/docs/elements/form.md:
--------------------------------------------------------------------------------
1 | # Form
2 |
3 | ```js
4 | import { Form } from 'nautil'
5 |
6 |
9 | ```
10 |
11 | ## props
12 |
13 | - onChange
14 | - onReset
15 | - onSubmit
16 |
--------------------------------------------------------------------------------
/docs/elements/image.md:
--------------------------------------------------------------------------------
1 | # Image
2 |
3 | ```js
4 | import { Image } from 'nautil'
5 |
6 | ```
7 |
8 | ## props
9 |
10 | - source: enumerate([String, dict({ uri: String })]),
11 | - width: Unit,
12 | - height: Unit,
13 | - maxWidth: ifexist(Unit),
14 | - maxHeight: ifexist(Unit),
15 | - onLoad
16 |
--------------------------------------------------------------------------------
/docs/elements/input.md:
--------------------------------------------------------------------------------
1 | # Input
2 |
3 | ```js
4 | import { Input } from 'nautil'
5 |
6 |
7 | ```
8 |
9 | ## props
10 |
11 | - type: enumerate(['text', 'number', 'email', 'tel', 'url']) // dont support `date` or `range` right now
12 | - placeholder: ifexist(String)
13 | - value: enumerate([String, Number])
14 | - onChange
15 | - onFocus
16 | - onBlur
17 | - onSelect
18 |
19 | `Input` support two-way-binding:
20 |
21 | ```js
22 | function Some() {
23 | const value = useState('')
24 |
25 | return
26 | }
27 | ```
--------------------------------------------------------------------------------
/docs/elements/line.md:
--------------------------------------------------------------------------------
1 | # Line
2 |
3 | ```js
4 | import { Line } from 'nautil'
5 |
6 |
7 | ```
8 |
9 | ## props
10 |
11 | - length: Number
12 | - thick: Number
13 | - color: String
--------------------------------------------------------------------------------
/docs/elements/list-section.md:
--------------------------------------------------------------------------------
1 | # ListSection
2 |
3 | A composition component which used to render a list.
4 |
5 | ```js
6 | import { ListSection } from 'nautil'
7 |
8 | ...}
11 | itemKey="id"
12 | itemStyle={{ ... }}
13 | />
14 | ```
15 |
16 | It optimize the implement of list render inside, so you can render a large list once.
--------------------------------------------------------------------------------
/docs/elements/radio.md:
--------------------------------------------------------------------------------
1 | # Radio
2 |
3 | ```js
4 | import { Radio } from 'nautil'
5 |
6 |
7 | ```
8 |
9 | ## props
10 |
11 | - checked: Boolean
12 | - onCheck
13 | - onUncheck
14 | - onChange
15 |
16 | `Radio` supports two-way-binding:
17 |
18 | ```js
19 |
20 | ```
--------------------------------------------------------------------------------
/docs/elements/scroll-section.md:
--------------------------------------------------------------------------------
1 | # ScrollSection
2 |
3 | A composition component which can be scrolled.
4 |
5 | ```js
6 | import { ScrollSection } from 'nautil'
7 |
8 | ,
18 | finish: 'finish',
19 | }}
20 | onTopRelease={fetchData}
21 | >
22 | ...
23 |
24 | ```
25 |
26 | ## props
27 |
28 | - direction: enumerate([UP, DOWN, BOTH, NONE]),
29 | - distance: Number,
30 | - damping: range({ min: 0, max: 1 }),
31 | - topLoading: Boolean,
32 | - topIndicator:
33 | - [ACTIVATE]: Any,
34 | - [DEACTIVATE]: Any,
35 | - [RELEASE]: Any,
36 | - [FINISH]: Any,
37 | - topIndicatorStyle: enumerate([Object, String]),
38 | - onTopRelease: Function,
39 | - bottomLoading: Boolean,
40 | - bottomIndicator: {
41 | - [ACTIVATE]: Any,
42 | - [DEACTIVATE]: Any,
43 | - [RELEASE]: Any,
44 | - [FINISH]: Any,
45 | - bottomIndicatorStyle: enumerate([Object, String]),
46 | - onBottomRelease: Function,
47 | - onScroll: Function,
48 | - containerStyle: enumerate([Object, String]),
49 | - contentStyle: enumerate([Object, String]),
50 |
51 | ```js
52 | const { UP, DOWN, BOTH, NONE, ACTIVATE, DEACTIVATE, RELEASE, FINISH } = ScrollSection
53 | ```
54 |
55 | Indicators are content to show in top or bottom area.
56 |
57 | - DEACTIVATE: when users pull down/up but not reach the `distance`
58 | - ACTIVATE: when users pull down/up and reach the `distance`
59 | - RELEASE: when users pull down/up and reach the `distance` and release their fingers, at the same time, onTopRelase/onBottomRelease will be fired, here, you should must set topLoading/bottomLoading from `false` to `true`
60 | - FINISH: after topLoading/bottomLoading change from `true` to `false`
--------------------------------------------------------------------------------
/docs/elements/section.md:
--------------------------------------------------------------------------------
1 | # Section
2 |
3 | ```js
4 | import { Section } from 'nautil'
5 |
6 |
7 | ...
8 |
9 | ```
10 |
11 | ## Props
12 |
13 | - onHit
14 | - onHitStart
15 | - onHitMove
16 | - onHitEnd
17 | - onHitCancel
18 | - onHitOutside
--------------------------------------------------------------------------------
/docs/elements/select.md:
--------------------------------------------------------------------------------
1 | # Select
2 |
3 | ```js
4 | import { Select } from 'nautil'
5 |
6 |
7 | ```
8 |
9 | ## props
10 |
11 | - value: Any
12 | - options: List
13 | - text: String
14 | - value: Any
15 | - disabled: ifexist(Boolean)
16 | - placeholder: ifexist(String)
17 | - onChange
18 |
19 | `Select` supports two-way-binding:
20 |
21 | ```js
22 |
23 | ```
--------------------------------------------------------------------------------
/docs/elements/swipe-section.md:
--------------------------------------------------------------------------------
1 | # SwipeSection
2 |
3 | ```js
4 | import { SwipeSection } from 'nautil'
5 |
6 |
7 | ...
8 |
9 | ```
10 |
11 | ## props
12 |
13 | - sensitivity: Number, distance from screen border
14 | - distance: Number, moved distance before onStart
15 | - disabled: Boolean,
16 | - direction: enumerate(['left', 'right', 'both']),
17 | - throttle: Number,
18 | - onStart
19 | - onMove
20 | - onEnd
21 | - onCancel
22 | - onReach
23 | - onUnreach
24 |
--------------------------------------------------------------------------------
/docs/elements/text.md:
--------------------------------------------------------------------------------
1 | # Text
2 |
3 | ```js
4 | import { Text } from 'nautil'
5 |
6 | text
7 | ```
8 |
--------------------------------------------------------------------------------
/docs/elements/textarea.md:
--------------------------------------------------------------------------------
1 | # Textarea
2 |
3 | ```js
4 | import { Textarea } from 'nautil'
5 |
6 |
7 | ```
8 |
9 | ## props
10 |
11 | - value: String
12 | - line: Number, textarea row
13 | - placeholder: ifexist(String)
14 | - onChange
15 | - onFocus
16 | - onBlur
17 | - onSelect
18 |
19 | `Textarea` support two-way-binding:
20 |
21 | ```js
22 |
23 | ```
--------------------------------------------------------------------------------
/docs/elements/video.md:
--------------------------------------------------------------------------------
1 | # Video
2 |
3 | ```js
4 | import { Video } from 'nautil'
5 |
6 |
