@next-bricks/presentational 1.21.9 → 1.21.10

package/dist/types.json

@@ -1795,116 +1795,6 @@
     "events": [],
     "methods": []
   },
-  "eo-alert": {
-    "properties": [
-      {
-        "name": "type",
-        "annotation": {
-          "type": "reference",
-          "typeName": {
-            "type": "identifier",
-            "name": "AlertType"
-          }
-        }
-      },
-      {
-        "name": "hasTitle",
-        "annotation": {
-          "type": "keyword",
-          "value": "boolean"
-        }
-      },
-      {
-        "name": "showIcon",
-        "annotation": {
-          "type": "keyword",
-          "value": "boolean"
-        }
-      },
-      {
-        "name": "closable",
-        "annotation": {
-          "type": "keyword",
-          "value": "boolean"
-        }
-      },
-      {
-        "name": "localStorageKey",
-        "annotation": {
-          "type": "keyword",
-          "value": "string"
-        }
-      },
-      {
-        "name": "disableUrlNamespace",
-        "annotation": {
-          "type": "keyword",
-          "value": "boolean"
-        }
-      },
-      {
-        "name": "textContent",
-        "annotation": {
-          "type": "keyword",
-          "value": "string"
-        }
-      }
-    ],
-    "events": [],
-    "methods": [],
-    "types": [
-      {
-        "type": "enum",
-        "name": "AlertType",
-        "members": [
-          {
-            "type": "enumMember",
-            "id": {
-              "type": "jsLiteral",
-              "value": "SUCCESS"
-            },
-            "initializer": {
-              "type": "jsLiteral",
-              "value": "success"
-            }
-          },
-          {
-            "type": "enumMember",
-            "id": {
-              "type": "jsLiteral",
-              "value": "INFO"
-            },
-            "initializer": {
-              "type": "jsLiteral",
-              "value": "info"
-            }
-          },
-          {
-            "type": "enumMember",
-            "id": {
-              "type": "jsLiteral",
-              "value": "WARNING"
-            },
-            "initializer": {
-              "type": "jsLiteral",
-              "value": "warning"
-            }
-          },
-          {
-            "type": "enumMember",
-            "id": {
-              "type": "jsLiteral",
-              "value": "ERROR"
-            },
-            "initializer": {
-              "type": "jsLiteral",
-              "value": "error"
-            }
-          }
-        ]
-      }
-    ]
-  },
   "eo-code-display": {
     "properties": [
       {
@@ -2160,6 +2050,116 @@
       }
     ]
   },
