### Local Development Setup

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/README.md

Clone the repository, install dependencies, and start development servers for documentation or components. Build the component library as needed.

```bash
# 克隆仓库
git clone https://github.com/HeJiaYue520/Element-Plus-X.git

# 安装依赖
pnpm install

# 启动文档开发服务器
pnpm run dev:docs

# 启动组件开发服务器 (Storybook)
pnpm run dev:core

# 构建组件库
pnpm run build:core
```

--------------------------------

### Build Core and Start Documentation Site

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/guide/develop.md

Build the core package to generate type definitions and then start the documentation site for local development.

```bash
pnpm build:core
pnpm dev:docs
```

--------------------------------

### Install vue-element-plus-x with npm, pnpm, or yarn

Source: https://context7.com/element-plus-x/element-plus-x/llms.txt

Install the library alongside its peer dependencies (element-plus, vue).

```bash
# npm
npm install vue-element-plus-x

# pnpm (recommended)
pnpm add vue-element-plus-x

# yarn
yarn add vue-element-plus-x
```

--------------------------------

### Install x-markdown-vue and Dependencies

Source: https://context7.com/element-plus-x/element-plus-x/llms.txt

Install the `x-markdown-vue` package along with `katex` and `shiki` for math rendering and syntax highlighting, and `shiki-stream` for streaming animation.

```bash
pnpm add x-markdown-vue katex shiki shiki-stream
```

--------------------------------

### ConfigProvider Basic Usage

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/components/configProvider/index.md

Wrap your application with ConfigProvider to apply global configurations. This example shows basic setup.

```vue
<template>
  <ConfigProvider :theme="theme">
    <App />
  </ConfigProvider>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { ConfigProvider } from 'vue-element-plus-x';

const theme = ref<'light' | 'dark'>('light');
</script>
```

--------------------------------

### Install x-markdown-vue and Dependencies

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/components/bubble/index.md

Provides the necessary commands to install x-markdown-vue and optional dependencies for code block syntax highlighting.

```bash
pnpm add x-markdown-vue
pnpm add katex
pnpm add shiki shiki-stream
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/guide/contribution.md

Clone the Element-Plus-X repository and install project dependencies using pnpm.

```bash
git clone https://github.com/your-username/Element-Plus-X.git
cd Element-Plus-X
pnpm install
```

--------------------------------

### Install x-markdown-vue Package

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/packages/core/README.en.md

Install the new x-markdown-vue package using pnpm.

```bash
# Install the new package
pnpm add x-markdown-vue
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/guide/develop.md

Install all project dependencies using the pnpm package manager.

```bash
pnpm install
```

--------------------------------

### Install Element-Plus-X with NPM, PNPM, or Yarn

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/README.en.md

Use your preferred package manager to install the Element-Plus-X library.

```bash
# NPM
npm install vue-element-plus-x

# PNPM (Recommended)
pnpm install vue-element-plus-x

# Yarn
yarn install vue-element-plus-x

```

--------------------------------

### Full Migration Example: v1 to v2

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/guide/migration-v2.md

This example demonstrates a complete migration from v1 to v2, showcasing the updated component usage and structure.

```vue
<template>
  <div class="chat-app">
    <BubbleList :list="list" />
    <MentionSender v-model="inputValue" @submit="handleSend" />
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { BubbleList, MentionSender } from 'vue-element-plus-x';

const list = ref([
  { content: 'Hello! How can I help you?', role: 'assistant' }
]);
const inputValue = ref('');

const handleSend = () => {
  list.value.push({ content: inputValue.value, role: 'user' });
  inputValue.value = '';
};
</script>
```

```vue
<template>
  <ConfigProvider :theme="isDark ? 'dark' : 'light'">
    <div class="chat-app">
      <BubbleList :list="list">
        <template #content="{ item }">
          <MarkdownRenderer :markdown="item.content" :enable-animate="true" />
        </template>
      </BubbleList>
      <XSender
        v-model="inputValue"
        :mention-config="mentionConfig"
        @submit="handleSend"
      />
    </div>
  </ConfigProvider>
</template>

<script setup>
import { ref } from 'vue';
import { BubbleList, XSender, ConfigProvider } from 'vue-element-plus-x';
import { MarkdownRenderer } from 'x-markdown-vue';
import 'x-markdown-vue/style';

const isDark = ref(false);
const mentionConfig = ref({
  /* mention configuration */
});
const list = ref([
  { content: 'Hello! How can I help you?', role: 'assistant' }
]);
const inputValue = ref('');

const handleSend = () => {
  list.value.push({ content: inputValue.value, role: 'user' });
  inputValue.value = '';
};
</script>
```

--------------------------------

### Install x-markdown-vue

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/components/xMarkdown/index.md

Install the x-markdown-vue package using your preferred package manager.

