@modern-js/main-doc 2.0.0-beta.0 → 2.0.0-beta.1

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/core/use-loader.md

@@ -0,0 +1,83 @@
+---
+title: useLoader
+---
+
+Isomorphic API，usually used to make asynchronous requests。When SSR, the server level uses `useLoader` to prefetch the data, and the browser side also reuses this part of the data.
+
+## Usage
+
+```ts
+import { useLoader } from '@modern-js/runtime';
+```
+
+## Function Signature
+
+```ts
+type LoaderFn = (context: runtimeContext) => Promise<unknow>;
+type Options = {
+  onSuccess: (data: Record<string, any>) => void;
+  onError: (error: Error) => void;
+  initialData: Record<string, any>;
+  skip: boolean;
+  params: Record<string, any>;
+  static: boolean;
+}
+type ReturnData = {
+  data: Record<string, any>;
+  loading: boolean;
+  error: Error;
+  reload: (params?: Record<string, any>) => Promise<any> | undefined;
+  reloading: boolean;
+}
+
+function useLoader(loaderFn: LoaderFn, options: Options): ReturnData;
+```
+
+:::info
+`runtimeContext` can refer to [useRuntimeContext](/docs/apis/app/runtime/core/use-runtime-context)。
+:::
+
+### Input
+
+- `loaderFn`: function for loading data, returning a Promise.
+- `options`: optional configuration.
+  - `onSuccess`: successful callback.
+  - `onError`: error callback.
+  - `initialData`: the initial data before the first execution,.
+  - `skip`: when the value is `true`, the function does not execute.
+  - `params`: when the result of the `params` serialization changes，the function is re-executed。`params` is also passed in as the second argument of the function.
+  - `static`: when the value is `true`, `useLoader` is used for [SSG](/docs/guides/advanced-features/ssg).
+
+### Return Value
+
+- `data`: return data on successful execution.
+- `loading`: indicates whether the function is in execution.
+- `error`: error message when function execution fails。
+- `reload`: the function can be re-executed after the call.
+  - `params`: when the value is `undefined`, the last value will be reused; otherwise, the function will be re-executed with the new value.
+- `reloading`: during the execution of the call to `reload`, the value of `reloading` is `true`.
+
+## Example
+
+```ts
+function Container() {
+  const { data, error, loading } = useLoader(
+    async (context, params) => {
+      console.log(params) // nicole
+      return fetch(user);
+    },
+    {
+      onSuccess: data => {
+        console.log('I did success:(',  data);
+      },
+      onError: error => {
+        console.log('I met error:)',  error);
+      },
+      initialData: { name: 'nicole', gender: 'female' },
+      params: 'nicole'
+    }
+  );
+
+  return ...;
+}
+```

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/core/use-module-apps.md

@@ -0,0 +1,101 @@
+---
+title: useModuleApps
+---
+
+Returns the React components of all micro-front-end sub-applications for freely controlled routing.
+
+## Usage
+
+```tsx
+import { useModuleApps } from '@modern/plugin-garfish';
+```
+
+:::info Turn on
+This API is used in the main application of micro frontend, please execute `pnpm run new` to turn on the micro frontend function first.
+
+```bash
+pnpm run new
+? 请选择你想要的操作 启用可选功能
+? 启用可选功能 启用「微前端」模式
+```
+:::
+
+## Function Signature
+
+`function useModuleApps(): Record<string, React.FC<any>>`
+
+Returns the React components wrapped around each subapp.
+
+## Example
+
+You need to configure the micro-front-end sub-application information first.
+
+```ts title=modern.config.js
+module.exports = {
+  runtime: {
+    features:{
+      masterApp: {
+        apps: [
+          {
+            name: 'Home',
+            entry: 'http://www.home.com'
+          },
+          {
+            name: 'Contact',
+            entry: 'http://www.contact.com'
+          },
+        ]
+      }
+    }
+  }
+}
+```
+
+```tsx title=App.tsx
+function App() {
+  const { Components: { Home, Contact } } = useModuleApps();
+
+  return <div>
+    Master APP
+    <Route exact path='/home'>
+      <Home />
+    </Route>
+    <Route exact path='/home'>
+      <Contact />
+    </Route>
+  </div>;
+}
+```
+
+Get the `Home` and `Contact` sub-application components(the same as name in the config) through `useModuleApps()`. After that, you can load the child application just like a normal React component.
+
+
+## Load Animation
+
+The transition animation of the component loading process can be customized in the following ways.
+
+```tsx title=App.tsx
+function App() {
+  const { Components: { Home } } = useModuleApps();
+
+  return <div>
+    Master APP
+    <Route exact path='/home'>
+      <Home
+        loadable={{
+          loading: ({ pastDelay, error }: any) => {
+            if (error) {
+              console.error(error);
+              return <div>error: {error?.message}</div>;
+            } else if (pastDelay) {
+              return <div>loading</div>;
+            } else {
+              return null;
+            }
+          },
+        }}
+      />
+    </Route>
+  </div>;
+}
+```

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/core/use-runtime-context.md

@@ -0,0 +1,59 @@
+---
+title: useRuntimeContext
+---
+
+This function is mainly used to get the runtime context and can only be used in function components.
+
+## Usage
+
+```tsx
+import { useRuntimeContext } from '@modern-js/runtime';
+
+export function App() {
+  const runtimeContext = useRuntimeContext();
+  return <div>Hello World</div>
+}
+```
+
+## Function Signature
+
+```ts
+type RuntimeContext = {
+  request: {
+    params: Record<string, string>;
+    pathname: string;
+    query: Record<string, string>;
+    headers: IncomingHttpHeaders;
+    cookie: string;
+  };
+  store: ReduckStore;
+}
+
+function useRuntimeContext(): RuntimeContext;
+```
+
+
+### Return Value
+
+- `request`: additional information in the request context.
+  - `params`: dynamic parameters in the request path.
+  - `pathname`: the pathname of the request.
+  - `query`: the query of the request.
+  - `headers`: the header info of the request.
+  - `cookie`: the cookie of the request.
+- `store`: when the runtime.state is enabled, this value is the reduck global `store`.
+
+## Example
+
+```tsx
+import { useRuntimeContext } from '@modern-js/runtime';
+import { fooModel } from '@/common/models';
+
+function App() {
+  const { store } = useRuntimeContext();
+
+  const [state, actions] = store.use(fooModel);
+
+  return <div>state: {state}</div>
+}
+```

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/default-alias.md

@@ -0,0 +1,25 @@
+---
+sidebar_position: 1
+title: Default Alias
+---
+
+Modern.js recommend referring to the source code by alias, which contains 3 default aliases:
+- `@/`: the file under the project root directory `src/* `.
+- `@api/`: the file under the `api/*` in the project root directory (you need to enable the BFF first).
+- `@shared/`: the file under the project root directory `shared/* `.
+
+:::tip
+In addition, developers can customize aliases in modern.config.js, see [Aliases](/docs/configure/app/source/alias) for detail.
+:::
+
+
+## Example
+
+The following example shows how to reference a function by default alias.
+
+```tsx
+import { hello } from '@/common/utils';
+
+hello();
+```
+A reference to `@/common/utils` is equal to a reference to `src/common/utils`.

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/env.md

@@ -0,0 +1,72 @@
+---
+sidebar_position: 1
+title: Environment Variables
+---
+
+Modern.js has built-in support for environment variables, including built-in environment variables and custom environment variables.
+
+## Built-in Environment Variables
+
+### NODE_ENV
+
+A **read-only** environment variable, whose have different values under different execution commands:
+
+- `production`: default value when executing `modern build`、`modern preview` commands.
+- `test`: default value when executing `modern test` commands.
+- `development`: default value when executing `modern dev` commands, also the default value in all other cases.
+
+### MODERN_ENV
+
+Used to set the current execution environment.In addition to the values corresponding to the above NODE_ENV, custom environment names are supported here, such as `staging`, `boe`.
+
+Modern.js loads the environment variables values set in the `.env.{process.env.MODERN_ENV}` file for that environment variable.
+
+When you need to use different configurations through the environment name, you can define environment variables in the `.env` file of the corresponding environment name.
+
+MODERN_ENV priority is higher than NODE_ENV.
+
+## Custom Environment Variables
+
+Modern.js support custom environment variables, which starting with MODERN_ can be used directly in the code.
+
+If you need to automatically use environment variables with any name, you need to declare them in the ['source.define'](/docs/configure/app/source/define) configuration.
+
+## Define Environment Variables
+
+Environment variables are specified in both `shell` and `.env` files.
+
+### Specify Via Shell
+
+Add custom environment variables before the command:
+
+```shell
+REACT_APP_FOO=123 BAR=456 pnpm run dev
+```
+
+### Specify Via File
+
+Create a `.env` file in the project with custom environment variables:
+
+```env
+REACT_APP_FOO=123
+BAR=456
+```
+
+`.env` files support suffixes NODE_ENV or MODERN_ENV defined environment names, such as `env.development`. Modern.js reads the env file based on the environment name variable value.
+
+## Using Environment Variables
+
+### Use In JS
+
+Get environment variables directly with `process.env.*`.
+
+```js
+console.log(process.env.NODE_ENV);
+// "development"
+```
+
+### Use In HTML
+
+```html title="config/html/head.ejs"
+<meta name="env" content="<%=process.env.NODE_ENV %>" />
+```

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/index.md

