@aloudata/aloudata-design 0.2.0-beta.7 → 0.2.1

package/README.md

@@ -1,91 +1,228 @@
-# aloudata-design
+# 组件库开发规范
 
-## Getting Started
+## 简介
 
-Install dependencies,
+本文档用于介绍组件库开发相关的规范以及组件库开发过程中的注意事项。
+
+## 环境配置
+
+组件库开发过程中，需要满足以下条件：
+
+Node version >= 16.0.0
+
+## 组件库介绍
+
+### 1 快速开始
+
+#### 安装和启动
 
 ```bash
-$ yarn i
+  git clone https://codeup.aliyun.com/60dd34bf4690c27532d3d021/fe/aloudata-design.git
+  cd aloudata-design
+  yarn install
+  yarn start
 ```
 
-开始 dev 环境开发,
+#### 创建组件模板
 
 ```bash
-$ yarn start
+  yarn run cmt //根据指令输入组件名称，创建组件开发模板
 ```
-lint校验
-```
-npm run lint
-```
-打包组件库 通过 `father-build`,
+
+#### 组件校验
 
 ```bash
-$ npm run build
+  yarn run lint //stylelint、eslint 校验
 ```
 
-构建 doc 文档
-
+#### 组件测试
+  
 ```bash
-$ npm run docs:build
+  yarn run test //单元测试
 ```
 
-测试命令
+#### 组件打包
 
 ```bash
-$ npm test
+  yarn run build //打包
 ```
