Finish docs (#72)

* finish docs

* react as dev deps to build docs

* typo

* Error -> ValidationError

Author: nighca

.github/workflows/doc.yml

@@ -16,10 +16,12 @@ jobs:
       uses: actions/setup-node@v1
       with:
         node-version: 16.x
-    - name: Generate and deploy document
-      uses: JamesIves/[email protected]
-      env:
-        BRANCH: gh-pages
-        FOLDER: dumi/dist
-        BUILD_SCRIPT: npm ci && npm run build:doc
-        ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
+    - name: Build docs
+      run: |
+        npm ci
+        npm run build:doc
+    - name: Deploy docs
+      uses: JamesIves/[email protected]
+      with:
+        branch: gh-pages
+        folder: dumi/dist/formstate-x

README.md

@@ -5,62 +5,31 @@
 [![](https://github.com/qiniu/formstate-x/workflows/Doc/badge.svg)](https://github.com/qiniu/formstate-x/actions?query=workflow%3ADoc+branch%3Amaster)
 [![](https://github.com/qiniu/formstate-x/workflows/Publish/badge.svg)](https://github.com/qiniu/formstate-x/actions?query=workflow%3APublish+branch%3Amaster)
 
-Manage the state of your form with ease, inspired by awesome [formstate](https://github.com/formstate/formstate). formstate-x maintains and validates form state for you, totally automatically.
+formstate-x is a tool to help you manage form state, based on [MobX](https://mobx.js.org/). formstate-x provides:
 
-What we offer:
-
-* **Type safety**: written in [Typescript](https://typescriptlang.org), you can compose complex form state without loss of type information
-
-    ![Demo](./assets/demo.gif)
-
-* **Reactive**: based on [MobX](https://mobx.js.org), every dependency's change causes reaction automatically and you can easily react to state's change
+* **Composability**: Forms are composition of inputs, complex inputs are composition of simpler inputs. With composability provided by formstate-x, you can build arbitrary complex forms or input components with maximal code reuse.
+* **Type safety**: With Typescript, no matter how complex or dynamic the form logic is, you can get type-safe result for value, error, validator, etc.
+* **Reactive validation**: With reactivity system of MobX, every dependency change triggers validation automatically and you can easily react to state change
 * **UI-independent**: formstate-x only deals with state / data, you can easily use it with any UI library you like
 
-### Documents 
-
-Full documents [here](https://qiniu.github.io/formstate-x).
-
-### Install
-
-```shell
-npm i formstate-x
-// or
-yarn add formstate-x
-```
-
-### Usage
+### Documentation
 
-```javascript
-import { FieldState, FormState, bindInput } from 'formstate-x'
+You can find full documentation [here](https://qiniu.github.io/formstate-x/).
 
-const foo = new FieldState('')
-const bar = new FieldState(0)
-const form = new FormState({ foo, bar })
+### Contributing
 
-// handle submit
-async function handleSubmit(e) {
-  e.preventDefault()
-  const result = await form.validate()
-  if (result.hasError) {
-    alert('Invalid input!')
-    return
-  }
-  // use the validated value
-  await submitted = submit(result.value)
-}
+1. Fork the repo and clone the forked repo
+2. Install dependencies
 
-// when render (with react)
-<form onSubmit={handleSubmit}>
-  <FooInput {...bindInput(form.$.foo)}>
-  <BarInput {...bindInput(form.$.bar)}>
-</form>
-```
+    ```shell
+    npm i
+    ```
 
-### Comparison with [formstate](https://github.com/formstate/formstate)
+3. Edit the code
+4. Do lint & unit test
 
-formstate-x provides similar APIs with [formstate](https://github.com/formstate/formstate) because we like their simplicity. formstate has a very helpful document which we will recommend you to read. But there are some points of formstate that brought inconvenience to our development, and we got disagreement with formstate in related problems. That's why we build formstate-x:
+    ```shell
+    npm run validate
+    ```
 
-1. formstate uses MobX but not embracing it, which constrained its ability (related issue: [#11](https://github.com/formstate/formstate/issues/11)). formstate-x leverages MobX's power substantially, so we can easily track all dependencies when do validation, including dynamic values or dynamic valdiators. That's also why realizing cross-field validation is extremly easy with formstat-x.
-2. formstate mixes validated, safe value with readable value (`$`), in some cases it's not suitable to use either `$` or `value`. formstate-x provides `value` as readable value, `$` as validated and safe value and `_value` for UI binding only.
-3. formstate doesn't provide a good way to extract value from `FormState` ( related issues: [#25](https://github.com/formstate/formstate/issues/25) [#28](https://github.com/formstate/formstate/issues/28)). formstate-x provides `value` as `FormState`'s serialized value, with full type info.
-4. formstate dosen't provide a good way to disable part of a `FormState`. `FormStateLazy` is like a hack and very different concept from `FieldState` & `FormState`. formstate-x provides `disableValidationWhen` to let you realize conditional validation with a single method call.
+5. Commit and push, then create a pull request

dumi/.umirc.ts

@@ -5,8 +5,8 @@ const repo = 'formstate-x'
 
 export default defineConfig({
   title: repo,
-  favicon: 'TODO',
-  logo: 'TODO',
+  favicon: 'https://qiniu.staticfile.org/favicon.ico',
+  logo: `/${repo}/logo.svg`,
   outputPath: `dist/${repo}`,
   mode: 'site',
   hash: true,
@@ -23,6 +23,7 @@ export default defineConfig({
   alias: {
     'formstate-x': path.join(__dirname, 'src')
   },
+  styles: [`.__dumi-default-navbar-logo { color: #454d64 !important; }`],
   mfsu: {}
   // more config: https://d.umijs.org/config
 })

dumi/docs/concepts/input/index.md

@@ -0,0 +1,104 @@
+---
+title: Input
+order: 1
+toc: menu
+---
+
+### Input
+
+A input is a part of an application, which collects info from user interaction. Typical inputs include:
+
+* HTML `<input type="text" />` which collects a text string
+* [MUI `Date Picker`](https://mui.com/components/date-picker/) which collects a date
+* [Antd `Upload`](https://ant.design/components/upload/) which collects a file
+* Some `FullNameInput` which collects someone's full name
+* ...
+
+### General Input API
+
+We will introduce general inputs' API based on [React.js](https://reactjs.org/). It will not be very different in other UI frameworks like [Vue.js](https://vuejs.org/) or [Angular](https://angular.io/).
+
+In a React.js application, a [(controlled) input component](https://reactjs.org/docs/forms.html#controlled-components) always provides an API like:
+
+```ts
+type Props<T> = {
+  value: T
+  onChange: (event: ChangeEvent) => void
+}
+```
+
+The prop `value` means the current input value, which will be displayed to the user.
+
+The prop `onChange` is a handler for event `change`. When user interaction produces a new value, the input fires event `change`—the handler `onChange` will be called.
+
+Typically the consumer of the input holds the value in a state. In the function `onChange`, it sets the state with the new value, which causes re-rendering, and the new value will be displayed.
+
+An [uncontrolled input component](https://reactjs.org/docs/uncontrolled-components.html) may behave slightly different, but the flow are mostly the same.
+
+A complex input may consist of multiple simpler inputs. MUI `Date Picker` includes a number input and a select-like date selector, A `FullNameInput` may includes a first-name input and a last-name input, etc. While no matter how complex it is, as consumer of the input, we do not need to know its implementation or UX details. All we need to do is making a convention of the input value type and then expect the input to collect it for us. That's the power of abstraction.
+
+### Input API in formstate-x
+
+While in forms of real applications, value of input is not the only thing we care. Users may make mistakes, we need to validate the input value and give users feedback.
+
+The validation logic, which decides if a value valid, is always related with the logic of value composition and value collection—the logic of the input.
+
+The feedback UI, which tells users if they made a mistake, is always placed beside the input UI, too.
+
+Ideally we define inputs which extracts not only value-collection logic, but also validation and feedback logic. Like that the value can be accessed by the consumer, the validation result should be accessable for the consumer.
+
+While the API above (`{ value, onChange }`) does not provide ability to encapsulate validation and feedback logic in inputs. That's why we introduce a new one:
+
+```ts
+type Props = {
+  state: State
+}
+```
+
+`State` is a object including the input value and current validation info. For more details about it, check section [State](/concepts/state). By passing a state to an input component, information exchanges between the input and its consumer are built.
+
+An important point is, the logic of (creating) state is expected to be provided by the input—that's how the input decides the validation logic. Apart from the component definition, the module of a input will also provide a state factoty, which makes the module like this:
+
+```ts
+// the input state factory
+export function createState(): State {
+  // create state with certain validation logic
+}
+
+// the input component who accepts the state
+export default function Input({ state }: { state: State }) {
+  // render input with value & validation info from `state`
+}
+```
+
+The consumer of the input may access and imperatively control (if needed) value and 
+validation info through `state`.
+
+### Composability
+
+Inputs are still composable. We can build a complex input based on simpler inputs. A `InputFooBar` which consists of `InputFoo` and `InputBar` may look like this:
+
+_Below content is a pseudo-code sample. For more realistic example, you can check section [Composition](/guide/composition)._
+
+```tsx | pure
+import InputFoo, * as inputFoo from './InputFoo'
+import InputBar, * as inputBar from './InputBar'
+
+type State = Compose<inputFoo.State, inputBar.State>
+
+export function createState(): State {
+  return compose(
+    inputFoo.createState(),
+    inputBar.createState()
+  )
+}
+
+export default function InputFooBar({ state }: { state: State }) {
+  return (
+    <>
+      <InputFoo state={state.foo} />
+      <InputBar state={state.bar} />
+    </>
+  )
+}
+```

dumi/docs/concepts/state/index.md

@@ -1,7 +1,102 @@
 ---
 title: State
-order: 1
+order: 2
 toc: menu
 ---
 
-TODO
+### State
+
+A formstate-x state is a object which holds state (value, error, etc.) for a input.
+
+In formstate-x, there are more than one state types (such as `FieldState`, `FormState`, `TransformedState`, ...), while all of them implemented the same interface `IState`. Here is the interface definition:
+
+_For convenience of reading, some unimportant fields are omitted._
+
+```ts
+/** interface for State */
+export interface IState<V> {
+  /** Value in the state. */
+  value: V
+  /** Set `value` on change event. */
+  onChange(value: V): void
+  /** Set `value` imperatively. */
+  set(value: V): void
+  /** If activated (with auto-validation). */
+  activated: boolean
+  /** Current validate status. */
+  validateStatus: ValidateStatus
+  /** The error info of validation. */
+  error: ValidationError
+  /** The state's own error info, regardless of child states. */
+  ownError: ValidationError
+  /** Append validator(s). */
+  withValidator(...validators: Array<Validator<V>>): this
+  /** Fire a validation behavior imperatively. */
+  validate(): Promise<ValidateResult<V>>
+  /** Configure when state should be disabled. */
+  disableWhen(predictFn: () => boolean): this
+}
+```
+
+### Composability
+
+Like inputs, states are composable.
+
+A state may be composed of multiple child states. Its value is the composition of these child states' values and its validation result reflects all its child states' validation results.
+
+A state for a complex input can be composed of its child inputs' states.
+
+A state for a list input can be composed of its item inputs' states.
+
+A form, which includes multiple inputs, can be considered as a complex input with a submit button. We use a formstate-x state to hold state for a form. The state for a form can be composed of its inputs' states.
+
+### Value
+
+A state holds the current value, and provides methods to change it.
+
+A input component is expected to get state from its props. The component read the value for rendering and set the value when user interacts.
+
+The input component's consumer is expected to create the state and hold it. By passing it to the input component, the consumer get the ability to "control" the input component.
+
+The consumer may also read value from the state for other purposes. Typically, when a user clicks the submit button, from its state a form reads the whole value for submitting (maybe sending an HTTP request).
+
+### Validation
+
+Validation is the process of validating user input values.
+
+Validation is important for cases like:
+
+* When user inputs, we display error tips if validation not passed, so users see that and correct the input
+* Before form submiiting, we check if all value is valid, so invalid requests to the server can be avoided
+
+That's why validation should provide such features:
+
+* It should run automatically, when users changed the value, or when some other data change influcend the value validity
+* It should produce details such as a meaningful message, so users can get friendly hint
+
+With formstate-x, we define validators and append them to states with `withValidator`. formstate-x will do validation for us. Through `validateStatus` & `error`, we can access the validate status and result.
+
+For more examples of validation, check section [Validation](/guide/validation).
+
+For more details about validators, check section [Validator](/concepts/validator).
+
+### Activated
+
+It's not user-friendly to notify a user for inputs he hasn't interact with.
+
+Most forms start with all inputs empty—which values are obviously invalid. While it's not appropriate to show error tips at the beginning.
+
+That's why there's a boolean field `activated` for states.
+
+States will not be auto-validated until it becomes **activated**. And they will become (and stay) activated if one of these happens:
+
+1. Value changed by user interactions (method `onChange()` is called). 
+2. State imperatively validated (method `validate()` is called).
+
+### Own Error
+
+`ownError` & `hasOwnError` are special fields especially for composed states. You can check details about them in issue [#71](https://github.com/qiniu/formstate-x/issues/71).
+
+### Disable State
+
+You may find that we defined method `disableWhen` to configure when a state should be disabled. It is useful in some specific cases. You can check details in section [Disable State](/guide/advanced#disable-state).

dumi/docs/concepts/validator/index.md

@@ -1,7 +1,56 @@
 ---
 title: Validator
-order: 2
+order: 3
 toc: menu
 ---
 
-TODO
+### Validator
+
+A validator is a function, which takes current value as input, and returns the validation result as output. Here are some examples:
+
+```ts
+function required(value: unknown) {
+  return value == null && 'Required!'
+}
+
+async function validateUsername(value: string) {
+  if (value === '') return 'Please input username!'
+  if (value.length > 10) return 'Too long username!'
+  const valid = await someAsyncLogic(value)
+  if (!valid) return 'Invalid username!'
+}
+```
+
+In a validator, we check the input value to see if it's valid. If invalid, we return a message for that. Defining validation logic as such standalone functions has benefits: they are easy to reuse and easy to test.
+
+### Validation Result
+
+```ts
+/** Result of validation. */
+export type ValidationResult =
+  string
+  | null
+  | undefined
+  | false
+
+/** Return value of validator. */
+export type ValidatorReturned = 
+  ValidationResult
+  | Promise<ValidationResult>
+
+/** A validator checks if given value is valid. **/
+export type Validator<T> = (value: T) => ValidatorReturned
+```
+
+A validation result can be one of these two types:
+
+1. A falsy value, such as `""`, `null`, `undefined`, `false`, which indicates that the input value is valid.
+2. A non-empty string value, such as `"Required!"`, which indicates that the input value is invalid, and the string value will be used as a meesage to notify the current user.
+
+If the validation process is async, a validator—we call it "async validator"—can return a `Promise`. The promise is expected to be resolved with a validation result.
+
+### Built-in Validators
+
+Unlike many other form-related libraries, formstate-x provides no built-in validators.
+
+Any function satisfies the definition above can be used as a validator for formstate-x. So it's easy to integrate tools like [joi](https://github.com/sideway/joi), [yup](https://github.com/jquense/yup), [validator.js](https://github.com/validatorjs/validator.js) or [async-validator](https://github.com/yiminghe/async-validator). It's also super easy to define your own validators and compose them. That's why we believe a built-in validator set is not necessary.

dumi/docs/guide/advanced/index.md

@@ -101,7 +101,7 @@ In section [Conditional Validation](/guide/validation#conditional-validation), w
 
 However, sometimes we may add more than one validators for one state. It will not be convenient to add the `if` logic in each validator.
 
-Sometimes we face complex states, which are composed with child states. It's not proper to change validators' logic of child states when writing logic of parent states. `formstate-x` provides a method `disableWhen` to help with such cases.
+Sometimes we face complex states, which are composed of more than one child states. It's not proper to change validators' logic of child states when writing logic of parent states. `formstate-x` provides a method `disableWhen` to help with such cases.
 
 Here is a demo: