@hsu-react/ui 0.0.1 → 0.0.3

package/src/components/Panel/index.md

@@ -8,10 +8,202 @@ title: Panel 页面容器
 
 # Panel 页面容器
 
-> `Panel` 组件。完整 API 见源码类型定义，下方为基础用法。
+页面级容器集合，封装了「左侧树 + 顶部搜索 + 表格」的列表页、内嵌 iframe 页以及通用内容页等常见布局形态。
 
 ## 引入
 
 ```ts
 import { Panel } from "@hsu-react/ui";
 ```
+
+## 子组件一览
+
+| 组件 | 说明 |
+| --- | --- |
+| `Panel.List` | 列表页容器，集成 `Search`、`Table`、`TabBar`、`Tree`、列管理与工具栏 |
+| `Panel.List.Modal` | 弹窗内的列表页容器，用于在 `Modal` 中复用列表布局 |
+| `Panel.Iframe` | iframe 内容容器，带加载态与全屏按钮 |
+| `Panel.Default` | 通用内容容器，可选左侧树与面包屑 |
+
+## 列表页
+
+`Panel.List` 通过 `searchProps`（搜索区）、`tableProps`（表格区）组合出标准增删改查列表页。下方为可交互示例：输入姓名搜索会实时过滤行，点击「新增」「编辑」有反馈。
+
+```tsx
+import React, { useState } from "react";
+import { Panel, Button } from "@hsu-react/ui";
+import { message } from "antd";
+
+const ALL = [
+  { id: 1, name: "张三", role: "管理员", status: "启用" },
+  { id: 2, name: "李四", role: "成员", status: "启用" },
+  { id: 3, name: "王五", role: "成员", status: "禁用" },
+];
+
+export default () => {
+  const [data, setData] = useState(ALL);
+
+  const columns = [
+    { title: "姓名", dataIndex: "name" },
+    { title: "角色", dataIndex: "role" },
+    { title: "状态", dataIndex: "status" },
+    {
+      title: "操作",
+      dataIndex: "op",
+      render: (_, row) => (
+        <Button type="link" onClick={() => message.info("编辑：" + row.name)}>
+          编辑
+        </Button>
+      ),
+    },
+  ];
+
+  return (
+    // Panel.List 为页面级宽组件；窄屏时外层横向滚动，避免溢出预览框。
+    // overflowY:hidden 去掉垂直滚动条；wrapperClassName 放开组件内层
+    // ListPanelWrapper 的 overflow:hidden（否则搜索区右侧约 24px 会被裁）。
+    <div style={{ overflowX: "auto", overflowY: "hidden" }}>
+      <div style={{ minWidth: 1000, height: 300 }}>
+        <Panel.List
+          wrapperClassName="hsu-demo-panel-wrapper"
+          searchProps={{
+            searchItems: [{ type: "INPUT", name: "name", label: "姓名" }],
+            onSearch: (v) =>
+              setData(ALL.filter((x) => !v.name || x.name.includes(v.name))),
+            onReset: () => setData(ALL),
+            beforeButtonGroup: [
+              {
+                title: "新增",
+                colorPalette: "blue",
+                onClick: () => message.success("点击了新增"),
+              },
+            ],
+          }}
+          tableProps={{
+            columns,
+            dataSource: data,
+            rowKey: "id",
+            pagination: false,
+            scrollAutoHeight: false,
+          }}
+        />
+      </div>
+    </div>
+  );
+};
+```
+
+## 内容页
+
+```tsx
+import React from "react";
+import { Panel } from "@hsu-react/ui";
+
+export default () => (
+  // 与列表页一致：外层 overflowX 横向滚动 + overflowY:hidden 去垂直滚动条；
+  // wrapperClassName 放开 DefaultPanel 内层的 overflow:hidden。
+  <div style={{ overflowX: "auto", overflowY: "hidden" }}>
+    <div style={{ minWidth: 1000, height: 200 }}>
+      <Panel.Default wrapperClassName="hsu-demo-panel-wrapper">
+        <div style={{ padding: 16 }}>这里是通用内容区域（窄屏时可横向滚动查看）</div>
+      </Panel.Default>
+    </div>
+  </div>
+);
+```
+
+## 内嵌页
+
+`Panel.Iframe` 用于内嵌外部页面，带加载态与全屏按钮（外部站点受 X-Frame-Options 限制，此处仅示意用法）：
+
+```tsx | pure
+import React from "react";
+import { Panel } from "@hsu-react/ui";
+
+export default () => <Panel.Iframe src="https://example.com" fullBtn />;
+```
+
+## 弹窗内列表
+
+`Panel.List.Modal` 在 `Modal` 内复用列表布局，本身继承 `ModalProps`（`open` / `onClose` 等），并通过 `searchProps`、`tableProps` 配置搜索区与表格区。常用于从某条记录弹出其关联子列表。
+
+```tsx
+import React, { useState } from "react";
+import { Panel, Button } from "@hsu-react/ui";
+
+const ALL = [
+  { id: 1, name: "明细一", status: "启用" },
+  { id: 2, name: "明细二", status: "禁用" },
+];
+
+export default () => {
+  const [open, setOpen] = useState(false);
+  const [data, setData] = useState(ALL);
+
+  return (
+    <>
+      <Button type="primary" onClick={() => setOpen(true)}>
+        打开子列表
+      </Button>
+      <Panel.List.Modal
+        open={open}
+        onCancel={() => setOpen(false)}
+        title="关联明细"
+        footer={null}
+        searchProps={{
+          searchItems: [{ type: "INPUT", name: "name", label: "名称" }],
+          onSearch: (v) =>
+            setData(ALL.filter((x) => !v.name || x.name.includes(v.name))),
+          onReset: () => setData(ALL),
+        }}
+        tableProps={{
+          columns: [
+            { title: "名称", dataIndex: "name" },
+            { title: "状态", dataIndex: "status" },
+          ],
+          dataSource: data,
+          rowKey: "id",
+          pagination: false,
+        }}
+      />
+    </>
+  );
+};
+```
+
+## API
+
+### Panel.List（ListPanelProps）
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| searchMode | Search 组件模式：`Default` / `Advanced` / `Collapsible` / `WithFilter` / `WithMore` / `Card` | `SearchModeKeys` | `'Default'` |
+| searchProps | 搜索区配置（随 `searchMode` 变化） | `SearchModePropsMap[T]` | - |
+| tableProps | 表格区配置，含 `title`、`buttonGroup`、`tabBarProps`、`tableTools` 等 | `ListPanelTabelProps` | - |
+| treeProps | 左侧树配置 | `TreeProps` | - |
+| headerTabBarProps | 顶部页签配置 | `TabBarProps` | - |
+| headerTabBarChildren | 顶部页签区自定义内容 | `ReactNode` | - |
+| hasPermi | 权限码，无权限时不渲染 | `string[]` | - |
+| baseTreeBreadcrumb | 树面包屑的基础项 | `BreadcrumbProps['items']` | - |
+| showTreeBreadcrumb | 是否展示树面包屑 | `boolean` | `true` |
+| treeResize | 左侧树可拖拽调宽配置（`enabled`/`defaultWidth`/`minWidth`/`maxWidth`/`minContentWidth`） | `object` | - |
+| className / wrapperClassName | 自定义类名 | `string` | - |
+
+### Panel.Iframe（IframePanelProps）
+
+继承原生 `<iframe>` 属性，并扩展：
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| fullBtn | 是否显示全屏按钮 | `boolean` | - |
+| children | 自定义内容（传入后替代 iframe 渲染） | `ReactNode` | - |
+
+### Panel.Default（DefaultPanelProps）
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| children | 内容区 | `ReactNode` | - |
+| treeProps | 左侧树配置（传入即展示树） | `TreeProps` | - |
+| baseTreeBreadcrumb | 树面包屑的基础项 | `BreadcrumbProps['items']` | - |
+| showTreeBreadcrumb | 是否展示树面包屑 | `boolean` | `true` |
+| className / contentClassName / wrapperClassName | 自定义类名 | `string` | - |

