@hsu-react/ui 0.0.1 → 0.0.3

package/src/components/Checkbox/index.md

@@ -8,10 +8,94 @@ title: Checkbox 多选框
 
 # Checkbox 多选框
 
-> `Checkbox` 组件。完整 API 见源码类型定义，下方为基础用法。
+基于 antd `Checkbox` 封装的多选框，额外提供 `outline` 描边样式，并附带支持全选、布局方向的 `Checkbox.Group`。
 
 ## 引入
 
 ```ts
 import { Checkbox } from "@hsu-react/ui";
 ```
+
+## 多选框
+
+```tsx
+import React from "react";
+import { Checkbox } from "@hsu-react/ui";
+
+const options = [
+  { label: "苹果", value: "apple" },
+  { label: "香蕉", value: "banana" },
+  { label: "橙子", value: "orange" },
+];
+
+export default () => {
+  const [value, setValue] = React.useState(["apple"]);
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: 12,
+        alignItems: "flex-start",
+      }}
+    >
+      <Checkbox outline>描边多选框</Checkbox>
+      <Checkbox.Group options={options} value={value} onChange={setValue} />
+    </div>
+  );
+};
+```
+
+## 多选框组
+
+多选框组，支持 `hasAll`（全选）、`layout`（排列方向）与 `outline`（描边样式）。
+
+```tsx
+import React from "react";
+import { Checkbox } from "@hsu-react/ui";
+
+const options = [
+  { label: "苹果", value: "apple" },
+  { label: "香蕉", value: "banana" },
+  { label: "橙子", value: "orange" },
+];
+
+export default () => {
+  const [value, setValue] = React.useState(["apple"]);
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+      <Checkbox.Group
+        options={options}
+        value={value}
+        onChange={setValue}
+        hasAll
+        outline
+        layout="vertical"
+      />
+    </div>
+  );
+};
+```
+
+## API
+
+### Checkbox
+
+在 [antd CheckboxProps](https://ant.design/components/checkbox-cn) 基础上扩展：
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| outline | 是否使用描边样式 | `boolean` | - |
+
+### Checkbox.Group
+
+在 antd `Checkbox.Group` 基础上扩展：
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| outline | 是否使用描边样式 | `boolean` | - |
+| hasAll | 是否显示"全选"选项 | `boolean` | - |
+| layout | 选项排列方向 | `'vertical' \| 'horizontal'` | `'horizontal'` |
+| allMaxHeight | 含全选时容器最大高度（px） | `number` | - |

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

@@ -2,8 +2,8 @@
   align-items: center;
 
   &.outline {
-    .ant-checkbox {
-      .ant-checkbox-inner {
+    :global(.ant-checkbox) {
+      :global(.ant-checkbox-inner) {
         border-color: rgba(204, 204, 204, 1) !important;
 
         background: transparent !important;
@@ -14,16 +14,16 @@
         }
       }
 
-      &.ant-checkbox-checked {
-        .ant-checkbox-inner {
+      &:global(.ant-checkbox-checked) {
+        :global(.ant-checkbox-inner) {
           background: rgba(255, 255, 255, 1) !important;
         }
       }
     }
 
-    &.ant-checkbox-wrapper-disabled {
-      .ant-checkbox {
-        .ant-checkbox-inner {
+    &:global(.ant-checkbox-wrapper-disabled) {
+      :global(.ant-checkbox) {
+        :global(.ant-checkbox-inner) {
           background: rgba(0, 0, 0, 0.04) !important;
 
           &::after {
@@ -31,8 +31,8 @@
           }
         }
 
-        &.ant-checkbox-checked {
-          .ant-checkbox-inner {
+        &:global(.ant-checkbox-checked) {
+          :global(.ant-checkbox-inner) {
             background: rgba(0, 0, 0, 0.04) !important;
           }
         }
@@ -40,7 +40,7 @@
     }
   }
 
-  .ant-checkbox {
+  :global(.ant-checkbox) {
     width: 16px;
     min-width: 16px;
     height: 16px;
@@ -48,12 +48,12 @@
 
     border-radius: 2px;
 
-    input[type="checkbox"].ant-checkbox-input {
+    input[type="checkbox"]:global(.ant-checkbox-input) {
       width: 100%;
       height: 100%;
     }
 
-    .ant-checkbox-inner {
+    :global(.ant-checkbox-inner) {
       width: 100%;
       height: 100%;
 
@@ -70,7 +70,7 @@
     }
 
     &-indeterminate {
-      .ant-checkbox-inner {
+      :global(.ant-checkbox-inner) {
         &::after {
           left: 50%;
           top: 50%;

package/src/components/CodeMirror/index.md

@@ -8,10 +8,50 @@ title: CodeMirror 代码编辑
 
 # CodeMirror 代码编辑
 
-> `CodeMirror` 组件。完整 API 见源码类型定义，下方为基础用法。
+基于 `@uiw/react-codemirror` 封装的代码编辑器，支持 SQL / JSON 语言的按需加载、语法检查与错误提示。
 
 ## 引入
 
 ```ts
 import { CodeMirror } from "@hsu-react/ui";
 ```
+
+## 代码编辑
+
+```tsx
+import React from "react";
+import { CodeMirror } from "@hsu-react/ui";
+
+export default () => {
+  const [value, setValue] = React.useState(
+    '{\n  "name": "hsu-ui",\n  "version": "1.0.0",\n  "private": true\n}'
+  );
+  const [error, setError] = React.useState(null);
+
+  return (
+    <CodeMirror
+      language="json"
+      value={value}
+      enableLint
+      hasError={!!error}
+      onChange={setValue}
+      onLintError={setError}
+    />
+  );
+};
+```
+
+## API
+
+在 [ReactCodeMirrorProps](https://uiwjs.github.io/react-codemirror/)（去除 `extensions`、`onError`）基础上扩展：
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| language | 语言类型，按需引入对应语言支持 | `'sql' \| 'json' \| 'plain'` | `'sql'` |
+| enableLint | 是否启用语法检查 | `boolean` | `true` |
+| onLintError | 错误信息回调，无错误时回调 `null` | `(error: string \| null) => void` | - |
+| hasError | 是否显示错误边框 | `boolean` | `false` |
+| translateError | 是否将错误信息翻译为中文 | `boolean` | `false` |
+| allowJsonArrayRoot | JSON 校验是否允许根节点为数组 `[...]` | `boolean` | `false` |
+
+> 其余如 `value`、`onChange`、`basicSetup`、`theme`、`minHeight` 等均继承自 `ReactCodeMirror`，默认主题为 `vscodeLight`。

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

@@ -7,17 +7,17 @@
 
   overflow: hidden;
 
-  .cm-line {
+  :global(.cm-line) {
     font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
       "Helvetica Neue", Arial, "Noto Sans", sans-serif, "Apple Color Emoji",
       "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
   }
 
-  .cm-focused {
+  :global(.cm-focused) {
     outline: none;
   }
 
-  .cm-lintRange-error {
+  :global(.cm-lintRange-error) {
     background-size: auto auto;
   }
 
@@ -28,7 +28,7 @@
       border-color: #ff4d4f;
     }
 
-    .cm-focused {
+    :global(.cm-focused) {
       border-color: #ff4d4f;
       box-shadow: 0 0 0 2px rgba(255, 77, 79, 0.2);
     }

package/src/components/Copy/index.md

@@ -16,7 +16,7 @@ title: Copy 复制
 import { Copy } from "@hsu-react/ui";
 ```
 
-## 基础用法
+## 复制
 
 ```tsx
 import React from "react";

package/src/components/DatePicker/RangePicker/index.module.less

@@ -25,7 +25,7 @@
   color: inherit;
   text-align: inherit;
 
-  .ant-picker-input {
+  :global(.ant-picker-input) {
     font-family: inherit;
     font-size: inherit;
     font-weight: inherit;

package/src/components/DatePicker/StepPicker/index.module.less

@@ -5,7 +5,7 @@
   column-gap: 5px;
 
   .icon {
-    &.ant-btn-icon-only {
+    &:global(.ant-btn-icon-only) {
       width: 32px;
       height: 32px;
     }

package/src/components/DatePicker/index.md

@@ -8,10 +8,91 @@ title: DatePicker 日期选择
 
 # DatePicker 日期选择
 
-> `DatePicker` 组件。完整 API 见源码类型定义，下方为基础用法。
+在 antd `DatePicker` 基础上扩展，支持通过下拉切换日期 / 周 / 月 / 季度 / 年等粒度，`onChange` 直接返回格式化后的字符串。
 
 ## 引入
 
 ```ts
 import { DatePicker } from "@hsu-react/ui";
 ```
+
+## 日期选择
+
+```tsx
+import React, { useState } from "react";
+import { DatePicker } from "@hsu-react/ui";
+
+export default () => {
+  const [value, setValue] = useState<string>();
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: 12,
+        alignItems: "flex-start",
+      }}
+    >
+      <DatePicker value={value} onChange={(date) => setValue(date)} />
+      <DatePicker showPicker onChange={(date, picker) => console.log(date, picker)} />
+    </div>
+  );
+};
+```
+
+## 日期范围选择
+
+区间选择，`value` / `defaultValue` 为 `string[]`，`onChange` 返回格式化后的 `string[]`，同样支持 `picker` / `showPicker` 等粒度切换。
+
+```tsx
+import React, { useState } from "react";
+import { DatePicker } from "@hsu-react/ui";
+
+export default () => {
+  const [value, setValue] = useState<string[]>();
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+      <DatePicker.RangePicker value={value} onChange={(dates) => setValue(dates)} />
+      <DatePicker.RangePicker showPicker onChange={(dates, picker) => console.log(dates, picker)} />
+    </div>
+  );
+};
+```
+
+## 步进日期选择
+
+按 `step` 步进的日期选择，支持 `picker: 'day' | 'month' | 'year'`，以及 `minDate` / `maxDate` 边界限制。
+
+```tsx
+import React, { useState } from "react";
+import { DatePicker } from "@hsu-react/ui";
+
+export default () => {
+  const [value, setValue] = useState<string>();
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+      <DatePicker.StepPicker picker="day" step={1} onChange={(date) => setValue(date)} />
+      <DatePicker.StepPicker picker="month" onChange={(date) => setValue(date)} />
+    </div>
+  );
+};
+```
+
+## API
+
+在 [antd DatePickerProps](https://ant.design/components/date-picker-cn) 基础上扩展（重写了 `picker`、`onChange`）：
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| picker | 日期选择粒度 | `'date' \| 'week' \| 'month' \| 'quarter' \| 'year' \| 'time'` | `'date'` |
+| showPicker | 是否在前方显示粒度切换下拉框 | `boolean` | `false` |
+| pickerHide | 在粒度下拉框中隐藏的选项 | `Picker[]` | `[]` |
+| pickerSelectProps | 透传给粒度下拉框的 `Select` 属性 | `SelectProps` | - |
+| pickerOptions | 自定义粒度下拉框的选项 | `SelectOption[]` | - |
+| dataPickerCls | 内部日期选择器的自定义类名 | `string` | - |
+| onChange | 值变化回调，返回格式化字符串与当前粒度 | `(date?: string, picker?: Picker) => void` | - |
+
+> 另提供 `DatePicker.RangePicker`（区间选择，`onChange` 返回 `string[]`，同样支持 `picker` / `showPicker` 等）与 `DatePicker.StepPicker`（按 `step` 步进的日期选择，支持 `picker: 'day' \| 'month' \| 'year'`、`minDate` / `maxDate`）。

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

@@ -5,6 +5,7 @@
 
   width: 100%;
   height: 100%;
+  min-height: 32px;
   max-height: max-content;
 
   border-radius: 6px;
@@ -20,7 +21,7 @@
     min-width: 80px;
   }
 
-  .ant-picker {
+  :global(.ant-picker) {
     height: 100%;
     width: 100%;
 

package/src/components/Descriptions/index.md

@@ -8,10 +8,54 @@ title: Descriptions 描述列表
 
 # Descriptions 描述列表
 
-> `Descriptions` 组件。完整 API 见源码类型定义，下方为基础用法。
+在 antd `Descriptions` 之上支持以 `columns` + `dataSource` 的方式声明式渲染，内置权限过滤、排序与标签宽度自适应。
 
 ## 引入
 
 ```ts
 import { Descriptions } from "@hsu-react/ui";
 ```
+
+## 描述列表
+
+```tsx
+import React from "react";
+import { Descriptions } from "@hsu-react/ui";
+
+export default () => (
+  <Descriptions
+    column={2}
+    columns={[
+      { title: "姓名", dataIndex: "name" },
+      { title: "年龄", dataIndex: "age" },
+      { title: "手机号", dataIndex: "phone" },
+      {
+        title: "状态",
+        dataIndex: "status",
+        render: (value) => (value === 1 ? "启用" : "停用"),
+      },
+    ]}
+    dataSource={{ name: "张三", age: 28, phone: "13800000000", status: 1 }}
+  />
+);
+```
+
+## API
+
+在 [antd DescriptionsProps](https://ant.design/components/descriptions-cn) 基础上扩展：
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| columns | 列配置，声明式描述每项内容 | `ColumnsType[]` | - |
+| dataSource | 数据源，配合 `columns` 的 `dataIndex` 取值 | `Record<string, unknown>` | `{}` |
+
+`ColumnsType` 字段：
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| title | 标签文本 | `string` | - |
+| dataIndex | 取值字段 | `string` | - |
+| hidded | 是否隐藏该项 | `boolean` | - |
+| sort | 排序权重（升序） | `number` | - |
+| hasPermi | 权限码；无权限时不渲染该项 | `string[]` | - |
+| render | 自定义渲染内容 | `(value: unknown, record: Record<string, unknown>) => ReactNode` | - |

package/src/components/Editor/index.md

@@ -8,10 +8,49 @@ title: Editor 富文本
 
 # Editor 富文本
 
-> `Editor` 组件。完整 API 见源码类型定义，下方为基础用法。
+基于 wangEditor 封装的富文本编辑器，受控输出 HTML 字符串，并提供 `Editor.Content` 用于只读展示富文本内容。
 
 ## 引入
 
 ```ts
 import { Editor } from "@hsu-react/ui";
 ```
+
+## 富文本
+
+```tsx
+import React from "react";
+import { Editor } from "@hsu-react/ui";
+
+export default () => {
+  const [html, setHtml] = React.useState(
+    "<p>这是一段<strong>富文本</strong>内容，可以编辑。</p>"
+  );
+
+  return (
+    <>
+      <Editor value={html} onChange={setHtml} height={240} />
+      {/* 只读展示 */}
+      <Editor.Content value={html} />
+    </>
+  );
+};
+```
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value | 编辑器内容（HTML 字符串） | `string` | - |
+| onChange | 内容变化回调 | `(html: string) => void` | - |
+| placeholder | 占位提示文字 | `string` | `'请输入内容...'` |
+| height | 编辑区高度（px） | `number` | `500` |
+| disabled | 是否禁用（只读，隐藏工具栏） | `boolean` | `false` |
+
+### Editor.Content
+
+只读展示组件，仅用于渲染富文本内容。
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value | 待展示的 HTML 字符串 | `string` | `''` |

package/src/components/FileCol/index.md

@@ -8,10 +8,33 @@ title: FileCol 文件列
 
 # FileCol 文件列
 
-> `FileCol` 组件。完整 API 见源码类型定义，下方为基础用法。
+展示文件列表，对支持预览的文件类型提供「查看」入口，常用于表格中的文件列。
 
 ## 引入
 
 ```ts
 import { FileCol } from "@hsu-react/ui";
 ```
+
+## 文件列
+
+```tsx
+import React from "react";
+import { FileCol } from "@hsu-react/ui";
+
+export default () => (
+  <FileCol
+    item={[
+      { uid: "1", name: "设计稿.png", url: "https://example.com/a.png" },
+      { uid: "2", name: "需求文档.pdf", url: "https://example.com/b.pdf" },
+    ]}
+  />
+);
+```
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| item | 文件列表 | `UploadFile[]` | `[]` |
+| hideNm | 是否隐藏文件名 | `boolean` | - |

package/src/components/FilePreview/index.md

@@ -8,10 +8,54 @@ title: FilePreview 文件预览
 
 # FilePreview 文件预览
 
-> `FilePreview` 组件。完整 API 见源码类型定义，下方为基础用法。
+根据文件类型展示对应预览（视频、PDF、图片、文本、Markdown、Excel），通过 `open` 控制显隐。
 
 ## 引入
 
 ```ts
 import { FilePreview } from "@hsu-react/ui";
 ```
+
+## 文件预览
+
+文本 / Markdown 类型通过 `text` 传入内容，无需远程地址即可预览；视频 / PDF / 图片 / Excel 类型则通过 `fileUrl` 传入文件地址。
+
+```tsx
+import React, { useState } from "react";
+import { FilePreview } from "@hsu-react/ui";
+import { Button } from "antd";
+
+export default () => {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <Button type="primary" onClick={() => setOpen(true)}>
+        预览文本
+      </Button>
+      <FilePreview
+        open={open}
+        fileType="txt"
+        fileName="说明.txt"
+        text={"第一行：这是一段示例文本内容。\n第二行：点击右上角关闭按钮可退出预览。\n第三行：txt / md 类型通过 text 传入，无需网络请求。"}
+        onClose={() => setOpen(false)}
+      />
+    </>
+  );
+};
+```
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| open | 是否展示预览（为 `false` 时不渲染） | `boolean` | - |
+| fileType | 文件类型，决定使用哪种预览器 | `'mp4' \| 'pdf' \| 'jpg' \| 'jpeg' \| 'png' \| 'gif' \| 'txt' \| 'md' \| 'xlsx' \| string` | - |
+| fileUrl | 文件地址（视频/PDF/图片/Excel） | `string` | - |
+| fileName | 文件名 | `string` | - |
+| text | 文本内容（`txt` / `md` 类型使用） | `string` | - |
+| pagination | PDF 是否显示分页 | `boolean` | - |
+| className | 自定义类名 | `string` | - |
+| onClose | 关闭回调 | `() => void` | - |
+
+> 另导出类型 `FilePreviewType` 与常量 `FilePreviewTypeArr`（支持的文件类型数组）。

package/src/components/FlexFill/index.md

@@ -8,10 +8,55 @@ title: FlexFill 自适应填充
 
 # FlexFill 自适应填充
 
-> `FlexFill` 组件。完整 API 见源码类型定义，下方为基础用法。
+在 `flex` + `justify-content: space-between` 的多行弹性布局中，用于占位补齐最后一行，避免末行元素被两端对齐拉散。组件渲染 10 个高度近似为 0 的占位块。
 
 ## 引入
 
 ```ts
 import { FlexFill } from "@hsu-react/ui";
 ```
+
+## 自适应填充
+
+将 `FlexFill` 放在弹性容器的子元素末尾，即可让最后一行的卡片按正常间距左对齐排列。
+
+```tsx
+import React from "react";
+import { FlexFill } from "@hsu-react/ui";
+
+export default () => (
+  <div
+    style={{
+      display: "flex",
+      flexWrap: "wrap",
+      justifyContent: "space-between",
+      gap: "12px 0",
+    }}
+  >
+    {[1, 2, 3, 4, 5].map((item) => (
+      <div
+        key={item}
+        style={{
+          width: 120,
+          height: 60,
+          lineHeight: "60px",
+          textAlign: "center",
+          background: "#f0f2f5",
+          borderRadius: 8,
+        }}
+      >
+        卡片 {item}
+      </div>
+    ))}
+    <FlexFill width="120px" />
+  </div>
+);
+```
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| width | 单个占位块的宽度，通常与列表项宽度保持一致 | `string` | `'100%'` |
+| className | 占位块的自定义类名 | `string` | - |
+| style | 占位块的自定义样式（支持 CSS 变量） | `CSSProperties` | - |

package/src/components/Form/DrawerForm/index.module.less

@@ -1,5 +1,5 @@
 .DrawerForm {
-  .ant-drawer-title {
+  :global(.ant-drawer-title) {
     display: flex;
     align-items: center;
     justify-content: space-between;
@@ -43,7 +43,7 @@
       align-items: center;
       column-gap: 10px;
 
-      .ant-btn-icon {
+      :global(.ant-btn-icon) {
         font-size: 16px;
       }
     }