@hsu-react/ui 0.0.1 → 0.0.2

package/src/components/Select/index.md

@@ -8,10 +8,56 @@ title: Select 选择器
 
 # Select 选择器
 
-> `Select` 组件。完整 API 见源码类型定义，下方为基础用法。
+基于 antd `Select` 封装的选择器，默认开启搜索与清除，支持前后缀、箭头动画、下拉宽度自适应内容、`label` 与 `value` 组合展示，并对中文输入法搜索做了优化。
 
 ## 引入
 
 ```ts
 import { Select } from "@hsu-react/ui";
 ```
+
+## 基础用法
+
+```tsx
+import React from "react";
+import { Select } from "@hsu-react/ui";
+
+const options = [
+  { label: "苹果", value: "apple" },
+  { label: "香蕉", value: "banana" },
+  { label: "橙子", value: "orange" },
+];
+
+export default () => {
+  const [value, setValue] = React.useState("apple");
+
+  return (
+    <Select
+      style={{ width: 200 }}
+      options={options}
+      value={value}
+      onChange={setValue}
+      placeholder="请选择"
+    />
+  );
+};
+```
+
+## API
+
+在 [antd SelectProps](https://ant.design/components/select-cn) 基础上扩展（移除了 `placement`、`filterOption` 并重新定义）：
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| options | 选项数据 | `SelectOption[]` | `[]` |
+| prefix | 选择框前缀内容 | `ReactNode` | - |
+| suffix | 选择框后缀内容 | `ReactNode` | - |
+| selectClassName | 内层 antd Select 的类名 | `string` | - |
+| arrowAnimation | 是否启用箭头展开动画 | `boolean` | `true` |
+| popupMatchContentWidth | 下拉面板宽度是否自适应内容 | `boolean` | - |
+| placement | 下拉弹出位置 | `'bottomLeft' \| 'topLeft'` | `'bottomLeft'` |
+| filterOption | 自定义搜索过滤 | `(searchValue: string, option?: DefaultOptionType) => boolean` | - |
+| optionFontSize | 选项字体大小，用于计算自适应宽度 | `number` | `14` |
+| valueInlabel | 在标签/选项中同时展示 value 的位置 | `'before' \| 'after'` | - |
+
+> `SelectOption` 形如 `{ label: string; value: number \| string; disabled?: boolean }`，并可携带额外字段。

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

@@ -30,11 +30,11 @@
     .antdSelect {
       cursor: not-allowed;
 
-      .ant-select-selection-item {
+      :global(.ant-select-selection-item) {
         color: var(--cf-text-3);
       }
 
-      .ant-select-arrow {
+      :global(.ant-select-arrow) {
         cursor: not-allowed;
       }
     }
@@ -77,7 +77,7 @@
     margin-inline-start: 4px;
   }
 
-  &:has(> .ant-select-status-error) {
+  &:has(> :global(.ant-select-status-error)) {
     border: 1px solid #ff4d4f;
 
     .prefix,
@@ -113,20 +113,20 @@
     font-weight: inherit;
     color: inherit !important;
 
-    &:has(> .ant-select-arrow),
-    &:has(> .ant-select-clear) {
-      .ant-select-selector {
+    &:has(> :global(.ant-select-arrow)),
+    &:has(> :global(.ant-select-clear)) {
+      :global(.ant-select-selector) {
         padding-right: 20px;
       }
     }
 
     &.legacyHasArrowOrClear {
-      .ant-select-selector {
+      :global(.ant-select-selector) {
         padding-right: 20px;
       }
     }
 
-    .ant-select-selector {
+    :global(.ant-select-selector) {
       width: 100%;
       height: 100%;
       padding: 0;
@@ -145,7 +145,7 @@
         content: none;
       }
 
-      .ant-select-selection-wrap {
+      :global(.ant-select-selection-wrap) {
         height: 100%;
 
         font-family: inherit;
@@ -154,7 +154,7 @@
         color: inherit;
       }
 
-      .ant-select-selection-search {
+      :global(.ant-select-selection-search) {
         inset-inline-start: 0px;
         inset-inline-end: 0px;
 
@@ -173,7 +173,7 @@
         }
       }
 
-      .ant-select-selection-placeholder {
+      :global(.ant-select-selection-placeholder) {
         display: inline-flex;
         align-items: center;
 
@@ -185,7 +185,7 @@
         font-weight: inherit;
       }
 
-      .ant-select-selection-item {
+      :global(.ant-select-selection-item) {
         padding-inline-end: 0px;
 
         font-family: inherit;
@@ -194,8 +194,8 @@
         color: inherit;
       }
 
-      .ant-select-selection-overflow-item {
-        .ant-select-selection-item {
+      :global(.ant-select-selection-overflow-item) {
+        :global(.ant-select-selection-item) {
           line-height: normal;
 
           padding-inline-end: 4px;
@@ -203,34 +203,34 @@
       }
     }
 
-    &.ant-select-focused {
-      .ant-select-selector {
+    &:global(.ant-select-focused) {
+      :global(.ant-select-selector) {
         border: none !important;
 
         box-shadow: none !important;
       }
     }
 
-    &.ant-select-open {
-      .ant-select-arrow {
+    &:global(.ant-select-open) {
+      :global(.ant-select-arrow) {
         transform: rotate(-180deg) translateY(50%);
       }
 
       &.noArrowAnimation {
-        .ant-select-arrow {
+        :global(.ant-select-arrow) {
           transform: translateY(-50%);
           transition: none !important;
         }
       }
     }
 
-    &.ant-select-status-error {
-      .ant-select-selector {
+    &:global(.ant-select-status-error) {
+      :global(.ant-select-selector) {
         border: none !important;
       }
     }
 
-    .ant-select-arrow {
+    :global(.ant-select-arrow) {
       width: 14px;
       height: 14px;
       margin-top: 0px;
@@ -244,7 +244,7 @@
       pointer-events: all;
     }
 
-    .ant-select-clear {
+    :global(.ant-select-clear) {
       width: 14px;
       height: 14px;
       margin-top: 0px;
@@ -256,17 +256,17 @@
       inset-inline-end: 0px;
     }
 
-    &.ant-select-multiple {
-      > .ant-select-selector {
-        > .ant-select-selection-overflow {
-          .ant-select-selection-search {
+    &:global(.ant-select-multiple) {
+      > :global(.ant-select-selector) {
+        > :global(.ant-select-selection-overflow) {
+          :global(.ant-select-selection-search) {
             width: 0px !important;
 
             margin-inline-start: 0px;
           }
         }
 
-        > .ant-select-selection-placeholder {
+        > :global(.ant-select-selection-placeholder) {
           inset-inline-start: 0px;
         }
       }
@@ -274,14 +274,14 @@
   }
 
   &.popupMatchContentWidth {
-    .ant-select-dropdown {
+    :global(.ant-select-dropdown) {
       [class="rc-virtual-list-holder-inner"] {
         position: relative !important;
       }
     }
   }
 
-  .ant-select-dropdown {
+  :global(.ant-select-dropdown) {
     position: fixed;
 
     font-family: inherit;
@@ -291,7 +291,7 @@
 
     border-radius: inherit;
 
-    .ant-select-item {
+    :global(.ant-select-item) {
       font-family: inherit;
       font-size: inherit;
       font-weight: inherit;
@@ -300,9 +300,9 @@
       border-radius: inherit;
     }
 
-    .ant-select-item-empty,
-    .ant-empty,
-    .ant-empty-description {
+    :global(.ant-select-item-empty),
+    :global(.ant-empty),
+    :global(.ant-empty-description) {
       font-family: inherit;
       font-size: inherit;
       font-weight: inherit;

package/src/components/Slider/index.md

@@ -8,10 +8,38 @@ title: Slider 滑动输入
 
 # Slider 滑动输入
 
-> `Slider` 组件。完整 API 见源码类型定义，下方为基础用法。
+基于 antd 单值 `Slider` 封装的滑动输入条，内部维护受控值、默认关闭 Tooltip，并支持通过 `topValue` 从外部强制更新当前值。
 
 ## 引入
 
 ```ts
 import { Slider } from "@hsu-react/ui";
 ```
+
+## 基础用法
+
+```tsx
+import React from "react";
+import { Slider } from "@hsu-react/ui";
+
+export default () => {
+  const [value, setValue] = React.useState(30);
+
+  return (
+    <div style={{ width: 240 }}>
+      <Slider value={value} onChange={setValue} />
+      <div style={{ marginTop: 12 }}>当前值：{value}</div>
+    </div>
+  );
+};
+```
+
+## API
+
+在 [antd SliderSingleProps](https://ant.design/components/slider-cn) 基础上扩展：
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| topValue | 外部强制同步的当前值，优先级高于 `value` | `number` | - |
+| value | 当前值 | `number` | `0` |
+| onChange | 值变化回调 | `(value: number) => void` | - |

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

@@ -6,14 +6,14 @@
   overflow-x: hidden;
   overflow-y: visible;
 
-  .ant-slider-step,
-  .ant-slider-track,
-  .ant-slider-rail {
+  :global(.ant-slider-step),
+  :global(.ant-slider-track),
+  :global(.ant-slider-rail) {
     top: 0px;
     height: 100% !important;
   }
 
-  .ant-slider-handle {
+  :global(.ant-slider-handle) {
     position: relative;
     top: 50%;
     transform: translate(calc(-50% - 4px), calc(-50% + 1px)) !important;

package/src/components/Spreadsheet/index.md

@@ -8,10 +8,51 @@ title: Spreadsheet 电子表格
 
 # Spreadsheet 电子表格
 
-> `Spreadsheet` 组件。完整 API 见源码类型定义，下方为基础用法。
+基于 `x-data-spreadsheet` 封装的电子表格组件，接收 `xlsx` 的 `WorkBook` 数据并自动转换为表格内容渲染。
 
 ## 引入
 
 ```ts
 import { Spreadsheet } from "@hsu-react/ui";
 ```
+
+## 基础用法
+
+```tsx
+import React from "react";
+import { Spreadsheet } from "@hsu-react/ui";
+import { utils } from "xlsx";
+
+// 用 xlsx 工具构建一个 WorkBook（实际项目中通常由 read() 读取文件得到）
+const aoa = [
+  ["姓名", "部门", "工资"],
+  ["张三", "研发部", 12000],
+  ["李四", "市场部", 9500],
+  ["王五", "财务部", 8800],
+];
+const ws = utils.aoa_to_sheet(aoa);
+const workbook = utils.book_new();
+utils.book_append_sheet(workbook, ws, "员工表");
+
+export default () => (
+  <div style={{ height: 320, width: "100%" }}>
+    <Spreadsheet data={workbook} xOptions={{ showBottomTool: true }} />
+  </div>
+);
+```
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| data | 表格数据，xlsx 的 `WorkBook` 对象 | `WorkBook` | - |
+| xOptions | x-data-spreadsheet 配置项（在其 `Options` 基础上扩展，已忽略 `view`） | `XOptions` | `{}` |
+| className | 容器类名 | `string` | - |
+
+### XOptions
+
+继承 x-data-spreadsheet 的 `Options`（`view` 由组件内部接管），并扩展：
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| showBottomTool | 是否显示底部工具栏（sheet 切换栏） | `boolean` | `true` |

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

@@ -4,8 +4,8 @@
 
   overflow: hidden;
 
-  .x-spreadsheet-toolbar,
-  .x-spreadsheet-bottombar {
+  :global(.x-spreadsheet-toolbar),
+  :global(.x-spreadsheet-bottombar) {
     width: 100% !important;
   }
 
@@ -13,14 +13,14 @@
     background-size: auto;
   }
 
-  .x-spreadsheet-menu {
+  :global(.x-spreadsheet-menu) {
     > li:first-child {
       display: none;
     }
   }
 
   &.showBottomTool {
-    .x-spreadsheet-menu {
+    :global(.x-spreadsheet-menu) {
       > li:first-child {
         display: list-item;
       }

package/src/components/Switch/index.md

@@ -8,10 +8,42 @@ title: Switch 开关
 
 # Switch 开关
 
-> `Switch` 组件。完整 API 见源码类型定义，下方为基础用法。
+基于 antd `Switch` 封装的开关，可通过 `options` 配合 `trueValue`/`falseValue` 自动生成开启与关闭状态的文案。
 
 ## 引入
 
 ```ts
 import { Switch } from "@hsu-react/ui";
 ```
+
+## 基础用法
+
+```tsx
+import React from "react";
+import { Switch } from "@hsu-react/ui";
+
+const options = [
+  { label: "启用", value: 1 },
+  { label: "停用", value: 0 },
+];
+
+export default () => (
+  <div style={{ display: "flex", gap: 16, alignItems: "center" }}>
+    <Switch defaultChecked />
+    <Switch options={options} trueValue={1} falseValue={0} defaultChecked />
+    <Switch disabled />
+  </div>
+);
+```
+
+## API
+
+在 [antd SwitchProps](https://ant.design/components/switch-cn) 基础上扩展：
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| options | 选项数据，用于匹配选中/未选中文案 | `SelectOption[]` | - |
+| trueValue | 开启状态对应的 value，从 `options` 中取其 `label` 作为 `checkedChildren` | `number \| string` | - |
+| falseValue | 关闭状态对应的 value，从 `options` 中取其 `label` 作为 `unCheckedChildren` | `number \| string` | - |
+
+> 若直接传入 `checkedChildren` / `unCheckedChildren`，则优先使用传入值。

package/src/components/TabBar/index.md

@@ -8,10 +8,62 @@ title: TabBar 标签栏
 
 # TabBar 标签栏
 
-> `TabBar` 组件。完整 API 见源码类型定义，下方为基础用法。
+轻量级标签切换栏，支持受控/非受控、`default` 与 `outline` 两种样式，并可结合路由实现页签跳转。
 
 ## 引入
 
 ```ts
 import { TabBar } from "@hsu-react/ui";
 ```
+
+## 基础用法
+
+通过 `tabGroup` 配置页签，`onTabChange` 监听切换。
+
+```tsx
+import React, { useState } from "react";
+import { TabBar } from "@hsu-react/ui";
+
+export default () => {
+  const [tab, setTab] = useState<string | number>("1");
+
+  const tabGroup = [
+    { title: "全部", key: "1" },
+    { title: "进行中", key: "2" },
+    { title: "已完成", key: "3" },
+  ];
+
+  return (
+    <div>
+      <TabBar tabGroup={tabGroup} tab={tab} onTabChange={setTab} />
+      <TabBar
+        variant="outline"
+        tabGroup={tabGroup}
+        defaultTab="1"
+        className="demo-tabbar-outline"
+      />
+      <p style={{ marginTop: 12 }}>当前选中：{tab}</p>
+    </div>
+  );
+};
+```
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| tabGroup | 页签数据 | `TabGroup[]` | - |
+| tab | 受控选中项的 key | `string \| number` | - |
+| defaultTab | 默认选中项的 key（非受控） | `string \| number` | - |
+| onTabChange | 切换页签时触发 | `(key: string \| number) => void` | - |
+| variant | 样式风格 | `'default' \| 'outline'` | `'default'` |
+| router | 是否在切换时按 key 进行路由跳转 | `boolean` | - |
+| className | 自定义类名 | `string` | - |
+
+`TabGroup` 结构：
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| title | 页签标题 | `string` | - |
+| key | 页签唯一标识 | `string \| number` | - |
+| onClick | 点击该页签时的回调 | `() => void` | - |

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

@@ -4,11 +4,11 @@
   justify-content: flex-end;
   column-gap: 8px;
 
-  &.ant-pagination-start {
+  &:global(.ant-pagination-start) {
     justify-content: flex-start;
   }
 
-  &.ant-pagination-center {
+  &:global(.ant-pagination-center) {
     justify-content: center;
   }
 
@@ -25,10 +25,10 @@
       width: 100%;
       height: 100%;
 
-      .ant-pagination-item-container {
+      :global(.ant-pagination-item-container) {
         width: 100%;
 
-        .ant-pagination-item-ellipsis {
+        :global(.ant-pagination-item-ellipsis) {
           width: 100%;
         }
       }
@@ -40,17 +40,17 @@
       justify-content: center;
     }
 
-    &.ant-pagination-options {
-      .ant-pagination-options-size-changer,
-      .ant-pagination-options-quick-jumper {
+    &:global(.ant-pagination-options) {
+      :global(.ant-pagination-options-size-changer),
+      :global(.ant-pagination-options-quick-jumper) {
         height: 100% !important;
       }
 
-      .ant-pagination-options-size-changer {
-        .ant-select-selector {
+      :global(.ant-pagination-options-size-changer) {
+        :global(.ant-select-selector) {
           height: 100% !important;
 
-          .ant-select-selection-item {
+          :global(.ant-select-selection-item) {
             display: flex;
             align-items: center;
 
@@ -58,14 +58,14 @@
           }
         }
 
-        .ant-select-arrow {
+        :global(.ant-select-arrow) {
           margin-top: 0px;
 
           transform: translateY(-50%);
         }
       }
 
-      .ant-pagination-options-quick-jumper {
+      :global(.ant-pagination-options-quick-jumper) {
         display: inline-flex;
         align-items: center;
 
@@ -78,18 +78,18 @@
 
   &.bordered {
     > li {
-      &:not(.ant-pagination-options):not(.ant-pagination-total-text) {
+      &:not(:global(.ant-pagination-options)):not(:global(.ant-pagination-total-text)) {
         border: 1px solid var(--cf-border);
         border-radius: 4px;
       }
 
-      &.ant-pagination-item {
+      &:global(.ant-pagination-item) {
         margin: 0px 4px 0px 0px;
 
-        &:not(.ant-pagination-item-active):not(
-            .ant-pagination-item-disabled
+        &:not(:global(.ant-pagination-item-active)):not(
+            :global(.ant-pagination-item-disabled)
           ):hover,
-        &.ant-pagination-item-active {
+        &:global(.ant-pagination-item-active) {
           background-color: var(--primary-color, #1890ff);
           border-color: var(--primary-color, #1890ff);
 
@@ -98,11 +98,11 @@
           }
         }
 
-        &:not(.ant-pagination-item-active):not(.ant-pagination-item-disabled) {
+        &:not(:global(.ant-pagination-item-active)):not(:global(.ant-pagination-item-disabled)) {
           border-color: var(--cf-border);
         }
 
-        &:not(.ant-pagination-item-active).ant-pagination-item-disabled {
+        &:not(:global(.ant-pagination-item-active)):global(.ant-pagination-item-disabled) {
           cursor: not-allowed;
 
           &:hover {
@@ -117,16 +117,16 @@
         }
       }
 
-      &.ant-pagination-prev {
+      &:global(.ant-pagination-prev) {
         margin-right: 4px;
       }
 
-      &.ant-pagination-options {
+      &:global(.ant-pagination-options) {
         margin-left: 4px;
       }
 
-      &.ant-pagination-jump-next,
-      &.ant-pagination-jump-prev {
+      &:global(.ant-pagination-jump-next),
+      &:global(.ant-pagination-jump-prev) {
         margin-right: 4px;
       }
     }