@next-bricks/presentational 1.21.9 → 1.21.11

package/docs/eo-code-wrapper.react.md

@@ -0,0 +1,100 @@
+---
+tagName: presentational.code-wrapper
+displayName: WrappedPresentationalCodeWrapper
+description: 代码内容包裹容器，提供统一的代码展示结构并支持一键复制功能。
+category: ""
+source: "@next-bricks/presentational"
+---
+
+# WrappedPresentationalCodeWrapper
+
+> 代码内容包裹容器，提供统一的代码展示结构并支持一键复制功能。
+
+## 导入
+
+```tsx
+import { WrappedPresentationalCodeWrapper } from "@easyops/wrapped-components";
+```
+
+## Props
+
+| 属性           | 类型                                                    | 必填 | 默认值 | 说明                                                              |
+| -------------- | ------------------------------------------------------- | ---- | ------ | ----------------------------------------------------------------- |
+| preProps       | `React.PropsWithChildren<JSX.IntrinsicElements["pre"]>` | 否   | -      | 传递给 `<pre>` 元素的额外属性，例如 `className`、`style` 等       |
+| showCopyButton | `boolean`                                               | 否   | `true` | 是否展示复制按钮                                                  |
+| themeVariant   | `"default" \| "elevo"`                                  | 否   | -      | 主题变体，影响复制按钮等内部元素的样式风格。`elevo` 为 Elevo 风格 |
+
+## CSS Parts
+
+| 名称 | 说明                        |
+| ---- | --------------------------- |
+| pre  | 包裹代码内容的 `<pre>` 元素 |
+| copy | 复制按钮                    |
+
+## Examples
+
+### Basic
+
+展示代码包裹容器的基本用法，将代码内容放入 `<code>` 子节点，默认展示复制按钮。
+
+```tsx
+<WrappedPresentationalCodeWrapper
+  preProps={{ children: <code>{"const greeting = 'Hello, World!';"}</code> }}
+/>
+```
+
+### 隐藏复制按钮
+
+设置 `showCopyButton` 为 `false` 可隐藏右上角的复制按钮。
+
+```tsx
+<WrappedPresentationalCodeWrapper
+  showCopyButton={false}
+  preProps={{ children: <code>{"const greeting = 'Hello, World!';"}</code> }}
+/>
+```
+
+### Elevo 主题变体
+
+设置 `themeVariant` 为 `"elevo"` 使复制按钮采用 Elevo 主题样式。
+
+```tsx
+<WrappedPresentationalCodeWrapper
+  themeVariant="elevo"
+  preProps={{ children: <code>{"const greeting = 'Hello, World!';"}</code> }}
+/>
+```
+
+### 自定义 pre 元素样式
+
+通过 `preProps` 的 `style` 字段为 `<pre>` 元素设置自定义内联样式。
+
+```tsx
+<WrappedPresentationalCodeWrapper
+  preProps={{
+    style: {
+      background: "#1e1e1e",
+      color: "#d4d4d4",
+      padding: "16px",
+      borderRadius: "8px",
+    },
+    children: <code>{"const greeting = 'Hello, World!';"}</code>,
+  }}
+/>
+```
+
+### 自定义 CSS Parts
+
+通过 `pre` 和 `copy` CSS Parts 对内部元素进行样式定制，例如修改 `<pre>` 背景色和圆角、调整复制按钮颜色。
+
+```tsx
+<WrappedPresentationalCodeWrapper
+  style={
+    {
+      "--part-pre-border-radius": "8px",
+      "--part-copy-color": "var(--color-brand)",
+    } as React.CSSProperties
+  }
+  preProps={{ children: <code>{"const greeting = 'Hello, World!';"}</code> }}
+/>
+```

package/docs/eo-current-time.md

@@ -1,9 +1,38 @@
-构件 `eo-current-time`
+---
+tagName: eo-current-time
+displayName: EoCurrentTime
+description: 实时当前时间展示构件，每秒自动刷新，支持自定义时间格式和前置图标。
+category: ""
+source: "@next-bricks/presentational"
+---
+
+# eo-current-time
+
+> 实时当前时间展示构件，每秒自动刷新，支持自定义时间格式和前置图标。
+
+## Props
+
+| 属性   | 类型                            | 必填 | 默认值                  | 说明                                |
+| ------ | ------------------------------- | ---- | ----------------------- | ----------------------------------- |
+| format | `string`                        | 是   | `"YYYY-MM-DD HH:mm:ss"` | 时间格式，使用 moment.js 格式字符串 |
+| icon   | `GeneralIconProps \| undefined` | 否   | -                       | 前置图标，仅在时间已渲染后显示      |
 
 ## Examples
 
 ### Basic
 
