@modern-js/main-doc 2.7.0 → 2.9.0

package/docs/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/web-infra-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's action
+  props.incB(); // call modelB's action
+
+  props.a; // get modelA's state: a
+  props.b; // get modelB's 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} />;
+}
+```

package/docs/en/apis/app/runtime/model/model_.mdx

@@ -0,0 +1,199 @@
+---
+sidebar_position: 1
+title: model
+---
+# model
+
+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 [**model**](https://github.com/web-infra-dev/reduck/blob/main/packages/store/src/model/model.ts).
+
+:::
+
+## model
+
+Create a Model for managing application state.
+
+`function model(name: string): { define: function }`
+
+- name: `string`, the unique id of the Model created.
+
+```ts title="example"
+model('foo');
+```
+
+## define
+
+Used to define the detailed structure of the Model, supporting passing in an object type or function type parameter.
+
+### Object Type
+
+`function define(modelDesc: ModelDesc): Model;`
+
+- modelDesc: `ModelDesc`，definition of Model structure，includes `state`、`computed`、`actions`、`effects` etc. props.
+
+```tsx title="example"
+const fooModel = model('foo').define({
+  state: 'foo',
+  computed: {
+    cFoo: state => `c${state}`,
+  },
+  actions: {
+    setState: (state, value) => {
+      return value;
+    },
+  },
+  effects: {
+    loadState: async () => {
+      // get state from remote
+    },
+  },
+});
+```
+
+### Function Type
+
+`function define((context: Context, utils: Utils) => ModelDesc): Model;`
+
+- `context`: Reduck Context, can get underlying `store` object. `store` support all Redux Store [API](https://redux.js.org/api/store), also mounts the `use` method for consuming the Model, and the `unmount` method for unmounting the Model.
+- utils: commonly used tool like `use`、`onMount`. `use` is the same as `store.use`，`onMount` is the hook function after the Model is mounted.
+
+{/* TODO: @anchao 调整类型  */}
+```ts
+interface Utils {
+  use: UseModel;
+  onMount: OnMountHook;
+}
+
+interface Context {
+  store: ReduxStore & {
+    use: UseModel;
+    unmount: (model: Model) => void;
+  };
+}
+```
+
+For example, through `use`, you can get the `state` and `actions` of the Model itself and other Models.
+
+```tsx title="example"
+const fooModel = model('foo').define(() => {
+  return {
+    state: 'foo',
+    actions: {
+      setState: (state, value) => {
+        return value;
+      },
+    },
+  };
+});
+
+const barModel = model('bar').define((_, { use }) => {
+  return {
+    state: 'bar',
+    effects: {
+      syncFoo() {
+        const [state, actions] = use(fooModel);
+        actions.setState(state);
+      },
+    },
+  };
+});
+```
+
+### Input
+
+#### ModelDesc.state
+
+Define the state of the Model. Technically, any type of **State** is supported, but in practice it is recommended to use a JSON serializable type.
+
+```ts
+interface ModelDesc {
+  state: any;
+}
+```
+
+#### ModelDesc.actions
+
+Define the Actions of the Model. The function type of Actions is:
+
+```ts
+interface ModelDesc {
+  actions: {
+    [actionKey: string]: (state: State, payload: any) => State | void;
+  };
+}
+```
+
+Reduck internally integrates [immer](https://github.com/immerjs/immer), which can directly return the original `state`. When the Action has no explicit return value, Reduck internally returns a modified new State object.
+
+#### ModelDesc.computed
+
+Defines the derived state of the Model. The definition of derived state supports two types:
+
+1. Depends only on the state of the Model itself
+
+```ts
+interface ModelDesc {
+  computed: {
+    [computedKey: string]: (state: State) => any;
+  };
+}
+```
+
+2. Depends on the state of other Models
+
+```ts
+interface ModelDesc {
+  computed: {
+    [computedKey: string]: [
+      ...models: Model[],
+      (state: State, ...args: ModelState[]) => any,
+    ];
+  };
+}
+```
+
+```ts title="example"
+const fooModel = model('foo').define({
+  state: 'foo',
+});
+
+const barModel = model('bar').define({
+  state: 'bar',
+  computed: {
+    combineFoo: [fooModel, (state, fooState) => state + fooState],
+  },
+});
+```
+
+#### ModelDesc.effects
+
+Defines the Effects of the Model. The function types defined in Effects are:
+
+```ts
+interface ModelDesc {
+  effects: {
+    [effectKey: string]: (...args: any[]) => any;
+  };
+}
+```
+
+```ts title="example"
+const fooModel = model('foo').define((context, { use }) => ({
+  state: 'foo',
+  effects: {
+    persist() {
+      const [state] = use(fooModel);
+      localStorage.setItem('state', state);
+    },
+  },
+}));
+```
+
+:::info More
+[Define Model](/guides/topic-detail/model/define-model).
+
+:::

package/docs/en/apis/app/runtime/model/use-model.mdx

@@ -0,0 +1,89 @@
+---
+sidebar_position: 2
+title: useModel
+---
+# useModel
+
+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 [**model**](https://github.com/web-infra-dev/reduck/blob/main/packages/store/src/model/model.ts).
+
+:::
+
+## Function Signature
+
+```ts
+function useModel(
+  models: Models[],
+  stateSelector?: StateSelector,
+  actionSelector?: ActionSelector,
+): [state, actions, subscribe];
+function useModel(
+  ...models: Models[],
+  stateSelector?: (...args: State[]) => any,
+  actionSelector?: (...args: Actions[]) => any,
+): [state, actions, subscribe];
+```
+
+### Input
+
+- models: Array of Model objects, which can be passed in as an array type parameter, or all Models can be passed in as parameters one by one.
+- stateSelector: Optional parameters, used to filter State calculations. The first n parameters are the States corresponding to n Models, and the returned data is used as the first element of the `useModel` return value array.
+- actionSelector: Optional parameters, used to filter Action calculations. The first n parameters are the States corresponding to n Models, and the returned data is used as the second element of the `useModel` return value array.
+
+### Return Value
+
+Returns an array with each value:
+
+- state: return value of `stateSelector`. if there is no `stateSelector`，will combine all incoming Model States(including derived states) and return them. If there is an attribute of the same name in the State of different Models, the following State will override the previous State. when `state` changes，the component call `useModel` will re-render.
+- actions: return value of `actionSelector`. if there is no `actionSelector`，will combine all incoming Model Action(including Effect) and return them. If there is an attribute of the same name in the Action of different Models, the following Action will override the previous Action.
+- subscribe: A function that subscribes to State changes. This function is called when the State of any Model passed in changes.
+
+## Example
+
+### Basic
+
+```tsx
+import todoModel from 'models/todo';
+import filterModel from 'models/filter';
+
+function Test(props) {
+  const [state, actions] = useModel([todoModel, filterModel]);
+  actions.add(); // call todoModel add action
+  actions.setVisibleStatus(); // call filterModel filterModel action
+
+  state.items; // get todoModel state items
+  state.visibleStatus; // get filterModel state visibleStatus
+}
+```
+
+### Selector Usage
+
+```js
+function Test(props) {
+  const [state, actions] = useModel(
+    [todoModel, filterModel],
+    (todoState, filterState) => ({
+      items: todoState.items,
+      visibleStatus: `${props.prefix}-${filterState.visibleStatus}`,
+    }),
+    (todoActions, filterActions) => ({
+      ...todoActions,
+      ...filterActions,
+    }),
+  );
+  actions.add(); // call todoModel add action
+  actions.setVisibleStatus(); // call filterModel filterModel action
+
+  state.items; // get todoModel state items
+  state.visibleStatus; // get filterModel state visibleStatus
+}
+```
+
+:::info More
+[use Model](/guides/topic-detail/model/use-model).
+
+:::

package/docs/en/apis/app/runtime/router/router.mdx

@@ -0,0 +1,262 @@
+---
+title: router
+sidebar_position: 1
+---
+# router
+
+:::info
+The router solution based on [react-router 6](https://reactrouter.com/).
+
+:::
+
+## hooks
+
+### useNavigate
+
+```ts
+declare function useNavigate(): NavigateFunction;
+
+interface NavigateFunction {
+  (
+    to: To,
+    options?: {
+      replace?: boolean;
+      state?: any;
+      relative?: RelativeRoutingType;
+    },
+  ): void;
+  (delta: number): void;
+}
+```
+
+The `useNavigate` hook returns a function that lets you navigate programmatically.
+
+```tsx
+import { useNavigate } from '@modern-js/runtime/router';
+
+export function HomeButton() {
+  let navigate = useNavigate();
+
+  function handleClick() {
+    navigate('/home');
+  }
+
+  return (
+    <button type="button" onClick={handleClick}>
+      Go home
+    </button>
+  );
+}
+```
+
+### useLocation
+
+```ts
+declare function useLocation(): Location;
+
+interface Location extends Path {
+  state: unknown;
+  key: Key;
+}
+```
+
+The `useLocation` hook returns the current [location](https://reactrouter.com/web/api/location) object. A new location object would be returned whenever the current location changes.
+
+```ts
+import { useLocation } from "@modern-js/runtime/router";
+
+function usePageViews() {
+  let location = useLocation();
+  React.useEffect(() => {
+    ga.send(["pageview", location.pathname]);
+  }, [location]);
+}
+
+function App() {
+  usePageViews();
+  return (
+    //...
+  );
+}
+```
+
+### useParams
+
+```ts
+declare function useParams<K extends string = string>(): Readonly<Params<K>>;
+```
+
+The `useParams` hook returns an object of key/value pairs of the dynamic params from the current URL that were matched by the `<Route path>`.
+
+```tsx
+import { Routes, Route, useParams } from '@modern-js/runtime/router';
+
+function BlogPost() {
+  const { slug } = useParams();
+  return <div>Now showing post {slug}</div>;
+}
+
+function App() {
+  return (
+    <Routes>
+      <Route path="/" element={<div>home</div>} />
+      <Route path="/blog/:slug" element={<BlogPost />} />
+    </Routes>
+  );
+}
+```
+
+## Components
+
+### Link
+
+```ts
+declare function Link(props: LinkProps): React.ReactElement;
+
+interface LinkProps
+  extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
+  replace?: boolean;
+  state?: any;
+  to: To;
+  reloadDocument?: boolean;
+}
+
+type To = string | Partial<Path>;
+```
+
+A `<Link>` is an element that lets the user navigate to another page by clicking or tapping on it.
+
+```ts
+<Link to="/about">About</Link>
+```
+
+### NavLink
+
+```ts
+declare function NavLink(props: NavLinkProps): React.ReactElement;
+
+interface NavLinkProps
+  extends Omit<LinkProps, 'className' | 'style' | 'children'> {
+  caseSensitive?: boolean;
+  children?:
+    | React.ReactNode
+    | ((props: { isActive: boolean }) => React.ReactNode);
+  className?: string | ((props: { isActive: boolean }) => string | undefined);
+  end?: boolean;
+  style?:
+    | React.CSSProperties
+    | ((props: { isActive: boolean }) => React.CSSProperties);
+}
+```
+
+A `<NavLink>` is a special kind of `<Link>` that knows whether or not it is "active".
+
+### Outlet
+
+```ts
+interface OutletProps {
+  context?: unknown;
+}
+declare function Outlet(props: OutletProps): React.ReactElement | null;
+```
+
+An `<Outlet>` should be used in parent route elements to render their child route elements. This allows nested UI to show up when child routes are rendered.
+
+```tsx
+function Dashboard() {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+
+      {/* This element will render either <DashboardMessages> when the URL is
+          "/messages", <DashboardTasks> at "/tasks", or null if it is "/"
+      */}
+      <Outlet />
+    </div>
+  );
+}
+
+function App() {
+  return (
+    <Routes>
+      <Route path="/" element={<Dashboard />}>
+        <Route path="messages" element={<DashboardMessages />} />
+        <Route path="tasks" element={<DashboardTasks />} />
+      </Route>
+    </Routes>
+  );
+}
+```
+
+### Route
+
+```ts
+interface RouteObject {
+  path?: string;
+  index?: boolean;
+  children?: React.ReactNode;
+  caseSensitive?: boolean;
+  id?: string;
+  loader?: LoaderFunction;
+  action?: ActionFunction;
+  element?: React.ReactNode | null;
+  errorElement?: React.ReactNode | null;
+  handle?: RouteObject['handle'];
+  shouldRevalidate?: ShouldRevalidateFunction;
+}
+```
+
+`Route` represents the route information. A `Route` object couples URL segments to components, data loading and data mutations.
+
+`Route` can be used as a plain object, passing to the router creation functions:
+
+```ts
+const router = createBrowserRouter([
+  {
+    // it renders this element
+    element: <Team />,
+
+    // when the URL matches this segment
+    path: 'teams/:teamId',
+
+    // with this data loaded before rendering
+    loader: async ({ request, params }) => {
+      return fetch(`/fake/api/teams/${params.teamId}.json`, {
+        signal: request.signal,
+      });
+    },
+
+    // performing this mutation when data is submitted to it
+    action: async ({ request }) => {
+      return updateFakeTeam(await request.formData());
+    },
+
+    // and renders this element in case something went wrong
+    errorElement: <ErrorBoundary />,
+  },
+]);
+```
+
+You can also declare your routes with JSX and `createRoutesFromElements`, the props to the element are identical to the properties of the route objects:
+
+```ts
+const router = createBrowserRouter(
+  createRoutesFromElements(
+    <Route
+      element={<Team />}
+      path="teams/:teamId"
+      loader={async ({ params }) => {
+        return fetch(`/fake/api/teams/${params.teamId}.json`);
+      }}
+      action={async ({ request }) => {
+        return updateFakeTeam(await request.formData());
+      }}
+      errorElement={<ErrorBoundary />}
+    />,
+  ),
+);
+```
+
+## More
+
+You can access to [React Router](https://reactrouter.com/) to get the full API information.