```bash
# pnpm (recommended)
pnpm add x-markdown-vue

# npm
npm install x-markdown-vue

# yarn
yarn add x-markdown-vue
```

--------------------------------

### Install Element-Plus-X with npm, pnpm, or yarn

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/guide/introduce.md

Choose your preferred package manager to install the Element-Plus-X library.

```sh
npm install vue-element-plus-x --save
```

```sh
pnpm add vue-element-plus-x --save
```

```sh
yarn add vue-element-plus-x --save
```

--------------------------------

### Basic useRecord Usage

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/components/useRecord/index.md

This example demonstrates the basic integration of the useRecord hook. It shows how to start and stop speech recognition and access the real-time transcribed text.

```vue
<template>
  <el-input v-model="text" placeholder="Please input" />
  <el-button @click="start">Start</el-button>
  <el-button @click="stop">Stop</el-button>
</template>

<script lang="ts" setup>
import { useRecord } from '@vue-element-plus/hooks'

const {
  start,
  stop,
  loading,
  value: text,
} = useRecord({
  onEnd: (res) => {
    console.log(res)
  },
})
</script>
```

--------------------------------

### Basic Welcome Usage

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/components/welcome/index.md

Demonstrates the fundamental usage of the Welcome component. No specific setup is required beyond importing the component.

```vue
<template>
  <Welcome />
</template>

<script setup>
import { Welcome } from '@element-plus/x'
</script>
```

--------------------------------

### Correct Commit Examples

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/guide/contribution.md

Examples demonstrating the correct commit message format for various types like features, bug fixes, documentation updates, and breaking changes.

```bash
# New feature
feat(Bubble): add maxWidth property
```

```bash
# Bug fix with Issue reference
fix(Sender): fix v-model binding issue #22
```

```bash
# Documentation update (no scope)
docs: update development guide
```

```bash
# Breaking change
breaking(Bubble): remove typing property
```

```bash
# Performance improvement
perf(BubbleList): optimize rendering performance for large data
```

--------------------------------

### Basic Attachments Usage

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/components/attachments/index.md

Demonstrates the basic setup and usage of the Attachments component. No specific setup or imports are required beyond including the component.

```vue
<template>
  <XAttachment :items="items" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import type { FilesCardProps } from '@element-plus/x/attachments'

const items = ref<FilesCardProps[]>([
  {
    name: 'element-plus-x.png',
    url: 'https://element-plus.org/images/element-plus-x.png',
  },
  {
    name: 'element-plus-x.png',
    url: 'https://element-plus.org/images/element-plus-x.png',
  },
])
</script>
```

--------------------------------

### Display an Onboarding Screen with Welcome Component

Source: https://context7.com/element-plus-x/element-plus-x/llms.txt

Use the Welcome component to display an introductory screen with customizable text, icons, and styles. Ensure 'vue-element-plus-x' is installed.

```vue
<template>
  <Welcome
    variant="filled"
    icon="https://cdn.element-plus-x.com/element-plus-x.png"
    title="Hello, I'm your AI Assistant"
    extra="Powered by Element Plus X"
    description="Ask me anything — I can summarize documents, write code, answer questions, and more."
    :styles="{
      title: { fontSize: '22px', fontWeight: 700 },
      extra: { color: '#7c3aed' },
      description: { maxWidth: '480px' }
    }"
  >
    <template #extra>
      <div style="display:flex; gap:8px; flex-wrap:wrap; margin-top:8px;">
        <el-tag type="success">GPT-4</el-tag>
        <el-tag type="info">Vision</el-tag>
        <el-tag type="warning">Code</el-tag>
      </div>
    </template>
  </Welcome>
</template>

<script setup>
import { Welcome } from 'vue-element-plus-x';
</script>
```

--------------------------------

### XSender Basic Usage

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/components/xsender/index.md

Demonstrates the basic implementation of the XSender component. No specific setup is required beyond importing the component.

```vue
<template>
  <XSender />
</template>

<script lang="ts" setup>
import XSender from "@/components/XSender.vue";
</script>
```

--------------------------------

### Install Element Plus X

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/README.md

Install the stable, beta, or a specific version of the vue-element-plus-x package using pnpm.

```bash
pnpm install vue-element-plus-x
```

```bash
pnpm install vue-element-plus-x@beta
```

```bash
pnpm install vue-element-plus-x@2.0.0-beta.0
```

--------------------------------

### Basic FilesCard Usage

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/zh/components/filesCard/index.md

Demonstrates the fundamental usage of the FilesCard component. No specific setup is required beyond importing the component.

```vue
<template>
  <FilesCard
    uid="1"
    name="document.pdf"
    fileSize={1024 * 1024}
    description="A sample PDF document"
  />
</template>

<script setup lang="ts">
import FilesCard from "@/components/FilesCard.vue";
</script>
```

--------------------------------

### Install x-markdown-vue and dependencies

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/guide/migration-v2.md