+使用默认时间格式展示当前时间，每秒自动刷新。
+
+```yaml preview
+brick: eo-current-time
+properties:
+  format: "YYYY-MM-DD HH:mm:ss"
+```
+
+### With Icon
+
+在时间前面展示一个图标，图标仅在时间渲染后可见。
+
 ```yaml preview
 brick: eo-current-time
 properties:
@@ -13,3 +42,13 @@ properties:
     category: itsc-form
     icon: time
 ```
+
+### Custom Format
+
+使用自定义格式只展示时分秒。
+
+```yaml preview
+brick: eo-current-time
+properties:
+  format: "HH:mm:ss"
+```

package/docs/eo-current-time.react.md

@@ -0,0 +1,53 @@
+---
+tagName: eo-current-time
+displayName: WrappedEoCurrentTime
+description: 实时当前时间展示构件，每秒自动刷新，支持自定义时间格式和前置图标。
+category: ""
+source: "@next-bricks/presentational"
+---
+
+# WrappedEoCurrentTime
+
+> 实时当前时间展示构件，每秒自动刷新，支持自定义时间格式和前置图标。
+
+## 导入
+
+```tsx
+import { WrappedEoCurrentTime } from "@easyops/wrapped-components";
+```
+
+## Props
+
+| 属性   | 类型                            | 必填 | 默认值                  | 说明                                |
+| ------ | ------------------------------- | ---- | ----------------------- | ----------------------------------- |
+| format | `string`                        | 是   | `"YYYY-MM-DD HH:mm:ss"` | 时间格式，使用 moment.js 格式字符串 |
+| icon   | `GeneralIconProps \| undefined` | 否   | -                       | 前置图标，仅在时间已渲染后显示      |
+
+## Examples
+
+### Basic
+
+使用默认时间格式展示当前时间，每秒自动刷新。
+
+```tsx preview
+<WrappedEoCurrentTime format="YYYY-MM-DD HH:mm:ss" />
+```
+
+### With Icon
+
+在时间前面展示一个图标，图标仅在时间渲染后可见。
+
+```tsx preview
+<WrappedEoCurrentTime
+  format="YYYY-MM-DD HH:mm:ss"
+  icon={{ lib: "easyops", category: "itsc-form", icon: "time" }}
+/>
+```
+
+### Custom Format
+
+使用自定义格式只展示时分秒。
+
+```tsx preview
+<WrappedEoCurrentTime format="HH:mm:ss" />
+```

package/docs/eo-descriptions.md

@@ -1,4 +1,46 @@
-通用描述列表构件。
+---
+tagName: eo-descriptions
+displayName: EoDescriptions
+description: 通用描述列表构件
+category: text
+source: "@next-bricks/presentational"
+---
+
+# eo-descriptions
+
+> 通用描述列表构件
+
+## Props
+
+| 属性             | 类型                         | 必填 | 默认值         | 说明                                                                                                                     |
+| ---------------- | ---------------------------- | ---- | -------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| descriptionTitle | `string`                     | 否   | -              | 描述标题                                                                                                                 |
+| list             | `DescriptionItem[]`          | 否   | -              | 描述列表，每项可通过 `text`、`field` 或 `useBrick` 指定内容                                                              |
+| showCard         | `boolean`                    | 否   | `true`         | 是否展示卡片背景（`themeVariant` 为 `elevo` 时强制不展示卡片）                                                           |
+| column           | `number`                     | 否   | `3`            | 列数                                                                                                                     |
+| templateColumns  | `string`                     | 否   | -              | CSS [grid-template-columns](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-columns)，优先级高于 `column` |
+| layout           | `"horizontal" \| "vertical"` | 否   | `"horizontal"` | 布局模式                                                                                                                 |
+| bordered         | `boolean`                    | 否   | `false`        | 是否展示边框                                                                                                             |
+| hideGroups       | `string \| string[]`         | 否   | -              | 需要隐藏的分组名称，匹配 list 项的 group 字段，支持字符串或字符串数组                                                    |
+| dataSource       | `object`                     | 否   | -              | 数据源，供 list 项通过 `field` 读取字段值或通过 `useBrick` 的 `DATA` 引用                                                |
+| themeVariant     | `"default" \| "elevo"`       | 否   | -              | 主题变体；`elevo` 模式下不渲染外层卡片，且标签后不添加冒号                                                               |
+
+### DescriptionItem
+
+| 字段       | 类型               | 说明                                                  |
+| ---------- | ------------------ | ----------------------------------------------------- |
+| label      | `string`           | 描述项标签文本                                        |
+| field      | `string`           | 从 `dataSource` 中读取值的字段路径（使用 lodash get） |
+| group      | `string`           | 所属分组名，可配合 `hideGroups` 隐藏整组              |
+| text       | `string \| number` | 静态文本内容，`field` 未设置时使用                    |
+| useBrick   | `UseBrickConf`     | 自定义渲染 brick，`dataSource` 作为 `DATA` 传入       |
+| gridColumn | `string`           | CSS `grid-column` 值，用于手动控制该项的列跨度        |
+
+## Examples
+
+### Basic
+
+最简用法，展示一组描述列表。
 
 ```yaml preview
 - brick: eo-descriptions
@@ -14,10 +56,10 @@
         text: 篮球
 ```
 
