@hsu-react/ui 0.0.1 → 0.0.2

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/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,52 @@ 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 || "（空）"}</div>
+    </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

@@ -20,7 +20,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;
       }
     }

package/src/components/Form/index.md

@@ -8,10 +8,101 @@ title: Form 表单
 
 # Form 表单
 
-> `Form` 组件。完整 API 见源码类型定义，下方为基础用法。
+配置驱动的表单集合，通过 `formItems` 描述表单项，提供弹窗表单、抽屉表单、导入表单三种形态及 `useForm`。
 
 ## 引入
 
 ```ts
 import { Form } from "@hsu-react/ui";
 ```
+
+## 基础用法
+
+`Form` 是一个命名空间对象，常用 `Form.Modal` 渲染弹窗表单，表单项通过 `formItems` 配置。点击下方按钮试试：
+
+```tsx
+import React, { useState } from "react";
+import { Form } from "@hsu-react/ui";
+import { Button, message } from "antd";
+
+export default () => {
+  const [open, setOpen] = useState(false);
+
+  const formItems = [
+    { type: "INPUT", name: "name", label: "姓名", required: true },
+    {
+      type: "SELECT",
+      name: "role",
+      label: "角色",
+      componentProps: {
+        options: [
+          { label: "管理员", value: "admin" },
+          { label: "访客", value: "guest" },
+        ],
+      },
+    },
+    {
+      type: "INPUTNUMBER",
+      name: "age",
+      label: "年龄",
+      componentProps: { min: 0, max: 120 },
+    },
+    { type: "SWITCH", name: "enabled", label: "启用" },
+  ];
+
+  return (
+    <>
+      <Button type="primary" onClick={() => setOpen(true)}>
+        新增用户
+      </Button>
+      <Form.Modal
+        open={open}
+        title="新增用户"
+        formItems={formItems}
+        onOk={(data) => {
+          message.success("提交数据：" + JSON.stringify(data));
+          setOpen(false);
+        }}
+        onCancel={() => setOpen(false)}
+      />
+    </>
+  );
+};
+```
+
+## API
+
+`Form` 是一个对象，包含以下成员：
+
+| 成员 | 说明 | 类型 |
+| --- | --- | --- |
+| Form.Modal | 弹窗表单 | `React.FC<ModalFormProps>` |
+| Form.Drawer | 抽屉表单 | `React.FC<DrawerFormProps>` |
+| Form.Import | 导入表单（上传文件） | `React.FC<ImportFormProps>` |
+| Form.useForm | antd `Form.useForm`，创建表单实例 | `typeof AntdForm.useForm` |
+
+### Form.Modal（ModalFormProps）
+
+在 `Modal`（antd `ModalProps`，`onCancel` / `onOk` 已重写）基础上扩展：
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| formItems | 表单项配置；传对象时按分组渲染 | `FormItemProps[] \| Record<string, FormItemProps[]>` | `[]` |
+| extraFormItems | 额外的自定义表单项节点 | `ExtraFormItem[]` | - |
+| externalForm | 外部传入的表单实例 | `FormInstance` | - |
+| value | 表单回填值 | `Record<string, unknown>` | - |
+| onOk | 校验通过后的提交回调 | `(data, form: FormInstance) => void` | - |
+| onCancel | 取消回调 | `() => void` | - |
+| hasPermi | 权限码 | `string[]` | - |
+| layout / formItemLayout | 表单 / 表单项布局方向 | `'horizontal' \| 'vertical'` | - |
+| columnNum | 表单列数 | `number` | - |
+| disabled | 是否禁用整个表单 | `boolean` | - |
+| onValuesChange | 表单值变化回调 | `(value, values) => void` | - |
+
+### Form.Drawer（DrawerFormProps）
+
+在 antd `DrawerProps`（`onClose` 已重写）基础上扩展：`formItems`、`extraFormItems`、`externalForm`、`value`、`hasPermi`、`buttonGroup`（底部按钮组 `ButtonProps[]`）、`onClose`、`reset`。
+
+### Form.Import（ImportFormProps）
+
+在 `Modal`（`onCancel` / `onOk` 已重写）基础上扩展：`open`、`title`、`onCancel`、`uploadAction`（上传地址）、`template`（模板下载地址）、`templateName`、`hasPermi`、`formClassName`、`formItemClassName`、`uploadProps`。

package/src/components/FormItem/FormRadio/index.module.less

@@ -18,7 +18,7 @@
 
   &.rect {
     > label {
-      > span.ant-radio {
+      > span:global(.ant-radio) {
         width: 24px;
         min-width: 24px;
         height: 24px;
@@ -26,12 +26,12 @@
 
         border-radius: 2px;
 
-        input[type="radio"].ant-radio-input {
+        input[type="radio"]:global(.ant-radio-input) {
           width: 100%;
           height: 100%;
         }
 
-        .ant-radio-inner {
+        :global(.ant-radio-inner) {
           width: 100%;
           height: 100%;
 
@@ -65,8 +65,8 @@
           }
         }
 
-        &.ant-radio-checked {
-          .ant-radio-inner {
+        &:global(.ant-radio-checked) {
+          :global(.ant-radio-inner) {
             background: rgba(255, 255, 255, 1) !important;
 
             &::after {
@@ -77,8 +77,8 @@
           }
         }
 
-        &.ant-radio-disabled {
-          .ant-radio-inner {
+        &:global(.ant-radio-disabled) {
+          :global(.ant-radio-inner) {
             background: rgba(0, 0, 0, 0.04) !important;
 
             &::after {
@@ -86,8 +86,8 @@
             }
           }
 
-          &.ant-radio-checked {
-            .ant-radio-inner {
+          &:global(.ant-radio-checked) {
+            :global(.ant-radio-inner) {
               background: rgba(0, 0, 0, 0.04) !important;
             }
           }