Install the x-markdown-vue package along with optional dependencies for LaTeX and code syntax highlighting using your preferred package manager.

```sh
pnpm add x-markdown-vue
pnpm add katex
pnpm add shiki shiki-stream
```

```sh
npm install x-markdown-vue
npm install katex
npm install shiki shiki-stream
```

```sh
yarn add x-markdown-vue
yarn add katex
yarn add shiki shiki-stream
```

--------------------------------

### Complete Migration Example v1 to v2

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/zh/guide/migration-v2.md

Compares the v1 and v2 implementations of a chat application, highlighting changes in components and imports.

```vue
<template>
  <div class="chat-app">
    <BubbleList :list="list" />
    <MentionSender v-model="inputValue" @submit="handleSend" />
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { BubbleList, MentionSender } from 'vue-element-plus-x';

const list = ref([{ content: '你好，有什么可以帮你的？', role: 'assistant' }]);
const inputValue = ref('');

const handleSend = () => {
  list.value.push({ content: inputValue.value, role: 'user' });
  inputValue.value = '';
};
</script>
```

```vue
<template>
  <ConfigProvider :theme="isDark ? 'dark' : 'light'">
    <div class="chat-app">
      <BubbleList :list="list">
        <template #content="{ item }">
          <MarkdownRenderer :markdown="item.content" :enable-animate="true" />
        </template>
      </BubbleList>
      <XSender
        v-model="inputValue"
        :mention-config="mentionConfig"
        @submit="handleSend"
      />
    </div>
  </ConfigProvider>
</template>

<script setup>
import { ref } from 'vue';
import { BubbleList, XSender, ConfigProvider } from 'vue-element-plus-x';
import { MarkdownRenderer } from 'x-markdown-vue';
import 'x-markdown-vue/style';

const isDark = ref(false);
const mentionConfig = ref({
  /* 提及配置 */
});
const list = ref([{ content: '你好，有什么可以帮你的？', role: 'assistant' }]);
const inputValue = ref('');

const handleSend = () => {
  list.value.push({ content: inputValue.value, role: 'user' });
  inputValue.value = '';
};
</script>
```

--------------------------------

### Install Optional Dependencies for x-markdown-vue

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/components/xMarkdown/index.md

Install optional peer dependencies for enhanced features like syntax highlighting, Mermaid diagrams, and LaTeX math.

```bash
# Syntax highlighting (Shiki)
pnpm add shiki shiki-stream

# Mermaid diagrams
pnpm add mermaid

# LaTeX math formulas (also requires importing the CSS)
pnpm add katex
```

--------------------------------

### Correct PR Title Examples

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/guide/contribution.md

Examples of correctly formatted Pull Request titles, including scope and type.

```bash
[Bubble] fix: fix maxWidth property issue
```

```bash
[XSender] feat: add submit-btn-disabled property
```

```bash
[docs] update: update theme configuration docs
```

--------------------------------

### Attachments Basic Usage

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/zh/components/attachments/index.md

Demonstrates the basic setup and usage of the Attachments component.

```vue
<template>
  <Attachments :items="fileList" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import Attachments from 'element-plus-x/components/attachments'
import type { FilesCardProps } from 'element-plus-x/components/attachments'

const fileList = ref<FilesCardProps[]>([
  {
    name: 'element-plus-x.png',
    url: 'https://element-plus.org/images/element-plus-logo.svg',
    status: 'success',
    type: 'image/png',
  },
  {
    name: 'element-plus-x.zip',
    url: 'https://element-plus.org/images/element-plus-logo.svg',
    status: 'uploading',
    type: 'application/zip',
  },
])
</script>
```

--------------------------------

### Install Element Plus X with npm

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/guide/install.md

Use npm to install the Element Plus X package. This is a common method for managing project dependencies.

```sh
npm install vue-element-plus-x --save
```

--------------------------------

### Basic Usage of Thinking Component

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/zh/components/thinking/index.md

Demonstrates the fundamental implementation of the Thinking component. No specific setup is required beyond importing the component.

```vue
<template>
  <Thinking />
</template>

<script lang="ts" setup>
import Thinking from "./thinking.vue";
</script>
```

--------------------------------

### Install Element Plus X with pnpm

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/guide/install.md

Use pnpm to install the Element Plus X package. pnpm is a fast, space-efficient package manager.

```sh
pnpm add vue-element-plus-x --save
```

--------------------------------

### Basic useSend Hook Usage

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/components/useSend/index.md

Demonstrates the fundamental usage of the useSend hook. Pass a start method to obtain loading state and a finish method.

```vue
<template>
  <button @click="send">Send Request</button>
  <p v-if="loading">Loading...</p>
</template>

<script setup lang="ts">
import { useSend } from "@/hooks/useSend";

const { send, loading } = useSend(() => {
  // Simulate a request
  return new Promise((resolve) => setTimeout(resolve, 1000));
});
</script>
```

