### Install chatui-vue3 Package

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/QUICK_START.md

Install the chatui-vue3 package using npm.

```bash
npm install chatui-vue3
```

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

### QuickReplies Component Usage Example

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/api-reference/components.md

Example of using the QuickReplies component with dynamic items and handling click events.

```vue
<template>
  <QuickReplies
    :items="replies"
    :visible="showReplies"
    @click="handleReplyClick"
  />
</template>

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

const replies = ref([
  { name: 'Hello', icon: 'hand' },
  { name: 'Thanks', isHighlight: true },
  { name: 'New Option', isNew: true }
])

const handleReplyClick = (item, index) => {
  console.log(`Clicked: ${item.name}`)
}
</script>
```

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

### Start Options Interface

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/api-reference/composables.md

Defines the optional parameters for the start function, including delay and timeout for the typing animation.

```typescript
interface StartOptions {
  delay?: number      // Delay before starting animation in milliseconds (default: 0)
  timeout?: number    // Total duration to run animation in milliseconds (optional)
}
```

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

### Bubble Component Usage Example

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/api-reference/components.md

Demonstrates how to use the Bubble component with text content and custom HTML content.

```vue
<template>
  <Bubble content="Hello World!" />
  <Bubble>
    <p>Custom HTML content</p>
  </Bubble>
</template>
```

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

### Vue Usage Example with useTitleTyping

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/api-reference/composables.md

Demonstrates how to use the useTitleTyping composable in a Vue 3 component to display a typing indicator in the title. The start function is called with a delay and timeout, and the stop function is available for manual control.

```vue
<script setup lang="ts">
import { useTitleTyping } from 'chatui-vue3'

const { isTyping, start, stop } = useTitleTyping()

const startTyping = () => {
  start({ delay: 500, timeout: 10000 })
}

const stopTyping = () => {
  stop()
}
</script>

<template>
  <div>
    <h1>
      Chat Assistant
      <span v-if="isTyping">...</span>
    </h1>
  </div>
</template>
```

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

### Usage Example of useQuickReplies

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/api-reference/composables.md

Demonstrates how to use the useQuickReplies composable in a Vue 3 component to manage and display quick replies. Includes functions for updating replies and toggling visibility.

```vue
<script setup lang="ts">
import { useQuickReplies } from 'chatui-vue3'

const { quickReplies, prepend, replace, visible, setVisible, save, pop } = useQuickReplies([
  { name: 'Hello', icon: 'hand' },
  { name: 'Thank you', icon: 'smile' }
])

const updateReplies = () => {
  save()
  replace([
    { name: 'New Option 1', isNew: true },
    { name: 'New Option 2', isHighlight: true }
  ])
}

const toggleVisibility = () => {
  setVisible(!visible.value)
}
</script>
```

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

### Title Typing Animation Start Options

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/types.md

Specifies options for initiating title typing animations, such as an initial delay or a total duration.

```typescript
interface StartOptions {
  delay?: number
  timeout?: number
}
```

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

### Implement Message Virtualization

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/ADVANCED.md

Use `vue-virtual-scroller` for efficient rendering of large message lists. Ensure `vue-virtual-scroller` is installed and imported.

```vue
<template>
  <DynamicScroller
    :items="messages"
    :min-item-size="50"
    key-field="_id"
  >
    <template #default="{ item, index, active }">
      <div :class="{ active }">
        <Message v-bind="item" :key="item._id" />
      </div>
    </template>
  </DynamicScroller>
</template>

<script setup lang="ts">
import { DynamicScroller, DynamicScrollerItem } from 'vue-virtual-scroller'
</script>
```

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

### Implement Pagination/Lazy Loading

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/ADVANCED.md

Load older messages on demand when the user scrolls to the top of the message list. This example assumes an `api.getMessages` function and `useMessages` composable.

```typescript
const { messages, prependMsgs } = useMessages()
const isLoading = ref(false)

const loadMoreMessages = async () => {
  if (isLoading.value) return
  
  isLoading.value = true
  const oldestMessageTime = messages.value[0]?.createdAt
  
  try {
    const olderMessages = await api.getMessages({
      before: oldestMessageTime,
      limit: 50
    })
    
    prependMsgs(olderMessages)
  } finally {
    isLoading.value = false
  }
}

// Trigger on scroll to top
const handleScroll = (e: Event) => {
  const target = e.target as HTMLElement
  if (target.scrollTop === 0) {
    loadMoreMessages()
  }
}
```

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

### Avatar Component Usage

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/api-reference/components.md

Example of using the Avatar component with various props like src, alt, size, shape, and url.

```vue
<template>
  <Avatar
    src="/user-avatar.jpg"
    alt="User"
    size="md"
    shape="circle"
    url="/profile"
  />
</template>
```

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

### useTitleTyping

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/api-reference/composables.md

A composable function for managing typing animation state in application title or status text. It returns the reactive `isTyping` state and functions to `start` and `stop` the animation.