-发布npm包
+
+#### 组件本地link
 
 ```bash
-# 先登录npm账号
-$ npm run release 
-//会自动打包，并基于version打tag
-```
-## 组件开发目录结构
+  npm link //将组件库link到本地npm
+  // 切换到业务项目目录，·引入组件库
+  npm link @aloudata/aloudata-design // 业务项目中引入组件库
 ```
 
---- component
-    --- index.tsx //组件开发 需引用./style
-    --- index.test.tsx //单测
-    --- index.md  //组件文档
-    style文件夹
-        ---index.ts //引用../../style ，引用./index.less
-        ---index.less //用于自定义，需引用'../../style/index.less';
-    demo文件夹 //用于放组件文档用例
-···
+### 2 目录结构
+
+```text
+.
+├── README.md --> readme
+├── docs --> 文档目录
+│   └── index.md
+├── jest --> jest 脚本目录
+├── public --> 公共资源目录
+│   ├── ad_logo.png
+│   ├── favicon.ico
+│   └── style
+├── scripts --> 自定义脚本目录
+│   └── createComponentTemplate.mjs
+├── lib --> 组件打包生成的lib目录
+├── es --> 组件打包生成的es目录
+├── src --> 组件目录
+├── tsconfig.json --> tsconfig ts配置文件
+├── .editorconfig 
+├── .eslintrc.js  --> eslint ts等校验规则配置
+├── .fatherrc.ts  ---> father组件打包配置
+├── .prettierrc.js ---> prettier 代码格式化配置
+├── .stylelintrc.json ---> less 校验规则配置
+├── .umirc.js          ---> 脚手架配置
+├── commitlint.config.js --> commit 配置规则
+├── typings.d.ts
+├── package-lock.json
+├── package.json
+├── yarn-error.log
+└── yarn.lock
 ```
 
-### 覆盖antd组件的icon
+### 3 代码风格
+
+我们使用eslint+stylelint+prettier 来统一代码风格，同时**需要对vscode做一定的配置**，具体[配置参考](https://docs.dingtalk.com/i/nodes/mM3zoYAw1Rr8D5Nong2XWnZ07y9NpXxD?dontjump=true&iframeQuery=utm_source%3Dportal%26utm_medium%3Dportal_space_file_tree&navQuery=spaceId%3Da0gX104nML97WzeJ&nav=spaces)
+
+ts文件使用 *eslint* 校验， 配置文件 .eslintrc.js [查看规则](https://cn.eslint.org/docs/rules/)
+less文件使用 *stylelint* 校验， 配置文件 .stylelintrc.json [查看规则](https://stylelint.bootcss.com/user-guide/rules/list)
+使用 *prettier* 格式化代码，配置文件 .prettierrc.js  
+
+## 组件开发指南（必读）
+
+### 了解组件分类
+
+1. 毛坯组件
+   原始的未做任何修改的antd组件
+2. 简装组件
+   是指在毛坯组件的基础上，只简单了修改了一些颜色、样式等的组件
+3. 精装组件
+   所谓精装组件，是指设计师精心设计过组件应用场景和UI的组件，可能基于antd，也可以完全自定义
+
+### 单元测试
+
+组件开发过程中需要写单测的，建议先写单测，然后进行开发。[了解TDD](https://baike.baidu.com/item/TDD/9064369)
+
+哪些情况需要写单元测试：
+
+1. 如果是基于antd的组件，但凡组件有api接口变动，必须要写单元测试
+2. 非基于antd的组件，必须要写单元测试
+3. 单元测试需要覆盖组件每一个api接口的各个状态
+4. 单元测试文件以 *.test.tsx* 结尾
+
+单元测试参考资料：
+
+- [jestjs](https://jestjs.io/zh-Hans/docs/getting-started)
+- [jest-dom](https://testing-library.com/docs/ecosystem-jest-dom/)
+
+### 组件开发注意事项
 
-在组件对应的 less 文件中
+组件开发支持两种模式，基于antd开发和其它自定义开发。
 
+**基于antd开发:** 在业务满足的情况下，建议基于antd开发或者rc组件开发。方式是把antd组件引用过来，然后做升级修改之后，再作为ald组件暴露出去
+
+**自定义开发：** 当antd组件不满足业务的时候，可以自定义开发，允许引用其它基础组件进行二次开发或者完全自定义组件进行开发。通常是精装组件。
+
+组件开发有以下几个**必须要注意**的点
+
+1. 组件样式要和组件类进行分离，即在组件开发的过程中，不允许引用css、less等样式组件。样式单独写在style文件夹下。
+2. 组件文档内的api接口展示，是获取组件属性props的接口interface定义来实现的（自定义md表格除外）。组件库脚手架对于组件接口interface有处理，即凡是接口来自于外部库引入的部分，不会被文档api识别，即无法展示。interface接口的每一个想要暴露的属性，都必须要写注释，主要包括类型、描述、默认值等。
+3. 组件简装及以上，必须要写demo样例，用于展示已经支持的样式及功能
+4. 精装组件必须要写单元测试。每一个组件的属性，都要在测例中进行测试，保证在组件的的维护修改过程中，不会出现bug。
+5. 组件由ts编写，必须对外暴露所有可能在业务使用过程中需要的ts类型。
+6. 组件库不使用css-module，请考虑权重问题，禁止出现 **!important** 这样的样式
+
+### 组件库文档编写注意事项
+
+#### 文档前文frontMatter编写
+
+在组件库官网展示的时候，会根据文档头部的信息，对文档进行分类，我们当前的计划是分成三类：设计、文档、组件；
+
+在文档头部，使用YAML预发进行编写，用于描述组件的文档的信息，如：
+
+```yaml
+---
+nav:
+  title: 组件
+  path: /components
+title: Select 选择器
+group:
+  title: 组件
+---
 ```
-@import '~@/Icon/index.less';
 
-// 找到antd组件的svg的父节点，覆盖其样式
-.ant-icon-parent-node-class {
-  // \e691 是 iconfont 中图标对应的 Unicode 码
-  .ald-iconfont('\e691');
-}
+具体参考：[FrontMatter](https://d.umijs.org/zh-CN/config/frontmatter)
+
+#### 组件场景用例demo展示
+
+每个简装以上组件都需要展示场景用例，写在src/**/demos/文件夹下
+demo项目中，像在业务中使用aloudata-design一样，脚手架会自动关联项目到node-modules下。(建议先build一下，然后再进行demo展示)
+在组件的md文档中使用code引入用例，在文档中展示用例，如：
+  
+  ```jsx
+  <code src="./demos/single/index.tsx" title="单项选择"/>
+  ```
+
+关于demo的配置，即code的用法，请参考[demo配置](https://d.umijs.org/zh-CN/config/frontmatter#demo-%E9%85%8D%E7%BD%AE%E9%A1%B9)
+
+#### 组件api展示
+
+api展示为表格形势，可以使用**API**标签，如：
+
+```jsx
+  <API src="/path/to/your/component.tsx" hideTitle></API>
 ```
 
-### 更新iconfont文件
+参考文档：[API](https://d.umijs.org/zh-CN/guide/advanced#%E5%9C%A8%E6%96%87%E6%A1%A3%E4%B8%AD%E5%B1%95%E7%A4%BA-api)
 
-在 iconfont 网站上点击“下载至本地”按钮。解压为名为 download 的文件夹。
+也可以自己使用md语法写表格
+  
+  ```md
+  | 属性 | 描述 | 类型 | 默认值 |
+  | ---- | ---- | ---- | ---- |
+  | value | 某个值 | string | 当前选中的值 |
+  ```
 
-将 `src/Icon/iconfont` 文件夹中的所有内容替换成 download 文件夹的内容。
+### 关于组件模板创建
 
-将 `src/Icon/index.less` 文件中的 `@font-face` 下的 `src` 属性的内容，替换成 `src/Icon/iconfont/iconfont.css` 文件中的 `@font-face` 下的 `src` 属性的内容。并将 `url(iconfont.woff` 和 `url(iconfont.ttf` 更改为 `url(./iconfont/iconfont.woff` 和 `url(./iconfont/iconfont.ttf`。
+使用 *npm run cmt* 创建的组件模板只是做一个参考，需要自己根据实际需求进行修改
 
-### link 到本地
+## 关于组件库打包
 
-link 到本地后，其它项目可以通过 link 本项目直接 import 使用
+### 一、组件打包
 
+```bash
+  npm run build
 ```
-npm link
-//转到 目标项目
-npm link @aloudata/aloudata-design
 
-// 移除link
-npm unlink @aloudata/aloudata-design
+组件打包的入口在src/index.tsx，必须在文件总暴露出来，组件才会被打包。
+组件打包使用umi框架的 [falter](https://github.com/umijs/father) 打包工具, 具体配置在 .fatherrc.ts中。打包后会生成lib目录，es目录。
+
+### 二、官方网站打包
+
+```bash
+  npm run docs:build
 ```
+
+官网打包我们默认使用dumi站点模式，会分为设计、文档、组件三个版块，其中设计和文档版块的内容在docs目录下，组件版块的内容在src/**/*.test.md文件中。
+
+1. 设计部分用于描述组件的设计理念，内容由设计师提供，可以是链接，也可以是资料等。
+2. 文档用于描述组件库开发的一些信息等。
+3. 组件用于展示组件的使用场景用例，组件的一些信息，组件的api接口等
+
+### 官方网站样式修改
+
+请在./public/style/common.css 中自定义修改样式
+
+## 组件开发踩过的坑(持续更新中)
+
+1. 组件未暴露className
+2. 组件未暴露ref
+3. 组件未打包出ts校验类型

package/es/Alert/index.d.ts

@@ -0,0 +1,4 @@
+import { Alert } from 'antd';
+import { AlertProps } from 'antd/lib/alert';
+export { AlertProps };
+export default Alert;

package/es/Alert/index.js

@@ -0,0 +1,3 @@
+import "antd/es/alert/style";
+import _Alert from "antd/es/alert";
+export default _Alert;

package/es/Alert/style/index.d.ts

@@ -0,0 +1,2 @@
+import '../../style';
+import './index.less';

package/es/Alert/style/index.js

@@ -0,0 +1,2 @@
+import '../../style';
+import './index.less';

package/es/Alert/style/index.less

@@ -0,0 +1 @@
+@import '../../style/index.less';

package/es/Button/style/index.less

@@ -1,10 +1,10 @@
 @import '../../style/index.less';
 
-@ald-prefix:ant;
-@ald-iconfont-css-prefix:anticon;
-.@{ald-prefix}-btn {
+@ald-prefix: ant;
+@ald-iconfont-css-prefix: anticon;
 
-  &.@{ald-prefix}-btn {
+.ant-btn {
+  &.ant-btn {
     // &-loading::before{
     //   // display: none !important;
     // }
@@ -14,14 +14,14 @@
     &-secondary,
     &-text,
     &-link {
-      font-size: 12px;
-      height: @height-base;
-      padding: 0 12px;
       display: inline-flex;
-      line-height: @height-base;
       align-items: center;
-      font-weight: 500;
       justify-content: center;
+      height: @height-base;
+      padding: 0 11px;
+      font-weight: 500;
+      font-size: 12px;
+      line-height: @height-base;
       .@{ald-iconfont-css-prefix} {
         + span {
           margin-left: 4px;
@@ -38,171 +38,216 @@
     }
 
     &-primary {
+      text-shadow: @text-shadow;
       background-color: @B40;
       border-color: @B40;
-      box-shadow: none;
       border-radius: @border-radius-base;
-      text-shadow: @text-shadow;
+      box-shadow: none;
+
+      &:focus {
+        text-shadow: @text-shadow;
+        background-color: @B40;
+        border-color: @B40;
+        border-radius: @border-radius-base;
+        box-shadow: none;
+      }
+
       &:hover,
-      &:focus,
       &:active,
-      &.@{ald-prefix}-btn-loading {
+      &.ant-btn-loading {
+        color: @ND0;
         background-color: @B20;
         border-color: @B20;
-        color: @ND0;
       }
 
       &[disabled] {
+        color: @NL80;
         background-color: @NL90;
         border-color: transparent;
-        color: @NL80;
+        cursor: default;
 
         &:hover,
         &:focus,
         &:active {
+          color: @NL80;
           background-color: @NL90;
           border-color: transparent;
-          color: @NL80;
         }
       }
     }
-    &-dangerous.@{ald-prefix}-btn-primary {
-      background-color: @SC40;
-      border-color: @SC40;
+
+    &-dangerous.ant-btn-primary {
       color: @ND0;
       text-shadow: @text-shadow;
+      background-color: @SC40;
+      border-color: @SC40;
       box-shadow: unset;
 
-      &:hover {
-        background-color: @SC20;
-        border-color: @SC20;
+      &:focus {
         color: @ND0;
+        text-shadow: @text-shadow;
+        background-color: @SC40;
+        border-color: @SC40;
+        box-shadow: unset;
       }
-      &:focus,
+
+      &:hover,
       &:active,
-      &.@{ald-prefix}-btn-loading {
+      &.ant-btn-loading {
+        color: @ND0;
         background-color: @SC20;
         border-color: @SC20;
-        color: @ND0;
       }
 
       &[disabled] {
+        color: @NL80;
         background-color: @NL90;
         border-color: transparent;
-        color: @NL80;
+        cursor: default;
 
         &:hover,
         &:focus,
         &:active {
+          color: @NL80;
           background-color: @NL90;
           border-color: transparent;
-          color: @NL80;
         }
       }
     }
 
     &-secondary {
+      color: @NL30;
+      text-shadow: @text-shadow;
       background-color: @BG100;
       border-color: @NL90;
-      color: @NL30;
-      box-shadow: none;
       border-radius: @border-radius-base;
-      text-shadow: @text-shadow;
+      box-shadow: none;
+
+      &:focus {
+        color: @NL30;
+        text-shadow: @text-shadow;
+        background-color: @BG100;
+        border-color: @NL90;
+        border-radius: @border-radius-base;
+        box-shadow: none;
+      }
 
       &:hover,
-      &:focus,
       &:active,
-      &.@{ald-prefix}-btn-loading {
+      &.ant-btn-loading {
+        color: @NL30;
         background-color: @NL97;
         border-color: @NL90;
-        color: @NL30;
       }
 
       &[disabled] {
+        color: @NL80;
         background-color: @BG100;
         border-color: @NL90;
-        color: @NL80;
+        cursor: default;
 
         &:hover,
         &:focus,
         &:active {
+          color: @NL80;
           background-color: @BG100;
           border-color: @NL90;
-          color: @NL80;
         }
       }
     }
 
     &-text {
+      color: @NL30;
+      text-shadow: @text-shadow;
       background-color: @BG100;
       border-color: @BG100;
-      color: @NL30;
-      box-shadow: none;
       border-radius: @border-radius-base;
-      text-shadow: @text-shadow;
+      box-shadow: none;
+
+      &:focus {
+        color: @NL30;
+        text-shadow: @text-shadow;
+        background-color: @BG100;
+        border-color: @BG100;
+        border-radius: @border-radius-base;
+        box-shadow: none;
+      }
+
       &:hover,
-      &:focus,
       &:active,
-      &.@{ald-prefix}-btn-loading {
-        background-color: @NL97;
+      &.ant-btn-loading {
         // border-color: @NL97;
         color: @NL30;
+        background-color: @NL97;
       }
 
       &[disabled] {
+        color: @NL80;
         background-color: transparent;
         border-color: transparent;
-        color: @NL80;
+        cursor: default;
 
         &:hover,
         &:focus,
         &:active {
+          color: @NL80;
           background-color: transparent;
           border-color: transparent;
-          color: @NL80;
         }
       }
     }
 
     &-link {
-      background-color: @BG100;
-      border-color: @BG100;
       color: @B40;
       font-weight: 400;
-      box-shadow: none;
-      border-radius: @border-radius-base;
       text-shadow: @text-shadow;
+      background-color: @BG100;
+      border-color: @BG100;
+      border-radius: @border-radius-base;
+      box-shadow: none;
+
+      &:focus {
+        color: @B40;
+        font-weight: 400;
+        text-shadow: @text-shadow;
+        background-color: @BG100;
+        border-color: @BG100;
+        border-radius: @border-radius-base;
+        box-shadow: none;
+      }
+
       &:hover,
-      &:focus,
       &:active,
-      &.@{ald-prefix}-btn-loading {
+      &.ant-btn-loading {
+        color: @B20;
         background-color: @BG100;
         border-color: @BG100;
-        color: @B20;
       }
 
       &[disabled] {
+        color: @NL80;
         background-color: transparent;
         border-color: transparent;
-        color: @NL80;
+        cursor: default;
 
         &:hover,
         &:focus,
         &:active {
+          color: @NL80;
           background-color: transparent;
           border-color: transparent;
-          color: @NL80;
         }
       }
     }
 
     &-icon-only {
       justify-content: center;
+      width: @height-base;
+      height: @height-base;
       padding: 0;
       vertical-align: bottom;
-      height: @height-base;
-      width: @height-base;
-      &.@{ald-prefix}-btn-loading-icon {
+
+      &.ant-btn-loading-icon {
         vertical-align: baseline;
       }
       .@{ald-iconfont-css-prefix} {
@@ -214,23 +259,25 @@
     }
 
     &-circle {
+      justify-content: center;
       width: @height-base;
       min-width: auto;
       padding: 0;
-      justify-content: center;
       border-radius: 50%;
     }
 
     &-lg {
+      min-width: auto;
       height: 32px;
       font-size: 14px;
-      min-width: auto;
-      &.@{ald-prefix}-btn-icon-only {
-        height: 32px;
+
+      &.ant-btn-icon-only {
         width: 32px;
         min-width: auto;
+        height: 32px;
       }
-      &.@{ald-prefix}-btn-circle {
+
+      &.ant-btn-circle {
         width: 32px;
         height: 32px;
         border-radius: 50%;
@@ -239,13 +286,16 @@
 
     &-sm {
       height: 24px;
+      line-height: 22px;
       border-radius: @border-radius-sm;
-      &.@{ald-prefix}-btn-icon-only {
-        height: 24px;
+
+      &.ant-btn-icon-only {
         width: 24px;
+        height: 24px;
         border-radius: @border-radius-sm;
       }
-      &.@{ald-prefix}-btn-circle {
+
+      &.ant-btn-circle {
         width: 32px;
         height: 32px;
         border-radius: 50%;

package/es/Checkbox/index.d.ts

@@ -0,0 +1,11 @@
+/// <reference types="react" />
+import { CheckboxProps } from 'antd';
+import { CheckboxGroupProps } from 'antd/lib/checkbox';
+export type { CheckboxValueType, CheckboxOptionType } from 'antd/es/checkbox/Group';
+export type { CheckboxChangeEvent } from 'antd/es/checkbox/Checkbox';
+declare function Checkbox(props: CheckboxProps): JSX.Element;
+declare namespace Checkbox {
+    var Group: (props: CheckboxGroupProps) => JSX.Element;
+}
+export type { CheckboxProps };
+export default Checkbox;