-## Examples
-
 ### Column
 
+通过 `column` 控制列数，并通过 `descriptionTitle` 设置标题。
+
 ```yaml preview
 - brick: eo-descriptions
   properties:
@@ -82,6 +124,8 @@
 
 ### Layout
 
+`layout` 支持 `horizontal`（标签与内容同行）和 `vertical`（标签在内容上方）两种布局。
+
 ```yaml preview
 - brick: eo-descriptions
   properties:
@@ -147,6 +191,8 @@
 
 ### Bordered
 
+`bordered` 为 `true` 时，列表项添加边框线，标签后不显示冒号。
+
 ```yaml preview
 - brick: eo-descriptions
   properties:
@@ -210,6 +256,8 @@
 
 ### Hide Groups
 
+通过 `hideGroups` 隐藏指定 group 的所有描述项，支持单个字符串或字符串数组。
+
 ```yaml preview
 - brick: eo-descriptions
   properties:
@@ -279,6 +327,8 @@
 
 ### DataSource
 
+通过 `dataSource` 提供数据源，list 项可用 `field` 读取字段，也可在 `useBrick` 中通过 `DATA` 引用整个数据源。
+
 ```yaml preview
 - brick: eo-descriptions
   properties:
@@ -301,7 +351,27 @@
             textContent: "<% DATA.text %>"
 ```
 