--------------------------------

### Basic useSend Hook Usage

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/zh/components/useSend/index.md

Demonstrates the fundamental usage of the useSend hook by passing a starting method to obtain loading state and a finish method.

```vue
<template>
  <button @click="send">{{ loading ? 'Loading...' : 'Send Request' }}</button>
</template>

<script setup lang="ts">
import { useSend } from '@vue-element-plus/hooks'

const { send, loading, finish } = useSend(() => {
  // Simulate a request
  return new Promise((resolve) => {
    setTimeout(() => {
      console.log('Request finished')
      finish()
      resolve(true)
    }, 2000)
  })
})
</script>
```

--------------------------------

### Responsive Width Prompts

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/components/prompts/index.md

Illustrates how the Prompts component can adapt its width responsively. This example likely relies on CSS or parent container behavior.

```vue
<template>
  <div style="width: 300px;">
    <elx-prompts :items="promptsItems"></elx-prompts>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const promptsItems = ref([
  {
    label: 'Responsive Item 1',
    key: 'r1',
  },
  {
    label: 'Responsive Item 2',
    key: 'r2',
  },
])
</script>
```

--------------------------------

### Install Element Plus X with yarn

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/guide/install.md

Use yarn to install the Element Plus X package. yarn is another popular package manager for JavaScript.

```sh
yarn add vue-element-plus-x --save
```

--------------------------------

### Basic Thinking Component Usage

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/components/thinking/index.md

Demonstrates the fundamental usage of the Thinking component. No specific setup is required beyond importing the component.

```vue
<template>
  <Thinking />
</template>

<script setup lang="ts">
import Thinking from "./thinking.vue";
</script>
```

--------------------------------

### Basic Conversations Usage

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/components/conversations/index.md

Demonstrates the fundamental setup and display of the Conversations component.

```vue
<template>
  <Conversations :items="conversations" />
</template>

<script setup lang="ts">
import { Conversations } from 'element-plus-x'
import type { ConversationItem } from 'element-plus-x'

const conversations = ref<ConversationItem[]>([
  {
    id: 1,
    label: 'New message',
    group: 'Unread',
  },
  {
    id: 2,
    label: 'Meeting reminder',
    group: 'Today',
    disabled: true,
  },
  {
    id: 3,
    label: 'Project discussion',
    group: 'Unread',
  },
])
</script>
```

--------------------------------

### Welcome Component Theme Overrides

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/components/welcome/index.md

Explains how to override theme tokens for the Welcome component using `ConfigProvider.themeOverrides`. Refer to the theme tokens guide for a full list.

```vue
<template>
  <el-config-provider :theme-overrides="{ welcome: { colorPrimary: '#ff0000' } }">
    <Welcome />
  </el-config-provider>
</template>

<script setup>
import { ElConfigProvider } from 'element-plus'
import { Welcome } from '@element-plus/x'
</script>
```

--------------------------------

### FilesCard Component Usage Examples

Source: https://context7.com/element-plus-x/element-plus-x/llms.txt

Demonstrates various use cases of the FilesCard component, including PDF display, image preview, upload progress, and error states. Ensure FilesCard is imported before use.

```vue
<template>
  <div style="display:flex; flex-wrap:wrap; gap:12px; padding:16px;">
    <!-- PDF at rest -->
    <FilesCard
      uid="1"
      name="Q3-Report.pdf"
      :file-size="204800"
      status="done"
      :show-del-icon="true"
      @delete="handleDelete"
    />

    <!-- Image with preview -->
    <FilesCard
      uid="2"
      name="screenshot.png"
      url="https://picsum.photos/400/300"
      file-type="image"
      img-variant="rectangle"
      :img-preview="true"
      :show-del-icon="true"
    />

    <!-- Uploading in progress -->
    <FilesCard
      uid="3"
      name="large-dataset.zip"
      status="uploading"
      :percent="67"
    />

    <!-- Error state -->
    <FilesCard
      uid="4"
      name="corrupt-file.docx"
      status="error"
      error-tip="Network error, upload failed"
    />
  </div>
</template>

<script setup>
import { FilesCard } from 'vue-element-plus-x';

function handleDelete(props) {
  console.log('Delete file:', props.uid, props.name);
}
</script>
```

--------------------------------

### Welcome Component

Source: https://context7.com/element-plus-x/element-plus-x/llms.txt

The Welcome component displays an introductory screen with customizable elements like icons, titles, and descriptions. It supports different visual variants and style overrides.

