@modern-js/main-doc 0.0.0-next-20221116121040

package/zh/tutorials/first-app/c06-css-and-component/6.2-utility-class.md

@@ -0,0 +1,148 @@
+---
+title: ​​用 Utility Class 写组件
+---
+
+上一小节我们学习了如何使用 style-components 实现 `Avatar` 组件。
+
+但当前的 UI 仍然不能让人满意，缺乏专业感，例如列表项内部的布局有点粗糙，很多地方没对齐。
+
+本小节中，我们自己来实现一个更好的 `Item` 组件，实现这样的设计稿：
+
+![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/design2.png)
+
+这次要实现的 UI 更复杂，有内部结构，但另一方面，并没有 `Avatar` 组件的**很粗的亮蓝色边框**这样很特殊的 UI，都是很常规的水平垂直布局、居中、字体样式等。
+
+这种情况下，其实根本没必要写 CSS，有更高效的、跟 styled-components 互补的实现方式：Utility Class。
+
+Modern.js 集成了主流、轻量、通用的 Utility Class 工具库 [Tailwind CSS](https://tailwindcss.com/)。
+
+执行 `pnpm run new`，进行如下选择，开启 Tailwind CSS：
+
+```bash
+# 启用可选功能
+❯ 启用 Tailwind CSS 支持
+  启用 Sass 支持
+  ...
+```
+
+:::info 注
+因为我们之前已经开启了 Less 支持，所以再次添加可选功能时，不再有这个选项。
+:::
+
+在 `src/App.tsx` 顶部引入 Tailwind CSS 的 css 文件，就可以开始快速实现专业的 UI：
+
+```js
+import 'tailwindcss/base.css';
+import 'tailwindcss/components.css';
+import 'tailwindcss/utilities.css';
+```
+
+先创建 Item 组件：
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs>
+<TabItem value="macOS" label="macOS" default>
+
+```bash
+mkdir -p src/components/Item
+touch src/components/Item/index.tsx
+```
+
+</TabItem>
+<TabItem value="Windows" label="Windows">
+
+```powershell
+mkdir -p src/components/Item
+ni src/components/Item/index.tsx
+```
+
+</TabItem>
+</Tabs>
+
+修改 `src/App.tsx`，把 `List` 的 `render` 实现交给 `Item` 组件：
+
+```js
+import { List } from 'antd';
+import 'tailwindcss/base.css';
+import 'tailwindcss/components.css';
+import 'tailwindcss/utilities.css';
+import Item from './components/Item';
+
+const getAvatar = (users: Array<{ name: string; email: string }>) =>
+  users.map(user => ({
+    ...user,
+    avatar: `https://avatars.dicebear.com/v2/identicon/${user.name}.svg`,
+  }));
+
+const mockData = getAvatar([
+  { name: 'Thomas', email: 'w.kccip@bllmfbgv.dm' },
+  { name: 'Chow', email: 'f.lfqljnlk@ywoefljhc.af' },
+  { name: 'Bradley', email: 'd.wfovsqyo@gpkcjwjgb.fr' },
+  { name: 'Davis', email: '"t.kqkoj@utlkwnpwk.nu' },
+]);
+
+function App() {
+  return (
+    <div className="container lg mx-auto">
+      <List
+        dataSource={mockData}
+        renderItem={info => <Item key={info.name} info={info} />}
+      />
+    </div>
+  );
+}
+
+export default App;
+```
+
+在父容器的上使用了 [Utility Class](https://tailwindcss.com/docs/container) ，快速实现了最基本的 [RWD](https://tailwindcss.com/docs/responsive-design)（最大宽度、居中）。
+
+接下来实现 `src/components/Item/index.tsx`：
+
+```tsx
+import Avatar from '../Avatar';
+
+type InfoProps = {
+  avatar: string;
+  name: string;
+  email: string;
+  archived?: boolean;
+};
+
+const Item = ({ info }: { info: InfoProps }) => {
+  const { avatar, name, email, archived } = info;
+  return (
+    <div className="flex p-4 items-center border-gray-200 border-b">
+      <Avatar src={avatar} />
+      <div className="ml-4 flex-1 flex justify-between">
+        <div className="flex-1">
+          <p>{name}</p>
+          <p>{email}</p>
+        </div>
+        <button
+          type="button"
+          disabled={archived}
+          className={`bg-blue-500  text-white font-bold
+            py-2 px-4 rounded-full hover:bg-blue-700`}>
+          Archive
+        </button>
+      </div>
+    </div>
+  );
+};
+
+export default Item;
+```
+
+执行 `pnpm run dev`，可以看到预期的运行结果：
+
+![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/result2.png)
+
+这一小节中，我们只使用了少量 Utility Class，比如 [Flex](https://tailwindcss.com/docs/display/)、[Padding](https://tailwindcss.com/docs/padding/)、[Margin](https://tailwindcss.com/docs/margin/)、[Text](https://tailwindcss.com/docs/text-color/)、[Font](https://tailwindcss.com/docs/font-weight/)、[Border](https://tailwindcss.com/docs/border-width)，不写一行 CSS 就实现了有【 设计系统（Design System）】的、符合设计稿的专业 UI。
+
+---
+
+> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c06/hello-modern-2)。
+

package/zh/tutorials/first-app/c06-css-and-component/6.3-postcss.md

@@ -0,0 +1,84 @@
+---
+title: ​​添加新的 Utility Class
+---
+
+上一小节，我们学习了如何使用通用的 Utility Class 工具库.
+
+我们不但可以自己写组件，也可以自己实现新的 Utility Class，方便在代码间复用。
+
+Utility Class 本身也是一种**面向组件**的技术（将不同 class 用在一个组件上，等价于给这个组件设置了一些来自基类的属性），但 Utility Class 的 classname 是全局的（因为要用在任意组件/元素上），很适合用独立 CSS 文件来实现。
+
+创建一个新的 CSS 文件：
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs>
+<TabItem value="macOS" label="macOS" default>
+
+```bash
+mkdir -p src/styles
+touch src/styles/utils.css
+```
+
+</TabItem>
+<TabItem value="Windows" label="Windows">
+
+```powershell
+mkdir -p src/styles
+ni src/styles/utils.css
+```
+
+</TabItem>
+</Tabs>
+
+在 `src/App.tsx` 里导入 `utils.css`：
+
+```js
+import './styles/utils.css';
+```
+
+在 `src/styles/utils.css` 里实现一个叫作 `custom-text-gray` 的 Utility Class。
+
+```css
+:root {
+  --custom-text-color:rgb(113, 128, 150);
+}
+
+.custom-text-gray {
+  color: var(--custom-text-color);
+}
+```
+
+:::info 注
+Modern.js 集成了 [PostCSS](/docs/guides/basic-features/css/postcss)，支持现代 CSS 语法特性，比如 [custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*)。
+:::
+
+在 `src/components/Item/index.tsx` 里使用，把：
+
+```js
+<div className="ml-4 flex-1 flex justify-between">
+```
+
+改成：
+
+```js
+<div className="ml-4 custom-text-gray flex-1 flex justify-between">
+```
+
+执行 `pnpm run dev`，可以看到字体颜色改变了：
+
+![design2](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/result3.png)
+
+:::info 注
+此处只是为了演示 Utility Class 用法。真实项目中，在有 Tailwind CSS 的情况下，这种 Utility Class 没什么价值，应该通过配置 Design System 的 [**theme**](https://tailwindcss.com/docs/customizing-colors) 来增加字体颜色。
+
+`utils.css` 也可以写成 `utils.scss` 或 `utils.less`，Modern.js 对 SCSS 和 Less 同样提供开箱即用的支持。
+
+不过在 PostCSS 的支持下，现代 CSS 应该足以满足这些开发需求，性能相较于预处理器也更好，建议优先用 .css 文件。
+:::
+
+---
+
+> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c06/hello-modern-3)。
+

package/zh/tutorials/first-app/c06-css-and-component/6.4-design-system.md

@@ -0,0 +1,83 @@
+---
+title: ​管理 Design System
+---
+
+在前两个小节中，我们了解了 Utility Class 以及使用了 Modern.js 已经集成的 Utility Class 工具库 [Tailwind CSS](https://tailwindcss.com/)，
+默认提供的设计系统生成的样式可以满足实际开发中的部分需求。
+
+然而实际开发中，我们可能需要修改默认的设计系统规范。为此，Modern.js 提供了
+[`source.designSystem`](/docs/configure/app/source/design-system) 配置来管理项目的设计系统。
+
+## 覆盖默认配置
+
+要覆盖默认的设计系统配置，请在 `modern.config.js` 的 `source.designSystem` 中添加要覆盖的键。
+
+```js title="modern.config.js"
+export default defineConfig({
+  source: {
+    designSystem: {
+      opacity: {
+        0: '0',
+        20: '0.2',
+        40: '0.4',
+        60: '0.6',
+        80: '0.8',
+        100: '1',
+      },
+    },
+  },
+});
+```
+
+这将完全替换默认键配置，因此在上面的示例中，不会生成默认的 opacity utilities。
+
+所有未覆盖的键都将从默认主题继承，因此在上面的示例中，将保留颜色，间距，边框圆角，背景位置等内容的默认主题配置。
+
+## 扩展默认配置
+
+如果您想保留主题选项的默认值，但又要添加新值，请在 `designSystem.extend` 下添加扩展的内容。
+
+例如，如果我们想添加一个额外的断点但保留现有的断点，则可以扩展 `screens` 属性：
+
+```js title="modern.config.js"
+export default defineConfig({
+  source: {
+    designSystem: {
+      opacity: {
+        0: '0',
+        20: '0.2',
+        40: '0.4',
+        60: '0.6',
+        80: '0.8',
+        100: '1',
+      },
+      extend: {
+        screens: {
+          '2xl': '1440px',
+        },
+      },
+    },
+  },
+});
+```
+
+修改 `src/Item/index.tsx` 的 button 组件代码
+
+```js
+<button
+  type="button"
+  disabled={archived}
+  className={`bg-blue-500 text-white font-bold
+    py-2 px-4 rounded-full hover:bg-blue-700 2xl:bg-red-500`}
+>
+  Archive
+</button>
+```
+
+执行 `pnpm run dev` 后，增加页面宽度超过 1440px 可以看到 button 颜色变化：
+
+![design2](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/result4.png)
+
+---
+
+> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c06/hello-modern-4)。

package/zh/tutorials/first-app/c06-css-and-component/6.5-storybook.md

@@ -0,0 +1,77 @@
+---
+title: ​用 Storybook 调试组件
+---
+
+前几个小节中，我们已经开发了一个简单的 UI 组件。组件开发完后，一般我们需要对它进行调试。
+
+除了可以直接在项目中进行调试以外，我们还可以使用 [**Storybook**](https://storybook.js.org/) 进行调试。
+
+Modern.js 提供了开箱即用的 Storybook 能力，可以识别应用工程下的 Story 文件。
+
+我们执行 `pnpm run new`，启用该模式：
+
+```bash
+# 启用可选功能
+  ...
+  启用「单元测试 / 集成测试」功能
+❯ 启用「Visual Testing (Storybook)」模式
+```
+
+安装成功后，我们需要为我们的组件添加 Story 文件。
+
+:::info 补充信息
+Story 文件是指 `*.stories.[t|j]sx?` 格式的文件。
+:::
+
+这里我们为 `Avatar` 组件 添加 `src/components/Avatar/index.stories.tsx` Story 文件。
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs>
+<TabItem value="macOS" label="macOS" default>
+
+```bash
+touch src/components/Avatar/index.stories.tsx
+```
+
+</TabItem>
+<TabItem value="Windows" label="Windows">
+
+```powershell
+ni src/components/Avatar/index.stories.tsx
+```
+
+</TabItem>
+</Tabs>
+
+内容如下：
+
+``` javascript
+import Avatar from '.';
+
+export const DanielTaylorAvatar = () => (
+  <Avatar src="https://avatars.dicebear.com/v2/identicon/Daniel Taylor.svg" />
+);
+
+export default {
+  title: 'Avatar Demo',
+};
+```
+
+然后我们启动 Storybook 调试：
+
+``` bash
+pnpm run dev story
+```
+
+然后我们可以看到如下界面：
+
+![storybook demo](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/mwa-storybook-demo.png)
+
+如果需要配置 Storybook，则需要在 [`config/storybook/**`](/docs/apis/app/hooks/config/storybook) 目录下进行配置。
+
+---
+
+> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c06/hello-modern-5)。
+

package/zh/tutorials/first-app/c06-css-and-component/6.6-testing.md

@@ -0,0 +1,113 @@
+---
+title: ​测试组件​​​
+---
+
+Modern.js 集成了 [Jest](https://jestjs.io/)，不需要做任何配置，可以直接给组件写测试用例。
+
+我们执行 `pnpm run new` 开启测试功能：
+
+```bash
+# 启用可选功能
+❯ 启用「单元测试 / 集成测试」功能
+```
+
+可以用以下两种方式给 Item 组件创建测试用例：
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs>
+<TabItem value="macOS" label="macOS" default>
+
+```bash
+touch src/components/Item/index.test.tsx
+```
+
+</TabItem>
+<TabItem value="Windows" label="Windows">
+
+```powershell
+ni src/components/Item/index.test.tsx
+```
+
+</TabItem>
+</Tabs>
+
+或
+
+<Tabs>
+<TabItem value="macOS" label="macOS" default>
+
+```bash
+mkdir -p src/components/Item/__tests__/
+touch src/components/Item/__tests__/index.tsx
+```
+
+</TabItem>
+<TabItem value="Windows" label="Windows">
+
+```powershell
+mkdir -p src/components/Item/__tests__/
+ni src/components/Item/__tests__/index.tsx
+```
+
+</TabItem>
+</Tabs>
+
+
+以前者为例，`Item/index.test.tsx` 的内容：
+
+```js
+import { render } from '@modern-js/runtime/testing';
+import Item from '.';
+
+const defaultProps = {
+  info: {
+    avatar: 'https://via.placeholder.com/350x350',
+    name: 'foo',
+    email: 'foo.bar@bytedance.com',
+    archived: false,
+  },
+};
+
+describe('Item', () => {
+  it('should have contents', () => {
+    const {
+      info: { name },
+    } = defaultProps;
+    const { getByText } = render(<Item {...defaultProps} />);
+    expect(getByText(name)).toBeInTheDocument();
+  });
+});
+```
+
+在之前章节创建的 `modern-app-env.d.ts` 文件 **顶部**（[`///` 语法只在文件顶部生效](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html#:~:text=Triple-slash%20directives%20are%20only%20valid%20at%20the%20top%20of%20their%20containing%20file.)） 加上类型定义：
+
+```ts
+/// <reference types="@modern-js/plugin-testing/type" />
+```
+
+:::info 注
+更多相关内容可以查看 [Test API](/docs/apis/app/runtime/testing/render)。
+:::
+
+执行 `pnpm run test`，可以看到测试报告：
+
+```bash
+> modern test
+
+ PASS  src/components/Item/index.test.tsx
+  Item
+    ✓ should have contents (27 ms)
+
+Test Suites: 1 passed, 1 total
+Tests:       1 passed, 1 total
+Snapshots:   0 total
+Time:        1.048 s, estimated 2 s
+Ran all test suites.
+```
+
+---
+
+> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c06/hello-modern-6)。
+

package/zh/tutorials/first-app/c06-css-and-component/_category_.json

@@ -0,0 +1,3 @@
+{
+  "label": "6: 添加 UI 组件"
+}

package/zh/tutorials/first-app/c07-app-entry/7.1-intro.md

@@ -0,0 +1,64 @@
+---
+title: 入口的用途​​​
+---
+
+上一章节中，我们介绍了如何编写 UI 组件。
+
+这一章节中，继续沿用之前的代码，到目前为止，hello-modern 的目录结构是这样的：
+
+```md
+.
+├── .vscode/
+├── src/
+│   ├── components/
+│   │   ├── Avatar/
+│   │   │   ├── index.stories.tsx
+│   │   │   └── index.tsx
+│   │   └── Item/
+│   │       ├── index.test.tsx
+│   │       └── index.tsx
+│   ├── styles/
+│   │   └── utils.css
+│   ├── .eslintrc.json
+│   ├── App.css
+│   ├── App.tsx
+│   └── modern-app-env.d.ts
+├── .editorconfig
+├── .gitignore
+├── .npmrc
+├── .nvmrc
+├── README.md
+├── package.json
+├── pnpm-lock.yaml
+└── tsconfig.json
+```
+
+hello-modern 项目是一个应用工程，`src/` 目录里是应用工程源代码的主要部分，我们称之为【 Universal App 代码（大一统应用代码）】—— 既可以在客户端运行又可以在服务器端运行，有多种运行模式和部署模式，既能实现多页（MPA）也能实现单页（SPA）。
+
+我们把 `src/App.tsx` 称作【 应用入口（App Entry）】，一个应用工程可以有一到多个应用入口。
+
+:::info 注
+应用入口不止 `App.[jt]sx` 一种，之后章节中会再次介绍。
+:::
+
+:::info 注
+在不启用 SSG（Static Site Generation）的情况下，Modern.js 会为每一个应用入口，都自动生成一个对应的 HTML，用于在浏览器、WebView 等平台上运行。
+
+一个应用入口适用于：
+
+- 一个中后台应用（SPA）
+- 一个桌面应用（SPA、Electron App）
+- 一个PWA
+- 一个大型的多页网站（SPA + SSR）
+- 一个落地页、活动页或分享页
+- 一个端内界面
+- 一个微前端子应用
+- ……
+
+多个应用入口适用于：
+
+- 简单的多页网站（多个 HTML 互相链接）
+- 由多种不同类型入口组成的产品『系统』（整个产品不是单一的客户端，而是由多种不同客户端组成，比如同时有落地页、端内界面、端外独立 Web App、后台管理应用）
+:::
+
+hello-modern 项目目前是【 单入口 】形式的，我们接下来添加一个新入口，实现这个联系人列表应用的落地页，把项目转变成【 多入口 】形式。

package/zh/tutorials/first-app/c07-app-entry/7.2-add-entry-in-cli.md

@@ -0,0 +1,104 @@
+---
+title: 用 new 命令创建入口​​​
+---
+
+Modern.js 支持自动创建新入口，前面的章节中提到过，`pnpm run new` 可以启用可选功能。
+
+我们也可以通过它来创建新的工程元素，在项目根目录下执行 `pnpm run new`：
+
+```bash
+# 请选择你想要的操作
+❯ 创建工程元素
+  启用可选功能
+
+# 创建工程元素
+❯ 新建「应用入口」
+  新建「Server 自定义」源码目录
+
+# 请填写入口名称
+- landing-page
+
+# 是否需要调整默认配置
+❯ 否
+  是
+```
+
+创建完成，项目会变成这样：
+
+```md
+.
+├── .vscode/
+├── src/
+│   ├── hello-modern/
+│   │   ├── components/
+│   │   │   ├── Avatar/
+│   │   │   │   ├── index.stories.tsx
+│   │   │   │   └── index.tsx
+│   │   │   └── Item/
+│   │   │       ├── index.test.tsx
+│   │   │       └── index.tsx
+│   │   ├── styles/
+│   │   │   └── utils.css
+│   │   ├── App.css
+│   │   └── App.tsx
+│   ├── landing-page/
+│   │   ├── App.css
+│   │   └── App.tsx
+│   ├── .eslintrc.json
+│   └── modern-app-env.d.ts
+├── .editorconfig
+├── .gitignore
+├── .npmrc
+├── .nvmrc
+├── README.md
+├── package.json
+├── pnpm-lock.yaml
+└── tsconfig.json
+```
+
+可以看到联系人列表应用的文件，都被自动重构到 `src/hello-modern/` 里。
+
+同时新建了一个 `src/landing-page/`，里面同样有 `App.tsx`（`pnpm run new` 命令只做了这些事，所以你也可以很容易的手动创建新入口或修改入口）
+
+执行 `pnpm run dev`，显示：
+
+![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/landing-page.png)
+
+访问 `http://localhost:8080/`，可以像之前一样看到联系人列表应用。
+
+访问 `http://localhost:8080/landing-page`，可以看到刚创建的新入口 `landing-page` 的页面（Modern.js 自动生成的默认页面）。
+
+## 手动调整应用入口
+
+Modern.js 框架的设计原则之一是【[约定优于配置（Convention over Configuration）](https://en.wikipedia.org/wiki/Convention_over_configuration)】，多数情况下可以按约定直接写代码，不需要做任何配置，这里 `src/` 中的目录结构就是一种约定：
+
+`src/hello-modern/` 和 `src/landing-page/` 被自动识别为两个应用入口：hello-modern 和 landing-page。
+
+其中 `src/hello-modern/` 的目录名跟项目名（`package.json` 里的 `name`）一致，会被认为是项目**主入口**，项目 URL 的根路径（开发环境里默认是 `http://localhost:8080/`）会自动指向主入口。
+
+其他入口的 URL，是在根路径后追加入口名，比如 `http://localhost:8080/landing-page`。
+
+:::info 注
+`src/` 下如果有 `App.[jt]sx`，就认为这个应用工程是单入口的，`src/` 下的其他文件和目录，都会被视为入口内部的文件。
+
+`src/` 下如果没有  `App.[jt]sx`，那么 `src/` **下一级**目录里，如果有 `App.[jt]sx`，这个目录就会被视为一个应用入口。
+
+`App.jsx` 被看作约定中**标识**，也有其他形式的**标识**，之后的章节中会继续介绍。
+:::
+
+接下来，我们把 `src/hello-modern/App.tsx` 重命名为 `src/contacts/App.tsx`：
+
+```bash
+mv src/hello-modern src/contacts
+```
+
+再次执行 `pnpm run dev`，结果变成：
+
+![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/contacts.png)
+
+现在不再有主入口，联系人列表现在是一个普通入口，需要用 `http://localhost:8080/contacts` 访问。
+
+---
+
+> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c07/hello-modern-2)。
+