```APIDOC
## useTitleTyping

A composition function for managing typing animation state in application title or status text.

### Import

```typescript
import { useTitleTyping } from 'chatui-vue3'
```

### Function Signature

```typescript
function useTitleTyping(): {
  isTyping: Ref<boolean>
  start: (options?: StartOptions) => void
  stop: () => void
}
```

### Parameters

None

### Return Type

Object containing the following:

| Property | Type | Description |
|----------|------|-------------|
| `isTyping` | `Ref<boolean>` | Reactive state: true while typing animation is active |
| `start` | `(options?: StartOptions) => void` | Start the typing animation with optional configuration |
| `stop` | `() => void` | Stop the animation and reset state |

### Start Options

```typescript
interface StartOptions {
  delay?: number      // Delay before starting animation in milliseconds (default: 0)
  timeout?: number    // Total duration to run animation in milliseconds (optional)
}
```

### Animation Timing

The `start()` function initiates a cyclical animation pattern:

1. After initial `delay`, `isTyping` becomes true
2. Typing continues for 2500-3500ms (random)
3. Typing pauses (isTyping = false)
4. After 1000-1800ms pause, animation repeats (unless stopped)
5. If `timeout` is set, animation stops after that duration

### Usage Example

```vue
<script setup lang="ts">
import { useTitleTyping } from 'chatui-vue3'

const { isTyping, start, stop } = useTitleTyping()

const startTyping = () => {
  start({ delay: 500, timeout: 10000 })
}

const stopTyping = () => {
  stop()
}
</script>

<template>
  <div>
    <h1>
      Chat Assistant
      <span v-if="isTyping">...</span>
    </h1>
  </div>
</template>
```

### Behavior Notes

- The animation is self-looping: after each cycle, it automatically restarts unless stopped
- Random delays between cycles create a more natural typing effect
- `stop()` clears all pending timeouts
- Multiple `start()` calls will clear previous timers before starting new ones

```

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

### Create Custom Typing Indicator Animation

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/ADVANCED.md

Replace the default typing indicator with a custom animation using CSS keyframes and spans. This example uses a bouncing effect for the dots.

```vue
<template>
  <Chat :isTyping="isTyping">
    <template v-if="isTyping" #messageContent>
      <div class="custom-typing">
        <span></span>
        <span></span>
        <span></span>
      </div>
    </template>
  </Chat>
</template>

<style scoped>
.custom-typing {
  display: flex;
  gap: 4px;
  padding: 10px 16px;
}

.custom-typing span {
  width: 8px;
  height: 8px;
  border-radius: 50%;
  background: #999;
  animation: bounce 1.4s infinite;
}

.custom-typing span:nth-child(2) {
  animation-delay: 0.2s;
}

.custom-typing span:nth-child(3) {
  animation-delay: 0.4s;
}

@keyframes bounce {
  0%, 60%, 100% {
    transform: translateY(0);
  }
  30% {
    transform: translateY(-10px);
  }
}
</style>
```

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

### useTitleTyping Composable

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/MODULES.md

Manages the typing animation for a title element. Provides functions to start and stop the typing effect, along with a ref for the typing status. Useful for dynamic title updates.

```typescript
{
  isTyping: Ref<boolean>,
  start: (options?: StartOptions) => void,
  stop: () => void
}
```

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

### Get iOS Major Version with getIOSMajorVersion

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/utilities.md

Extracts the major iOS version number from the user agent string. Returns 0 if not on iOS or version cannot be determined. Useful for applying version-specific styles.

```typescript
import { getIOSMajorVersion } from 'chatui-vue3'

const iosVersion = getIOSMajorVersion()

if (iosVersion < 11) {
  // Apply styles for iOS < 11 (no flex buttons)
  document.documentElement.classList.add('no-btn-flex')
}

if (iosVersion < 13) {
  // Apply styles for iOS < 13 (no smooth scrolling)
  document.documentElement.classList.add('no-scrolling')
}
```

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

### Reflow Element Utility

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/MODULES.md

Triggers a reflow of the specified HTML element, returning the computed width. This is often used to force a browser repaint or to get accurate dimensions after DOM changes.

```typescript
reflow(el: HTMLElement): number
```

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

### Import useQuickReplies and QuickReplyItemProps

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/api-reference/composables.md

Import the necessary composable and type from the chatui-vue3 library.

```typescript
import { useQuickReplies, type QuickReplyItemProps } from 'chatui-vue3'
```

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

### Create a Simple Chat Interface

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/QUICK_START.md

Set up a basic chat interface using the Chat component, handling user messages and simulating bot responses.

```vue
<template>
  <Chat
    :messages="messages"
    :isTyping="isTyping"
    @send="handleSend"
  >
    <template #messageContent="{ message }">
      <Bubble v-if="message.type === 'text'" :content="message.content.text" />
    </template>
  </Chat>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { Chat, Bubble, useMessages } from 'chatui-vue3'
import 'chatui-vue3/dist/index.css'

const { messages, appendMsg } = useMessages([])
const isTyping = ref(false)

const handleSend = (type: string, text: string) => {
  // Add user message
  appendMsg({
    type: 'text',
    content: { text },
    position: 'right'
  })
  
  // Simulate bot response
  isTyping.value = true
  setTimeout(() => {
    appendMsg({
      type: 'text',
      content: { text: `You said: ${text}` },
      position: 'left'
    })
    isTyping.value = false
  }, 1000)
}
</script>
```

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