```APIDOC
## Welcome — Onboarding Screen

`Welcome` displays an introductory screen with an icon/image, title, subtitle (`extra`), and description. Supports `filled` and `borderless` variants and fine-grained style overrides per sub-element.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `variant` | `'filled' | 'borderless'` | `'filled'` | Visual style |
| `icon` | `string` | — | Icon/logo URL |
| `title` | `string` | — | Main heading |
| `extra` | `string` | — | Subtitle text |
| `description` | `string` | — | Body description |
| `styles` | `{ icon, title, extra, description }` | — | Per-element inline styles |
| `classNames` | `{ icon, title, extra, description }` | — | Per-element class names |
| `direction` | `'ltr' | 'rtl'` | `'ltr'` | Text direction |

**Slots:** `#image`, `#extra`
```

--------------------------------

### Create Release and Current Directories

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/scripts/docs/README.md

Sets up the necessary directory structure for storing releases and the current active version. These directories are essential for managing deployments.

```bash
sudo mkdir -p /var/www/element-plus-x/v1/releases /var/www/element-plus-x/v2/releases
sudo mkdir -p /var/www/element-plus-x/v1/current /var/www/element-plus-x/v2/current
```

--------------------------------

### Incorrect Commit Examples

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/guide/contribution.md

Examples of commit messages that do not follow the required format and will be automatically categorized as 'Chore'.

```bash
# ❌ Non-compliant, will be categorized as "Chore"
fixed a bug
new feature
update docs
Bubble fixed issue
```

--------------------------------

### Welcome Component with Background Color

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/components/welcome/index.md

Illustrates how to apply a background color to the Welcome component. This can be achieved through standard CSS or by passing style objects.

```vue
<template>
  <Welcome style="background-color: #f0f0f0;" />
</template>

<script setup>
import { Welcome } from '@element-plus/x'
</script>
```

--------------------------------

### Install Certbot for Nginx

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/scripts/docs/README.md

Installs Certbot and the Nginx plugin to manage TLS certificates for Nginx. This is a prerequisite for enabling HTTPS.

```bash
sudo apt update
sudo apt install -y certbot python3-certbot-nginx
```

--------------------------------

### Basic Usage of XSender

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/zh/components/xsender/index.md

Demonstrates the fundamental implementation of the XSender component.

```vue
<template>
  <XSender />
</template>

<script lang="ts" setup>
import XSender from "@/components/xsender/index.vue";
</script>
```

--------------------------------

### Dark Mode Example

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/components/xMarkdown/index.md

Applies dark mode styling to the Markdown rendering.

```vue
<template>
  <MarkdownRenderer :content="markdown" theme="dark" />
</template>

<script setup lang="ts">
import MarkdownRenderer from 'x-markdown-vue';

const markdown = 'This content will be rendered in dark mode.';
</script>
```

--------------------------------

### Welcome Component with Custom Image

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/components/welcome/index.md

Demonstrates how to replace the default icon with a custom image using the `icon` property. Ensure the provided URL is accessible.

```vue
<template>
  <Welcome icon="/path/to/your/custom-icon.png" />
</template>

<script setup>
import { Welcome } from '@element-plus/x'
</script>
```

--------------------------------

### Custom Attributes Example

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/components/xMarkdown/index.md

Applies custom attributes to HTML elements generated from Markdown.

```vue
<template>
  <MarkdownRenderer :content="markdown" :custom-attrs="attrs" />
</template>

<script setup lang="ts">
import MarkdownRenderer from 'x-markdown-vue';

const markdown = '<p data-testid="my-paragraph">This paragraph has custom attributes.</p>';

const attrs = {
  'data-testid': 'my-paragraph',
  class: 'custom-class',
};
</script>
```

--------------------------------

### Mermaid Diagram Rendering

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/components/xMarkdown/index.md

Renders Mermaid diagrams within the Markdown content. Ensure 'mermaid' is installed.

```vue
<template>
  <MarkdownRenderer :content="mermaidMarkdown" />
</template>

<script setup lang="ts">
import MarkdownRenderer from 'x-markdown-vue';

const mermaidMarkdown = '```mermaid
graph TD;
    A-->B;
    B-->C;
```';
</script>
```

--------------------------------

### FilesCard Custom Styles and Interaction

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/components/filesCard/index.md

Provides an example of customizing the appearance and interactive behavior of the FilesCard component.

```vue
<template>
  <FilesCard class="custom-files-card" />
</template>

<script lang="ts" setup>
import { FilesCard } from '@element-plus/x/components/files-card'
</script>

<style>
.custom-files-card {
  /* Custom styles here */
}
</style>
```

--------------------------------

### Streaming Animation Example

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/components/xMarkdown/index.md

Renders Markdown content with a streaming animation effect, suitable for AI chat responses.

```vue
<template>
  <MarkdownRenderer :content="streamingMarkdown" :streaming="true" />
</template>

<script setup lang="ts">
import MarkdownRenderer from 'x-markdown-vue';

const streamingMarkdown = 'This text will appear character by character.';
</script>
```

--------------------------------

### FilesCard Basic Usage

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/components/filesCard/index.md

Demonstrates the fundamental usage of the FilesCard component.

