npm package: @leapfuture-fastui/core
Description: FastUI Vue 核心组件库
Latest version: 0.1.1

# @leapfuture-fastui/core

FastUI 核心组件库 - 基于 Vue 3 + TypeScript 的现代化 UI 组件

[![npm version](https://img.shields.io/npm/v/@leapfuture-fastui/core.svg)](https://www.npmjs.com/package/@leapfuture-fastui/core)
[![license](https://img.shields.io/npm/l/@leapfuture-fastui/core.svg)](https://github.com/leapfuture-fastui/fastui/blob/main/LICENSE)

## 📦 安装

```bash
# npm
npm install @leapfuture-fastui/core @leapfuture-fastui/theme

# pnpm
pnpm add @leapfuture-fastui/core @leapfuture-fastui/theme

# yarn
yarn add @leapfuture-fastui/core @leapfuture-fastui/theme
```

## 🚀 快速开始

```vue
<template>
  <div>
    <FButton variant="primary" @click="handleClick">
      点击我
    </FButton>
  </div>
</template>

<script setup lang="ts">
import { FButton } from '@leapfuture-fastui/core'
import '@leapfuture-fastui/theme/dist/index.css'

function handleClick() {
  console.log('按钮被点击了！')
}
</script>
```

## 🎯 组件列表

### 基础组件

#### Button (按钮)
多功能按钮组件，支持多种变体、尺寸和状态。

```vue
<template>
  <!-- 不同变体 -->
  <FButton variant="primary">主要按钮</FButton>
  <FButton variant="secondary">次要按钮</FButton>
  <FButton variant="outline">轮廓按钮</FButton>
  <FButton variant="ghost">幽灵按钮</FButton>
  <FButton variant="danger">危险按钮</FButton>
  
  <!-- 不同尺寸 -->
  <FButton size="small">小按钮</FButton>
  <FButton size="default">默认按钮</FButton>
  <FButton size="large">大按钮</FButton>
  
  <!-- 状态 -->
  <FButton loading>加载中</FButton>
  <FButton disabled>禁用状态</FButton>
</template>
```

**Props:**
- `variant?: 'primary' | 'secondary' | 'outline' | 'ghost' | 'danger'` - 按钮变体
- `size?: 'small' | 'default' | 'large'` - 按钮尺寸
- `loading?: boolean` - 加载状态
- `disabled?: boolean` - 禁用状态
- `text?: string` - 按钮文本

#### Input (输入框)
灵活的输入框组件，支持多种类型和验证功能。

```vue
<template>
  <!-- 基础输入框 -->
  <FInput v-model="value" placeholder="请输入内容" />
  
  <!-- 带标签 -->
  <FInput 
    v-model="username" 
    label="用户名"
    placeholder="请输入用户名"
    required
  />
  
  <!-- 密码输入框 -->
  <FInput 
    v-model="password"
    type="password"
    show-password
    placeholder="请输入密码"
  />
  
  <!-- 带图标 -->
  <FInput 
    v-model="search"
    prefix-icon="search"
    placeholder="搜索..."
    clearable
  />
</template>
```

**Props:**
- `modelValue?: string | number` - 输入值 (v-model)
- `type?: string` - 输入类型
- `label?: string` - 标签文本
- `placeholder?: string` - 占位符
- `size?: 'small' | 'default' | 'large'` - 输入框尺寸
- `disabled?: boolean` - 禁用状态
- `required?: boolean` - 必填标识
- `clearable?: boolean` - 显示清除按钮
- `show-password?: boolean` - 显示密码切换按钮
- `prefix-icon?: string` - 前缀图标
- `help-text?: string` - 帮助文本

#### Card (卡片)
容器组件，用于展示相关内容的分组。

```vue
<template>
  <!-- 基础卡片 -->
  <FCard title="卡片标题">
    <p>这是卡片内容</p>
  </FCard>
  
  <!-- 带操作区域的卡片 -->
  <FCard 
    title="可交互卡片"
    hoverable
    clickable
    @click="handleCardClick"
  >
    <p>点击卡片会触发事件</p>
    <template #actions>
      <FButton size="small">编辑</FButton>
      <FButton size="small" variant="danger">删除</FButton>
    </template>
  </FCard>
  
  <!-- 不同阴影效果 -->
  <FCard shadow="sm">小阴影</FCard>
  <FCard shadow="lg">大阴影</FCard>
</template>
```

**Props:**
- `title?: string` - 卡片标题
- `description?: string` - 卡片描述
- `shadow?: 'sm' | 'md' | 'lg'` - 阴影大小
- `hoverable?: boolean` - 悬停效果
- `clickable?: boolean` - 可点击状态

**Slots:**
- `default` - 卡片内容
- `actions` - 操作区域

#### Tag (标签)
用于标记和分类的标签组件。

```vue
<template>
  <!-- 不同类型 -->
  <FTag>默认标签</FTag>
  <FTag type="success">成功</FTag>
  <FTag type="warning">警告</FTag>
  <FTag type="danger">危险</FTag>
  
  <!-- 不同尺寸 -->
  <FTag size="small">小标签</FTag>
  <FTag size="large">大标签</FTag>
  
  <!-- 交互功能 -->
  <FTag clickable @click="handleClick">可点击</FTag>
  <FTag closable @close="handleClose">可关闭</FTag>
  
  <!-- 带图标 -->
  <FTag icon="check">带图标</FTag>
  
  <!-- 圆角样式 -->
  <FTag round>圆角标签</FTag>
</template>
```

**Props:**
- `text?: string` - 标签文本
- `type?: 'primary' | 'secondary' | 'success' | 'warning' | 'danger'` - 标签类型
- `size?: 'small' | 'default' | 'large'` - 标签尺寸
- `icon?: string` - 图标名称
- `closable?: boolean` - 可关闭
- `clickable?: boolean` - 可点击
- `round?: boolean` - 圆角样式
- `outlined?: boolean` - 轮廓样式

#### Icon (图标)
SVG 图标组件，支持多种尺寸和交互。

```vue
<template>
  <!-- 基础图标 -->
  <FIcon name="home" />
  <FIcon name="user" />
  <FIcon name="settings" />
  
  <!-- 不同尺寸 -->
  <FIcon name="heart" size="xs" />
  <FIcon name="heart" size="sm" />
  <FIcon name="heart" size="md" />
  <FIcon name="heart" size="lg" />
  <FIcon name="heart" size="xl" />
  <FIcon name="heart" :size="32" />
  
  <!-- 可点击图标 -->
  <FIcon name="star" clickable @click="handleIconClick" />
  
  <!-- 旋转动画 -->
  <FIcon name="loading" spin />
</template>
```

**Props:**
- `name: string` - 图标名称 (必填)
- `size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number` - 图标尺寸
- `clickable?: boolean` - 可点击状态
- `spin?: boolean` - 旋转动画

### 主题组件

#### ThemeProvider (主题提供者)
为应用提供主题上下文的根组件。

```vue
<template>
  <ThemeProvider>
    <div class="app">
      <!-- 你的应用内容 -->
    </div>
  </ThemeProvider>
</template>
```

#### ThemeSelect (主题选择器)
下拉选择主题模式的组件。

```vue
<template>
  <ThemeSelect />
</template>
```

#### ThemeToggle (主题切换)
切换亮色/暗色主题的按钮组件。

```vue
<template>
  <ThemeToggle />
</template>
```

## 🎨 主题系统

FastUI 提供了完整的主题系统，支持亮色/暗色双主题。

### 使用主题

```vue
<script setup lang="ts">
import { useTheme } from '@leapfuture-fastui/core'

const { theme, resolvedTheme, isDark, setTheme, toggleTheme } = useTheme()

// 设置主题
setTheme('dark')    // 暗色主题
setTheme('light')   // 亮色主题
setTheme('system')  // 跟随系统

// 切换主题
toggleTheme()
</script>
```

### useTheme Composable

`useTheme` 返回以下属性和方法：

- `theme` - 当前主题模式 ('light' | 'dark' | 'system')
- `resolvedTheme` - 实际应用的主题 ('light' | 'dark')
- `isDark` - 是否为暗色主题
- `setTheme(theme)` - 设置主题
- `toggleTheme()` - 切换亮色/暗色主题

## 📘 TypeScript 支持

FastUI 使用 TypeScript 编写，提供完整的类型定义：

```typescript
import type { ButtonProps, InputProps, CardProps } from '@leapfuture-fastui/core'

// 组件 Props 类型
const buttonProps: ButtonProps = {
  variant: 'primary',
  size: 'large',
  loading: false
}

// 主题相关类型
import type { ThemeMode, UseThemeReturn } from '@leapfuture-fastui/core'

const currentTheme: ThemeMode = 'dark'
```

## 🔧 开发

```bash
# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 构建
pnpm build

# 测试
pnpm test
```

## 📄 许可证

MIT License