Veltra Ui

# veltra-ui

veltra-ui 是一套 Vue 3 UI 体系。

开发 Vue 3 功能时，**优先**使用 `veltra-ui` 已提供的组件、样式、工具函数、组合式方法、指令、图标与构建集成。只有检索文档和源码后确认没有合适能力时，才新增实现或引入外部方案。

## 使用方式

- 先按需求检索下方包文档入口，不要把完整 API 预加载到上下文。
- 组件相关先看 `packages/desktop/`，再按组件名检索具体 API、示例和类型。
- 样式、主题与 Design Tokens 看 `packages/styles/`；工具、组合式方法、指令、图标、Vite 集成分别看对应入口。

## 文档结构

```
packages/
  desktop/          ← 桌面组件
  styles/           ← 样式、主题、Design Tokens
  compositions.md   ← 组合式方法
  directives.md     ← 指令
  icons.md          ← 图标
  utils.md          ← 工具函数 / 共享类型
  vite.md           ← Vite 工具
```


# UAction / UActionGroup - 操作按钮

## 类型文件

见 `./types.d.ts`

## 示例

见 `./examples.md`


# UAction 示例

## 基础操作组

```vue
<u-action-group :max="4">
  <u-action @run="handleView">查看</u-action>
  <u-action @run="handleEdit">编辑</u-action>
  <u-action need-confirm type="danger" @run="handleDelete">删除</u-action>
</u-action-group>
```

## 统一默认样式 + 单独覆盖

```vue
<u-action-group type="info" size="default" :text="false">
  <u-action @run="handleCopy">复制</u-action>
  <u-action @run="handlePaste">粘贴</u-action>
  <!-- 覆盖组默认值 -->
  <u-action type="danger" @run="handleRemove">移除</u-action>
</u-action-group>
```

## 在表格操作列中使用

```vue
<u-table :columns="columns" :data="data" row-key="id">
  <template #column:action="{ row }">
    <u-action-group :max="3">
      <u-action @run="handleEdit(row)">编辑</u-action>
      <u-action @run="handleDetail(row)">详情</u-action>
      <u-action need-confirm type="danger" @run="handleDelete(row)">删除</u-action>
      <u-action @run="handleCopy(row)">复制</u-action>
    </u-action-group>
  </template>
</u-table>

<script setup>
import { defineTableColumns } from '@veltra/desktop'

const columns = defineTableColumns([
  { key: 'name', name: '名称' },
  { key: 'action', name: '操作', width: 200, align: 'center' }
])
</script>
```

## 始终在下拉菜单 + 圆形图标（`@veltra/icons`）

```vue
<u-action-group circle>
  <u-action type="primary" :icon="Edit" @run="handleEdit">
    {{ '' }}
  </u-action>
  <!-- in-dropdown 强制收纳到下拉，方便在紧凑场景隐藏次常用操作 -->
  <u-action type="danger" :icon="Delete" in-dropdown @run="handleDelete">
    {{ '' }}
  </u-action>
</u-action-group>
```

## 手动关闭下拉菜单

```vue
<script setup lang="ts">
import { useTemplateRef } from 'vue'
import type { ActionGroupExposed } from '@veltra/desktop'

const groupRef = useTemplateRef<ActionGroupExposed>('group')

const handleRun = () => {
  // ... 执行操作后关闭下拉
  groupRef.value?.closeTip()
}
</script>

<template>
  <u-action-group ref="group" :max="2">
    <u-action @run="handleRun">操作一</u-action>
    <u-action @run="handleRun">操作二</u-action>
    <u-action @run="handleRun">操作三</u-action>
  </u-action-group>
</template>
```


# UAutoComplete 示例

## 基础用法

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

const query = ref('')
const fruits = ['Apple', 'Banana', 'Cherry', 'Durian', 'Grape', 'Mango', 'Orange', 'Peach']
</script>

<template>
  <u-auto-complete v-model="query" :suggestions="fruits" placeholder="输入水果名称" />
</template>
```

## 异步建议

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

const query = ref('')

async function fetchSuggestions(keyword?: string): Promise<string[]> {
  if (!keyword) return []
  const res = await fetch(`/api/search?q=${encodeURIComponent(keyword)}`)
  return res.json()
}
</script>

<template>
  <u-auto-complete v-model="query" :suggestions="fetchSuggestions" placeholder="搜索..." />
</template>
```

## 自定义选项模板

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

const query = ref('')
const users = ['Alice', 'Bob', 'Charlie', 'Diana']
</script>

<template>
  <u-auto-complete v-model="query" :suggestions="users">
    <template #default="{ option }">
      <span style="font-weight: bold;">👤 {{ option }}</span>
    </template>
  </u-auto-complete>
</template>
```

## 只读模式

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

const query = ref('Apple')
const fruits = ['Apple', 'Banana', 'Cherry