package/src/components/Search/index.md

@@ -8,10 +8,257 @@ title: Search 搜索
 
 # Search 搜索
 
-> `Search` 组件。完整 API 见源码类型定义，下方为基础用法。
+配置驱动的搜索栏组件，通过 `searchItems` 描述搜索项，内置查询 / 重置按钮、列自适应与展开收起能力。
 
 ## 引入
 
 ```ts
 import { Search } from "@hsu-react/ui";
 ```
+
+## 搜索
+
+`Search` 通过 `searchItems`（复用 `FormItem` 的配置）定义搜索项，`onSearch` / `onReset` 接收回调：
+
+```tsx
+import React from "react";
+import { Search } from "@hsu-react/ui";
+
+export default () => {
+  return (
+    <>
+      <Search
+        columnNum={3}
+        searchItems={[
+          { type: "INPUT", name: "keyword", label: "关键字" },
+          {
+            type: "SELECT",
+            name: "status",
+            label: "状态",
+            componentProps: {
+              options: [
+                { label: "启用", value: 1 },
+                { label: "停用", value: 0 },
+              ],
+            },
+          },
+          { type: "RANGEPICKER", name: "date", label: "时间范围" },
+        ]}
+        onSearch={(data) => console.log("search", data)}
+        onReset={() => console.log("reset")}
+      />
+    </>
+  );
+};
+```
+
+`Search` 在基础形态外，额外提供多种搜索形态。除 `Search.Card` 使用 `options` 配置外，其余均复用 `searchItems`（`FormItemProps[]`）+ `onSearch` / `onReset`。
+
+## 高级筛选
+
+不显示标签，通过抽屉承载更多筛选项；配合 `setFilter` 可显示筛选项下拉。
+
+```tsx
+import React from "react";
+import { Search } from "@hsu-react/ui";
+
+export default () => (
+  <>
+    <Search.Advanced
+      columnNum={3}
+      setFilter
+      searchItems={[
+        { type: "INPUT", name: "name", label: "姓名" },
+        {
+          type: "SELECT",
+          name: "status",
+          label: "状态",
+          componentProps: {
+            options: [
+              { label: "启用", value: 1 },
+              { label: "禁用", value: 0 },
+            ],
+          },
+        },
+      ]}
+      moreSearchItems={[{ type: "INPUT", name: "remark", label: "备注" }]}
+      onSearch={(data) => console.log("search", data)}
+      onReset={() => console.log("reset")}
+    />
+  </>
+);
+```
+
+## 可折叠搜索
+
+整块搜索区可折叠 / 展开，通过 `defaultExpanded` 控制初始状态，`onCollapseToggle` 监听折叠变化。
+
+```tsx
+import React from "react";
+import { Search } from "@hsu-react/ui";
+
+export default () => (
+  <>
+    <Search.Collapsible
+      columnNum={3}
+      defaultExpanded
+      searchItems={[
+        { type: "INPUT", name: "name", label: "姓名" },
+        {
+          type: "SELECT",
+          name: "status",
+          label: "状态",
+          componentProps: {
+            options: [
+              { label: "启用", value: 1 },
+              { label: "禁用", value: 0 },
+            ],
+          },
+        },
+      ]}
+      onCollapseToggle={(c) => console.log("collapse", c)}
+      onSearch={(data) => console.log("search", data)}
+      onReset={() => console.log("reset")}
+    />
+  </>
+);
+```
+
+## 带筛选器搜索
+
+在按钮组旁内置筛选下拉，允许用户动态勾选要显示的搜索项，`onFilterChange` 接收勾选变化。
+
+```tsx
+import React from "react";
+import { Search } from "@hsu-react/ui";
+
+export default () => (
+  <>
+    <Search.WithFilter
+      columnNum={3}
+      searchItems={[
+        { type: "INPUT", name: "name", label: "姓名" },
+        {
+          type: "SELECT",
+          name: "status",
+          label: "状态",
+          componentProps: {
+            options: [
+              { label: "启用", value: 1 },
+              { label: "禁用", value: 0 },
+            ],
+          },
+        },
+        { type: "INPUT", name: "phone", label: "电话" },
+      ]}
+      onFilterChange={(items) => console.log("filter", items)}
+      onSearch={(data) => console.log("search", data)}
+      onReset={() => console.log("reset")}
+    />
+  </>
+);
+```
+
+## 带更多项搜索
+
+把搜索项分为基础项（`searchItems`）与更多项（`moreSearchItems`，必填），始终展示全部并提供展开收起。
+
+```tsx
+import React from "react";
+import { Search } from "@hsu-react/ui";
+
+export default () => (
+  <>
+    <Search.WithMore
+      columnNum={3}
+      searchItems={[
+        { type: "INPUT", name: "name", label: "姓名" },
+        {
+          type: "SELECT",
+          name: "status",
+          label: "状态",
+          componentProps: {
+            options: [
+              { label: "启用", value: 1 },
+              { label: "禁用", value: 0 },
+            ],
+          },
+        },
+      ]}
+      moreSearchItems={[
+        { type: "INPUT", name: "phone", label: "电话" },
+        { type: "INPUT", name: "remark", label: "备注" },
+      ]}
+      onSearch={(data) => console.log("search", data)}
+      onReset={() => console.log("reset")}
+    />
+  </>
+);
+```
+
+## 卡片式搜索
+
+标签式快捷筛选，使用 `options`（`SearchCardOption[]`）而非 `searchItems`，`onChange` 返回当前选中值；支持 `multiple` 多选与 `showSearchBox` 搜索框。
+
+```tsx
+import React from "react";
+import { Search } from "@hsu-react/ui";
+
+export default () => (
+  <>
+    <Search.Card
+      options={[
+        {
+          label: "状态",
+          name: "status",
+          items: [
+            { label: "启用", value: 1 },
+            { label: "禁用", value: 0 },
+          ],
+        },
+        {
+          label: "类型",
+          name: "type",
+          multiple: true,
+          items: [
+            { label: "普通", value: "normal" },
+            { label: "重要", value: "important" },
+            { label: "紧急", value: "urgent" },
+          ],
+        },
+      ]}
+      onChange={(data) => console.log("change", data)}
+    />
+  </>
+);
+```
+
+## API
+
+`SearchProps` 继承自 `BaseSearchProps`：
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| searchItems | 搜索项配置（复用 `FormItemProps`） | `FormItemProps[]` | `[]` |
+| moreSearchItems | 展开后显示的更多搜索项 | `FormItemProps[]` | `[]` |
+| onSearch | 点击查询的回调，返回收集到的表单值 | `(data?: Partial<T>) => void` | - |
+| onReset | 点击重置的回调 | `() => void` | - |
+| externalForm | 外部传入的表单实例 | `FormInstance` | - |
+| hasPermi | 权限码；无权限时不渲染 | `string[]` | - |
+| columnNum | 搜索项列数（按钮组额外占一列） | `number` | `4` |
+| beforeButtonGroup | 查询 / 重置按钮前的附加按钮 | `ChakraButtonProps[]` | - |
+| affterButtonGroup | 查询 / 重置按钮后的附加按钮 | `ChakraButtonProps[]` | - |
+| searchData | 搜索项的初始值 | `Record<string, unknown>` | - |
+| minLabelWidth | 标签最小宽度，或是否启用最小宽度 | `boolean \| number` | - |
+| defaultExpanded | 默认是否展开 | `boolean` | `false` |
+| onExpandChange | 展开状态变化回调 | `(expand: boolean) => void` | - |
+| autoAdaptWidth | 是否启用基于宽度的自适应布局 | `boolean` | `true` |
+| baseWidth | 自适应布局的基准宽度 | `number` | - |
+| onValuesChange | 表单值变化回调 | `(value, values) => void` | - |
+| searchDisabled | 是否禁用查询按钮 | `boolean` | `false` |
+| showAllSearchItems | 是否一次性展示全部搜索项 | `boolean` | `false` |
+| searchText | 查询按钮文本 | `ReactNode` | - |
+| resetText | 重置按钮文本 | `ReactNode` | - |
+| columnOffsetWidth | 列宽计算的偏移量 | `number` | `0` |
+
+> 另提供多种搜索形态：`Search.Card`、`Search.Advanced`、`Search.Collapsible`、`Search.WithFilter`（带筛选下拉）、`Search.WithMore`。

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