### Import QuickReplies Component

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/api-reference/components.md

Import the QuickReplies component from the chatui-vue3 library.

```typescript
import { QuickReplies } from 'chatui-vue3'
```

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

### Title Typing Types - StartOptions

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/types.md

Options for initiating the title typing animation, including initial delay and total animation duration.

```APIDOC
## Title Typing Types - StartOptions

### Description
Options for starting title typing animation.

### Fields
- **delay** (number) - Optional - Initial delay in milliseconds before animation starts. Default: `0`
- **timeout** (number) - Optional - Total duration to run animation (optional).

### Used by
`useTitleTyping().start()` method
```

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

### useQuickReplies

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/api-reference/composables.md

A composition function for managing quick reply options in a chat interface. It allows for reactive management of quick replies, including adding, replacing, and controlling visibility, along with state saving and restoration.

```APIDOC
## useQuickReplies

### Description
A composition function for managing quick reply options in a chat interface.

### Import

```typescript
import { useQuickReplies, type QuickReplyItemProps } from 'chatui-vue3'
```

### Function Signature

```typescript
function useQuickReplies(initialState: QuickReplies = []): {
  quickReplies: Ref<QuickReplyItemProps[]>
  prepend: (list: QuickReplies) => void
  replace: (newReplies: QuickReplies) => void
  visible: Ref<boolean>
  setVisible: (isVisible: boolean) => void
  save: () => void
  pop: () => void
}
```

### Parameters

#### initialState
- **Type**: `QuickReplyItemProps[]`
- **Required**: No
- **Default**: `[]`
- **Description**: Initial quick reply options

### Return Type

Object containing the following:

#### quickReplies
- **Type**: `Ref<QuickReplyItemProps[]>`
- **Description**: Reactive reference to quick replies array

#### prepend
- **Type**: `(list: QuickReplies) => void`
- **Description**: Add new quick replies to the beginning

#### replace
- **Type**: `(newReplies: QuickReplies) => void`
- **Description**: Replace all quick replies with new ones

#### visible
- **Type**: `Ref<boolean>`
- **Description**: Reactive visibility state

#### setVisible
- **Type**: `(isVisible: boolean) => void`
- **Description**: Toggle quick replies visibility

#### save
- **Type**: `() => void`
- **Description**: Save the current quick replies state for later restoration

#### pop
- **Type**: `() => void`
- **Description**: Restore the last saved state

### Quick Reply Item Properties

```typescript
interface QuickReplyItemProps {
  name: string                  // Display text of the quick reply
  icon?: string                 // FontAwesome icon class name
  isNew?: boolean               // Shows a new badge if true
  isHighlight?: boolean         // Highlights the item if true
  [key: string]: any            // Additional custom properties
}
```

### Usage Example

```vue
<script setup lang="ts">
import { useQuickReplies } from 'chatui-vue3'

const { quickReplies, prepend, replace, visible, setVisible, save, pop } = useQuickReplies([
  { name: 'Hello', icon: 'hand' },
  { name: 'Thank you', icon: 'smile' }
])

const updateReplies = () => {
  save()
  replace([
    { name: 'New Option 1', isNew: true },
    { name: 'New Option 2', isHighlight: true }
  ])
}

const toggleVisibility = () => {
  setVisible(!visible.value)
}
</script>
```
```

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

### Import useTitleTyping

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/api-reference/composables.md

Import the useTitleTyping composable from the chatui-vue3 library.

```typescript
import { useTitleTyping } from 'chatui-vue3'
```

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

### useQuickReplies Composable

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/MODULES.md

Manages quick reply options for a chat interface. Provides functions to prepend, replace, set visibility, save, and pop quick replies. Use this when you need to offer users predefined response options.

```typescript
{
  quickReplies: Ref<QuickReplyItemProps[]>,
  prepend: (list: QuickReplies) => void,
  replace: (newReplies: QuickReplies) => void,
  visible: Ref<boolean>,
  setVisible: (isVisible: boolean) => void,
  save: () => void,
  pop: () => void
}
```

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

### Import Chat UI Styles

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/QUICK_START.md

Import the necessary CSS styles for the chat UI.

```typescript
import 'chatui-vue3/dist/index.css'
```

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

### Define QuickReplyItemProps Interface

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/api-reference/composables.md

Defines the structure for individual quick reply items, including display text, optional icon, and flags for new or highlighted items.

```typescript
interface QuickReplyItemProps {
  name: string                  // Display text of the quick reply
  icon?: string                 // FontAwesome icon class name
  isNew?: boolean               // Shows a new badge if true
  isHighlight?: boolean         // Highlights the item if true
  [key: string]: any            // Additional custom properties
}
```

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

### Importing Re-exported Modules

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/MODULES.md