```vue
<template>
  <FilesCard />
</template>

<script lang="ts" setup>
import { FilesCard } from '@element-plus/x/components/files-card'
</script>
```

--------------------------------

### ConfigProvider Theme Overrides (Components)

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/components/configProvider/index.md

Customize theme variables for specific components. This example overrides styles for 'Attachments' and 'Thinking' components.

```typescript
const themeOverrides = {
  components: {
    Attachments: {
      'attachments-nav-bg': 'rgba(124, 58, 237, 0.35)',
      'attachments-nav-bg-hover': 'rgba(124, 58, 237, 0.45)',
      'attachments-nav-bg-active': 'rgba(124, 58, 237, 0.55)'
    },
    Thinking: {
      'thinking-trigger-bg': '#f8fafc',
      'thinking-trigger-border-color': 'rgba(15, 23, 42, 0.12)'
    }
  }
};
```

--------------------------------

### useRecord

Source: https://context7.com/element-plus-x/element-plus-x/llms.txt

Wraps the browser's `SpeechRecognition` API, providing reactive controls for starting and stopping, a live transcript, and loading state.

```APIDOC
## useRecord — Browser Speech Recognition

`useRecord` wraps the browser's built-in `SpeechRecognition` API, returning reactive start/stop controls, a live transcript, and loading state — ready to wire into any custom voice-input button alongside `XSender`.

### Configuration

- **`onEnd`**: `(result: string) => void` - Called with the final recognized text.

### Methods

- **`start`**: `(event: MouseEvent) => void` - Begin recording.
- **`stop`**: `(event: MouseEvent) => void` - Stop recording.

### State

- **`loading`**: `Ref<boolean>` - `true` while microphone is active.
- **`value`**: `Ref<string>` - Live speech-to-text transcript.

### Example Usage

```vue
<template>
  <div style="display:flex; flex-direction:column; gap:12px;">
    <XSender v-model="inputValue" @submit="handleSubmit">
      <template #action-list>
        <!-- Custom mic button driven by useRecord -->
        <el-button
          :type="isRecording ? 'danger' : 'primary'"
          circle
          :loading="isRecording"
          @mousedown="start"
          @mouseup="stop"
        >
          🎤
        </el-button>
      </template>
    </XSender>

    <div v-if="transcript" style="font-size:12px; color:#666;">
      Live: {{ transcript }}
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref, watch } from 'vue';
import { useRecord, XSender } from 'vue-element-plus-x';

const inputValue = ref('');

const {
  start,
  stop,
  loading: isRecording,
  value: transcript
} = useRecord({
  onEnd(result: string) {
    // Final transcript delivered here
    inputValue.value = result;
  }
});

// Also sync live transcript to the input in real-time
watch(transcript, val => {
  inputValue.value = val;
});

function handleSubmit(text: string) {
  console.log('Submitted:', text);
  inputValue.value = '';
}
</script>

```

--------------------------------

### Basic Bubble Usage

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/components/bubble/index.md

Demonstrates the fundamental usage of the Bubble component.

```vue
<template>
  <Bubble>
    <template #content>
      Hello World!
    </template>
  </Bubble>
</template>

<script setup>
import { Bubble } from 'element-plus-x'
</script>
```

--------------------------------

### Create Redirect Configuration

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/scripts/docs/README.md

Creates a redirect configuration file for Nginx to point to a specific domain. Ensure the directory exists before running.

```bash
sudo mkdir -p /var/www/element-plus-x/root
echo 'set $root_target https://v1.element-plus-x.com;' | sudo tee /var/www/element-plus-x/root/redirect.conf
```

--------------------------------

### Instance Methods

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/zh/components/bubbleList/index.md

Methods available on the component instance for programmatic control.

```APIDOC
## Ref Instance Methods

| Method / Property      | Signature                                     | Description                                                                      |
| ---------------------- | --------------------------------------------- | -------------------------------------------------------------------------------- |
| `scrollToTop`          | `(smooth?: boolean) => void`                  |
| `scrollToBottom`       | `(smooth?: boolean) => void`                  |
| `scrollToBubble`       | `(index: number, smooth?: boolean) => void`   |
| `loadMoreTopComplete`  | `() => void`                                  |
| `loadMoreBottomComplete` | `() => void`                                  |
| `currentScrollState`   | `BubbleListScrollState`                       |
| `currentUnreadCount`   | `number`                                      |
```

--------------------------------

### Basic BubbleList Usage

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/components/bubbleList/index.md

Demonstrates the basic implementation of the BubbleList component.

```vue
<template>
  <BubbleList>
    <Bubble v-for="(item, index) in list" :key="index" :content="item.content" :direction="item.direction"></Bubble>
  </BubbleList>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { Bubble, BubbleList } from '@element-plus-x/components'