+  "eo-alert": {
+    "properties": [
+      {
+        "name": "type",
+        "annotation": {
+          "type": "reference",
+          "typeName": {
+            "type": "identifier",
+            "name": "AlertType"
+          }
+        }
+      },
+      {
+        "name": "hasTitle",
+        "annotation": {
+          "type": "keyword",
+          "value": "boolean"
+        }
+      },
+      {
+        "name": "showIcon",
+        "annotation": {
+          "type": "keyword",
+          "value": "boolean"
+        }
+      },
+      {
+        "name": "closable",
+        "annotation": {
+          "type": "keyword",
+          "value": "boolean"
+        }
+      },
+      {
+        "name": "localStorageKey",
+        "annotation": {
+          "type": "keyword",
+          "value": "string"
+        }
+      },
+      {
+        "name": "disableUrlNamespace",
+        "annotation": {
+          "type": "keyword",
+          "value": "boolean"
+        }
+      },
+      {
+        "name": "textContent",
+        "annotation": {
+          "type": "keyword",
+          "value": "string"
+        }
+      }
+    ],
+    "events": [],
+    "methods": [],
+    "types": [
+      {
+        "type": "enum",
+        "name": "AlertType",
+        "members": [
+          {
+            "type": "enumMember",
+            "id": {
+              "type": "jsLiteral",
+              "value": "SUCCESS"
+            },
+            "initializer": {
+              "type": "jsLiteral",
+              "value": "success"
+            }
+          },
+          {
+            "type": "enumMember",
+            "id": {
+              "type": "jsLiteral",
+              "value": "INFO"
+            },
+            "initializer": {
+              "type": "jsLiteral",
+              "value": "info"
+            }
+          },
+          {
+            "type": "enumMember",
+            "id": {
+              "type": "jsLiteral",
+              "value": "WARNING"
+            },
+            "initializer": {
+              "type": "jsLiteral",
+              "value": "warning"
+            }
+          },
+          {
+            "type": "enumMember",
+            "id": {
+              "type": "jsLiteral",
+              "value": "ERROR"
+            },
+            "initializer": {
+              "type": "jsLiteral",
+              "value": "error"
+            }
+          }
+        ]
+      }
+    ]
+  },
   "eo-humanize-time": {
     "properties": [
       {

package/dist-types/card-item/index.d.ts

@@ -76,6 +76,7 @@ export interface EoCardItemEventsMapping {
 /**
  * 信息类卡片 —— 通用卡片
  * @slot - 内容区域，通常放置卡片自定义内容
+ * @slot title-suffix - 标题后缀区域，通常放置状态标签等内容
  * @slot expanded-area-1 - 扩展区域 1，通常放置标签信息
  * @slot expanded-area-2 - 扩展区域 2，通常放置操作和其他属性信息（图标/头像/小字描述/统计信息）
  * @category card-info
@@ -83,7 +84,7 @@ export interface EoCardItemEventsMapping {
 export declare class EoCardItem extends ReactNextElement implements EoCardItemProps {
     #private;
     /**
-     * 是否有顶部小标题
+     * 是否有顶部小标题区域，开启后会显示 `auxiliaryText` 辅助文字
      */
     accessor hasHeader: boolean | undefined;
     /**
@@ -99,7 +100,7 @@ export declare class EoCardItem extends ReactNextElement implements EoCardItemPr
      */
     accessor auxiliaryText: string | undefined;
     /**
-     * 图标
+     * 图标或图片，支持图标头像（IconAvatar）和图片头像（ImgAvatar）两种形式
      */
     accessor avatar: IconAvatar | ImgAvatar | undefined;
     /**
@@ -119,7 +120,7 @@ export declare class EoCardItem extends ReactNextElement implements EoCardItemPr
      */
     accessor actions: ActionType[] | undefined;
     /**
-     * 展示操作按钮组
+     * 操作按钮组的展示时机，`always` 始终展示，`hover` 悬停时展示
      */
     accessor showActions: "always" | "hover";
     /**
@@ -147,13 +148,16 @@ export declare class EoCardItem extends ReactNextElement implements EoCardItemPr
      */
     accessor coverImageSize: React.CSSProperties["backgroundSize"] | undefined;
     /**
-     * 图标是否放置在卡片封面
+     * 头像的放置位置，设为 `cover` 时头像显示在封面区域，否则显示在内容区域
      */
     accessor avatarPosition: "content" | "cover";
     /**
      * 图标位置，在 avatarPosition 不为 cover 时有效
      */
     accessor avatarPlacement: "left" | "title-left";
+    /**
+     * 徽标配置，可设置文本、图标、背景色和字体颜色
+     */
     accessor tagConfig: TagConfig | undefined;
     /**
      * 卡片边框颜色

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

@@ -2,7 +2,7 @@ import React, { CSSProperties } from "react";
 import { ReactNextElement } from "@next-core/react-element";
 import "@next-core/theme";
 /**
- * 构件 `eo-carousel-text`
+ * 文字跑马灯构件，文本内容从右向左循环滚动展示，支持自定义速度、字体大小和字体颜色。
  */
 export declare class EoCarouselText extends ReactNextElement {
     /**

package/dist-types/code-block/index.d.ts

@@ -11,7 +11,7 @@ export interface CodeBlockProps {
     showCopyButton?: boolean;
 }
 /**
- * 构件 `eo-code-block`
+ * 代码块展示构件，基于 Shiki 进行语法高亮，支持多种编程语言、亮色/暗色主题自动切换及复制功能。
  *
  * @part pre - 包裹代码内容的 `<pre>` 元素
  * @part copy - 复制按钮
@@ -19,12 +19,21 @@ export interface CodeBlockProps {
  * @part wrapper - code-wrapper 构件
  */
 export declare class CodeBlock extends ReactNextElement implements CodeBlockProps {
+    /**
+     * 代码语言，用于语法高亮，例如 `javascript`、`python`、`yaml` 等
+     */
     accessor language: string | undefined;
+    /**
+     * 代码内容字符串
+     */
     accessor source: string | undefined;
-    /** @default "auto" */
+    /**
+     * 代码高亮主题。`auto` 跟随系统主题自动切换亮色/暗色
+     * @default "auto"
+     */
     accessor theme: "auto" | "light-plus" | "dark-plus" | undefined;
     /**
-     * 主题变体
+     * 主题变体，影响代码块的整体样式风格
      */
     accessor themeVariant: "default" | "elevo" | undefined;
     /**

package/dist-types/code-display/index.d.ts

@@ -47,7 +47,6 @@ export declare class CodeDisplay extends ReactNextElement implements CodeDisplay
     accessor showExportButton: boolean | undefined;
     /**
      * 导出的文件名
-     * @default download.txt
      */
     accessor exportFileName: string | undefined;
     render(): React.JSX.Element;

package/dist-types/code-wrapper/index.d.ts

@@ -10,7 +10,9 @@ export interface CodeWrapperProps {
     themeVariant?: "default" | "elevo";
 }
 /**
- * 构件 `presentational.code-wrapper`
+ * 代码内容包裹容器，提供统一的代码展示结构并支持一键复制功能。
+ *
+ * @description 代码内容包裹容器，提供统一的代码展示结构并支持一键复制功能。
  *
  * @internal
  *
@@ -18,6 +20,9 @@ export interface CodeWrapperProps {
  * @part copy - 复制按钮
  */
 export declare class CodeWrapper extends ReactNextElement implements CodeWrapperProps {
+    /**
+     * 传递给 `<pre>` 元素的额外属性，例如 `className`、`style` 等
+     */
     accessor preProps: React.PropsWithChildren<JSX.IntrinsicElements["pre"]> | undefined;
     /**
      * 是否展示复制按钮
@@ -25,7 +30,7 @@ export declare class CodeWrapper extends ReactNextElement implements CodeWrapper
      */
     accessor showCopyButton: boolean | undefined;
     /**
-     * 主题变体
+     * 主题变体，影响复制按钮等内部元素的样式风格。`elevo` 为 Elevo 风格
      */
     accessor themeVariant: "default" | "elevo" | undefined;
     render(): React.JSX.Element;

package/dist-types/current-time/index.d.ts

@@ -7,7 +7,7 @@ export interface CurrentTimeProps {
     icon?: GeneralIconProps;
 }
 /**
- * 构件 `eo-current-time`
+ * 实时当前时间展示构件，每秒自动刷新，支持自定义时间格式和前置图标。
  */
 export declare class EoCurrentTime extends ReactNextElement {
     /**

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

@@ -45,6 +45,7 @@ declare class Descriptions extends ReactNextElement {
     accessor showCard: boolean | undefined;
     /**
      * 列数
+     * @default 3
      */
     accessor column: number | undefined;
     /**
@@ -62,7 +63,7 @@ declare class Descriptions extends ReactNextElement {
      */
     accessor bordered: boolean | undefined;
     /**
-     * 隐藏的描述列表项
+     * 需要隐藏的分组名称，匹配 list 项的 group 字段，支持字符串或字符串数组
      */
     accessor hideGroups: string | string[] | undefined;
     /**

package/dist-types/humanize-time/index.d.ts

@@ -22,16 +22,16 @@ export interface EoHumanizeTimeProps {
  */
 export declare class EoHumanizeTime extends ReactNextElement {
     /**
-     * 时间截，或字符串，当为字符串时，应提供时间格式 `inputFormat`
+     * 时间戳（秒或毫秒，由 `isMillisecond` 决定），或时间字符串（字符串类型时应提供 `inputFormat`）
      * @required
      */
     accessor value: number | string;
     /**
-     * 字符串的时间格式，如 "YYYY-MM-DD", [时间格式参照表](https://day.js.org/docs/en/parse/string-format)
+     * 字符串类型 `value` 的解析格式，如 "YYYY-MM-DD"，[时间格式参照表](https://momentjs.com/docs/#/parsing/string-format/)
      */
     accessor inputFormat: string;
     /**
-     * 展示时间格式，如 "YYYY-MM-DD"，当设置该属性时，属性 `formatter` 无效 [时间格式参照表](https://day.js.org/docs/en/display/format)
+     * 自定义输出格式，如 "YYYY-MM-DD HH:mm:ss"，设置后 `formatter` 属性无效，[时间格式参照表](https://momentjs.com/docs/#/displaying/format/)
      */
     accessor outputFormat: string;
     /**
@@ -44,23 +44,23 @@ export declare class EoHumanizeTime extends ReactNextElement {
      */
     accessor isCostTime: boolean;
     /**
-     * 格式类型
+     * 格式类型，可选值：`"full"`（完整时间）、`"default"`（自动相对/完整）、`"relative"`（相对时间，支持过去和未来）、`"past"`（仅过去相对时间）、`"future"`（仅未来相对时间）、`"accurate"`（精确耗时）、`"auto"`
      *
-     * @default "default"
+     * @default "auto"
      */
     accessor formatter: HumanizeTimeFormat;
     /**
-     * value 值的单位是否为毫秒（此处属性 id 写错，实际表达意义为 isMillisecond）
+     * 已废弃：`value` 值的单位是否为毫秒（属性名拼写有误，请改用 `isMillisecond`）
      *
      * @deprecated 请使用 `isMillisecond`
      */
     accessor isMicrosecond: boolean;
     /**
-     * value 值的单位是否为毫秒
+     * `value` 值的单位是否为毫秒，默认将 `value` 视为秒级时间戳
      */
     accessor isMillisecond: boolean;
     /**
-     * 跳转链接，默认为空
+     * 将时间显示为可点击链接
      */
     accessor link: LinkInfo;
     connectedCallback(): void;

package/dist-types/info-card-item/index.d.ts

@@ -5,32 +5,33 @@ import "@next-core/theme";
 import type { LinkProps } from "@next-bricks/basic/link";
 import type { GeneralIconProps } from "@next-bricks/icons/general-icon";
 /**
- * 信息卡片
+ * 信息类卡片 —— 横向布局信息卡片
+ * @description 展示带图标、标题、描述和详细列表的横向布局信息卡片，支持链接跳转、插槽图标、标题后缀及操作区。
  * @author dophijing
  * @category card-info
  */
 export declare class EoInfoCardItem extends ReactNextElement implements EoInfoCardItemProps {
     #private;
     /**
-     * title
+     * 卡片标题
      */
     accessor cardTitle: string;
     /**
-     * description
+     * 卡片描述信息
      */
-    accessor description: string;
+    accessor description: string | undefined;
     /**
      * 链接地址
      */
     accessor url: string | undefined;
     /**
-     * 图标
+     * 图标配置，支持设置图标、颜色、尺寸、形状和背景色
      */
     accessor cardIcon: IconAvatar | undefined;
     /**
-     * 详细列表
+     * 详细列表，每项可设置标题、描述文字或自定义构件
      */
-    accessor detailList: InfoCardDetail[];
+    accessor detailList: InfoCardDetail[] | undefined;
     /**
      * 链接跳转目标
      */

package/dist-types/loading-step/index.d.ts

@@ -14,36 +14,36 @@ export interface EoLoadingStepEventsMapping {
     onClose: "close";
 }
 /**
- * 加载步骤框
+ * @description 加载步骤框。以全屏遮罩的形式展示多步骤加载进度，适用于系统初始化、批量操作等需要阻塞用户交互的场景。
  */
 export declare class EoLoadingStep extends ReactNextElement implements EoLoadingStepProps {
     #private;
     /**
-     * 是否可见
+     * @description 是否可见。为 `true` 时展示全屏遮罩并锁定页面滚动，为 `false` 时隐藏遮罩并恢复滚动。
      */
     accessor visible: boolean | undefined;
     /**
-     * 宽度
+     * @description 容器宽度，支持任意 CSS 宽度值（如 `"400px"`、`"50%"`）。不设置时使用默认宽度。
      */
     accessor width: string | undefined;
     /**
-     * 步骤标题
+     * @description 步骤区域的标题文字，显示在步骤列表上方。
      */
     accessor stepTitle: string | undefined;
     /**
-     * 步骤列表
+     * @description 步骤列表，每项包含 `title`（显示名称）和 `key`（唯一标识）。步骤按数组顺序渲染。
      */
     accessor stepList: StepItem[] | undefined;
     /**
-     * 当前步骤
+     * @description 当前正在执行的步骤 `key`。key 对应的步骤显示为加载中（loading），之前的步骤显示为已完成（finished），之后的步骤显示为待执行（pending）。
      */
     accessor curStep: string | undefined;
     /**
-     * 打开
+     * @description 打开加载步骤框。将 `visible` 设为 `true` 并触发 `open` 事件。
      */
     open(): void;
     /**
-     * 关闭
+     * @description 关闭加载步骤框。将 `visible` 设为 `false` 并触发 `close` 事件。
      */
     close(): void;
     disconnectedCallback(): void;

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

@@ -36,6 +36,7 @@ export interface EoPaginationEventsMapping {
 export declare class EoPagination extends ReactNextElement implements EoPaginationProps {
     #private;
     /**
+     * 分页模式：`page` 为页码模式，`token` 为令牌（游标）模式
      * @default "page"
      */
     accessor type: "page" | "token" | undefined;
@@ -60,7 +61,13 @@ export declare class EoPagination extends ReactNextElement implements EoPaginati
      * @default true
      */
     accessor showSizeChanger: boolean | undefined;
+    /**
+     * 令牌模式下的下一页令牌（nextToken），有值时"下一页"按钮可点击
+     */
     accessor nextToken: string | undefined;
+    /**
+     * 令牌模式下的上一页令牌（previousToken），有值时"上一页"按钮可点击
+     */
     accessor previousToken: string | undefined;
     render(): React.JSX.Element;
 }

package/dist-types/statistics-card/index.d.ts

@@ -21,7 +21,7 @@ export interface EoStatisticsCardProps {
  * 统计卡片
  *
  * @slot titlePrefix - 标题前缀，放置辅助信息
- * @slot titleSuffix - 标题前缀，放置辅助信息
+ * @slot titleSuffix - 标题后缀，放置辅助信息
  * @slot description - 描述信息，通常是对于统计值的描述
  * @slot basicContent - 卡片右侧内容区，适合放置迷你图表，常用于小卡片
  * @slot extraContent - 卡片下方内容区，适合放置图表，用于展示更多信息的场景
@@ -42,7 +42,7 @@ export declare class EoStatisticsCard extends ReactNextElement {
      */
     accessor unit: string | undefined;
     /**
-     * 图标
+     * 图标，支持 GeneralIconProps 的所有字段，额外支持 `color`（图标颜色）和 `bgColor`（背景色）
      */
     accessor icon: EoStatisticsCardProps["icon"] | undefined;
     /**

package/docs/eo-alert.md

@@ -1,9 +1,39 @@
-告警提示
+---
+tagName: eo-alert
+displayName: WrappedEoAlert
+description: 告警提示
+category: display-component
+source: "@next-bricks/presentational"
+---
+
+# eo-alert
+
+> 告警提示
+
+## Props
+
+| 属性                | 类型                                          | 必填 | 默认值 | 说明                                                                                                            |
+| ------------------- | --------------------------------------------- | ---- | ------ | --------------------------------------------------------------------------------------------------------------- |
+| type                | `"success" \| "info" \| "warning" \| "error"` | 是   | -      | 警告类型                                                                                                        |
+| hasTitle            | `boolean`                                     | 否   | -      | 是否显示标题。开启后，可以使用 `title` 插槽                                                                     |
+| showIcon            | `boolean`                                     | 否   | -      | 是否显示提示图标                                                                                                |
+| closable            | `boolean`                                     | 否   | -      | 是否显示关闭按钮                                                                                                |
+| localStorageKey     | `string`                                      | 否   | -      | 以该值和页面 url 作为命名空间，决定是否显示该警告提示。关闭后将记录到 localStorage，下次访问同一 url 时不再显示 |
+| disableUrlNamespace | `boolean`                                     | 否   | -      | 仅以 `localStorageKey` 作为命名空间（不拼接页面 url），关闭后在所有页面均不再显示                               |
+
+## Slots
+
+| 名称     | 说明                         |
+| -------- | ---------------------------- |
+| （默认） | 内容区                       |
+| title    | 标题，需配合 `hasTitle` 使用 |
 
 ## Examples
 
 ### Basic
 
+展示四种警告类型（`info`、`success`、`warning`、`error`），并启用关闭按钮。
+
 ```yaml preview
 brick: div
 properties:
@@ -42,6 +72,8 @@ slots:
 
 ### HasTitle
 
+通过 `hasTitle` 启用标题区域，并使用 `title` 插槽放置标题内容。
+
 ```yaml preview
 brick: div
 properties:
@@ -110,3 +142,35 @@ slots:
                 properties:
                   textContent: 出错了
 ```
+
+### LocalStorageKey
+
+通过 `localStorageKey` 和 `disableUrlNamespace` 控制关闭后的持久化范围：`disableUrlNamespace` 为 `true` 时，关闭后在所有页面均不再显示；否则仅在当前 url 下不再显示。
+
+```yaml preview
+brick: div
+properties:
+  style:
+    display: flex
+    flex-direction: column
+    gap: 10px
+slots:
+  "":
+    type: bricks
+    bricks:
+      - brick: eo-alert
+        properties:
+          textContent: 关闭后仅在当前页面不再显示（localStorageKey + url 命名空间）。
+          type: info
+          closable: true
+          showIcon: true
+          localStorageKey: demo-alert-url
+      - brick: eo-alert
+        properties:
+          textContent: 关闭后在所有页面均不再显示（仅 localStorageKey 命名空间）。
+          type: warning
+          closable: true
+          showIcon: true
+          localStorageKey: demo-alert-global
+          disableUrlNamespace: true
+```