Demonstrates how to import re-exported modules from the 'chatui-vue3' package in a typical Vue application.

```typescript
import { Chat, useMessages, getRandomString } from 'chatui-vue3'
```

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

### Import Bubble Component

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/api-reference/components.md

Import the Bubble component from the chatui-vue3 library.

```typescript
import { Bubble } from 'chatui-vue3'
```

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

### Manage Quick Replies

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/QUICK_START.md

Control quick reply options and their visibility using the `useQuickReplies` composable. Use the `replace` method to update replies and `setVisible` to toggle their display.

```typescript
const { quickReplies, replace, visible, setVisible } = useQuickReplies([
  { name: 'Hello', icon: 'hand' },
  { name: 'Thank you', icon: 'thumbs-up' },
  { name: 'Goodbye', icon: 'wave' }
])

// Update replies
replace([
  { name: 'Option 1', isNew: true },
  { name: 'Option 2', isHighlight: true }
])

// Toggle visibility
setVisible(false)
```

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

### Import Time Component

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/api-reference/components.md

Import the Time component from the chatui-vue3 library.

```typescript
import { Time } from 'chatui-vue3'
```

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

### Implement Keyboard Navigation

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/ADVANCED.md

Enable keyboard navigation for scrolling through messages. Use Ctrl/Meta with Arrow keys to move up or down.

```typescript
const handleKeyDown = (e: KeyboardEvent) => {
  if (e.ctrlKey || e.metaKey) {
    switch (e.key) {
      case 'ArrowUp':
        e.preventDefault()
        scrollToMessage(-1)
        break
      case 'ArrowDown':
        e.preventDefault()
        scrollToMessage(1)
        break
    }
  }
}
```

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

### QuickReplies Component

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/api-reference/components.md

A horizontal scrollable container for quick reply buttons. It accepts an array of items and emits events on click and scroll.

```APIDOC
## QuickReplies Component

### Description
Horizontal scrollable container for quick reply buttons.

### Import
```typescript
import { QuickReplies } from 'chatui-vue3'
```

### Component Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `items` | `QuickReplyItemProps[]` | `[]` | Array of quick reply items |
| `visible` | `boolean` | `true` | Controls component visibility |

### Events

| Event | Payload | Description |
|-------|---------|-------------|
| `click` | `(item: QuickReplyItemProps, index: number)` | Fired when a quick reply is clicked |
| `scroll` | `(e: Event)` | Fired when horizontal scroll occurs |

### Usage Example

```vue
<template>
  <QuickReplies
    :items="replies"
    :visible="showReplies"
    @click="handleReplyClick"
  />
</template>

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

const replies = ref([
  { name: 'Hello', icon: 'hand' },
  { name: 'Thanks', isHighlight: true },
  { name: 'New Option', isNew: true }
])

const handleReplyClick = (item, index) => {
  console.log(`Clicked: ${item.name}`)
}
</script>
```

### Behavior

- Resets scroll position when items change
- Disables scroll events for 500ms after items update to prevent race conditions
- Hidden items collapse with height: 0 when `visible` is false
```

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

### Time Component Usage with Custom Locale

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/api-reference/components.md

Demonstrates using the Time component with a default date and a custom locale configuration for formatting.

```vue
<template>
  <Time :date="messageTime" />
  <Time :date="messageTime" :locale="customLocale" />
</template>

<script setup lang="ts">
const messageTime = Date.now()

const customLocale = {
  weekdays: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
  formats: {
    LT: 'HH:mm',
    YT: 'Yesterday HH:mm',
    WT: 'dddd HH:mm',
    lll: 'M/D/YYYY HH:mm'
  }
}
</script>
```

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

### Import Avatar Component

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/api-reference/components.md

Import the Avatar component from the chatui-vue3 library.

```typescript
import { Avatar } from 'chatui-vue3'
```

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

### useTypewriter

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/MODULES.md

Simulates a typewriter effect for displaying text content.

```APIDOC
## useTypewriter

### Description
Simulates a typewriter effect for displaying text content.

### Function Signature
`useTypewriter(content: string, options?: Options): Object`

### Returned Object
- `typedContent`: ComputedRef<string> - A computed reference to the text content with the typewriter effect applied.
- `isTyping`: ComputedRef<boolean> - A computed reference indicating if the typing effect is currently active.
- `cleanup`: () => void - Cleans up any ongoing typing processes.
```

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

### Integrate Quick Replies with Chat Component

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/QUICK_START.md

Bind the `quickReplies` and `quickRepliesVisible` props to the Chat component and handle `quickReplyClick` events.

```vue
<Chat
  :quickReplies="quickReplies"
  :quickRepliesVisible="visible"
  @quickReplyClick="(item) => handleSend('text', item.name)"
/>
```

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

### Typewriter Animation Options

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/types.md

Defines configuration options for typewriter animations, including interval, character step, and initial display index.

```typescript
interface Options {
  interval?: number
  step?: number | number[]
  initialIndex?: number
}
```

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

### User Agent Detection Utilities

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/MODULES.md