const list = ref([
  { content: 'Hello', direction: 'left' },
  { content: 'Hi', direction: 'right' },
  { content: 'How are you?', direction: 'left' },
  { content: 'I am fine', direction: 'right' },
])
</script>
```

--------------------------------

### XRequest Utility Class with Customization

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/components/useSend/index.md

Demonstrates a more advanced usage of the XRequest utility class, showing how to configure it for specific request needs.

```javascript
import { XRequest } from "@/utils/XRequest";

const request = new XRequest({
  baseURL: "/api",
  headers: {
    "Content-Type": "application/json",
  },
  timeout: 5000,
});

request.post("/data", { name: "example" }).then((res) => {
  console.log(res);
});
```

--------------------------------

### On-demand Import of Components

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/README.en.md

Import specific components like BubbleList and XSender for use in your Vue application. Ensure you have the necessary setup in your script and template.

```vue
<script setup>
import { BubbleList, XSender } from 'vue-element-plus-x';

const list = [
  {
    content: 'Hello, Element Plus X',
    role: 'user'
  }
];
</script>

<template>
  <div
    style="display: flex; flex-direction: column; height: 230px; justify-content: space-between;"
  >
    <BubbleList :list="list" />
    <XSender />
  </div>
</template>

```

--------------------------------

### Basic Markdown Rendering

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/components/xMarkdown/index.md

Demonstrates the basic usage of the MarkdownRenderer component.

```vue
<template>
  <MarkdownRenderer :content="markdownContent" />
</template>

<script setup lang="ts">
import MarkdownRenderer from 'x-markdown-vue';

const markdownContent = `
# Hello, x-markdown-vue!

This is **bold** and *italic* text.
`;
</script>
```

--------------------------------

### On-demand import of components

Source: https://context7.com/element-plus-x/element-plus-x/llms.txt

Import and use components like BubbleList and XSender directly in your Vue setup. Ensure you have a parent container with appropriate styling for layout.

```vue
<script setup>
import { BubbleList, XSender } from 'vue-element-plus-x';

const list = [
  { content: 'Hello, Element Plus X', role: 'user' }
];
</script>

<template>
  <div style="display:flex; flex-direction:column; height:400px; justify-content:space-between;">
    <BubbleList :list="list" />
    <XSender />
  </div>
</template>
```

--------------------------------

### XSender Component Usage

Source: https://context7.com/element-plus-x/element-plus-x/llms.txt

Demonstrates basic and advanced usage of the XSender component, including its props, slots, and event handling.

```APIDOC
## XSender Component

`XSender` is a rich conversational input component with built-in support for text input, user `@mention` selection, slash-command triggers, tag selection popups, voice input slots, custom headers/footers, loading/disabled states, and configurable submit keys.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `placeholder` | `string` | `'请输入内容'` | Input placeholder text |
| `variant` | `'default' | 'updown'` | `'default'` | Layout variant |
| `submitType` | `'enter' | 'shiftEnter'` | `'enter'` | Key combination to submit |
| `loading` | `boolean` | `false` | Show loading/stop state |
| `disabled` | `boolean` | `false` | Disable the input |
| `clearable` | `boolean` | `false` | Show clear button |
| `maxLength` | `number` | `-1` | Character limit (`-1` = unlimited) |
| `autoFocus` | `boolean` | `false` | Auto focus on mount |
| `mentionConfig` | `MentionConfig` | `null` | `@` mention user configuration |
| `triggerConfig` | `TriggerConfig[]` | `null` | Slash-command popup configuration |
| `selectConfig` | `SelectConfig[]` | `null` | Tag/option selection configuration |
| `tipConfig` | `TipConfig | boolean` | `true` | Prefix tip bar configuration |
| `customStyle` | `CSSStyleDeclaration` | `{}` | Inline styles for the inner textarea |

### Slots

- `#header`
- `#footer`
- `#prefix`
- `#action-list`

### Ref Methods

- `setMention(id)`: Programmatically insert a mention.
- `setTrigger(key, id)`: Programmatically insert a command tag.
- `setChatNode(nodes)`: Programmatically preset the full editor content.
```

--------------------------------

### Clone Element Plus X Repository

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/guide/develop.md

Clone the Element Plus X repository and navigate into the project directory.

```bash
git clone https://github.com/element-plus-x/Element-Plus-X.git
cd Element-Plus-X
```

--------------------------------

### Customizing FilesCard Style and Interaction

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/zh/components/filesCard/index.md

Provides examples of customizing the appearance and hover effects of a FilesCard using the `style` and `hoverStyle` props. These props accept standard CSS properties.

```vue
<template>
  <FilesCard
    uid="6"
    name="custom.txt"
    :style="{ backgroundColor: '#f0f0f0', padding: '10px' }"
    :hoverStyle="{ transform: 'scale(1.05)', boxShadow: '0 4px 8px rgba(0,0,0,0.2)' }"
  />
</template>