@@ -0,0 +1,12 @@
+---
+type: ref
+---
+
+# Runtime
+
+This section covers all APIs using `@modern-js/runtime`.
+
+
+
+
+

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/model/Provider.md

@@ -0,0 +1,35 @@
+---
+sidebar_position: 8
+title: Provider
+---
+
+import ReduckTip from '@site-docs/components/reduck-tip.md'
+
+<ReduckTip />
+
+`Provider` is a component that injects Reduck's Store into the application's component tree, making the Model accessible to components inside the component tree. Normally, `Provider` is defined at the top level of the component tree.
+
+## Function Signature
+
+```ts
+interface ProviderProps {
+  store?: ReduckStore;
+  config?: AppConfig;
+}
+```
+
+### Input
+
+- store: the Store object created by [`createStore`](./create-store.md).
+- config: this config to create Reduck Store, same as `config` param in [`createApp`](./create-app.md).
+
+## Example
+
+```tsx title="App entry file"
+ReactDOM.render(
+  <Provider>
+    <App />
+  </Provider>,
+  document.getElementById('root'),
+);
+```

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/model/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Model API",
+  "position": 6
+}

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/model/auto-actions.md

@@ -0,0 +1,120 @@
+---
+sidebar_position: 6
+title: Auto actions
+---
+
+import ReduckTip from '@site-docs/components/reduck-tip.md'
+
+<ReduckTip />
+
+Reduck can automatically generate Actions according to the type of State，for easy to modify State.
+
+:::tip
+can use [`runtime.state.autoActions`](/docs/configure/app/runtime/state#autoactions) close auto actions feature.
+:::
+
+## Example
+
+### Basic Data Type
+
+State type in `string`、`number`、`boolean`、`null`，generate `setState` Action。
+
+```tsx title="example"
+const fooModel = model('foo').define({
+  state: 1,
+});
+
+function App() {
+  const [state, actions] = useModel(fooModel);
+
+  return (
+    <div>
+      <div>State: {state}</div>
+      <button
+        type="button"
+        onClick={() => {
+          // call auto generate setState Action
+          actions.setState(state + 1);
+        }}
+      >
+        add
+      </button>
+    </div>
+  );
+}
+```
+
+### Array
+
+State type is Array，generate the following Actions:
+
+- `push`: adds one or more elements to the end of the array.
+- `pop`: removes the last element from the array.
+- `shift`: removes the first element from the array.
+- `unshift`: adds one or more elements to the beginning of the array.
+  - usage: `arr.unshift(element1, ..., elementN)`
+  - `elementN`: the element or elements to add to the beginning of the array.
+- `filter`: filter element.
+<!-- 语义与原生方法不同，待修改 API -->
+- `concat`: concat array.
+<!-- 语义与原生方法不同，待修改 API -->
+- `splice`: modify the array by deleting or replacing existing elements or adding new elements in place, and return the modified array(Note that it is different from the native `splice` return value).
+  - usage: `splice(start[, deleteCount[, item1[, item2[, ...]]]])`
+  - `start`: specifies the start position of the modification(counting from 0).
+  - `deleteCount`: an integer representing the number of array elements to remove.
+  - `item, item2, ...`: The elements to add to the array, starting at the start position. If not specified, `splice` will only delete array elements.
+
+```tsx title="example"
+const fooModel = model('foo').define({
+  state: [1, 2, 3],
+});
+
+function App() {
+  const [state, actions] = useModel(fooModel);
+
+  useEffect(() => {
+    actions.push(4);
+    actions.pop();
+    actions.shift(0);
+    actions.unshift();
+    actions.filter(val => val <= 2);
+    actions.splice(0, 1, 1, 2);
+  }, []);
+
+  return (
+    <div>
+      <div>State: {state}</div>
+    </div>
+  );
+}
+```
+
+### PlainObject
+
+State type is PlainObject，base on the names contained in State，generate `set${key}`(Camel-Case) Actions。
+
+```tsx title="example"
+const fooModel = model('foo').define({
+  state: {
+    a: 1,
+    b: { value: 1 },
+    c: 'c',
+  },
+});
+
+function App() {
+  const [state, actions] = useModel(fooModel);
+
+  useEffect(() => {
+    actions.setA(2);
+    actions.setB({ value: 2 });
+    actions.setC('d');
+  }, []);
+
+  return (
+    <div>
+      <div>State: {state}</div>
+    </div>
+  );
+}
+```

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/model/connect.md

@@ -0,0 +1,140 @@
+---
+sidebar_position: 5
+title: connect
+---
+
+import ReduckTip from '@site-docs/components/reduck-tip.md'
+
+<ReduckTip />
+
+:::tip
+The original type of Reduck is complex. The following type definition shows the simplified type information. For the original type, see [**connect**](https://github.com/modern-js-dev/reduck/blob/main/packages/react/src/connect.ts)。
+:::
+
+`Connect` is the same as `useModel` and is the corresponding HOC-style API. It is recommended to use the Hook-style `useModel` first.
+
+
+## Function Signature
+
+```ts
+type SelectStateToProps = (...modelStates: State[], ownProps? :any) => PlainObject;
+type SelectActionsToProps = (...modelActions: Actions[], ownProps? :any) => PlainObject;
+
+function connect(models: Model, options?: ConnectOptions);
+function connect(
+  models: [...Model[], SelectStateToProps?, SelectActionsToProps?],
+  options?: ConnectOptions,
+);
+```
+
+
+### Input
+
+- `models`: passed one or more Models. When `models` is an array type parameter, the last two params can be a function for filtering State (`SelectStateToProps` type) and a function for filtering Actions (`SelectActionsToProps` type).
+
+  - `SelectStateToProps`: `modelStates` is an array of the State of the passed Model object, `ownProps` is the props received by current component. The data returned by `SelectStateToProps` is passed to the props of the component. When the `SelectStateToProps` parameter is not passed in `models`, the States of all Models are merged and passed to the props of the component.
+
+  - `SelectActionsToProps`: `modelActions` is an array of the Action of the passed Model object, `ownProps` is the props received by current component. returned by `SelectActionsToProps` is passed to the props of the component. When the `SelectActionsToProps` parameter is not passed in `models`, the Action of all Models are merged and passed to the props of the component.
+
+- `options`: Optional parameter for auxiliary configuration. Currently supports setting `forwardRef`, which is used to control whether to forward the `ref` of the component. The default value is `false`, which means that the `ref` is not forwarded. Set to `{ forwardRef: true }`, which means to forward `ref`.
+
+
+### Return Type
+
+Returns a HOC: receives an component, returns a component with extra State and Actions injected on `props`.
+
+## Example
+
+### Basic
+
+```ts
+const modelA = model('modelA').define({
+  state: {
+    a: 1,
+  },
+  actions: {
+    incA(state) {
+      return {
+        ...state,
+        a: state.a + 1,
+      };
+    },
+  },
+});
+
+const modelB = model('modelB').define({
+  state: {
+    b: 10,
+  },
+  actions: {
+    incB(state) {
+      return {
+        ...state,
+        b: state.b + 1,
+      };
+    },
+  },
+});
+
+function Test(props) {
+  props.incA(); // call modelA 的 action
+  props.incB(); // call modelB 的 action
+
+  props.a; // get modelA 的 state: a
+  props.b; // get modelB 的 state: b
+}
+
+export default connect([modelA, modelB])(Test);
+```
+
+### Select State & Actions
+
+```ts
+function Test(props) {
+  props.incAll();
+  props.c;
+}
+
+const stateSelector = (stateA, stateB) => ({
+  ...stateA,
+  ...stateB,
+  c: stateA.a + stateA.b,
+});
+const actionsSelector = (actionsA, actionsB) => ({
+  ...actionsA,
+  ...actionsB,
+  incAll: () => {
+    actionsA.incA();
+    actionsB.incB();
+  },
+});
+
+export default connect([modelA, modelB, stateSelector, actionsSelector])(Test);
+```
+
+### Forwarding Ref
+
+```ts
+import { useRef, forwardRef } from 'react';
+
+function Test(props, ref) {
+  const { a, b } = props;
+
+  return (
+    <div ref={ref}>
+      <span>{a}</span>
+      <span>{b}</span>
+    </div>
+  );
+}
+
+const TestWrapper = connect([modelA, modelB], { forwardRef: true })(
+  forwardRef(Test),
+);
+
+function App() {
+  const testRef = useRef();
+
+  return <TestWrapper ref={testRef} />;
+}
+```