@@ -48,7 +48,7 @@
         justify-content: flex-start;
       }
 
-      .ant-btn-icon {
+      :global(.ant-btn-icon) {
         font-size: 16px;
       }
 
@@ -166,7 +166,7 @@
 }
 
 .filterDropdown {
-  .ant-dropdown-menu {
+  :global(.ant-dropdown-menu) {
     height: max-content;
     max-height: 500px;
 

package/src/components/SecondConf/index.md

@@ -8,10 +8,48 @@ title: SecondConf 二次确认
 
 # SecondConf 二次确认
 
-> `SecondConf` 组件。完整 API 见源码类型定义，下方为基础用法。
+基于 `Modal` 封装的二次确认弹窗，内置问号图标，自动拼接「确认{contentTitle}吗？」标题与说明文案。
 
 ## 引入
 
 ```ts
 import { SecondConf } from "@hsu-react/ui";
 ```
+
+## 二次确认
+
+```tsx
+import React, { useState } from "react";
+import { SecondConf } from "@hsu-react/ui";
+import { Button } from "antd";
+
+export default () => {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <Button danger onClick={() => setOpen(true)}>
+        删除
+      </Button>
+      <SecondConf
+        open={open}
+        contentTitle="删除该条数据"
+        contentText="删除后将无法恢复，请谨慎操作。"
+        onOk={() => setOpen(false)}
+        onCancel={() => setOpen(false)}
+      />
+    </>
+  );
+};
+```
+
+## API
+
+在 `Modal`（即 antd `ModalProps`）基础上扩展（`title` 已被内部接管）：
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| contentTitle | 标题中「确认 … 吗？」的中间内容 | `ReactNode` | - |
+| contentText | 标题下方的补充说明文案 | `ReactNode` | - |
+
+> 其余属性（`open`、`onOk`、`onCancel`、`width`、`confirmLoading` 等）与 `Modal` 一致；组件内部默认 `width={800}`、`centered`、`maskClosable={false}`、`mask={false}`。