docs: intro & cli

Author: elliothux

README.md

@@ -1,24 +1,42 @@
-# Vize: 现代化的 Web 可视化搭建引擎
+# Vize：代化的 Web 可视化编排引擎
 
-文档: [https://vize-team.github.io/](https://vize-team.github.io/)
+Github: [https://github.com/vize-team/vize](https://github.com/vize-team/vize)
 
 ![stars] ![forks] ![issues] ![pr] ![closed-pr]
 
-## ⚠️ 警告 Warning
-
-此项目仍处于开发状态，某些功能可能不稳定，部分 API 也可能会有变动。
-
-This is an **experimental** project and is still in development. BUGs may exist. APIs and features may change.
-
-## ✨ 特性 Features
+## ✨ 特性
 
+- 丰富的物料抽象粒度
+- 强大的可配置事件系统
 - 友好、便捷的可视化编辑体验
+- 支持物料间联动
+- 友好、一致的物料 API
 - 完全所见即所得
-- 丰富的物料抽象粒度
-- 支持物料间联动，强大的可配置事件系统
+- 丰富的拓展接口
 - 物料与系统完全解耦
 - 完备的开发工具链支持
-- 便捷的接入方式
+- 开箱即用的接入方式
+- ...
+
+## 🤟 体验
+
+体验站点：[vize.cool](https://vize.cool)
+
+## 🛠 部署
+
+参考：[部署服务](/deploy/intro.html)
+
+## 👨‍💻 开发者
+
+核心架构 & 开发：**[Aedron@github](https://github.com/Aedron)**
+
+贡献者：
+
+- [Copyes@github](https://github.com/Copyes)
+
+## 🙌 帮助和交流
+
+<img src="./packages/doc/src/welcome/wechat.jpg" class="zoom" alt="Preview" style="width:128px;height:auto;border-radius:3px;margin-top:14px;"/>
 
 ## 📦 核心包 Core Packages
 
@@ -61,3 +79,9 @@ This is an **experimental** project and is still in development. BUGs may exist.
 [issues]: https://img.shields.io/github/issues/vize-team/vize?style=social&label=Issues&style=plastic
 [pr]: https://img.shields.io/github/issues-pr/vize-team/vize?style=social&label=PullRequests&style=plastic
 [closed-pr]: https://img.shields.io/github/issues-pr-closed/vize-team/vize?style=social&label=PullRequests&style=plastic
+
+## ⚠️ 警告 Warning
+
+此项目仍处于开发状态，某些功能可能不稳定，部分 API 也可能会有变动。
+
+This is an **experimental** project and is still in development. BUGs may exist. APIs and features may change.

packages/doc/src/.vuepress/config.js

@@ -2,7 +2,7 @@ const { sidebar } = require('./sidebar');
 
 module.exports = {
   title: 'Vize',
-  description: 'Vize: 现代化的可视化搭建引擎',
+  description: 'Vize: 现代化的可视化编排引擎',
   repo: 'https://github.com/vize-team/vize',
   serviceWorker: true,
   displayAllHeaders: true,
@@ -28,10 +28,18 @@ module.exports = {
         text: '文档',
         link: '/welcome/intro',
       },
+      {
+        text: 'Types',
+        link: 'https://vize-team.github.io/types/modules.html',
+      },
       {
         text: 'Github',
         link: 'https://github.com/vize-team/vize',
       },
+      {
+        text: 'Discussions',
+        link: 'https://github.com/vize-team/vize/discussions',
+      },
     ],
     sidebarDepth: 2,
     sidebar,

packages/doc/src/.vuepress/sidebar.js

@@ -1,21 +1,21 @@
 const sidebar = [
   {
-    title: '欢迎',
+    title: '👏 欢迎',
     collapsable: true,
     children: ['/welcome/intro', '/welcome/packages'],
   },
   {
-    title: '快速上手',
+    title: '⚡️ 快速上手',
     collapsable: true,
     children: ['/start/ready', '/start/component', '/start/plugin', '/start/action', '/start/container'],
   },
   {
-    title: '物料开发',
+    title: '🌟 物料开发',
     collapsable: true,
     children: ['/dev/materials', '/dev/component', '/dev/plugin', '/dev/action', '/dev/container'],
   },
   {
-    title: '事件系统',
+    title: '⚛️ 事件系统',
     collapsable: true,
     children: [
       '/events/intro',
@@ -27,28 +27,28 @@ const sidebar = [
     ],
   },
   {
-    title: '表单',
+    title: '✉️ 表单',
     collapsable: true,
     children: ['/form/intro', '/form/jsonSchema', '/form/registryField', '/form/dynamicForm'],
   },
   {
-    title: '样式',
+    title: '💅 样式',
     collapsable: true,
     children: ['/style/styleGroup', '/style/styleInject', '/style/fixed'],
   },
   {
-    title: '进阶',
+    title: '⚙️ 进阶',
     collapsable: true,
     children: [
       '/advanced/meta',
       '/advanced/containerComponent',
       '/advanced/routerController.md',
-      '/advanced/hot-area-component.md',
+      '/advanced/hotAreaComponent.md',
       '/advanced/dsl.md',
     ],
   },
   {
-    title: '部署',
+    title: '🛠 部署',
     collapsable: true,
     children: [
       '/deploy/intro',
@@ -60,8 +60,9 @@ const sidebar = [
     ],
   },
   {
-    title: 'CLI',
+    title: '🪄 CLI',
     collapsable: true,
+    children: ['/cli/config', '/cli/commands'],
   },
 ];
 

packages/doc/src/README.md

@@ -5,23 +5,23 @@ actionText: 上手 →
 actionLink: /welcome/intro
 
 features:
-  - title: 丰富完备的物料抽象
-    details: 组件、插件、动作、页面容器等多种粒度的物料抽象，具备无限的拓展能力
-  - title: 易用的可视化编辑
+  - title: 🌟 丰富完备的物料抽象
+    details: 组件、插件、事件、动作、页面容器等多种粒度的物料抽象，具备无限的拓展能力
+  - title: 🤟 易用的可视化编辑
     details: 拖拽式编排、流式/自由布局能力、可视化热区、容器组件嵌套等能力，让复杂的编排功能也变得友好且易用
-  - title: 强大的逻辑配置能力
-    details: 强大的事件配置系统，让物料具备真正的联动能力，即使复杂地逻辑与交互也不在话下
-  - title: 真 · 所见即所得
-    details: 高性能地实时预览渲染引擎，带来真正所见即做的编辑体验
-  - title: 便捷的接入方式
-    details: 为所有的单元能力提供 NPM Packages，超低成本接入
-  - title: 完善的工具链支持
-    details: CLI 提供完善的模板创建、开发、调试、发布等功能
+  - title: ⚛️ 强大的逻辑编排能力
+    details: 强大的可视化事件配置系统，让物料具备真正的联动能力，即使复杂的逻辑与交互也不在话下
+  - title: 👁 真 · 所见即所得
+    details: 高性能的实时预览渲染引擎，带来真正所见即做的编辑体验
+  - title: 🛠 强大的拓展能力
+    details: 为所有的单元能力提供独立 Packages，开箱即用，超低成本接入，同时提供丰富的拓展接口
+  - title: 🪄 完善的工具链支持
+    details: CLI 提供完善的模板创建、开发、调试、构建、发布等功能
 
 footer: Developing with ❤️ by Aedron@github
 meta:
   - name: description
-    content: 现代化的 Web 可视化搭建引擎
+    content: 现代化的 Web 可视化编排引擎
   - name: keywords
     content: home homepage homepages
 ---

…s/doc/src/advanced/hot-area-component.md …ges/doc/src/advanced/hotAreaComponent.mdpackages/doc/src/advanced/hot-area-component.md renamed to packages/doc/src/advanced/hotAreaComponent.md packages/doc/src/advanced/hot-area-component.md renamed to packages/doc/src/advanced/hotAreaComponent.md

@@ -12,50 +12,134 @@ meta:
 
 Vize 支持注册自定义路由，来控制子页面的加载和渲染方式。
 
-## 1. 实现路由
+## 1. 实现 RouterController
 
-在页面容器目录下新建 `Router.tsx`：
+在页面容器目录下新建 `Router.tsx` 和 `PageLoader.tsx`：
 
-```tsx {8,9,13-17,26-29}
+<CodeSwitcher :languages="{r:'Router.tsx',p:'PageLoader.tsx'}">
+
+<template v-slot:r>
+
+```tsx
 import * as React from 'react';
-import { useState, ComponentType, useEffect } from 'react';
-import { RouterProps, PageRouter } from '@vize/types';
+import { useEffect, useMemo, useState } from 'react';
+import { Maybe, PageInstance, PageRouter, RouterProps } from '@vize/types';
+import { PageLoader } from './pagerLoader';
 
-export function MyRouter({ pages, dynamicPageImports, SharedComponentInstances }: RouterProps) {
-  const [Page, setPageRender] = useState<ComponentType | null>(null);
+export function Router({
+  setCurrentPageInstance,
+  setRouter,
+  pages,
+  pageImports,
+  sharedComponentInstances,
+  ComponentsRender,
+  PageRender,
+}: RouterProps) {
+  // 当前页面的 key
   const [currentPage, setCurrentPage] = useState(pages[0].key);
-  // 声明 router
+  // 当前页面的实例（动态引入）
+  const [pageInstance, setPageInstance] = useState<Maybe<PageInstance>>(null);
+
+  // 页面路由状态
   const router = useMemo<PageRouter>(() => ({ pages, currentPage, setCurrentPage }), [currentPage]);
 
+  // 当路由变更时，执行 set 回调，同步 router 状态
   useEffect(() => {
-    setPageRender(null);
-    // 动态引入页面
-    const dynamicPageImport = dynamicPageImports[currentPage];
-    dynamicPageImport()
-      .then(setPageRender)
-      .catch(console.error);
-  }, [currentPage]);
-
-  if (!Page) {
-    return <div>loading...</div>;
-  }
+    setRouter(router);
+    setCurrentPageInstance(pageInstance);
+  }, [pageInstance, router]);
 
   return (
     <>
-      {/* 跨页面共享的组件 */}
-      <SharedComponentInstances router={router} />
-      {/* 当前页面 */}
-      <Page router={router} />
+      {/* 渲染跨页面共享的组件 */}
+      {sharedComponentInstances && <ComponentsRender componentInstances={sharedComponentInstances} />}
+      <PageLoader
+        pageImports={pageImports}
+        currentPage={currentPage}
+        currentPageInstance={pageInstance}
+        setCurrentPageInstance={setPageInstance}
+        PageRender={PageRender}
+      />
     </>
   );
 }
 ```
 
+</template>
+
+<template v-slot:p>
+
+```tsx
+import * as React from 'react';
+import { useState, useEffect } from 'react';
+import { PageInstance, Maybe, RouterProps } from '@vize/types';
+
+interface Props extends Pick<RouterProps, 'PageRender' | 'pageImports' | 'setCurrentPageInstance'> {
+  currentPage: number;
+  currentPageInstance: Maybe<PageInstance>;
+}
+
+export function PageLoader({
+  currentPage,
+  pageImports,
+  currentPageInstance,
+  setCurrentPageInstance,
+  PageRender,
+}: Props) {
+  const [[loading, error], setStatus] = useState([true, false]);
+
+  useEffect(() => {
+    setStatus([true, false]);
+    // 当页面为多页模式时，所有子页面独立存在
+    // 这时 pageImports 为空，直接跳转到对应的地址
+    const pageImport = pageImports[currentPage];
+    if (!pageImport) {
+      window.location.href = `/${currentPage}`;
+      return;
+    }
+
+    // 动态 import 页面实例
+    pageImport()
+      .then(({ pageInstance }) => {
+        setCurrentPageInstance(pageInstance);
+        setStatus([false, false]);
+      })
+      .catch(e => {
+        console.error('Load page error:\n', e);
+        setStatus([false, true]);
+      });
+  }, [currentPage]);
+
+  if (loading) {
+    return <Loading />;
+  }
+
+  if (error) {
+    return <LoadError />;
+  }
+
+  // 渲染页面实例
+  return <PageRender pageInstance={currentPageInstance} />;
+}
+
+function Loading() {
+  return <div>loading...</div>;
+}
+
+function LoadError() {
+  return <div>Error occurred</div>;
+}
+```
+
+</template>
+
+</CodeSwitcher>
+
 ## 2. 注册路由
 
-在页面容器目录下编辑 `index.ts`：
+在页面容器目录下编辑 `index.ts`，引入并注册 RouterController：
 
-```ts {5,6}
+```ts {2,5,6}
 import { ContainerProps } from '@vize/types';
 import { MyRouter } from './Router';