@modern-js/main-doc 2.1.0 → 2.2.0

package/en/apis/app/runtime/core/create-app.mdx

@@ -0,0 +1,45 @@
+---
+title: createApp
+---
+# createApp
+
+Used to create custom entries, custom runtime plugins. This API is only required when using [Custom App](/guides/concept/entries#自定义-app).
+
+## Usage
+
+```ts
+import { createApp } from '@modern-js/runtime';
+```
+
+## Function Signature
+
+```ts
+import type { Plugin } from '@modern-js/runtime';
+
+function createApp(options: { plugins: Plugin[] }): React.ComponentType<any>;
+```
+
+### Input
+
+- `options`: optional configuration.
+  - `plugins`: custom plugin extensions.
+
+## Example
+
+### Create Custom Entry
+
+For details, see [`bootstrap`](./bootstrap.md)。
+
+### Custom Plugins
+
+```ts
+import { createApp } from '@modern-js/runtime';
+
+function App() {
+  return <div>app</div>;
+}
+
+export default createApp({
+  plugins: [customPlugin()],
+})(App);
+```

package/en/apis/app/runtime/core/use-loader.mdx

@@ -0,0 +1,85 @@
+---
+title: useLoader
+---
+# 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](/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](/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/apis/app/runtime/core/use-module-apps.mdx

@@ -0,0 +1,140 @@
+---
+title: useModuleApps
+---
+# useModuleApps
+
+Returns the React components of all micro-front-end sub-applications for freely controlled routing.
+
+## Usage
+
+```tsx
+import { useModuleApps } from '@modern-js/plugin-garfish/runtime';
+```
+
+## 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.
+
+import EnableMicroFrontend from "@site-docs-en/components/enable-micro-frontend";
+
+<EnableMicroFrontend />
+
+```tsx title=App.tsx
+function App() {
+  const { Home, Contact } = useModuleApps();
+
+  return (
+    <div>
+      Master APP
+      <Route exact path="/home">
+        <Home />
+      </Route>
+      <Route exact path="/home">
+        <Contact />
+      </Route>
+    </div>
+  );
+}
+
+defineConfig(App, {
+  masterApp: {
+    apps: [
+      {
+        // name 区分大小写，name 提供的是什么 useModuleApps 返回的就是什么
+        name: 'Home',
+        entry: 'http://127.0.0.1:8081/',
+      },
+      {
+        name: 'Contact',
+        entry: 'http://localhost:8082',
+      },
+    ],
+  },
+});
+```
+
+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.
+
+### Centralized Routing
+
+**Centralized Routing** is a way to centrally configure the activation routes of sub-applications. Add `activeWhen` config to enable **Centralized Routing**。
+
+import MicroRuntimeConfig from "@site-docs-en/components/micro-runtime-config";
+
+<MicroRuntimeConfig />
+
+Then use the `useModuleApp` method to get the `MApp` component in the main application, and render the `MApp` in the main application.
+
+```tsx title=main: App.tsx
+import { useModuleApp } from '@modern-js/plugin-runtime';
+
+function App() {
+  const { MApp } = useModuleApps();
+
+  return (
+    <div>
+      <MApp />
+    </div>
+  );
+}
+
+defineConfig(App, {
+  masterApp: {
+    apps: [
+      {
+        // name is case sensitive, what name provides is what useModuleApps returns
+        name: 'Dashboard',
+        activeWhen: '/dashboard',
+        entry: 'http://127.0.0.1:8081/',
+      },
+      {
+        name: 'TableList',
+        activeWhen: '/table',
+        entry: 'http://localhost:8082',
+      },
+    ],
+  },
+});
+```
+
+After starting the application in this way, accessing the `/dashboard` route will render the `Dashboard`, and accessing the `/table` route will render the `TableList`.
+
+## 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/apis/app/runtime/core/use-runtime-context.mdx

@@ -0,0 +1,59 @@
+---
+title: useRuntimeContext
+---
+# 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/apis/app/runtime/model/Provider.mdx

@@ -0,0 +1,36 @@
+---
+sidebar_position: 8
+title: Provider
+---
+# Provider
+
+import ReduckTip from "@site-docs-en/components/reduck-tip"
+
+<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/apis/app/runtime/model/auto-actions.mdx

@@ -0,0 +1,122 @@
+---
+sidebar_position: 6
+title: Auto actions
+---
+# Auto actions
+
+import ReduckTip from "@site-docs-en/components/reduck-tip"
+
+<ReduckTip />
+
+Reduck can automatically generate Actions according to the type of State，for easy to modify State.
+
+:::tip
+can use [`runtime.state.autoActions`](/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/apis/app/runtime/model/connect.mdx

@@ -0,0 +1,145 @@
+---
+sidebar_position: 5
+title: connect
+---
+# connect
+
+import ReduckTip from "@site-docs-en/components/reduck-tip"
+
+<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} />;
+}
+```