@next-bricks/presentational 1.21.9 → 1.21.10

package/docs/eo-code-block.md

@@ -1,15 +1,146 @@
-构件 `eo-code-block`
+---
+tagName: eo-code-block
+displayName: WrappedEoCodeBlock
+description: 代码块展示构件，基于 Shiki 进行语法高亮，支持多种编程语言、亮色/暗色主题自动切换及复制功能。
+category: presentational
+source: "@next-bricks/presentational"
+---
+
+# eo-code-block
+
+> 代码块展示构件，基于 Shiki 进行语法高亮，支持多种编程语言、亮色/暗色主题自动切换及复制功能。
+
+## Props
+
+| 属性           | 类型                                    | 必填 | 默认值   | 说明                                                           |
+| -------------- | --------------------------------------- | ---- | -------- | -------------------------------------------------------------- |
+| language       | `string`                                | 否   | -        | 代码语言，用于语法高亮，例如 `javascript`、`python`、`yaml` 等 |
+| source         | `string`                                | 否   | -        | 代码内容字符串                                                 |
+| theme          | `"auto" \| "light-plus" \| "dark-plus"` | 否   | `"auto"` | 代码高亮主题。`auto` 跟随系统主题自动切换亮色/暗色             |
+| themeVariant   | `"default" \| "elevo"`                  | 否   | -        | 主题变体，影响代码块的整体样式风格                             |
+| showCopyButton | `boolean`                               | 否   | `true`   | 是否展示复制按钮                                               |
+
+## CSS Parts
+
+| 名称    | 说明                        |
+| ------- | --------------------------- |
+| pre     | 包裹代码内容的 `<pre>` 元素 |
+| copy    | 复制按钮                    |
+| mermaid | Mermaid 图表                |
+| wrapper | code-wrapper 构件           |
 
 ## Examples
 
 ### Basic
 
+展示代码块的基本用法，通过 `language` 和 `source` 属性渲染带语法高亮的代码。
+
 ```yaml preview
 brick: eo-code-block
 properties:
-  language: js
+  language: javascript
   source: |
-    function test() {
-      console.log("Hello, world");
+    function greet(name) {
+      console.log("Hello, " + name + "!");
     }
+    greet("world");
+```
+
+### Multiple Languages
+
+展示对不同编程语言的语法高亮支持，包括 Python、YAML 和 Shell。
+
+```yaml preview
+- brick: eo-code-block
+  properties:
+    language: python
+    source: |
+      def greet(name):
+          print(f"Hello, {name}!")
+
+      greet("world")
+- brick: eo-code-block
+  properties:
+    language: yaml
+    source: |
+      name: Alice
+      age: 30
+      hobbies:
+        - reading
+        - coding
+- brick: eo-code-block
+  properties:
+    language: shell
+    source: |
+      echo "Hello, world!"
+      ls -la /tmp
+```
+
+### Theme
+
+通过 `theme` 属性指定代码高亮主题，支持 `light-plus`（亮色）、`dark-plus`（暗色）和 `auto`（跟随系统）。
+
+```yaml preview
+- brick: eo-code-block
+  properties:
+    language: javascript
+    theme: light-plus
+    source: |
+      const x = 42;
+      console.log(x);
+- brick: eo-code-block
+  properties:
+    language: javascript
+    theme: dark-plus
+    source: |
+      const x = 42;
+      console.log(x);
+```
+
+### Theme Variant Elevo
+
+设置 `themeVariant` 为 `elevo` 以使用 Elevo 风格的代码块样式。
+
+```yaml preview
+brick: eo-code-block
+properties:
+  language: javascript
+  themeVariant: elevo
+  source: |
+    const greet = (name) => {
+      return `Hello, ${name}!`;
+    };
+    console.log(greet("world"));
+```
+
+### Hide Copy Button
+
+设置 `showCopyButton` 为 `false` 隐藏复制按钮。
+
+```yaml preview
+brick: eo-code-block
+properties:
+  language: python
+  showCopyButton: false
+  source: |
+    for i in range(10):
+        print(i)
+```
+
+### CSS Parts
+
+通过 CSS Parts 自定义代码块样式，例如为 `pre` 部分设置圆角和边框，为 `copy` 按钮设置颜色。
+
+```yaml preview
+- brick: eo-code-block
+  properties:
+    style:
+      "--part-pre-border-radius": "8px"
+    language: typescript
+    source: |
+      interface User {
+        name: string;
+        age: number;
+      }
+      const user: User = { name: "Alice", age: 30 };
 ```

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