<script setup lang="ts">
import FilesCard from "@/components/FilesCard.vue";
</script>
```

--------------------------------

### BubbleList Component Usage

Source: https://context7.com/element-plus-x/element-plus-x/llms.txt

Demonstrates the basic setup and usage of the BubbleList component, including message data, event handling, and slot customization for rendering message content and footers.

```vue
<template>
  <div style="height:500px; display:flex; flex-direction:column;">
    <BubbleList
      ref="listRef"
      :list="messages"
      :auto-scroll="true"
      :virtual="true"
      item-key="key"
      :show-back-button="true"
      :back-button-threshold="80"
      :top-status="topStatus"
      @load-more-top="loadHistory"
      @scroll-state-change="onScrollStateChange"
      @unread-count-change="onUnreadCountChange"
    >
      <!-- Render markdown inside each AI bubble -->
      <template #content="{ item }">
        <MarkdownRenderer
          v-if="item.role === 'ai'"
          :markdown="item.content"
          :enable-animate="true"
        />
        <span v-else>{{ item.content }}</span>
      </template>

      <!-- Custom footer per bubble (timestamps, actions) -->
      <template #footer="{ item }">
        <span style="font-size:11px; color:#aaa;">{{ item.time }}</span>
      </template>
    </BubbleList>
  </div>
</template>

<script setup lang="ts">
import { ref, nextTick } from 'vue';
import type { BubbleListInstance, BubbleListScrollState } from 'vue-element-plus-x/types/BubbleList';
import { BubbleList } from 'vue-element-plus-x';
import { MarkdownRenderer } from 'x-markdown-vue';
import 'x-markdown-vue/style';

interface Message {
  key: number;
  role: 'user' | 'ai';
  placement: 'start' | 'end';
  content: string;
  avatar: string;
  shape: string;
  variant: string;
  time: string;
}

const listRef = ref<BubbleListInstance | null>(null);
const messages = ref<Message[]>([
  {
    key: 1, role: 'ai', placement: 'start', content: 'Hello! How can I help?',
    avatar: 'https://cube.elemecdn.com/0/88/03b0d39583f48206768a7534e55bcpng.png',
    shape: 'corner', variant: 'filled', time: '10:00'
  },
  {
    key: 2, role: 'user', placement: 'end', content: 'Summarize the latest report.',
    avatar: 'https://avatars.githubusercontent.com/u/76239030?v=4',
    shape: 'corner', variant: 'outlined', time: '10:01'
  }
]);

const topStatus = ref<{ type: 'idle' | 'loading' | 'no-more' | 'error' }>({ type: 'idle' });

// Append a streaming AI response
function startStreamingResponse() {
  const msg: Message = {
    key: Date.now(), role: 'ai', placement: 'start', content: '',
    avatar: 'https://cube.elemecdn.com/0/88/03b0d39583f48206768a7534e55bcpng.png',
    shape: 'corner', variant: 'filled', time: new Date().toLocaleTimeString()
  };
  messages.value.push(msg);

  const chunks = ['Certainly! ', 'The report shows ', '**15% growth** ', 'in Q3.'];
  let i = 0;
  const timer = setInterval(() => {
    if (i >= chunks.length) { clearInterval(timer); return; }
    msg.content += chunks[i++];
  }, 300);
}

async function loadHistory() {
  topStatus.value = { type: 'loading' };
  // Simulate fetching older messages
  await new Promise(r => setTimeout(r, 1000));
  messages.value.unshift({
    key: 0, role: 'ai', placement: 'start', content: 'This is an older message.',
    avatar: 'https://cube.elemecdn.com/0/88/03b0d39583f48206768a7534e55bcpng.png',
    shape: 'corner', variant: 'filled', time: '09:59'
  });
  topStatus.value = { type: 'idle' };
  listRef.value?.loadMoreTopComplete();  // fixes scroll jump
}

function onScrollStateChange(state: BubbleListScrollState) {
  console.log('Scroll state:', state); // 'AT_BOTTOM' | 'SCROLLED_UP' | 'HAS_NEW_MESSAGES'
}

function onUnreadCountChange(count: number) {
  console.log('Unread:', count);
}

// Programmatic scroll control
function scrollToLatest() { listRef.value?.scrollToBottom(true); }
function scrollToTop() { listRef.value?.scrollToTop(false); }
function scrollToIndex(i: number) { listRef.value?.scrollToBubble(i); }
</script>
```

--------------------------------

### Welcome Component with Custom Subtitle

Source: https://github.com/element-plus-x/element-plus-x/blob/updata-2602/apps/docs/en/components/welcome/index.md

Shows how to add custom subtitle text using the `extra` property. This allows for more detailed or personalized messaging.

```vue
<template>
  <Welcome extra="This is a custom subtitle." />
</template>

<script setup>
import { Welcome } from '@element-plus/x'
</script>
```