@hsu-react/ui 0.0.1 → 0.0.2

package/src/components/Table/index.md

@@ -8,10 +8,69 @@ title: Table 表格
 
 # Table 表格
 
-> `Table` 组件。完整 API 见源码类型定义，下方为基础用法。
+在 antd `Table` 之上封装，扩展了自定义列（权限、排序、省略 Tooltip）、内置分页、自动高度、行拖拽、自动滚动等能力。
 
 ## 引入
 
 ```ts
 import { Table } from "@hsu-react/ui";
 ```
+
+## 基础用法
+
+```tsx
+import React from "react";
+import { Table } from "@hsu-react/ui";
+
+const columns = [
+  { title: "姓名", dataIndex: "name", width: 120 },
+  { title: "年龄", dataIndex: "age", width: 80 },
+  { title: "住址", dataIndex: "address" },
+];
+
+const dataSource = [
+  { key: "1", name: "张三", age: 32, address: "西湖区湖底公园 1 号" },
+  { key: "2", name: "李四", age: 28, address: "滨江区江南大道 100 号" },
+  { key: "3", name: "王五", age: 45, address: "余杭区文一西路 998 号" },
+];
+
+export default () => (
+  <Table columns={columns} dataSource={dataSource} pagination={false} />
+);
+```
+
+## API
+
+在 [antd TableProps](https://ant.design/components/table-cn) 基础上扩展（`scroll`、`pagination`、`columns` 被重写），常用新增/重写属性如下：
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| columns | 列配置，使用自定义 `ColumnsType`（支持 `hidden`、`sort`、`hasPermi`、`help`、`mergeRow`、`fixedWidth`、`ellipsisPosition` 等） | `ColumnsType<RecordType>` | `[]` |
+| scroll | 是否开启滚动；`{ y: false }` 可关闭纵向滚动 | `boolean \| { y: boolean }` | `false` |
+| pagination | 分页配置；为 `false` 时不展示分页 | `false \| PaginationProps` | `{}` |
+| autoWidth | 列宽自适应 | `boolean` | - |
+| scrollAutoHeight | 自动计算并撑满可用高度 | `boolean` | `true` |
+| hideScrollbar | 隐藏表头滚动条 | `boolean` | `true` |
+| thPadding | 表头单元格内边距 | `string` | - |
+| tdPadding | 表体单元格内边距 | `string` | - |
+| expandedCellPadding | 展开行单元格内边距 | `string` | `tdPadding` |
+| fillPanel | 撑满父级 Panel 高度 | `boolean` | - |
+| staticDataSource | 使用静态数据源（前端分页） | `boolean` | `false` |
+| serialNumberColumn | 是否展示序号列 | `boolean` | `false` |
+| hideEmpty | 隐藏空数据占位 | `boolean` | `false` |
+| ellipsisTooltipConfig | 文本省略 Tooltip 配置 | `EllipsisTooltipConfig` | - |
+| onDragEnd | 行拖拽结束回调（开启后启用拖拽排序） | `DragProps["onDragEnd"]` | - |
+| autoScrolling | 是否开启内容自动滚动 | `boolean` | - |
+| autoScrollMode | 自动滚动模式 | `'smooth' \| 'row'` | - |
+| autoScrollingSpeed | smooth 模式滚动速度（px/s） | `number` | `25` |
+| autoScrollLoop | 滚动到末尾后是否循环 | `boolean` | `true` |
+| autoScrollLoopMode | 循环模式 | `'reset' \| 'seamless'` | `'reset'` |
+| onScrollEnd | 滚动到底部回调 | `() => void` | - |
+| onAutoScrollEndAdd | 自动滚动到底部时追加数据 | `() => Promise<boolean>` | - |
+| order | 当前排序 | `{ k: string; t: 'asc' \| 'desc' }` | - |
+| onOrderChange | 排序变化回调 | `(order?) => void` | - |
+| sorter | 是否启用排序 | `boolean` | - |
+| showTotal | 自定义分页总数展示；为 `false` 时不展示 | `false \| ((total, range) => ReactNode)` | - |
+| isExpandedCellTable | 是否为展开行内嵌表格样式 | `boolean` | `false` |
+
+> 另导出 `TableDrag`，用于行拖拽排序场景。

package/src/components/Table/index.module.less

@@ -15,16 +15,16 @@
     cursor: pointer;
   }
 