-### Theme variant Elevo
+### Template Columns
+
+通过 `templateColumns` 精确控制各列宽度，list 项可用 `gridColumn` 跨列显示。
+
+```yaml preview
+- brick: eo-descriptions
+  properties:
+    templateColumns: "200px 1fr 2fr"
+    list:
+      - label: 姓名
+        text: Tom
+      - label: 年龄
+        text: 18
+      - label: 备注
+        text: 这是一段较长的备注信息
+        gridColumn: "2 / 4"
+```
+
+### Theme Variant Elevo
+
+`themeVariant` 为 `elevo` 时，不渲染外层卡片，适用于 AI 门户等特殊背景场景。
 
 ```yaml preview
 # Use this container to emulate background

package/docs/eo-descriptions.react.md

@@ -0,0 +1,329 @@
+---
+tagName: eo-descriptions
+displayName: WrappedEoDescriptions
+description: 通用描述列表构件
+category: text
+source: "@next-bricks/presentational"
+---
+
+# WrappedEoDescriptions
+
+> 通用描述列表构件
+
+## 导入
+
+```tsx
+import { WrappedEoDescriptions } from "@easyops/wrapped-components";
+```
+
+## Props
+
+| 属性             | 类型                         | 必填 | 默认值         | 说明                                                                                                                     |
+| ---------------- | ---------------------------- | ---- | -------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| descriptionTitle | `string`                     | 否   | -              | 描述标题                                                                                                                 |
+| list             | `DescriptionItem[]`          | 否   | -              | 描述列表，每项可通过 `text`、`field` 或 `useBrick` 指定内容                                                              |
+| showCard         | `boolean`                    | 否   | `true`         | 是否展示卡片背景（`themeVariant` 为 `elevo` 时强制不展示卡片）                                                           |
+| column           | `number`                     | 否   | `3`            | 列数                                                                                                                     |
+| templateColumns  | `string`                     | 否   | -              | CSS [grid-template-columns](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-columns)，优先级高于 `column` |
+| layout           | `"horizontal" \| "vertical"` | 否   | `"horizontal"` | 布局模式                                                                                                                 |
+| bordered         | `boolean`                    | 否   | `false`        | 是否展示边框                                                                                                             |
+| hideGroups       | `string \| string[]`         | 否   | -              | 需要隐藏的分组名称，匹配 list 项的 group 字段，支持字符串或字符串数组                                                    |
+| dataSource       | `object`                     | 否   | -              | 数据源，供 list 项通过 `field` 读取字段值或通过 `useBrick` 的 `DATA` 引用                                                |
+| themeVariant     | `"default" \| "elevo"`       | 否   | -              | 主题变体；`elevo` 模式下不渲染外层卡片，且标签后不添加冒号                                                               |
+
+### DescriptionItem
+
+| 字段       | 类型               | 说明                                                  |
+| ---------- | ------------------ | ----------------------------------------------------- |
+| label      | `string`           | 描述项标签文本                                        |
+| field      | `string`           | 从 `dataSource` 中读取值的字段路径（使用 lodash get） |
+| group      | `string`           | 所属分组名，可配合 `hideGroups` 隐藏整组              |
+| text       | `string \| number` | 静态文本内容，`field` 未设置时使用                    |
+| useBrick   | `UseBrickConf`     | 自定义渲染 brick，`dataSource` 作为 `DATA` 传入       |
+| gridColumn | `string`           | CSS `grid-column` 值，用于手动控制该项的列跨度        |
+
+## Examples
+
+### Basic
+
+最简用法，展示一组描述列表。
+
+```tsx preview
+import { WrappedEoDescriptions } from "@easyops/wrapped-components";
+
+export default function App() {
+  return (
+    <WrappedEoDescriptions
+      list={[
+        { label: "姓名", text: "Tom" },
+        { label: "年龄", text: 18 },
+        { label: "身高", text: "180cm" },
+        { label: "爱好", text: "篮球" },
+      ]}
+    />
+  );
+}
+```
+
+### Column
+
+通过 `column` 控制列数，并通过 `descriptionTitle` 设置标题。
+
+```tsx preview
+import { WrappedEoDescriptions } from "@easyops/wrapped-components";
+import { WrappedEoDivider } from "@easyops/wrapped-components";
+
+const tagList = [
+  { text: "阳光", key: 0, color: "blue" },
+  { text: "开朗", key: 1, color: "red" },
+  { text: "大男孩", key: 2, color: "green" },
+];
+
+export default function App() {
+  return (
+    <>
+      <WrappedEoDescriptions
+        descriptionTitle="UserInfo"
+        column={2}
+        list={[
+          { label: "姓名", text: "Tom" },
+          { label: "年龄", text: 18 },
+          { label: "身高", text: "180cm" },
+          { label: "爱好", text: "篮球" },
+          {
+            label: "标签",
+            useBrick: [{ brick: "eo-tag-list", properties: { list: tagList } }],
+          },
+        ]}
+      />
+      <WrappedEoDivider dividerStyle={{ margin: "8px 0 4px 0" }} />
+      <WrappedEoDescriptions
+        descriptionTitle="用户信息"
+        column={4}
+        list={[
+          { label: "姓名", text: "Tom" },
+          { label: "年龄", text: 18 },
+          { label: "身高", text: "180cm" },
+          { label: "爱好", text: "篮球" },
+          {
+            label: "标签",
+            useBrick: [{ brick: "eo-tag-list", properties: { list: tagList } }],
+          },
+        ]}
+      />
+    </>
+  );
+}
+```
+
+### Layout
+
+`layout` 支持 `horizontal`（标签与内容同行）和 `vertical`（标签在内容上方）两种布局。
+
+```tsx preview
+import { WrappedEoDescriptions } from "@easyops/wrapped-components";
+import { WrappedEoDivider } from "@easyops/wrapped-components";
+
+const tagList = [
+  { text: "阳光", key: 0, color: "blue" },
+  { text: "开朗", key: 1, color: "red" },
+  { text: "大男孩", key: 2, color: "green" },
+];
+
+const items = [
+  { label: "姓名", text: "Tom" },
+  { label: "年龄", text: 18 },
+  { label: "身高", text: "180cm" },
+  { label: "爱好", text: "篮球" },
+  {
+    label: "标签",
+    useBrick: [{ brick: "eo-tag-list", properties: { list: tagList } }],
+  },
+];
+
+export default function App() {
+  return (
+    <>
+      <WrappedEoDescriptions layout="horizontal" list={items} />
+      <WrappedEoDivider dividerStyle={{ margin: "8px 0 4px 0" }} />
+      <WrappedEoDescriptions layout="vertical" list={items} />
+      <div style={{ margin: "10px 0px" }} />
+    </>
+  );
+}
+```
+
+### Bordered
+
+`bordered` 为 `true` 时，列表项添加边框线，标签后不显示冒号。
+
+```tsx preview
+import { WrappedEoDescriptions } from "@easyops/wrapped-components";
+
+const tagList = [
+  { text: "阳光", key: 0, color: "blue" },
+  { text: "开朗", key: 1, color: "red" },
+  { text: "大男孩", key: 2, color: "green" },
+];
+
+const items = [
+  { label: "姓名", text: "Tom" },
+  { label: "年龄", text: 18 },
+  { label: "身高", text: "180cm" },
+  { label: "爱好", text: "篮球" },
+  {
+    label: "标签",
+    useBrick: [{ brick: "eo-tag-list", properties: { list: tagList } }],
+  },
+];
+
+export default function App() {
+  return (
+    <>
+      <WrappedEoDescriptions bordered layout="vertical" list={items} />
+      <div style={{ margin: "10px 0px" }} />
+      <WrappedEoDescriptions bordered layout="horizontal" list={items} />
+    </>
+  );
+}
+```
+
+### Hide Groups
+
+通过 `hideGroups` 隐藏指定 group 的所有描述项，支持单个字符串或字符串数组。
+
+```tsx preview
+import { WrappedEoDescriptions } from "@easyops/wrapped-components";
+
+export default function App() {
+  return (
+    <>
+      <WrappedEoDescriptions
+        hideGroups="other"
+        list={[
+          { label: "姓名", text: "Tom" },
+          { label: "年龄", text: 18 },
+          { label: "身高", text: "180cm" },
+          { label: "爱好", text: "篮球", group: "other" },
+          {
+            label: "标签",
+            group: "other",
+            useBrick: [
+              {
+                brick: "eo-tag-list",
+                properties: {
+                  list: [
+                    { text: "阳光", key: 0, color: "blue" },
+                    { text: "开朗", key: 1, color: "red" },
+                    { text: "大男孩", key: 2, color: "green" },
+                  ],
+                },
+              },
+            ],
+          },
+        ]}
+      />
+      <div style={{ margin: "10px 0px" }} />
+      <WrappedEoDescriptions
+        hideGroups={["name", "other"]}
+        list={[
+          { label: "姓名", text: "Tom", group: "name" },
+          { label: "年龄", text: 18, group: "age" },
+          { label: "身高", text: "180cm" },
+          { label: "爱好", text: "篮球", group: "other" },
+          {
+            label: "标签",
+            useBrick: [
+              {
+                brick: "eo-tag-list",
+                properties: {
+                  list: [
+                    { text: "阳光", key: 0, color: "blue" },
+                    { text: "开朗", key: 1, color: "red" },
+                    { text: "大男孩", key: 2, color: "green" },
+                  ],
+                },
+              },
+            ],
+          },
+        ]}
+      />
+    </>
+  );
+}
+```
+
+### DataSource
+
+通过 `dataSource` 提供数据源，list 项可用 `field` 读取字段，也可在 `useBrick` 中通过 `DATA` 引用整个数据源。
+
+```tsx preview
+import { WrappedEoDescriptions } from "@easyops/wrapped-components";
+
+export default function App() {
+  return (
+    <WrappedEoDescriptions
+      dataSource={{ text: "Hello world", name: "Tom" }}
+      list={[
+        { label: "姓名", field: "name" },
+        { label: "年龄", text: 18 },
+        { label: "身高", text: "180cm" },
+        { label: "爱好", text: "篮球" },
+        {
+          label: "Form dataSource",
+          useBrick: {
+            brick: "div",
+            properties: { textContent: "<% DATA.text %>" },
+          },
+        },
+      ]}
+    />
+  );
+}
+```
+
+### Template Columns
+
+通过 `templateColumns` 精确控制各列宽度，list 项可用 `gridColumn` 跨列显示。
+
+```tsx preview
+import { WrappedEoDescriptions } from "@easyops/wrapped-components";
+
+export default function App() {
+  return (
+    <WrappedEoDescriptions
+      templateColumns="200px 1fr 2fr"
+      list={[
+        { label: "姓名", text: "Tom" },
+        { label: "年龄", text: 18 },
+        { label: "备注", text: "这是一段较长的备注信息", gridColumn: "2 / 4" },
+      ]}
+    />
+  );
+}
+```
+
+### Theme Variant Elevo
+
+`themeVariant` 为 `elevo` 时，不渲染外层卡片，适用于 AI 门户等特殊背景场景。
+
+```tsx preview
+import { WrappedEoDescriptions } from "@easyops/wrapped-components";
+
+export default function App() {
+  return (
+    <div style={{ padding: "2em", backgroundColor: "#d8d8d8" }}>
+      <WrappedEoDescriptions
+        themeVariant="elevo"
+        column={1}
+        list={[
+          { label: "姓名", text: "Tom" },
+          { label: "年龄", text: 18 },
+          { label: "身高", text: "180cm" },
+          { label: "爱好", text: "篮球" },
+        ]}
+      />
+    </div>
+  );
+}
+```