@@ -0,0 +1,146 @@
+---
+tagName: eo-code-block
+displayName: WrappedEoCodeBlock
+description: 代码块展示构件，基于 Shiki 进行语法高亮，支持多种编程语言、亮色/暗色主题自动切换及复制功能。
+category: presentational
+source: "@next-bricks/presentational"
+---
+
+# WrappedEoCodeBlock
+
+> 代码块展示构件，基于 Shiki 进行语法高亮，支持多种编程语言、亮色/暗色主题自动切换及复制功能。
+
+## 导入
+
+```tsx
+import { WrappedEoCodeBlock } from "@easyops/wrapped-components";
+```
+
+## Props
+
+| 属性           | 类型                                    | 必填 | 默认值   | 说明                                                           |
+| -------------- | --------------------------------------- | ---- | -------- | -------------------------------------------------------------- |
+| language       | `string`                                | 否   | -        | 代码语言，用于语法高亮，例如 `javascript`、`python`、`yaml` 等 |
+| source         | `string`                                | 否   | -        | 代码内容字符串                                                 |
+| theme          | `"auto" \| "light-plus" \| "dark-plus"` | 否   | `"auto"` | 代码高亮主题。`auto` 跟随系统主题自动切换亮色/暗色             |
+| themeVariant   | `"default" \| "elevo"`                  | 否   | -        | 主题变体，影响代码块的整体样式风格                             |
+| showCopyButton | `boolean`                               | 否   | `true`   | 是否展示复制按钮                                               |
+
+## CSS Parts
+
+| 名称    | 说明                        |
+| ------- | --------------------------- |
+| pre     | 包裹代码内容的 `<pre>` 元素 |
+| copy    | 复制按钮                    |
+| mermaid | Mermaid 图表                |
+| wrapper | code-wrapper 构件           |
+
+## Examples
+
+### Basic
+
+展示代码块的基本用法，通过 `language` 和 `source` 属性渲染带语法高亮的代码。
+
+```tsx
+<WrappedEoCodeBlock
+  language="javascript"
+  source={`function greet(name) {
+  console.log("Hello, " + name + "!");
+}
+greet("world");`}
+/>
+```
+
+### Multiple Languages
+
+展示对不同编程语言的语法高亮支持，包括 Python、YAML 和 Shell。
+
+```tsx
+<>
+  <WrappedEoCodeBlock
+    language="python"
+    source={`def greet(name):
+    print(f"Hello, {name}!")
+
+greet("world")`}
+  />
+  <WrappedEoCodeBlock
+    language="yaml"
+    source={`name: Alice
+age: 30
+hobbies:
+  - reading
+  - coding`}
+  />
+  <WrappedEoCodeBlock
+    language="shell"
+    source={`echo "Hello, world!"
+ls -la /tmp`}
+  />
+</>
+```
+
+### Theme
+
+通过 `theme` 属性指定代码高亮主题，支持 `light-plus`（亮色）、`dark-plus`（暗色）和 `auto`（跟随系统）。
+
+```tsx
+<>
+  <WrappedEoCodeBlock
+    language="javascript"
+    theme="light-plus"
+    source={`const x = 42;
+console.log(x);`}
+  />
+  <WrappedEoCodeBlock
+    language="javascript"
+    theme="dark-plus"
+    source={`const x = 42;
+console.log(x);`}
+  />
+</>
+```
+
+### Theme Variant Elevo
+
+设置 `themeVariant` 为 `elevo` 以使用 Elevo 风格的代码块样式。
+
+```tsx
+<WrappedEoCodeBlock
+  language="javascript"
+  themeVariant="elevo"
+  source={`const greet = (name) => {
+  return \`Hello, \${name}!\`;
+};
+console.log(greet("world"));`}
+/>
+```
+
+### Hide Copy Button
+
+设置 `showCopyButton` 为 `false` 隐藏复制按钮。
+
+```tsx
+<WrappedEoCodeBlock
+  language="python"
+  showCopyButton={false}
+  source={`for i in range(10):
+    print(i)`}
+/>
+```
+
+### CSS Parts
+
+通过 CSS Parts 自定义代码块样式，例如为 `pre` 部分设置圆角和边框，为 `copy` 按钮设置颜色。
+
+```tsx
+<WrappedEoCodeBlock
+  language="typescript"
+  style={{ "--part-pre-border-radius": "8px" } as React.CSSProperties}
+  source={`interface User {
+  name: string;
+  age: number;
+}
+const user: User = { name: "Alice", age: 30 };`}
+/>
+```

package/docs/eo-code-display.md

@@ -1,9 +1,34 @@
-代码展示
+---
+tagName: eo-code-display
+displayName: WrappedEoCodeDisplay
+description: 代码展示
+category: display-component
+source: "@next-bricks/presentational"
+---
+
+# eo-code-display
+
+> 代码展示
+
+## Props
+
+| 属性             | 类型      | 必填 | 默认值 | 说明                                                                           |
+| ---------------- | --------- | ---- | ------ | ------------------------------------------------------------------------------ |
+| value            | `string`  | -    | `""`   | 代码内容                                                                       |
+| language         | `string`  | -    | -      | 语言，具体查阅 [Supported languages](https://prismjs.com/#supported-languages) |
+| hideLineNumber   | `boolean` | -    | -      | 是否隐藏行号                                                                   |
+| maxLines         | `number`  | -    | -      | 最大行数                                                                       |
+| minLines         | `number`  | -    | -      | 最小行数                                                                       |
+| showCopyButton   | `boolean` | -    | `true` | 是否显示复制按钮                                                               |
+| showExportButton | `boolean` | -    | -      | 是否显示导出按钮                                                               |
+| exportFileName   | `string`  | -    | -      | 导出的文件名                                                                   |
 
 ## Examples
 
 ### Basic
 
+基本用法，展示一段 JavaScript 代码并显示行号。
+
 ```yaml preview
 - brick: eo-code-display
   properties:
@@ -17,3 +42,74 @@
         };
       }
 ```
+
+### 隐藏行号
+
+隐藏代码行号显示。
+
+```yaml preview
+- brick: eo-code-display
+  properties:
+    language: javascript
+    hideLineNumber: true
+    value: |
+      const greeting = "Hello, World!";
+      console.log(greeting);
+```
+
+### 限制行数
+
+通过 maxLines 和 minLines 控制代码展示区域的行数范围。
+
+```yaml preview
+- brick: eo-code-display
+  properties:
+    language: javascript
+    maxLines: 5
+    minLines: 3
+    value: |
+      const a = 1;
+      const b = 2;
+      const c = 3;
+      const d = 4;
+      const e = 5;
+      const f = 6;
+      const g = 7;
+      const h = 8;
+```
+
+### 工具栏按钮
+
+显示复制和导出按钮，支持将代码复制到剪贴板或导出为文件。
+
+```yaml preview
+- brick: eo-code-display
+  properties:
+    language: json
+    showCopyButton: true
+    showExportButton: true
+    exportFileName: config.json
+    value: |
+      {
+        "name": "my-app",
+        "version": "1.0.0",
+        "description": "A sample application"
+      }
+```
+
+### 隐藏复制按钮
+
+将 showCopyButton 设置为 false 隐藏默认的复制按钮。
+
+```yaml preview
+- brick: eo-code-display
+  properties:
+    language: css
+    showCopyButton: false
+    value: |
+      .container {
+        display: flex;
+        justify-content: center;
+        align-items: center;
+      }
+```

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

@@ -0,0 +1,116 @@
+---
+tagName: eo-code-display
+displayName: WrappedEoCodeDisplay
+description: 代码展示
+category: display-component
+source: "@next-bricks/presentational"
+---
+
+# WrappedEoCodeDisplay
+
+> 代码展示
+
+## 导入
+
+```tsx
+import { WrappedEoCodeDisplay } from "@easyops/wrapped-components";
+```
+
+## Props
+
+| 属性             | 类型      | 必填 | 默认值 | 说明                                                                           |
+| ---------------- | --------- | ---- | ------ | ------------------------------------------------------------------------------ |
+| value            | `string`  | -    | `""`   | 代码内容                                                                       |
+| language         | `string`  | -    | -      | 语言，具体查阅 [Supported languages](https://prismjs.com/#supported-languages) |
+| hideLineNumber   | `boolean` | -    | -      | 是否隐藏行号                                                                   |
+| maxLines         | `number`  | -    | -      | 最大行数                                                                       |
+| minLines         | `number`  | -    | -      | 最小行数                                                                       |
+| showCopyButton   | `boolean` | -    | `true` | 是否显示复制按钮                                                               |
+| showExportButton | `boolean` | -    | -      | 是否显示导出按钮                                                               |
+| exportFileName   | `string`  | -    | -      | 导出的文件名                                                                   |
+
+## Examples
+
+### Basic
+
+基本用法，展示一段 JavaScript 代码并显示行号。
+
+```tsx
+<WrappedEoCodeDisplay
+  language="javascript"
+  value={`function onSubmit (e) {
+  const fn = () => 123;
+  const job = {
+    title: 'Developer',
+    company: 'Facebook'
+  };
+}`}
+/>
+```
+
+### 隐藏行号
+
+隐藏代码行号显示。
+
+```tsx
+<WrappedEoCodeDisplay
+  language="javascript"
+  hideLineNumber={true}
+  value={`const greeting = "Hello, World!";
+console.log(greeting);`}
+/>
+```
+
+### 限制行数
+
+通过 maxLines 和 minLines 控制代码展示区域的行数范围。
+
+```tsx
+<WrappedEoCodeDisplay
+  language="javascript"
+  maxLines={5}
+  minLines={3}
+  value={`const a = 1;
+const b = 2;
+const c = 3;
+const d = 4;
+const e = 5;
+const f = 6;
+const g = 7;
+const h = 8;`}
+/>
+```
+
+### 工具栏按钮
+
+显示复制和导出按钮，支持将代码复制到剪贴板或导出为文件。
+
+```tsx
+<WrappedEoCodeDisplay
+  language="json"
+  showCopyButton={true}
+  showExportButton={true}
+  exportFileName="config.json"
+  value={`{
+  "name": "my-app",
+  "version": "1.0.0",
+  "description": "A sample application"
+}`}
+/>
+```
+
+### 隐藏复制按钮
+
+将 showCopyButton 设置为 false 隐藏默认的复制按钮。
+
+```tsx
+<WrappedEoCodeDisplay
+  language="css"
+  showCopyButton={false}
+  value={`.container {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+}`}
+/>
+```

package/docs/eo-code-wrapper.md

@@ -0,0 +1,108 @@
+---
+tagName: presentational.code-wrapper
+displayName: WrappedPresentationalCodeWrapper
+description: 代码内容包裹容器，提供统一的代码展示结构并支持一键复制功能。
+category: ""
+source: "@next-bricks/presentational"
+---
+
+# presentational.code-wrapper
+
+> 代码内容包裹容器，提供统一的代码展示结构并支持一键复制功能。
+
+## 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>` 子节点，默认展示复制按钮。
+
+```yaml preview
+brick: presentational.code-wrapper
+properties:
+  preProps:
+    children:
+      - brick: code
+        properties:
+          textContent: "const greeting = 'Hello, World!';"
+```
+
+### 隐藏复制按钮
+
+设置 `showCopyButton` 为 `false` 可隐藏右上角的复制按钮。
+
+```yaml preview
+brick: presentational.code-wrapper
+properties:
+  showCopyButton: false
+  preProps:
+    children:
+      - brick: code
+        properties:
+          textContent: "const greeting = 'Hello, World!';"
+```
+
+### Elevo 主题变体
+
+设置 `themeVariant` 为 `"elevo"` 使复制按钮采用 Elevo 主题样式。
+
+```yaml preview
+brick: presentational.code-wrapper
+properties:
+  themeVariant: elevo
+  preProps:
+    children:
+      - brick: code
+        properties:
+          textContent: "const greeting = 'Hello, World!';"
+```
+
+### 自定义 pre 元素样式
+
+通过 `preProps` 的 `style` 字段为 `<pre>` 元素设置自定义内联样式。
+
+```yaml preview
+brick: presentational.code-wrapper
+properties:
+  preProps:
+    style:
+      background: "#1e1e1e"
+      color: "#d4d4d4"
+      padding: 16px
+      borderRadius: 8px
+    children:
+      - brick: code
+        properties:
+          textContent: "const greeting = 'Hello, World!';"
+```
+
+### 自定义 CSS Parts
+
+通过 `pre` 和 `copy` CSS Parts 对内部元素进行样式定制，例如修改 `<pre>` 背景色和圆角、调整复制按钮颜色。
+
+```yaml preview
+brick: presentational.code-wrapper
+properties:
+  style:
+    "--part-pre-border-radius": "8px"
+    "--part-copy-color": "var(--color-brand)"
+  preProps:
+    children:
+      - brick: code
+        properties:
+          textContent: "const greeting = 'Hello, World!';"
+```