@next-bricks/advanced 0.51.3 → 0.51.5

package/dist-types/table/BrickTable.d.ts

@@ -1,7 +1,7 @@
 import React from "react";
 import { type TableProps } from "antd";
 import { CustomColumn } from "./index.js";
-import type { UseSingleBrickConf } from "@next-core/types";
+import type { UseSingleBrickConfOrRenderFunction } from "@next-core/react-runtime";
 import type { GeneralIconProps } from "@next-bricks/icons/general-icon";
 export interface BrickTableProps {
     shadowRoot: ShadowRoot | null;
@@ -14,7 +14,7 @@ export interface BrickTableProps {
     onSelectChange?: (selected: string[]) => void;
     showCard?: boolean;
     expandedRowBrick?: {
-        useBrick?: UseSingleBrickConf;
+        useBrick?: UseSingleBrickConfOrRenderFunction;
     };
     expandIcon?: {
         collapsedIcon: GeneralIconProps;

package/dist-types/table/index.d.ts

@@ -1,7 +1,8 @@
 import React from "react";
 import { ReactNextElement } from "@next-core/react-element";
 import { ColumnProps, TablePaginationConfig, TableProps } from "antd/es/table";
-import { BrickEventsMap, UseSingleBrickConf } from "@next-core/types";
+import { BrickEventsMap } from "@next-core/types";
+import { UseSingleBrickConfOrRenderFunction } from "@next-core/react-runtime";
 import { TableRowSelection, RowSelectionType } from "antd/lib/table/interface.js";
 import type { DataIndex } from "rc-table/lib/interface.js";
 import type { SizeType } from "antd/lib/config-provider/SizeContext.js";
@@ -37,7 +38,7 @@ export interface CustomColumn extends ColumnProps<Record<string, any>> {
     /**
      * 支持为某列自定义展示构件
      */
-    useBrick?: UseSingleBrickConf;
+    useBrick?: UseSingleBrickConfOrRenderFunction;
     /**
      * 字段的值展示时的后缀
      */
@@ -46,7 +47,7 @@ export interface CustomColumn extends ColumnProps<Record<string, any>> {
      * 支持为某列的表头自定义展示构件，可通过 DATA.title 获取标题文本
      */
     headerBrick?: {
-        useBrick: UseSingleBrickConf;
+        useBrick: UseSingleBrickConfOrRenderFunction;
     };
     /**
      * 在渲染自定义构件的场景下额外设置单元格的状态样式， `dataIndex` 表示取哪一列的字段值作为判断数据，不填的话默认取当前列的字段，`mapping` 表示判断的条件，条件被成功匹配时用当前的样式。目前仅支持单元格 `leftBorderColor` 属性的设置
@@ -72,7 +73,7 @@ export interface CustomColumn extends ColumnProps<Record<string, any>> {
      * 自定义筛选菜单
      */
     filterDropdownBrick?: {
-        useBrick: UseSingleBrickConf;
+        useBrick: UseSingleBrickConfOrRenderFunction;
     };
 }
 export interface SortUpdateEventDetail {
@@ -181,7 +182,7 @@ declare class TableComponent extends ReactNextElement {
      * @group expand
      */
     accessor expandedRowBrick: {
-        useBrick?: UseSingleBrickConf;
+        useBrick?: UseSingleBrickConfOrRenderFunction;
     } | undefined;
     /**
      * 自定义展开图标。
@@ -292,13 +293,13 @@ declare class TableComponent extends ReactNextElement {
      */
     accessor pageSize: number | undefined;
     /**
+     * 表格是否可滚动，也可以指定滚动区域的宽、高，配置项。详见 [scroll](https://ant.design/components/table-cn/#scroll)
      * @kind {
      *   x?: string | number | true;
      *   y?: number | string;
      * } & {
      *   scrollToFirstRowOnChange?: boolean;
      * }
-     * 表格是否可滚动，也可以指定滚动区域的宽、高，配置项。详见 [scroll](https://ant.design/components/table-cn/#scroll)
      * @required false
      * @default { x: true }
      * @group other
@@ -400,6 +401,7 @@ declare class TableComponent extends ReactNextElement {
     private _isInSelect;
     /**
      * 搜索过滤
+     * @param event - 搜索事件，event.detail.q 为搜索关键词
      */
     filterSourceData(event: CustomEvent): void;
     handleFrontendDataChange(data?: Record<string, any>[], columns?: CustomColumn[]): Record<string, any>[];

package/dist-types/text-tooltip/index.d.ts

@@ -2,17 +2,18 @@ import React from "react";
 import { ReactNextElement } from "@next-core/react-element";
 import "@next-core/theme";
 /**
- * 超出宽度鼠标悬浮显示tooltip
- * 构件 `eo-text-tooltip`
+ * 文本超出显示区域时，鼠标悬浮显示完整内容的 Tooltip
+ * @author developer
+ * @category display
  */
 export declare class EoTextTooltip extends ReactNextElement implements EoTextTooltipProps {
     /**
-     * 文案
+     * 显示的文本内容，超出时以省略号截断
      * @default
      */
     accessor label: string | undefined;
     /**
-     * 省略行数
+     * 省略的行数，超过该行数后显示省略号，设为 0 表示不省略
      * @default 1
      */
     accessor lineClamp: number;

package/dist-types/tree/index.d.ts

@@ -3,7 +3,7 @@ import { ReactNextElement } from "@next-core/react-element";
 import "@next-core/theme";
 import type { TreeProps } from "antd";
 import type { BasicDataNode } from "antd/es/tree";
-import { UseBrickConf } from "@next-core/types";
+import { UseBrickConfOrRenderFunction } from "@next-core/react-runtime";
 export interface EoTreeProps {
     dataSource?: TreeNode[];
     checkable?: boolean;
@@ -18,7 +18,7 @@ export interface EoTreeProps {
     switcherIcon?: "auto" | "chevron" | false;
     allowDrop?: (info: AllowDropInfo) => boolean;
     titleSuffixBrick?: {
-        useBrick: UseBrickConf;
+        useBrick: UseBrickConfOrRenderFunction;
     };
 }
 export interface TreeNode extends BasicDataNode {
@@ -82,7 +82,7 @@ export declare class EoTree extends ReactNextElement implements EoTreeProps {
     accessor switcherIcon: "auto" | "chevron" | false | undefined;
     accessor allowDrop: ((info: AllowDropInfo) => boolean) | undefined;
     accessor titleSuffixBrick: {
-        useBrick: UseBrickConf;
+        useBrick: UseBrickConfOrRenderFunction;
     } | undefined;
     render(): React.JSX.Element;
 }

package/dist-types/tree-select/index.d.ts

@@ -12,34 +12,74 @@ export interface TreeSelectProps extends Pick<AntdTreeSelectProps, "value" | "al
     maxTagCount?: number | "responsive";
     popupMatchSelectWidth?: boolean;
 }
+export interface TreeSelectEventsMap {
+    change: CustomEvent<{
+        value: AntdTreeSelectProps["value"];
+    }>;
+    search: CustomEvent<string>;
+    select: CustomEvent<{
+        value: AntdTreeSelectProps["value"];
+    }>;
+    expand: CustomEvent<{
+        keys: React.Key[];
+    }>;
+}
+export interface TreeSelectEventsMapping {
+    onChange: "change";
+    onSearch: "search";
+    onSelect: "select";
+    onExpand: "expand";
+}
 /**
- * 树选择器
+ * 树选择器，支持从树形数据中单选或多选节点
  * @author sailor
  * @category form-input-basic
  */
 export declare class TreeSelectBrick extends FormItemElementBase implements TreeSelectProps {
     #private;
+    /** 表单字段名 */
     accessor name: string | undefined;
+    /** 表单字段标签 */
     accessor label: string | undefined;
+    /** 是否为必填项 */
     accessor required: boolean | undefined;
+    /** 树形数据源 */
     accessor treeData: AntdTreeSelectProps["treeData"];
+    /** 是否默认展开所有树节点 */
     accessor treeDefaultExpandAll: boolean | undefined;
+    /** 受控展开的树节点 key 集合 */
     accessor treeExpandedKeys: string[] | undefined;
+    /** 自定义字段名，指定 label、value、children 对应的字段 */
     accessor fieldNames: AntdTreeSelectProps["fieldNames"];
+    /** 当前选中的值 */
     accessor value: AntdTreeSelectProps["value"];
+    /** 输入框占位文本 */
     accessor placeholder: string | undefined;
+    /** 是否支持多选 */
     accessor multiple: boolean | undefined;
+    /** 是否禁用 */
     accessor disabled: boolean | undefined;
+    /** 是否支持勾选树节点（开启后自动开启 multiple 模式） */
     accessor checkable: boolean | undefined;
+    /** 是否支持清除 */
     accessor allowClear: boolean | undefined;
+    /** 是否显示加载中状态 */
     accessor loading: boolean | undefined;
+    /** 自定义树节点过滤函数 */
     accessor filterTreeNode: AntdTreeSelectProps["filterTreeNode"];
+    /** 是否支持搜索，开启后可通过输入关键字过滤树节点 */
     accessor showSearch: boolean | undefined;
+    /** 自定义下拉箭头图标 */
     accessor suffixIcon: GeneralIconProps | undefined;
+    /** 浮层预设位置，可选 bottomLeft、bottomRight、topLeft、topRight */
     accessor popupPlacement: AntdTreeSelectProps["placement"];
+    /** 输入框大小，可选 large、middle、small */
     accessor size: AntdTreeSelectProps["size"];
+    /** 多选模式下最多显示的 tag 数量，设为 responsive 时会自适应宽度 */
     accessor maxTagCount: number | "responsive" | undefined;
+    /** 下拉框的样式 */
     accessor dropdownStyle: CSSProperties | undefined;
+    /** 下拉菜单的宽度是否与选择框相同 */
     accessor popupMatchSelectWidth: boolean | undefined;
     handleOnChange: (value: AntdTreeSelectProps["value"]) => void;
     render(): React.JSX.Element;

package/dist-types/workbench-layout/index.d.ts

@@ -1,6 +1,6 @@
 import React from "react";
 import { ReactNextElement } from "@next-core/react-element";
-import { UseSingleBrickConf } from "@next-core/types";
+import { UseSingleBrickConfOrRenderFunction } from "@next-core/react-runtime";
 import "@next-core/theme";
 import { Layout } from "react-grid-layout";
 import { SimpleAction } from "@next-bricks/basic/actions";
@@ -9,7 +9,7 @@ type Item = {
     key: string;
     title: string;
     style?: React.CSSProperties;
-    useBrick: UseSingleBrickConf;
+    useBrick: UseSingleBrickConfOrRenderFunction;
 };
 export interface EoWorkbenchLayoutProps {
     cardTitle?: string;
@@ -27,16 +27,41 @@ export interface EoWorkbenchLayoutComponentProps extends EoWorkbenchLayoutProps
     onActionClick?: (action: SimpleAction, layouts: Layout[]) => void;
 }
 export declare const EoWorkbenchLayoutComponent: React.ForwardRefExoticComponent<EoWorkbenchLayoutComponentProps & React.RefAttributes<EoWorkbenchLayoutComponentRef>>;
+export interface EoWorkbenchLayoutEventsMap {
+    change: CustomEvent<Layout[]>;
+    save: CustomEvent<Layout[]>;
+    cancel: CustomEvent<void>;
+    "action.click": CustomEvent<{
+        action: SimpleAction;
+        layouts: Layout[];
+    }>;
+}
+export interface EoWorkbenchLayoutEventsMapping {
+    onChange: "change";
+    onSave: "save";
+    onCancel: "cancel";
+    onActionClick: "action.click";
+}
 /**
- * 工作台布局
+ * 工作台布局（拖拽式卡片布局，支持编辑模式）
  * @deprecated Please use eo-workbench-layout-v2 which support global styles instead
+ * @author developer
+ * @category layout
  */
 export declare class EoWorkbenchLayout extends ReactNextElement {
     #private;
+    /** 编辑模式下左侧卡片列表面板的标题 */
     accessor cardTitle: string | undefined;
+    /** 是否进入编辑模式，编辑模式下可拖拽调整布局并显示卡片选择面板 */
     accessor isEdit: boolean | undefined;
+    /** 当前布局配置，每项对应一个卡片的位置与大小 */
     accessor layouts: Layout[] | undefined;
+    /** 组件列表，每项包含 key、title、useBrick 和 position 信息 */
     accessor componentList: Item[] | undefined;
+    /**
+     * 设置布局配置
+     * @param layouts - 新的布局配置数组
+     */
     setLayouts(layouts: Layout[]): void;
     render(): React.JSX.Element;
 }

package/dist-types/workbench-layout-v2/index.d.ts

@@ -1,6 +1,6 @@
 import React from "react";
 import { ReactNextElement } from "@next-core/react-element";
-import { UseSingleBrickConf } from "@next-core/types";
+import { UseBrickConfOrRenderFunction } from "@next-core/react-runtime";
 import { Layout } from "react-grid-layout";
 import "@next-core/theme";
 import { SimpleAction } from "@next-bricks/basic/actions";
@@ -10,7 +10,7 @@ export interface EoWorkbenchLayoutV2Props {
     cardTitle?: string;
     layouts?: ExtraLayout[];
     toolbarBricks?: {
-        useBrick: UseSingleBrickConf[];
+        useBrick: UseBrickConfOrRenderFunction;
     };
     componentList?: WorkbenchComponent[];
     isEdit?: boolean;
@@ -29,30 +29,52 @@ export interface EoWorkbenchLayoutV2ComponentProps extends EoWorkbenchLayoutV2Pr
     onSetting?: () => void;
 }
 export declare const EoWorkbenchLayoutComponent: React.ForwardRefExoticComponent<EoWorkbenchLayoutV2ComponentProps & React.RefAttributes<EoWorkbenchLayoutV2ComponentRef>>;
+export interface EoWorkbenchLayoutV2EventsMap {
+    change: CustomEvent<ExtraLayout[]>;
+    save: CustomEvent<ExtraLayout[]>;
+    cancel: CustomEvent<void>;
+    setting: CustomEvent<void>;
+    "action.click": CustomEvent<{
+        action: SimpleAction;
+        layouts: ExtraLayout[];
+    }>;
+}
+export interface EoWorkbenchLayoutV2EventsMapping {
+    onChange: "change";
+    onSave: "save";
+    onCancel: "cancel";
+    onSetting: "setting";
+    onActionClick: "action.click";
+}
 /**
- * 工作台布局V2, 未使用shadow dom
+ * 工作台布局 V2，支持拖拽式卡片布局与全局样式（不使用 shadow DOM）
+ * @author developer
+ * @category layout
  */
 export declare class EoWorkbenchLayoutV2 extends ReactNextElement {
     #private;
+    /** 编辑模式下左侧卡片列表面板的标题 */
     accessor cardTitle: string | undefined;
+    /** 是否进入编辑模式，编辑模式下可拖拽调整布局并显示卡片选择面板 */
     accessor isEdit: boolean | undefined;
+    /** 当前布局配置，每项对应一个卡片的位置与大小及样式信息 */
     accessor layouts: ExtraLayout[] | undefined;
+    /** 编辑模式下工具栏区域的自定义构件 */
     accessor toolbarBricks: {
-        useBrick: UseSingleBrickConf[];
+        useBrick: UseBrickConfOrRenderFunction;
     } | undefined;
+    /** 组件列表，每项包含 key、title、useBrick 和 position 信息 */
     accessor componentList: WorkbenchComponent[] | undefined;
-    /**
-     * 自定义卡片默认配置, 用于覆盖默认卡片配置
-     */
+    /** 自定义卡片默认配置，用于覆盖默认卡片样式配置 */
     accessor customDefaultCardConfigMap: Record<string, CardStyleConfig> | undefined;
-    /**
-     * description: 用于设置页面样式和布局的按钮
-     */
+    /** 是否显示设置按钮，用于触发页面样式和布局设置 */
     accessor showSettingButton: boolean | undefined;
+    /** 卡片之间的间距（px） */
+    accessor gap: number | undefined;
     /**
-     * description: 卡片间隔
+     * 设置布局配置
+     * @param layouts - 新的布局配置数组
      */
-    accessor gap: number | undefined;
     setLayouts(layouts: Layout[]): void;
     connectedCallback(): void;
     render(): React.JSX.Element;

package/docs/eo-cascader.md

@@ -1,9 +1,50 @@
-级联选择器
+---
+tagName: eo-cascader
+displayName: WrappedEoCascader
+description: 级联选择器
+category: form-input-basic
+source: "@next-bricks/advanced"
+---
+
+# eo-cascader
+
+> 级联选择器
+
+## Props
+
+| 属性           | 类型                                 | 必填 | 默认值                                                     | 说明                                                          |
+| -------------- | ------------------------------------ | ---- | ---------------------------------------------------------- | ------------------------------------------------------------- |
+| name           | `string`                             | 否   | -                                                          | 表单字段名                                                    |
+| label          | `string`                             | 否   | -                                                          | 表单字段标签                                                  |
+| required       | `boolean`                            | 否   | -                                                          | 是否为必填项                                                  |
+| options        | `AntdCascaderProps["options"]`       | 否   | -                                                          | 可选项数据源                                                  |
+| fieldNames     | `AntdCascaderProps["fieldNames"]`    | 否   | `{ label: "label", value: "value", children: "children" }` | 自定义字段名，指定 label、value、children 对应的字段          |
+| value          | `AntdCascaderProps["value"]`         | 否   | -                                                          | 当前选中的值                                                  |
+| placeholder    | `string`                             | 否   | -                                                          | 输入框占位文本                                                |
+| multiple       | `boolean`                            | 否   | -                                                          | 是否支持多选                                                  |
+| disabled       | `boolean`                            | 否   | -                                                          | 是否禁用                                                      |
+| allowClear     | `boolean`                            | 否   | `true`                                                     | 是否支持清除                                                  |
+| showSearch     | `boolean`                            | 否   | `true`                                                     | 是否支持搜索，开启后可通过输入关键字过滤选项                  |
+| suffixIcon     | `GeneralIconProps`                   | 否   | -                                                          | 自定义下拉箭头图标                                            |
+| expandTrigger  | `AntdCascaderProps["expandTrigger"]` | 否   | `"click"`                                                  | 次级菜单的展开方式，可选 click 或 hover                       |
+| popupPlacement | `AntdCascaderProps["placement"]`     | 否   | `"bottomLeft"`                                             | 浮层预设位置，可选 bottomLeft、bottomRight、topLeft、topRight |
+| size           | `AntdCascaderProps["size"]`          | 否   | -                                                          | 输入框大小，可选 large、middle、small                         |
+| limit          | `number`                             | 否   | `50`                                                       | 搜索结果的最大条数，0 表示不限制                              |
+| maxTagCount    | `number \| "responsive"`             | 否   | -                                                          | 多选模式下最多显示的 tag 数量，设为 responsive 时会自适应宽度 |
+| cascaderStyle  | `CSSProperties`                      | 否   | -                                                          | 级联选择器的内联样式                                          |
+
+## Events
+
+| 事件            | detail                                                                                       | 说明                     |
+| --------------- | -------------------------------------------------------------------------------------------- | ------------------------ |
+| cascader.change | `CascaderChangeEventDetail` — { value: 选择的值, selectedOptions: 选择的值所对应的 options } | 级联选择项输入变化时触发 |
 
 ## Examples
 
 ### Basic
 
+展示级联选择器的基本用法，通过 options 提供层级数据源。
+
 ```yaml preview minHeight="300px"
 - brick: eo-cascader
   properties:
@@ -29,6 +70,8 @@
 
 ### With Form
 
+在表单中使用级联选择器，配置 name、label 和 required 实现表单集成与校验。
+
 ```yaml preview minHeight="300px"
 - brick: eo-form
   events:
@@ -65,3 +108,143 @@
           - action: console.log
     - brick: eo-submit-buttons
 ```
+
+### Multiple Selection
+
+开启多选模式，并配置 maxTagCount 限制最多显示的 tag 数量。
+
+```yaml preview minHeight="300px"
+- brick: eo-cascader
+  properties:
+    placeholder: 请选择城市（可多选）
+    multiple: true
+    maxTagCount: 2
+    options:
+      - children:
+          - children:
+              - label: West Lake
+                value: xihu
+            label: Hangzhou
+            value: hangzhou
+        label: Zhejiang
+        value: zhejiang
+      - children:
+          - children:
+              - label: Zhong Hua Men
+                value: zhonghuamen
+            label: Nanjing
+            value: nanjing
+        label: Jiangsu
+        value: jiangsu
+  events:
+    cascader.change:
+      - action: console.log
+```
+
+### Custom Field Names
+
+使用 fieldNames 自定义数据源中 label、value、children 对应的字段名。
+
+```yaml preview minHeight="300px"
+- brick: eo-cascader
+  properties:
+    placeholder: 请选择分类
+    fieldNames:
+      label: name
+      value: id
+      children: sub
+    options:
+      - id: tech
+        name: 技术
+        sub:
+          - id: frontend
+            name: 前端
+            sub:
+              - id: react
+                name: React
+              - id: vue
+                name: Vue
+          - id: backend
+            name: 后端
+            sub:
+              - id: java
+                name: Java
+```
+
+### Disabled and Size
+
+展示禁用状态和不同尺寸（large、middle、small）的级联选择器。
+
+```yaml preview minHeight="300px"
+- brick: div
+  properties:
+    style:
+      display: flex
+      flexDirection: column
+      gap: 12px
+  children:
+    - brick: eo-cascader
+      properties:
+        placeholder: Large 尺寸
+        size: large
+        options:
+          - label: Zhejiang
+            value: zhejiang
+            children:
+              - label: Hangzhou
+                value: hangzhou
+                children:
+                  - label: West Lake
+                    value: xihu
+    - brick: eo-cascader
+      properties:
+        placeholder: Small 尺寸
+        size: small
+        options:
+          - label: Zhejiang
+            value: zhejiang
+            children:
+              - label: Hangzhou
+                value: hangzhou
+                children:
+                  - label: West Lake
+                    value: xihu
+    - brick: eo-cascader
+      properties:
+        placeholder: 禁用状态
+        disabled: true
+        options:
+          - label: Zhejiang
+            value: zhejiang
+            children:
+              - label: Hangzhou
+                value: hangzhou
+                children:
+                  - label: West Lake
+                    value: xihu
+```
+
+### Custom Style and Icon
+
+通过 cascaderStyle 设置内联样式，通过 suffixIcon 自定义下拉箭头图标。
+
+```yaml preview minHeight="300px"
+- brick: eo-cascader
+  properties:
+    placeholder: 自定义样式与图标
+    suffixIcon:
+      lib: antd
+      icon: down
+    cascaderStyle:
+      width: 300px
+    expandTrigger: hover
+    options:
+      - label: Zhejiang
+        value: zhejiang
+        children:
+          - label: Hangzhou
+            value: hangzhou
+            children:
+              - label: West Lake
+                value: xihu
+```