@clair/react

React implementation of Clair design

Usage no npm install needed!

<script type="module">
  import clairReact from 'https://cdn.skypack.dev/@clair/react';
</script>

README

clair-react

各类选择

依赖管理

yarn

开发语言

TypeScript + Sass

代码风格

Prettier + BEM

测试工具

Jest + @testing-library/react + enzyme

请优先使用 @testing-library/react

样式布局

使用 grid

意味着 IE 10+ 。其中 IE 10 和 IE 11 支持的是旧规范,可能需要留意。

补充资料

A11y

目录结构

简单介绍

- src: 源文件
  - components: 各个组件
    - __test__: 组件测试目录
      - index.spec.tsx: 测试文件
    - index.tsx: 组件入口文件
    - lib: 凡是不想放入 index.tsx 的逻辑,统统放入这里,且组件文件,首字母大写
  - index.ts: 项目入口文件
  - setupTests.ts: 测试配置文件,通常不需要修改
- examples: 放置文档中的 demo
  - [Component]: 具体组件
    - index.mdx: 组件文档入口,可以理解为具体的文档文件
    - demo1.mdx: demo1 以此类推
- .storybook: storybook 相关。webpack 的配置在这里存放
- test: 项目级别的 e2e 测试,暂时没有组织好
- types: ts 相关的类型文件,主要指不提供 typings 的第三方模块

开发流程

  1. @clair/theme-default 下有没有组件样式,有 -> 4 没有 -> 2;
  2. 参照 @clair/theme-default readme 进行样式开发,同时最好创建 issue 占个位置;
  3. 开发好样式之后,提交 merge request,并 assign liuyuchen-iri/fujun-iri;
  4. 提交组件 API issue,assign liuyuchen-iri,并 @zhaowenbo;
  5. 等待 zhaowenbo/liuyuchen-iri 回复(可能是直接点赞);
  6. API 通过 且 样式被 merge 之后,进行组件开发
  7. 开发完毕后(需要有测试用例,覆盖度别太磕碜),提交 merge request,assign liuyuchen-iri;
  8. 无休止的扯皮,直到 merge。

样式开发

  • 如果有对应的原生 HTMLElement,尽量只在该 HTMLElement 上添加样式(不强求);
  • 想要使用 div 嵌套前,先想想伪元素能否实现效果,原则是少用嵌套;
  • 多翻阅 function + mixins 目录,以及 _variable.scss,避免重复劳动。

组件开发

样式开发完毕后,在 src/components 下创建新的组件目录(首字母大写),开发具体组件。

site/pages/component 中创建对应的 [component].mdx首字母小写,写法可参照 button.mdx),并在 site/nav.json 中添加路由配置,之后可以在浏览器中看到具体效果。

[component.mdx] 中,应该只是 src/examples/[Component]/index.mdx 的直接引用,更多信息参见这里

组件风格

  • named export
  • stateless > stateful, hooks > class,可以用 class,可以用 class,可以用 class。
  • 函数式组件,可以用函数声明,也可以用箭头函数
    • 用箭头函数时候,建议备注类型 React.FC<Props>,例如 const Component: React.FC<Props> = props => {},此时 props 无需在标明类型
  • 每个组件同时使用 prop-types 标明类型,所以是 typescript + prop-types。但是不使用 defaultProps。现阶段 defaultProps 的类型推导尚不完善。

写 examples

组件的具体使用示例,都放在 src/examples 下。

使用 mdx 格式。

正确 export 的组件(指在 src/index.ts 中 export),可以在 jsx 或者 tsx 代码块中直接使用(实际上是提前注入为 react-livescope 变量),参见 button

使用 mdx + 代码块 时,添加 live=true 会显示源码。也可以添加 className=xxx 控制代码块真实 DOM 的类名(控制样式用),同样参见 button

提交代码

yarn commit

合并代码

先执行两个命令:

yarn workspace @clair/react test
yarn workspace @clair/react build

前者检验新代码是否会 break 他人组件。

后者主要用于验证,新的组件是否支持 SSR。

两者验证通过后,提交 PR/MR,以便 review。

提交新组件时,不接受没有 __test__ 的 PR/MR

todo

  • export in ES Module
  • gatsby 搭建 site 页面
  • 更丰富的覆盖样式变量方式
  • react-a11y
  • 集中式管理 snapshot
  • 复用 clair-vue 的 test suites
  • ci clean 的环境中,gatsbynode-sass 的安装时长问题。(ci 中不一定需要 gatsby,before script 修改 package.json ?)
  • 样式使用 git Submodules 分离出去
  • 项目级别的 e2e test
  • 样式 和 js 分开输出,同时输出编译后的 css 文件
  • ES Module 下,path alias 问题(tsc 编译保留了开发时的 alias 路径)
  • hooks 管理全局 z-index ?

当下,ES Module 模式,需要使用者自行编译 scss 文件。antd 采用的方式是,不在源文件中 import 样式文件,而是通过 babel-import-plugin 动态加载样式。使用者可以直接可使用 css 文件,也可以改用 less 文件。