-  .ant-table-container {
+  :global(.ant-table-container) {
     border-left: none !important;
   }
 
-  .ant-table-thead {
+  :global(.ant-table-thead) {
     tr {
-      .ant-table-cell {
+      :global(.ant-table-cell) {
         padding: var(--th-padding);
 
-        &.ant-table-column-has-sorters {
+        &:global(.ant-table-column-has-sorters) {
           background: var(--cf-subtle);
 
           &:hover {
@@ -35,22 +35,22 @@
     }
   }
 
-  .ant-table-tbody {
-    .ant-table-placeholder {
+  :global(.ant-table-tbody) {
+    :global(.ant-table-placeholder) {
       height: 100%;
     }
 
-    .ant-table-expanded-row {
-      .ant-table-cell {
+    :global(.ant-table-expanded-row) {
+      :global(.ant-table-cell) {
         padding: var(--expanded-cell-padding);
       }
     }
 
-    .ant-table-row {
-      .ant-table-cell {
+    :global(.ant-table-row) {
+      :global(.ant-table-cell) {
         padding: var(--td-padding);
 
-        &:not(.ant-table-cell-ellipsis):not(.noWarp) {
+        &:not(:global(.ant-table-cell-ellipsis)):not(.noWarp) {
           white-space: pre-wrap;
           word-break: break-all;
         }
@@ -59,21 +59,21 @@
           white-space: nowrap;
         }
 
-        &.ant-table-column-sort {
+        &:global(.ant-table-column-sort) {
           background: transparent;
 
-          &.ant-table-cell-row-hover {
+          &:global(.ant-table-cell-row-hover) {
             background: var(--cf-subtle);
           }
         }
       }
 
-      &.ant-table-row-selected {
-        .ant-table-cell {
-          &.ant-table-column-sort {
+      &:global(.ant-table-row-selected) {
+        :global(.ant-table-cell) {
+          &:global(.ant-table-column-sort) {
             background: rgba(19, 194, 194, 0.12);
 
-            &.ant-table-cell-row-hover {
+            &:global(.ant-table-cell-row-hover) {
               background: rgba(19, 194, 194, 0.22);
             }
           }
@@ -82,15 +82,15 @@
     }
   }
 
-  .ant-table-summary {
+  :global(.ant-table-summary) {
     > tr {
-      .ant-table-cell {
+      :global(.ant-table-cell) {
         padding: var(--td-padding);
 
-        &.ant-table-column-sort {
+        &:global(.ant-table-column-sort) {
           background: transparent;
 
-          &.ant-table-cell-row-hover {
+          &:global(.ant-table-cell-row-hover) {
             background: var(--cf-subtle);
           }
         }
@@ -98,11 +98,11 @@
     }
   }
 
-  .ant-table-tbody-virtual-scrollbar {
+  :global(.ant-table-tbody-virtual-scrollbar) {
     display: none;
   }
 
-  .ant-table-cell {
+  :global(.ant-table-cell) {
     &.hidden {
       width: 0px !important;
       overflow: hidden !important;
@@ -115,7 +115,7 @@
       }
     }
 
-    .ant-table-row-expand-icon {
+    :global(.ant-table-row-expand-icon) {
       &::before {
         top: calc(50% - 0.5px);
       }
@@ -128,9 +128,9 @@
       content: none !important;
     }
 
-    .ant-checkbox {
-      &.ant-checkbox-checked {
-        .ant-checkbox-inner {
+    :global(.ant-checkbox) {
+      &:global(.ant-checkbox-checked) {
+        :global(.ant-checkbox-inner) {
           &::after {
             top: 45%;
             inset-inline-start: 25%;
@@ -147,10 +147,10 @@
   .antdTable {
     border-color: var(--cf-border-weak);
 
-    *:not(.ant-table-cell *) {
+    *:not(:global(.ant-table-cell) *) {
       border-color: inherit !important;
 
-      .ant-table-cell::after {
+      :global(.ant-table-cell)::after {
         border-color: inherit !important;
       }
     }
@@ -164,15 +164,15 @@
     }
 
     &.hideEmpty {
-      .ant-table-placeholder {
+      :global(.ant-table-placeholder) {
         display: none !important;
       }
     }
 
     &:not(.scroll) {
-      .ant-table-bordered {
-        .ant-table-container {
-          .ant-table-content {
+      :global(.ant-table-bordered) {
+        :global(.ant-table-container) {
+          :global(.ant-table-content) {
             > table {
               border-left: 1px solid var(--cf-border-weak);
             }
@@ -181,12 +181,12 @@
       }
     }
 
-    .ant-table {
+    :global(.ant-table) {
       line-height: normal;
     }
 
     &.isExpandedCellTable {
-      .ant-table-tbody {
+      :global(.ant-table-tbody) {
         tr {
           &:last-child {
             td {
@@ -196,9 +196,9 @@
         }
       }
 
-      .ant-table-bordered {
-        .ant-table-container {
-          > .ant-table-content {
+      :global(.ant-table-bordered) {
+        :global(.ant-table-container) {
+          > :global(.ant-table-content) {
             > table {
               border-radius: 0 !important;
               border-left: none !important;
@@ -212,7 +212,7 @@
                 }
               }
 
-              .ant-table-thead {
+              :global(.ant-table-thead) {
                 tr {
                   th {
                     &:first-child {
@@ -235,23 +235,23 @@
       width: 100%;
       min-height: 0px;
 
-      .ant-table-bordered {
-        .ant-table-container {
-          > .ant-table-header {
+      :global(.ant-table-bordered) {
+        :global(.ant-table-container) {
+          > :global(.ant-table-header) {
             > table {
               border-radius: 6px 6px 0 0;
               border-left: 1px solid var(--cf-border-weak);
             }
           }
 
-          > .ant-table-body {
+          > :global(.ant-table-body) {
             > table {
               border-radius: 0px !important;
               border-left: 1px solid var(--cf-border-weak);
             }
           }
 
-          > .ant-table-summary {
+          > :global(.ant-table-summary) {
             > table {
               border-radius: 0px !important;
               border-left: 1px solid var(--cf-border-weak);
@@ -262,23 +262,23 @@
       }
 
       &.isExpanded {
-        .ant-table-bordered {
-          .ant-table-container {
-            > .ant-table-header {
+        :global(.ant-table-bordered) {
+          :global(.ant-table-container) {
+            > :global(.ant-table-header) {
               > table {
                 border-radius: 0px !important;
                 border-left: none !important;
               }
             }
 
-            > .ant-table-body {
+            > :global(.ant-table-body) {
               > table {
                 border-radius: 0px !important;
                 border-left: none !important;
               }
             }
 
-            > .ant-table-summary {
+            > :global(.ant-table-summary) {
               > table {
                 border-radius: 0px !important;
                 border-left: none !important;
@@ -289,38 +289,38 @@
         }
       }
 
-      .ant-table-wrapper {
+      :global(.ant-table-wrapper) {
         width: 100%;
         height: 100%;
       }
 
-      .ant-spin-nested-loading {
+      :global(.ant-spin-nested-loading) {
         width: 100%;
         height: 100%;
 
-        .ant-spin-container {
+        :global(.ant-spin-container) {
           display: flex;
           flex-direction: column;
 
           width: 100%;
           height: 100%;
 
-          .ant-table {
+          :global(.ant-table) {
             width: 100%;
             height: 100%;
 
-            .ant-table-container {
+            :global(.ant-table-container) {
               display: flex;
               flex-direction: column;
 
               width: 100%;
               height: 100%;
 
-              > .ant-table-header {
+              > :global(.ant-table-header) {
                 min-height: max-content;
               }
 
-              > .ant-table-body {
+              > :global(.ant-table-body) {
                 position: relative;
 
                 flex: 1;
@@ -344,11 +344,11 @@
       }
 
       &.y-unScroll {
-        .ant-spin-nested-loading {
-          .ant-spin-container {
-            .ant-table {
-              .ant-table-container {
-                > .ant-table-body {
+        :global(.ant-spin-nested-loading) {
+          :global(.ant-spin-container) {
+            :global(.ant-table) {
+              :global(.ant-table-container) {
+                > :global(.ant-table-body) {
                   overflow-y: visible !important;
                 }
               }

package/src/components/Tags/index.md

@@ -8,10 +8,32 @@ title: Tags 标签
 
 # Tags 标签
 
-> `Tags` 组件。完整 API 见源码类型定义，下方为基础用法。
+基于 antd `Tag` 的标签组，支持自动配色、对齐方式，并可在容器宽度不足时自动省略并收纳超出的标签。
 
 ## 引入
 
 ```ts
 import { Tags } from "@hsu-react/ui";
 ```
+
+## 基础用法
+
+```tsx
+import React from "react";
+import { Tags } from "@hsu-react/ui";
+
+export default () => (
+  <Tags tags={["前端", "React", "TypeScript", "Ant Design", "dumi"]} />
+);
+```
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| tags | 标签内容列表 | `string[]` | `[]` |
+| colors | 自定义标签配色（按索引循环取用） | `string[]` | - |
+| ellipsis | 容器宽度不足时是否自动省略并收纳多余标签 | `boolean` | `true` |
+| align | 对齐方式 | `'left' \| 'center' \| 'right'` | `'left'` |
+| gap | 标签之间的间距 | `number` | `8` |
+| className | 自定义类名 | `string` | - |

package/src/components/TextEllipsis/index.md

@@ -8,10 +8,38 @@ title: TextEllipsis 文本省略
 
 # TextEllipsis 文本省略
 
-> `TextEllipsis` 组件。完整 API 见源码类型定义，下方为基础用法。
+文本溢出时自动省略，并通过 antd `Tooltip` 展示完整内容，支持省略号位置切换。
 
 ## 引入
 
 ```ts
 import { TextEllipsis } from "@hsu-react/ui";
 ```
+
+## 基础用法
+
+```tsx
+import React from "react";
+import { TextEllipsis } from "@hsu-react/ui";
+
+export default () => (
+  <div style={{ width: 200 }}>
+    <TextEllipsis>
+      这是一段很长的文本，当容器宽度不足以完整展示时会自动省略，并在悬停时显示完整内容。
+    </TextEllipsis>
+  </div>
+);
+```
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| children | 要显示的文本内容 | `ReactNode` | - |
+| width | 容器宽度，用于计算 Tooltip 宽度 | `number \| string` | - |
+| tooltipConfig | Tooltip 配置（可附加 `defaultWidth`） | `Omit<TooltipProps, 'title' \| 'children'> & { defaultWidth?: number }` | - |
+| disabled | 是否禁用 Tooltip（即使溢出也不显示） | `boolean` | `false` |
+| ellipsisPosition | 省略号位置，`start` 省略前面，`end` 省略后面 | `'start' \| 'end'` | `'end'` |
+| style | 文本自定义样式 | `React.CSSProperties` | - |
+| className | 文本自定义类名 | `string` | - |
+| containerStyle | 容器自定义样式 | `React.CSSProperties` | - |

package/src/components/Tree/index.md

@@ -8,10 +8,75 @@ title: Tree 树形控件
 
 # Tree 树形控件
 
-> `Tree` 组件。完整 API 见源码类型定义，下方为基础用法。
+在 antd `Tree` 之上增强：内置标题栏、搜索过滤、按层级默认展开、勾选半选自动规范化、选中路径回调与权限控制。
 
 ## 引入
 
 ```ts
 import { Tree } from "@hsu-react/ui";
 ```
+
+## 基础用法
+
+通过 `treeData` 传入树数据，开启 `search` 即可在标题栏内搜索过滤节点。
+
+```tsx
+import React from "react";
+import { Tree } from "@hsu-react/ui";
+
+const treeData = [
+  {
+    title: "华东区",
+    key: "1",
+    value: "1",
+    children: [
+      { title: "上海", key: "1-1", value: "1-1" },
+      { title: "杭州", key: "1-2", value: "1-2" },
+    ],
+  },
+  {
+    title: "华南区",
+    key: "2",
+    value: "2",
+    children: [{ title: "广州", key: "2-1", value: "2-1" }],
+  },
+];
+
+export default () => (
+  <div style={{ height: 280 }}>
+    <Tree
+      title="区域"
+      search
+      treeData={treeData}
+      defaultExpandLevel={1}
+      onSelectPath={(path) => console.log(path)}
+    />
+  </div>
+);
+```
+
+## API
+
+在 [antd TreeProps](https://ant.design/components/tree-cn)（已 `Omit` 掉 `treeData`、`loadData`、`loadedKeys`、`titleRender`）基础上扩展：
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| treeData | 树数据 | `TreeData[]` | `[]` |
+| title | 标题栏标题 | `ReactNode` | - |
+| search | 是否显示搜索框 | `boolean` | - |
+| searchProps | 搜索框（Input）属性 | `InputProps` | - |
+| titleRender | 自定义节点渲染 | `(data: TreeData) => ReactNode` | - |
+| onChange | 勾选变化回调 | `(checked: CheckedKeys) => void` | - |
+| onSelectPath | 节点选中回调，返回选中节点的完整路径 | `(path: TreeData[] \| null, selectedKeys: Key[]) => void` | - |
+| allowDeselect | 点击已选中节点时是否允许取消选中 | `boolean` | `true` |
+| defaultExpandLevel | 默认展开层级（从 1 开始） | `number` | - |
+| hideLeafExpand | 是否隐藏叶子节点的展开图标 | `boolean` | - |
+| indent | 缩进单位宽度（px） | `number` | - |
+| switchWidth | 展开/收起图标宽度（px） | `number` | - |
+| switchGap | 展开/收起图标与节点的间距（px） | `number` | - |
+| buttonGroup | 标题栏按钮组 | `ButtonProps[]` | - |
+| btnPosition | 按钮组位置 | `'left' \| 'right'` | `'right'` |
+| hasPermi | 权限码，无权限时不渲染 | `string[]` | - |
+| treeClassName / treeContainerClassName / titleClassName / titleSearchBarClassName | 各区域自定义类名 | `string` | - |
+
+`TreeData` 结构（继承 antd 节点字段）：`title`、`key`、`value`、`selectable`、`disabled`、`disableCheckbox`、`isLeaf`、`checkable`、`icon`、`children`。

package/src/components/Tree/index.module.less

@@ -56,25 +56,25 @@
     overflow-y: auto;
     scrollbar-gutter: stable;
 
-    .ant-tree-treenode {
+    :global(.ant-tree-treenode) {
       &:hover {
         background: var(--cf-subtle);
       }
 
-      &:has(> .ant-tree-node-selected) {
+      &:has(> :global(.ant-tree-node-selected)) {
         background-color: #e6f4ff;
 
-        .ant-tree-node-selected {
+        :global(.ant-tree-node-selected) {
           background-color: transparent;
         }
       }
     }
 
-    .ant-tree-indent-unit {
+    :global(.ant-tree-indent-unit) {
       width: var(--tree-indent-unit-width);
     }
 
-    .ant-tree-switcher {
+    :global(.ant-tree-switcher) {
       display: inline-flex;
       align-items: center;
       justify-content: center;
@@ -95,7 +95,7 @@
       }
     }
 
-    .ant-tree-node-content-wrapper {
+    :global(.ant-tree-node-content-wrapper) {
       display: inline-flex;
       align-items: center;
       column-gap: 4px;
@@ -105,7 +105,7 @@
 
       padding: 2px 0px;
 
-      .ant-tree-title {
+      :global(.ant-tree-title) {
         display: inline-block;
       }
 
@@ -113,7 +113,7 @@
         background: transparent;
       }
 
-      .ant-tree-iconEle {
+      :global(.ant-tree-iconEle) {
         display: inline-flex;
         align-items: center;
 
@@ -123,17 +123,17 @@
   }
 
   &.hideLeafExpand {
-    .ant-tree-switcher-noop {
+    :global(.ant-tree-switcher-noop) {
       display: none;
     }
   }
 
   &.legacyHasSelectedNodeBackground {
     .treeContainer {
-      .ant-tree-treenode.ant-tree-treenode-selected {
+      :global(.ant-tree-treenode):global(.ant-tree-treenode-selected) {
         background-color: #e6f4ff;
 
-        .ant-tree-node-selected {
+        :global(.ant-tree-node-selected) {
           background-color: transparent;
         }
       }