Provides boolean constants and a function for detecting browser and OS characteristics. Useful for implementing platform-specific features or applying conditional styling.

```typescript
isIOS: boolean
```

```typescript
isSafari: boolean
```

```typescript
isSafariOrIOS11: boolean
```

```typescript
isArkWeb: boolean
```

```typescript
getIOSMajorVersion(): number
```

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

### isArkWeb

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/utilities.md

Detects if the browser is ArkWeb (Huawei's web engine).

```APIDOC
## isArkWeb

### Description
Detects if the browser is ArkWeb (Huawei's web engine).

### Type
`const isArkWeb: boolean`

### Description
Checks the user agent string for ArkWeb identifier.

### Usage Example
```typescript
import { isArkWeb } from 'chatui-vue3'

if (isArkWeb) {
  // Apply ArkWeb-specific styling or polyfills
}
```
```

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

### ua utilities

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/MODULES.md

Provides utility constants and functions for user agent detection.

```APIDOC
## UA Utilities

### Description
Provides utility constants and functions for user agent detection.

### Exports
- `isIOS`: boolean - True if the user agent is iOS.
- `isSafari`: boolean - True if the user agent is Safari.
- `isSafariOrIOS11`: boolean - True if the user agent is Safari or iOS 11.
- `isArkWeb`: boolean - True if the user agent is ArkWeb.
- `getIOSMajorVersion`: () => number - Returns the major version of iOS.
```

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

### Define Custom Message Types

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/QUICK_START.md

Illustrates the structure for different message types, including 'text', 'system', and custom types like 'card'.

```typescript
// Text message
{ type: 'text', content: { text: '...' }, position: 'left' }

// System message
{ type: 'system', content: { text: 'User joined' } }

// Custom type
{ type: 'card', content: { title: 'My Card', data: {...} } }
```

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

### useTitleTyping

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/MODULES.md

Manages a typing indicator for the page title.

```APIDOC
## useTitleTyping

### Description
Manages a typing indicator for the page title.

### Function Signature
`useTitleTyping(): Object`

### Returned Object
- `isTyping`: Ref<boolean> - A reactive reference indicating if the title typing effect is active.
- `start`: (options?: StartOptions) => void - Starts the title typing effect.
- `stop`: () => void - Stops the title typing effect.
```

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

### Typewriter Types - Options

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/types.md

Configuration options for the typewriter animation, controlling its speed, character addition rate, and initial display.

```APIDOC
## Typewriter Types - Options

### Description
Configuration options for typewriter animation.

### Fields
- **interval** (number) - Optional - Delay in milliseconds between character additions. Default: `80`
- **step** (number | number[]) - Optional - Characters to add per interval, or [min, max] for random range. Default: `1`
- **initialIndex** (number) - Optional - Starting position in the string (how many chars show initially). Default: `5`

### Used by
`useTypewriter()` function
```

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

### isSafariOrIOS11

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/utilities.md

Detects Safari browser or iOS 11.x specifically.

```APIDOC
## isSafariOrIOS11

### Description
Detects Safari browser or iOS 11.x specifically.

### Type
`const isSafariOrIOS11: boolean`

### Description
Checks for Safari or specifically iOS 11 versions (11.0 - 11.3).

### Usage Example
```typescript
import { isSafariOrIOS11 } from 'chatui-vue3'

if (isSafariOrIOS11) {
  // Apply workarounds for known Safari/iOS 11 issues
}
```
```

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

### Detect ArkWeb with isArkWeb

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/utilities.md

Detects if the browser is ArkWeb (Huawei's web engine). Use for applying ArkWeb-specific styling or polyfills.

```typescript
import { isArkWeb } from 'chatui-vue3'

if (isArkWeb) {
  // Apply ArkWeb-specific styling or polyfills
}
```

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

### getRandomString

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/MODULES.md

Generates a random string.

```APIDOC
## getRandomString

### Description
Generates a random string.

### Function Signature
`getRandomString(): string`
```

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

### Add Message Entrance Animation

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/ADVANCED.md

Apply entrance and exit animations to messages using Vue's `<TransitionGroup>` component. Define CSS transitions for `message-enter-active` and `message-leave-active`.

```vue
<template>
  <TransitionGroup name="message" tag="div">
    <Message 
      v-for="msg in messages"
      :key="msg._id"
      v-bind="msg"
    />
  </TransitionGroup>
</template>

<style scoped>
.message-enter-active {
  animation: slideIn 0.3s ease-out;
}

.message-leave-active {
  animation: slideOut 0.3s ease-out;
}

@keyframes slideIn {
  from {
    opacity: 0;
    transform: translateY(10px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

@keyframes slideOut {
  from {
    opacity: 1;
    transform: translateY(0);
  }
  to {
    opacity: 0;
    transform: translateY(-10px);
  }
}
</style>
```

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

### Manage Chat Messages with useMessages

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/QUICK_START.md

Utilize the `useMessages` composable to manage message state, including appending, updating, and deleting messages.

```typescript
const { messages, appendMsg, updateMsg, deleteMsg } = useMessages([])

// Add a message
const msgId = appendMsg({
  type: 'text',
  content: { text: 'Hello!' },
  position: 'right'
})

// Update a message
updateMsg(msgId, {
  type: 'text',
  content: { text: 'Updated message' },
  position: 'right'
})

// Delete a message
deleteMsg(msgId)
```

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

### getRandomInt

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/MODULES.md

Generates a random integer within a specified range.

```APIDOC
## getRandomInt

### Description
Generates a random integer within a specified range.

### Function Signature
`getRandomInt(min: number, max: number): number`

### Note
This function is available as a default export and a named export.
```

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

### Button Types - ButtonSize

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/types.md

Determines the size of buttons, ranging from small to large, with an option for auto sizing.

```APIDOC
## Button Types - ButtonSize

### Description
Implicit union type from Button props.

### Values
- **'sm'**: Small (28px height)
- **'md'**: Medium (32px height, default)
- **'lg'**: Large (40px height)
- **''**: Auto size based on context

### Used by
`Button` component `size` prop
```

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

### useMessages

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/MODULES.md

Manages the list of messages in a chat interface. It provides functions to prepend, append, update, delete, and reset messages.

```APIDOC
## useMessages

### Description
Manages the list of messages in a chat interface. It provides functions to prepend, append, update, delete, and reset messages.

### Function Signature
`useMessages(initialState?: MessageWithoutId[]): Object`

### Returned Object
- `messages`: Ref<MessageProps[]> - A reactive reference to the list of messages.
- `prependMsgs`: (msgs: MessageProps[]) => void - Prepends an array of messages to the list.
- `appendMsg`: (msg: MessageWithoutId) => MessageId - Appends a single message to the list and returns its ID.
- `updateMsg`: (id: MessageId, msg: MessageWithoutId) => void - Updates an existing message by its ID.
- `deleteMsg`: (id: MessageId) => void - Deletes a message by its ID.
- `resetList`: (list?: MessageProps[]) => void - Resets the message list, optionally with a new list.
```

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

### useTypewriter Composable

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/MODULES.md

Simulates a typing effect for displaying text content. Returns computed properties for the typed content and typing status, along with a cleanup function. Ideal for creating dynamic text animations.

```typescript
{
  typedContent: ComputedRef<string>,
  isTyping: ComputedRef<boolean>,
  cleanup: () => void
}
```

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

### isIOS

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/utilities.md

Detects if the current browser is running on iOS (iPhone, iPad, or iPod).

```APIDOC
## isIOS

### Description
Detects if the current browser is running on iOS (iPhone, iPad, or iPod).

### Type
`const isIOS: boolean`

### Description
Checks the user agent string for iPad, iPhone, or iPod identifiers.

### Usage Example
```typescript
import { isIOS } from 'chatui-vue3'

if (isIOS) {
  // Apply iOS-specific styling or behavior
  document.documentElement.classList.add('ios-device')
}
```
```

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

### getIOSMajorVersion

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/utilities.md

Extracts the major iOS version number from the user agent string.

```APIDOC
## getIOSMajorVersion

### Description
Extracts the major iOS version number from the user agent string.

### Method
`function getIOSMajorVersion(): number`

### Parameters
None

### Return Type
`number` - Major version number (0 if not iOS or version cannot be determined)

### Description
Parses the user agent string to extract the iOS major version. Returns 0 if not on iOS.

### Usage Example
```typescript
import { getIOSMajorVersion } from 'chatui-vue3'

const iosVersion = getIOSMajorVersion()

if (iosVersion < 11) {
  // Apply styles for iOS < 11 (no flex buttons)
  document.documentElement.classList.add('no-btn-flex')
}

if (iosVersion < 13) {
  // Apply styles for iOS < 13 (no smooth scrolling)
  document.documentElement.classList.add('no-scrolling')
}
```
```

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

### Detect iOS with isIOS

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/utilities.md

Detects if the current browser is running on iOS. Apply iOS-specific styling or behavior when true.

```typescript
import { isIOS } from 'chatui-vue3'

if (isIOS) {
  // Apply iOS-specific styling or behavior
  document.documentElement.classList.add('ios-device')
}
```

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

### Re-exporting Components and Composables

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/MODULES.md

Re-exports components and composables at the package root for easy import into Vue SFCs. This is the standard way to make library features available to users.

```typescript
export { Chat } from './components/Chat/index.vue'
export { useMessages } from './composables/useMessages'
export * from './utils'
```

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

### Input Types - InputType

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/types.md

Defines the type of input accepted by the composer component, either text or voice.

```APIDOC
## Input Types - InputType

### Description
Type of input in the composer component.

### Values
- **'text'**: Text input mode
- **'voice'**: Voice input mode

### Used by
`Composer` component `inputType` prop
```

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

### Time Component

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/api-reference/components.md

The Time component formats and displays timestamps with support for localization.

```APIDOC
## Time Component

### Description
Component for displaying formatted timestamps with localization support.

### Import
```typescript
import { Time } from 'chatui-vue3'
```

### Component Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `date` | `number | string | Date` | — | Date to format (required) |
| `locale` | `TimeLocale` | `defaultLocale` | Locale configuration object |

### Locale Configuration

```typescript
interface TimeLocale {
  weekdays: string[]          // Weekday names
  formats: {
    LT: string               // Today format (e.g., "HH:mm")
    YT: string               // Yesterday format (e.g., "昨天 HH:mm")
    WT: string               // This week format (e.g., "dddd HH:mm")
    lll: string               // Older format (e.g., "YYYY年M月D日 HH:mm")
  }
}
```

### Format Tokens

| Token | Meaning | Example |
|-------|---------|---------|
| `YYYY` | 4-digit year | 2026 |
| `M` | Month without zero-padding | 6 |
| `D` | Day without zero-padding | 25 |
| `dddd` | Weekday name | 周三 |
| `HH` | Hour with zero-padding | 14 |
| `mm` | Minute with zero-padding | 30 |

### Default Locale

Chinese locale with time-based format selection:
- Today: "HH:mm"
- Yesterday: "昨天 HH:mm"
- This week: "dddd HH:mm"
- Older: "YYYY年M月D日 HH:mm"

### Usage Example

```vue
<template>
  <Time :date="messageTime" />
  <Time :date="messageTime" :locale="customLocale" />
</template>

<script setup lang="ts">
const messageTime = Date.now()

const customLocale = {
  weekdays: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
  formats: {
    LT: 'HH:mm',
    YT: 'Yesterday HH:mm',
    WT: 'dddd HH:mm',
    lll: 'M/D/YYYY HH:mm'
  }
}
</script>
```
```

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

### Detect Safari or iOS 11 with isSafariOrIOS11

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/utilities.md

Detects if the browser is Safari or specifically iOS 11.x. Use for applying workarounds for known issues.

```typescript
import { isSafariOrIOS11 } from 'chatui-vue3'

if (isSafariOrIOS11) {
  // Apply workarounds for known Safari/iOS 11 issues
}
```

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

### Generate Random Integer Utility

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/MODULES.md

Generates a random integer within a specified range (inclusive). Use this utility for random number generation in your application logic.

```typescript
default: getRandomInt(min: number, max: number): number
```

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

### Button Size Type

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/types.md

Defines the size options for buttons, ranging from small to large, or auto-sized.

```typescript
type ButtonSize = 'sm' | 'md' | 'lg' | ''
```

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

### Button Types - ButtonColor

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/types.md

Specifies the color variant for buttons, including primary brand color or default gray.

```APIDOC
## Button Types - ButtonColor

### Description
Implicit union type from Button props.

### Values
- **'primary'**: Primary brand color button
- **''**: Default gray button

### Used by
`Button` component `color` prop
```

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

### isSafari

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/utilities.md

Detects if the current browser is Safari (excluding Chrome on Android).

```APIDOC
## isSafari

### Description
Detects if the current browser is Safari (excluding Chrome on Android).

### Type
`const isSafari: boolean`

### Description
Checks the user agent string for Safari browser, excluding Chrome and other browsers that report Safari-like strings.

### Usage Example
```typescript
import { isSafari } from 'chatui-vue3'

if (isSafari) {
  // Apply Safari-specific workarounds
  rootElement.dataset.safari = ''
}
```
```

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

### Generate Random String Utility

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/MODULES.md

Generates a random string of characters. This utility function is useful for creating unique identifiers or temporary keys.

```typescript
getRandomString(): string
```

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

### Type-Only Exports for Strict Environments

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/MODULES.md

Exports types that should be imported using the 'type' keyword in strict TypeScript environments. This ensures type safety without importing runtime code.

```typescript
import type {
  MessageProps,
  MessageId,
  QuickReplyItemProps,
  TimeLocale,
  IDate,
  Options,
  AvatarSize,
  AvatarShape,
  InputType,
  ScrollToEndOptions
} from 'chatui-vue3'
```

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

### useMessages Composable

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/MODULES.md

Manages a list of messages, providing functions to prepend, append, update, delete, and reset the message list. Use this composable to handle dynamic message interactions in a chat interface.

```typescript
{
  messages: Ref<MessageProps[]>,
  prependMsgs: (msgs: MessageProps[]) => void,
  appendMsg: (msg: MessageWithoutId) => MessageId,
  updateMsg: (id: MessageId, msg: MessageWithoutId) => void,
  deleteMsg: (id: MessageId) => void,
  resetList: (list?: MessageProps[]) => void
}
```

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

### Bubble Component

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/api-reference/components.md

A simple message bubble component for displaying text content. It supports custom HTML content via slots and has styling for code blocks and dark mode.

```APIDOC
## Bubble Component

### Description
Simple message bubble component for displaying text content.

### Import
```typescript
import { Bubble } from 'chatui-vue3'
```

### Component Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `type` | `string` | `'text'` | Bubble type for styling |
| `content` | `string` | `''` | Text content to display |

### Slots

| Slot | Scope | Description |
|------|-------|-------------|
| `default` | — | Custom content (overrides `content` prop) |

### Usage Example

```vue
<template>
  <Bubble content="Hello World!" />
  <Bubble>
    <p>Custom HTML content</p>
  </Bubble>
</template>
```

### Styling

- Supports `<code>` and `<pre>` blocks with proper syntax highlighting styles
- Right-aligned messages (`.Message.right .Bubble`) use brand color gradient
- Automatically adapts to dark mode with CSS variables
```

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

### Avatar Component

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/api-reference/components.md

The Avatar component displays user images or fallback content, supporting various sizes and shapes.

```APIDOC
## Avatar Component

### Description
User avatar component supporting images, shapes, and sizes.

### Import
```typescript
import { Avatar } from 'chatui-vue3'
```

### Component Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `src` | `string` | `''` | Image URL |
| `alt` | `string` | `''` | Image alt text |
| `url` | `string` | `''` | Link URL (renders as `<a>` if provided) |
| `size` | `'sm' | 'md' | 'lg'` | `'md'` | Avatar size |
| `shape` | `'circle' | 'square'` | `'circle'` | Avatar shape |
| `className` | `string` | `''` | Additional CSS class |

### Size Dimensions

- `'sm'`: 24x24px
- `'md'`: 32x32px
- `'lg'`: 40x40px

### Slots

| Slot | Scope | Description |
|------|-------|-------------|
| `default` | — | Fallback content if no image |

### Usage Example

```vue
<template>
  <Avatar
    src="/user-avatar.jpg"
    alt="User"
    size="md"
    shape="circle"
    url="/profile"
  />
</template>
```
```

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

### Button Types - ButtonVariant

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/types.md

Defines the visual style of buttons, such as text-only, outlined, or solid filled.

```APIDOC
## Button Types - ButtonVariant

### Description
Implicit union type from Button props.

### Values
- **'text'**: Text-only button (no background)
- **'outline'**: Outlined button (border only)
- **''**: Solid filled button (default)

### Used by
`Button` component `variant` prop
```

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

### reflow

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/MODULES.md

Forces a reflow of the DOM for a given element.

```APIDOC
## reflow

### Description
Forces a reflow of the DOM for a given element.

### Function Signature
`reflow(el: HTMLElement): number`

### Return Value
- Returns a number representing the forced reflow value.
```

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

### Add ARIA Labels for Accessibility

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/ADVANCED.md

Enhance accessibility by adding ARIA labels to chat components for semantic meaning. This helps screen readers and assistive technologies.

```vue
<Chat
  role="main"
  aria-label="Chat conversation"
  :messages="messages"
>
  <template #messageContent="{ message }">
    <Bubble
      :content="message.content.text"
      :aria-label="`Message from ${message.position}: ${message.content.text}`"
    />
  </template>
</Chat>
```

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

### Debounce Input Changes

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/ADVANCED.md

Utilize `@vueuse/core`'s `useDebounceFn` to limit the rate at which input change events are emitted, preventing excessive updates during typing.

```typescript
import { useDebounceFn } from '@vueuse/core'

const handleInputChange = useDebounceFn((value: string) => {
  emit('inputChange', value)
}, 300)
```

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

### Detect Safari with isSafari

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/utilities.md

Detects if the current browser is Safari, excluding Chrome on Android. Use for applying Safari-specific workarounds.

```typescript
import { isSafari } from 'chatui-vue3'

if (isSafari) {
  // Apply Safari-specific workarounds
  rootElement.dataset.safari = ''
}
```

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

### Composer Input Type

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/types.md

Defines the type of input accepted by the composer component, either text or voice.

```typescript
type InputType = 'voice' | 'text'
```

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

### reflow

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/utilities.md

Forces DOM reflow by reading element's offsetHeight. This is useful for ensuring styles are applied before animations or transitions.

```APIDOC
## reflow

### Description
Forces DOM reflow by reading element's offsetHeight.

### Method
`reflow(el: HTMLElement): number`

### Parameters
#### Path Parameters
- **el** (`HTMLElement`) - Required - DOM element to reflow

### Return Type
`number` - The element's offsetHeight (in pixels)

### Description
Reads the `offsetHeight` property of an HTML element, which forces the browser to synchronously calculate and update layout. Useful for ensuring styles are applied before animations or transitions.

### Usage Example
```typescript
import { reflow } from 'chatui-vue3'

// Force reflow before applying animation
const element = document.querySelector('.message')
reflow(element)
element.classList.add('animate-in')
```
```

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

### Message Structure Definition

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/QUICK_START.md

Defines the structure of a message object, including type, content, position, user information, and creation timestamp.

```typescript
interface Message {
  type: string              // 'text', 'system', custom types
  content: any              // Type-specific content
  position?: 'left' | 'right' | 'center'
  user?: {
    avatar?: string
    name?: string
    url?: string
  }
  createdAt?: number        // Unix timestamp (auto-set if omitted)
}
```

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

### Button Color Type

Source: https://github.com/kevinjiang2022/chatui_vue3/blob/main/_autodocs/types.md

Defines the possible color variants for buttons, including primary and default.

```typescript
type ButtonColor = 'primary' | ''
```