### Install @fantastic-admin/composables

Source: https://github.com/fantastic-admin/basic/blob/main/_autodocs/api-reference/composables.md

Provides installation instructions for the composables package using pnpm and npm.

```bash
# pnpm
pnpm add @fantastic-admin/composables

# npm
npm install @fantastic-admin/composables
```

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

### Example Custom Slot Directory Structure

Source: https://github.com/fantastic-admin/basic/blob/main/skills/fa-slot-creator/references/slot-positions.md

This illustrates the expected directory structure for several example custom slots within the Fantastic-admin project.

```bash
/src/slots/LayoutTop/index.vue
/src/slots/LayoutBottom/index.vue
/src/slots/HeaderStart/index.vue
/src/slots/MainSidebarBottom/index.vue
/src/slots/FreePosition/index.vue
```

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

### Full Navigation Menu Configuration Example

Source: https://github.com/fantastic-admin/basic/blob/main/skills/fa-framework-settings/references/menu-settings.md

This snippet shows a comprehensive configuration for the navigation menu, setting all available options.

```typescript
menu: {
  mode: 'side',
  mainMenuClickMode: 'switch',
  subMenuUniqueExpand: true,
  subMenuCollapse: false,
  subMenuCollapseButton: true,
  hotkeys: true,
}
```

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

### Example Component Composition

Source: https://github.com/fantastic-admin/basic/blob/main/skills/fa-page-optimizer/SKILL.md

Demonstrates how to compose Fantastic-admin components like FaCard, FaSearchBar, FaEmpty, and FaPagination to build a user interface. This example shows a typical usage pattern for managing lists and their associated controls.

```vue
<FaCard title="用户列表">
  <FaSearchBar v-model="keyword" />
  <FaEmpty v-if="users.length === 0" />
  <template #footer>
    <FaPagination :page="page" :size="size" :total="total" />
  </template>
</FaCard>
```

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

### Pagination Dual Format Example

Source: https://github.com/fantastic-admin/basic/blob/main/_autodocs/api-reference/composables.md

Demonstrates how `getParams` from `usePagination` can be used to fetch data using either `page`/`size` or `from`/`limit` conventions, accommodating different API requirements.

```typescript
import { usePagination } from '@fantastic-admin/composables'

const { getParams } = usePagination()

// Some APIs use page/size
const params1 = getParams()
// { page: 1, size: 10, from: 0, limit: 10 }
const response1 = await fetch('/api/users?page=1&size=10')

// Some APIs use from/limit
const params2 = getParams()
// Same getParams() provides both formats
// Can use params2.from and params2.limit instead
const response2 = await fetch('/api/users?from=0&limit=10')
```

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

### Dockerizing the Application Build

Source: https://github.com/fantastic-admin/basic/blob/main/_autodocs/integration-guide.md

Create a Docker image for your application using a multi-stage build. This process installs dependencies, builds the application, and then copies the build artifacts to an Nginx server.

```dockerfile
FROM node:22-alpine AS builder
WORKDIR /app
COPY . .
RUN pnpm install && pnpm build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```

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

### Community Theme CSS Variable Example

Source: https://github.com/fantastic-admin/basic/blob/main/skills/fa-theme-customizer/references/design-styles.md

Illustrates the standard CSS variable format used by community themes on tweakcn.com, which can be adapted for the framework.

```css
:root {
  --background: oklch(1 0 0);
  --primary: oklch(0.623 0.214 259.815);
}
```

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

### CSS for FreePosition Slot

Source: https://github.com/fantastic-admin/basic/blob/main/skills/fa-slot-creator/references/slot-positions.md

This CSS example demonstrates how to style elements placed in the FreePosition slot. It requires absolute positioning and manual coordinate setting.

```css
.free-position-slot {
  position: absolute;
  bottom: 20px;
  right: 20px;
  z-index: 1000;
}
```

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

### Apache Web Server Configuration for HTML5 Mode

Source: https://github.com/fantastic-admin/basic/blob/main/_autodocs/integration-guide.md

Configure Apache's .htaccess file to ensure proper routing for HTML5 mode applications. This setup serves index.html for all non-file and non-directory requests.

```apache
<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /index.html [L]
</IfModule>
```

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

### List Available Apps

Source: https://github.com/fantastic-admin/basic/blob/main/skills/fa-page-optimizer/SKILL.md

Before performing any file operations, list all available applications in the monorepo. This is a prerequisite step to confirm the workspace.

```bash
ls apps/
```

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

### FaTable Custom Cell Template

Source: https://github.com/fantastic-admin/basic/blob/main/skills/fa-crud-page-generator/references/templates.md

Example of a custom cell template for a FaTable column, using a slot to render custom content with conditional styling.

```vue
<template #cell-status="{ row }">
  <FaBadge :variant="row.original.status ? 'default' : 'secondary'">
    {{ row.original.status ? '启用' : '停用' }}
  </FaBadge>
</template>
```

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

### Common Commands

Source: https://github.com/fantastic-admin/basic/blob/main/CLAUDE.md

Lists essential pnpm commands for developing and building the Fantastic-admin project.

```bash
pnpm dev          # 启动开发服务器
pnpm build        # 构建
pnpm lint         # 运行全量 lint（tsc + eslint + stylelint）
```

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

### Build Scripts for Different Environments

Source: https://github.com/fantastic-admin/basic/blob/main/_autodocs/integration-guide.md

Execute build commands for production or test environments. These scripts automate the process of compiling and preparing your application for deployment.

```bash
pnpm build          # Build the application
pnpm build:test     # Build for test environment
```

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

### Project Structure

Source: https://github.com/fantastic-admin/basic/blob/main/CLAUDE.md

Illustrates the monorepo directory structure for Fantastic-admin, detailing the organization of applications, shared packages, and scripts.

```bash
├── apps/
│   └── <app>/                # 应用
│       └── src/
│           ├── api/          # API 请求模块
│           ├── assets/       # 静态资源
│           ├── components/   # 全局业务组件
│           ├── composables/  # 组合式函数
│           ├── layouts/      # 布局组件
│           ├── router/       # 路由配置
│           ├── slots/        # 插槽组件
│           ├── store/        # Pinia store
│           ├── types/        # TypeScript 类型定义
│           ├── ui/           # 框架内建 UI 组件（本地）
│           ├── utils/        # 工具函数
│           └── views/        # 页面视图
├── packages/
│   ├── components/           # 框架内建 UI 组件库（子包，跨应用共享）
│   ├── settings/             # 框架设置（子包，跨应用共享）
│   └── themes/               # 主题配置（子包，跨应用共享）
├── scripts/                  # 工程脚本
└── pnpm-workspace.yaml       # monorepo workspace 配置
```

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

### 生成 GitHub Discussions 链接并打开

Source: https://github.com/fantastic-admin/basic/blob/main/skills/fa-feedback/SKILL.md

使用 Python 脚本将整理好的标题和正文通过 URL 参数编码，拼接到 GitHub Discussions 的新问题创建链接中，并自动打开该链接。如果 URL 参数预填失败，则提供手动复制的备选方案。

```bash
# 生成 URL 编码的链接并打开
python3 -c "
import urllib.parse
import subprocess

title = '''在此填入标题'''
body = '''在此填入正文'''

params = urllib.parse.urlencode({
    'category': '通用',
    'title': title,
    'body': body
}, quote_via=urllib.parse.quote)

url = f'https://github.com/orgs/fantastic-admin/discussions/new?{params}'
print(f'链接已生成：{url}')
subprocess.run(['open', url])
"
```

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

### Vue.js Form Page Template

Source: https://github.com/fantastic-admin/basic/blob/main/skills/fa-form-builder/references/templates.md

Use this template for creating new form pages. It includes setup for vee-validate, zod, and Fa* UI components. Customize placeholders like {cname}, {componentName}, {zodSchema}, {initialValues}, {formItems}, {imports}, {maxWidth}, and {gridClass} according to your module's requirements.

```vue
<script setup lang="ts">
import { toTypedSchema } from '@vee-validate/zod'
import { useForm } from 'vee-validate'
import * as z from 'zod'
import { FormControl, FormItem, FormLabel, FormMessage } from '@/ui/shadcn/ui/form'
{imports}

defineOptions({
  name: '{componentName}',
})

const router = useRouter()

const formSchema = toTypedSchema(z.object({
  {zodSchema}
}))

const { handleSubmit, isSubmitting } = useForm({
  validationSchema: formSchema,
  initialValues: {
    {initialValues}
  },
})

const loading = ref(false)

const onSubmit = handleSubmit(async (values) => {
  // TODO: 调用 API，如 apiXxx.create(values) 或 apiXxx.edit(values)
})

function handleCancel() {
  router.back()
}
</script>

<template>
  <div>
    <FaPageHeader title="{cname}" />
    <FaPageMain>
      <div v-loading="loading" class="mx-auto {maxWidth}">
        <form class="{gridClass}" @submit="onSubmit">
          {formItems}
        </form>
      </div>
    </FaPageMain>
    <FaFixedBar position="bottom" class="flex gap-2 justify-center">
      <FaButton type="button" variant="outline" @click="handleCancel">
        取消
      </FaButton>
      <FaButton type="submit" :loading="isSubmitting" @click="onSubmit">
        提交
      </FaButton>
    </FaFixedBar>
  </div>
</template>

```

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

### Initialize File Items with TypeScript

Source: https://github.com/fantastic-admin/basic/blob/main/_autodocs/README.md

Initializes a `ref` with an array of `FileItem` objects, representing uploaded files with their name, size, URL, and status.

```typescript
import type { FileItem } from '@fantastic-admin/components'

const files = ref<FileItem[]>([
  {
    name: 'document.pdf',
    size: 1024000,
    url: '/uploads/doc.pdf',
    status: 'success',
  },
])
```

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

### Smart Main Navigation Menu Click Mode Configuration

Source: https://github.com/fantastic-admin/basic/blob/main/skills/fa-framework-settings/references/menu-settings.md

Set the main navigation menu click mode to 'smart' for intelligent switching or jumping behavior.

```typescript
menu: {
  mainMenuClickMode: 'smart',
}
```

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

### Configure Vite for Auto-Import

Source: https://github.com/fantastic-admin/basic/blob/main/_autodocs/api-reference/composables.md

Shows how to configure Vite to automatically import composables from `@fantastic-admin/composables` using `unplugin-auto-import`.

```typescript
import { defineConfig } from 'vite'
import AutoImport from 'unplugin-auto-import/vite'
import { composablesResolver } from '@fantastic-admin/composables/resolver'

export default defineConfig({
  plugins: [
    AutoImport({
      resolvers: [composablesResolver()],
    }),
  ],
})
```

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

### 生成反馈报告的 Markdown 格式

Source: https://github.com/fantastic-admin/basic/blob/main/skills/fa-feedback/SKILL.md

当用户同意反馈问题后，使用此 Markdown 模板整理精简的反馈报告，包含问题描述、使用的技能、复现步骤、期望行为、实际行为和可能的原因。

```markdown
## 问题描述

[一句话说明用户想做什么，以及遇到了什么问题]

## 使用的技能

[fa-xxx-xxx]

## 复现步骤

1. [用户的原始请求]
2. [第一次修改及结果]
3. [后续修改及结果]

## 期望行为

[用户期望的结果是什么]

## 实际行为

[实际发生了什么，为什么不符合预期]

## 可能的原因

[基于分析，推测问题可能出在哪里，比如 skill 指令、框架 API、默认配置等]
```

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

### Usage with Auto-Import

Source: https://github.com/fantastic-admin/basic/blob/main/_autodocs/api-reference/composables.md

Demonstrates how to use composables directly within components without explicit import statements after configuring auto-import.

```typescript
<script setup lang="ts">
// Auto-imported, no import statement needed
const { pagination, getParams } = usePagination()
</script>
```

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

### 二级菜单路由配置

Source: https://github.com/fantastic-admin/basic/blob/main/skills/fa-route-generator/references/examples.md

用于系统管理等场景的二级菜单路由配置。

```typescript
const routes: RouteRecordRaw = {
  path: '/system',
  component: Layout,
  name: 'system',
  meta: {
    title: '系统管理',
    icon: 'i-ep:setting',
  },
  children: [
    {
      path: 'user',
      name: 'systemUser',
      component: () => import('@/views/system/user/index.vue'),
      meta: {
        title: '用户管理',
        icon: 'i-ep:user',
      },
    },
    {
      path: 'role',
      name: 'systemRole',
      component: () => import('@/views/system/role/index.vue'),
      meta: {
        title: '角色管理',
        icon: 'i-ep:avatar',
      },
    },
    {
      path: 'permission',
      name: 'systemPermission',
      component: () => import('@/views/system/permission/index.vue'),
      meta: {
        title: '权限管理',
        icon: 'i-ep:lock',
      },
    },
  ],
}
```

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

### Top Navigation Menu Mode Configuration

Source: https://github.com/fantastic-admin/basic/blob/main/skills/fa-framework-settings/references/menu-settings.md

Configure the menu to use the 'head' mode for top navigation. This is useful for a different layout.

```typescript
menu: {
  mode: 'head',
}
```

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

### Directory Structure for Custom Slots

Source: https://github.com/fantastic-admin/basic/blob/main/skills/fa-slot-creator/references/slot-positions.md

All custom slots must adhere to this directory structure. The component file must be named 'index.vue'.

```bash
/src/slots/{SlotName}/index.vue
```

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

### 询问用户是否愿意反馈问题

Source: https://github.com/fantastic-admin/basic/blob/main/skills/fa-feedback/SKILL.md

当检测到用户反复修改同一功能但未达到预期时，使用此模板询问用户是否愿意将问题反馈给框架作者，以帮助改进框架。

```markdown
我注意到在 [具体功能] 上我们已经来回调整了好几次，这很可能说明框架的 [skill/文档/API] 在这方面有改进空间。

你是否愿意将这个问题反馈给 Fantastic-admin 的作者？这有助于改进框架，让以后的使用体验更好。

如果你同意，我会帮你整理一份精简的问题描述，然后打开 GitHub Discussions 页面，内容会自动填好，你只需要检查一下就可以提交。
```

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

### Pinia Store for Authentication

Source: https://github.com/fantastic-admin/basic/blob/main/_autodocs/integration-guide.md

Manage authentication state, including user data, token, and permissions. Persists state to localStorage. Handles login, logout, and permission checks.

```typescript
// stores/auth.ts
import { defineStore } from 'pinia'
import { ref } from 'vue'
import { authApi } from '@/api/modules/auth'

export const useAuthStore = defineStore('auth', () => {
  const user = ref(null)
  const token = ref('')
  const permissions = ref<string[]>([])

  async function login(username: string, password: string) {
    const response = await authApi.login({ username, password })
    token.value = response.data.token
    user.value = response.data.user
    permissions.value = response.data.permissions
    
    // Save to localStorage or sessionStorage
    localStorage.setItem('auth_token', token.value)
  }

  async function logout() {
    await authApi.logout()
    token.value = ''
    user.value = null
    permissions.value = []
    localStorage.removeItem('auth_token')
  }

  function hasPermission(permission: string | string[]) {
    if (Array.isArray(permission)) {
      return permission.some(p => permissions.value.includes(p))
    }
    return permissions.value.includes(permission)
  }

  return {
    user,
    token,
    permissions,
    login,
    logout,
    hasPermission,
  }
}, {
  persist: true,
})
```

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

### Functional API Calls for Dialogs

Source: https://github.com/fantastic-admin/basic/blob/main/packages/components/src/basic/modal/README.md

Demonstrates how to use the `useFaModal()` hook to display different types of dialogs (info, success, confirm, error, warning) with custom titles, content, and event handlers.

```vue
<script setup lang="ts">
const modal = useFaModal()

function showAlert() {
  modal.info({
    title: '提示',
    content: '这是一条提示信息',
    onConfirm: () => {
      console.log('确认')
    },
  })
}

function showSuccess() {
  modal.success({
    title: '成功',
    content: '操作成功完成',
  })
}

function showConfirm() {
  modal.confirm({
    title: '确认',
    content: '确定要删除吗？',
    onConfirm: () => {
      console.log('删除')
    },
  })
}

function showError() {
  modal.error({
    title: '错误',
    content: '操作失败',
  })
}

function showWarning() {
  modal.warning({
    title: '警告',
    content: '此操作有风险',
  })
}
</script>

<template>
  <div class="flex gap-2">
    <FaButton @click="showAlert">信息提示</FaButton>
    <FaButton @click="showSuccess">成功提示</FaButton>
    <FaButton @click="showConfirm">确认对话框</FaButton>
    <FaButton @click="showError">错误提示</FaButton>
    <FaButton @click="showWarning">警告提示</FaButton>
  </div>
</template>
```

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

### FaTable Props

Source: https://github.com/fantastic-admin/basic/blob/main/packages/components/src/basic/table/README.md

Configuration options for the FaTable component.

```APIDOC
## FaTable Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `columns` | `TableColumn[]` | **Required** | Table column configuration. |
| `data` | `TData[]` | **Required** | Table data. |
| `border` | `boolean` | `false` | Whether to display outer borders and cell vertical dividers. |
| `caption` | `string` | - | Table title. |
| `columnVisibility` | `boolean` | `false` | Whether to display a column visibility control button on the right side of the toolbar. |
| `defaultSorting` | `TableSortingState` | `[]` | Initial sorting state, only effective when uncontrolled. |
| `defaultExpanded` | `TableExpandedState` | `{}` | Initial expanded state, only effective when uncontrolled. |
| `emptyText` | `string` | `'暂无数据'` | Text to display when there is no data. |
| `enableMultiSort` | `boolean` | `true` | Whether to allow multi-column sorting. |
| `enableSortingRemoval` | `boolean` | `true` | Whether to allow clearing the sort. |
| `expanded` | `TableExpandedState` | - | Controlled expanded state. |
| `getRowId` | `TableOptions<TData>['getRowId']` | - | Custom row ID retrieval method. |
| `getSubRows` | `TableOptions<TData>['getSubRows']` | - | Custom sub-row retrieval method; defaults to reading `children` if not set. |
| `indentSize` | `number` | `20` | Indentation in pixels for each level of tree data. |
| `manualExpanding` | `boolean` | `false` | Whether to handle expansion data manually from the outside. |
| `multiple` | `boolean` | `false` | Whether to use multi-select mode. |
| `rowKey` | `keyof TData | string | ((row: TData, index: number) => string | number)` | - | Unique identifier for the row. |
| `selectable` | `boolean` | `false` | Whether to enable the selection column. |
| `sortable` | `boolean` | `false` | Whether to enable sorting interaction. |
| `sorting` | `TableSortingState` | - | Controlled sorting state. |
| `sortDescFirst` | `boolean` | `true` | Whether the first sort starts from descending order. |
| `stripe` | `boolean` | `false` | Whether to display zebra stripes. |
| `class` | `HTMLAttributes['class']` | - | Outer root class, including toolbar and table. |
| `tableRootClass` | `HTMLAttributes['class']` | - | Table root class, only applies to the table area. |
| `tableClass` | `HTMLAttributes['class']` | - | Table class. |
| `headerClass` | `HTMLAttributes['class']` | - | Table header class. |
| `headerRowClass` | `HTMLAttributes['class']` | - | Table header row class. |
| `bodyClass` | `HTMLAttributes['class']` | - | Table body class. |
| `rowClass` | `HTMLAttributes['class'] | ((row: Row<TData>) => HTMLAttributes['class'])` | - | Table row class. |
| `selectionColumnClass` | `HTMLAttributes['class']` | - | Selection column class. |
| `tree` | `boolean` | `false` | Whether to enable tree data display; expansion icons are rendered in the first column. |
```

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

### Add Multiple Permissions to Route Meta

Source: https://github.com/fantastic-admin/basic/blob/main/skills/fa-route-generator/references/examples.md

Shows how to add an array of permissions to a route's meta configuration, allowing access if any of the specified permissions are met.

```typescript
meta: {
  title: '用户管理',
  auth: ['user:view', 'user:edit'], // 满足其中一个即可
}
```

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

### Functional Call API

Source: https://github.com/fantastic-admin/basic/blob/main/packages/components/src/basic/modal/README.md

Demonstrates how to use the `useFaModal()` hook to programmatically display different types of modal dialogs.

```APIDOC
## Functional Call API

### Description
The `useFaModal()` hook provides methods to display modal dialogs programmatically.

### Methods
- `modal.info(options)`: Displays an information dialog.
- `modal.success(options)`: Displays a success dialog.
- `modal.warning(options)`: Displays a warning dialog.
- `modal.error(options)`: Displays an error dialog.
- `modal.confirm(options)`: Displays a confirmation dialog.

### Options for all methods:
- `title` (string | () => string): The title of the dialog.
- `content` (string | () => string): The main content of the dialog.
- `onConfirm` (() => void): Callback function when the confirm button is clicked.
- `onCancel` (() => void): Callback function when the cancel button is clicked.

### Example Usage:
```vue
<script setup lang="ts">
const modal = useFaModal()

function showAlert() {
  modal.info({
    title: '提示',
    content: '这是一条提示信息',
    onConfirm: () => {
      console.log('确认')
    },
  })
}

function showSuccess() {
  modal.success({
    title: '成功',
    content: '操作成功完成',
  })
}

function showConfirm() {
  modal.confirm({
    title: '确认',
    content: '确定要删除吗？',
    onConfirm: () => {
      console.log('删除')
    },
  })
}

function showError() {
  modal.error({
    title: '错误',
    content: '操作失败',
  })
}

function showWarning() {
  modal.warning({
    title: '警告',
    content: '此操作有风险',
  })
}
</script>

<template>
  <div class="flex gap-2">
    <FaButton @click="showAlert">信息提示</FaButton>
    <FaButton @click="showSuccess">成功提示</FaButton>
    <FaButton @click="showConfirm">确认对话框</FaButton>
    <FaButton @click="showError">错误提示</FaButton>
    <FaButton @click="showWarning">警告提示</FaButton>
  </div>
</template>
```
```

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

### Environment Variables Configuration

Source: https://github.com/fantastic-admin/basic/blob/main/_autodocs/integration-guide.md

Define environment-specific variables for different deployment stages. Use these variables in your code to dynamically configure application settings.

```typescript
// .env
VITE_API_BASE_URL=http://localhost:3000/api
VITE_APP_NAME=My Admin

// .env.production
VITE_API_BASE_URL=https://api.example.com/api
VITE_APP_NAME=My Admin

// .env.test
VITE_API_BASE_URL=https://test-api.example.com/api
VITE_APP_NAME=My Admin Test
```

```typescript
const apiUrl = import.meta.env.VITE_API_BASE_URL
const appName = import.meta.env.VITE_APP_NAME
```

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

### Menu Settings Interface

Source: https://github.com/fantastic-admin/basic/blob/main/_autodocs/configuration.md

Specifies the configuration options for the application's menu, controlling layout, click behavior, and submenu expansion. Default values are included for each setting.

```typescript
interface MenuSettings {
  mode?: 'side' | 'head' | 'single'               // Default: 'side'
  mainMenuClickMode?: 'switch' | 'jump' | 'smart' // Default: 'switch'
  subMenuUniqueExpand?: boolean                    // Default: true
  subMenuCollapse?: boolean                        // Default: false
  subMenuCollapseButton?: boolean                  // Default: false
  hotkeys?: boolean                                // Default: false
}
```

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

### Theme Settings Interface

Source: https://github.com/fantastic-admin/basic/blob/main/_autodocs/configuration.md

Defines the structure for theme customization, including color scheme, radius, and color blindness support. Defaults are provided for each option.

```typescript
interface ThemeSettings {
  colorScheme?: 'light' | 'dark' | ''   // Default: 'light'
  radius?: number                        // Default: 0.5 (0-1)
  colorAmblyopia?: boolean               // Default: false
}
```

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

### FaSelect Component Props

Source: https://github.com/fantastic-admin/basic/blob/main/packages/components/src/basic/select/README.md

This snippet details the available properties for the FaSelect component, including their types, default values, and descriptions. It also outlines the structure for Option and GroupOption interfaces.

```APIDOC
## FaSelect Component API

### Props

| Property | Type | Default Value | Description |
|---|---|---|---|
| `multiple` | `boolean` | `false` | Whether to enable multiple selection. |
| `disabled` | `boolean` | `false` | Whether the component is disabled. |
| `position` | `'popper' | 'item-aligned'` | `'popper'` | The positioning mode for the dropdown content. `'popper'` makes the dropdown follow the trigger, while `'item-aligned'` offers alignment closer to native select behavior. |
| `options` | `(Option | GroupOption)[]` | **Required** | The data for the options. Must be an array of Option or GroupOption objects. |
| `placeholder` | `string` | - | Placeholder text displayed when no option is selected. |
| `class` | `HTMLAttributes['class']` | - | Custom CSS class for styling the component. |

### Option Interface

```ts
interface Option {
  label: string
  value: AcceptableValue
  disabled?: boolean
}
```

### GroupOption Interface (Grouped Options)

```ts
interface GroupOption {
  label: string
  options: Option[]
}
```

### Events

| Event Name | Description | Callback Parameters |
|---|---|---|
| `change` | Triggered when the selected option changes. | `value: AcceptableValue | undefined` |

### Notes

1. **v-model Binding**: Use `v-model` for two-way data binding.
2. **Option Data Structure**: `options` supports both plain and grouped option formats.
3. **Value Type**: The `value` can be of type string, number, etc.
4. **Group Display**: If an item in `options` has an `options` property, it's recognized as a group.
5. **z-index**: The dropdown menu's z-index defaults to 2000 for proper layering.
6. **Positioning Mode**: `position="popper"` for follow-trigger positioning, `position="item-aligned"` for native-like alignment.
```

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

### 列表-详情路由配置

Source: https://github.com/fantastic-admin/basic/blob/main/skills/fa-route-generator/references/examples.md

常见的列表和详情页面路由配置，支持从详情返回时保持列表状态。

```typescript
const routes: RouteRecordRaw = {
  path: '/article',
  component: Layout,
  name: 'article',
  meta: {
    title: '文章管理',
    icon: 'i-ep:document',
  },
  children: [
    {
      path: '',
      name: 'articleList',
      component: () => import('@/views/article/list.vue'),
      meta: {
        title: '文章列表',
        keepAlive: 'articleDetail', // 从详情返回时保持列表状态
      },
    },
    {
      path: 'detail/:id?',
      name: 'articleDetail',
      component: () => import('@/views/article/detail.vue'),
      meta: {
        title: '文章详情',
        menu: false, // 不在导航中显示
        activeMenu: '/article', // 高亮文章管理菜单
        keepAlive: true,
        noKeepAlive: 'articleList', // 从列表进入时不保活
      },
    },
  ],
}
```

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

### Define Light Theme Structure in TypeScript

Source: https://github.com/fantastic-admin/basic/blob/main/skills/fa-theme-customizer/SKILL.md

Defines the structure for a light theme using OKLCH color values. Includes standard shadcn tokens and framework-specific tokens.

```typescript
export const lightTheme = {
  // shadcn 标准 token（必填）
  '--background': 'L C H',
  '--foreground': 'L C H',
  '--card': 'L C H',
  '--card-foreground': 'L C H',
  '--popover': 'L C H',
  '--popover-foreground': 'L C H',
  '--primary': 'L C H',
  '--primary-foreground': 'L C H',
  '--secondary': 'L C H',
  '--secondary-foreground': 'L C H',
  '--muted': 'L C H',
  '--muted-foreground': 'L C H',
  '--accent': 'L C H',
  '--accent-foreground': 'L C H',
  '--destructive': '0.577 0.245 27.325',  // 通常保持不变
  '--border': 'L C H',
  '--input': 'L C H',
  '--ring': 'L C H',  // 通常与 primary 相同
  // 框架专属 token（必填）
  '--g-main-area-bg': 'oklch(L C H)',  // 明色略深于背景，形成层次感
  '--g-header-bg': 'oklch(var(--background))',
  '--g-header-color': 'oklch(var(--foreground))',
  '--g-header-menu-color': 'oklch(var(--accent-foreground))',
  '--g-header-menu-hover-bg': 'oklch(var(--accent))',
  '--g-header-menu-hover-color': 'oklch(var(--accent-foreground))',
  '--g-header-menu-active-bg': 'oklch(var(--primary))',
  '--g-header-menu-active-color': 'oklch(var(--primary-foreground))',
  '--g-main-sidebar-bg': 'oklch(var(--background))',
  '--g-main-sidebar-menu-color': 'oklch(var(--accent-foreground))',
  '--g-main-sidebar-menu-hover-bg': 'oklch(var(--accent))',
  '--g-main-sidebar-menu-hover-color': 'oklch(var(--accent-foreground))',
  '--g-main-sidebar-menu-active-bg': 'oklch(var(--primary))',
  '--g-main-sidebar-menu-active-color': 'oklch(var(--primary-foreground))',
  '--g-sub-sidebar-bg': 'oklch(var(--background))',
  '--g-sub-sidebar-menu-color': 'oklch(var(--accent-foreground))',
  '--g-sub-sidebar-menu-hover-bg': 'oklch(var(--accent))',
  '--g-sub-sidebar-menu-hover-color': 'oklch(var(--accent-foreground))',
  '--g-sub-sidebar-menu-active-bg': 'oklch(var(--primary))',
  '--g-sub-sidebar-menu-active-color': 'oklch(var(--primary-foreground))',
  '--g-tabbar-bg': 'oklch(var(--background))',
  '--g-tabbar-tab-color': 'oklch(var(--accent-foreground) / 50%)',
  '--g-tabbar-tab-hover-bg': 'oklch(var(--accent) / 50%)',
  '--g-tabbar-tab-hover-color': 'oklch(var(--accent-foreground) / 50%)',
  '--g-tabbar-tab-active-bg': 'oklch(var(--accent))',
  '--g-tabbar-tab-active-color': 'oklch(var(--foreground))',
  '--g-toolbar-bg': 'oklch(var(--background))',
} as const
```

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

### Vue Loading Overlay Optimization

Source: https://github.com/fantastic-admin/basic/blob/main/skills/fa-page-optimizer/references/optimization-patterns.md

Replaces a custom loading overlay with a more efficient `useFaLoading` hook. Ensure the `api.getData()` call is correctly implemented.

```vue
<div v-if="loading" class="loading-overlay">
  <div class="spinner">
</div>

  <p>
加载中...
</p>
</div>

<style scoped>
.loading-overlay {
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
  background: rgba(255, 255, 255, 0.8);
  display: flex;
  align-items: center;
  justify-content: center;
}
.spinner {
  /* 自定义动画 */
}
</style>
```

```vue
<script setup>
import { useFaLoading } from '@/ui/components/FaLoading'

async function fetchData() {
  const { close } = useFaLoading()
  try {
    await api.getData()
  }
  finally {
    close()
  }
}
</script>
```

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

### 单页面路由配置

Source: https://github.com/fantastic-admin/basic/blob/main/skills/fa-route-generator/references/examples.md

最简单的单页面路由配置，用于仪表盘等场景。

```typescript
import type { RouteRecordRaw } from 'vue-router'

function Layout() {
  return import('@/layouts/index.vue')
}

const routes: RouteRecordRaw = {
  path: '/dashboard',
  component: Layout,
  name: 'dashboard',
  meta: {
    title: '仪表盘',
    icon: 'i-ep:data-line',
  },
  children: [
    {
      path: '',
      name: 'dashboardIndex',
      component: () => import('@/views/dashboard/index.vue'),
      meta: {
        title: '数据概览',
      },
    },
  ],
}

export default routes
```

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

### usePagination

Source: https://github.com/fantastic-admin/basic/blob/main/_autodocs/api-reference/composables.md

Manages pagination state and parameters, supporting dual parameter formats (page/size and from/limit) for API compatibility. It provides handlers for page size, current page, and sorting changes.

```APIDOC
## usePagination

### Description
A composition function for managing pagination state and parameters. It returns reactive pagination state and utility functions to interact with it, including generating API-ready parameters and handling user interactions like page size and sort changes.

### Returns
- **pagination** (Ref<PaginationState>) - Reactive pagination state object.
- **getParams** (() => PaginationParams) - Returns current pagination parameters formatted for API calls, supporting both `page`/`size` and `from`/`limit` conventions.
- **onSizeChange** ((size: number) => Promise<void>) - Handler to update the page size.
- **onCurrentChange** ((page: number) => Promise<void>) - Handler to update the current page.
- **onSortChange** ((prop: string, order: string) => Promise<void>) - Handler to update the sort column and order.

### Pagination State Structure
```typescript
interface PaginationState {
  page: number          // Current page number (1-indexed)
  size: number          // Items per page (default: 10)
  total: number         // Total number of items
  sort: string | null   // Sort column name
  order: string | null  // Sort order ('asc' or 'desc')
}
```

### Parameters Returned by getParams()
```typescript
interface PaginationParams {
  page: number          // Current page (1-indexed)
  size: number          // Items per page
  from: number          // Offset: (page - 1) * size
  limit: number         // Alias for size
  sort?: string         // Sort column (if set)
  order?: string        // Sort order (if set)
}
```

### Example Usage
```typescript
<script setup lang="ts">
import { usePagination } from '@fantastic-admin/composables'

const { pagination, getParams, onSizeChange, onCurrentChange, onSortChange } = usePagination()

async function fetchUsers() {
  const params = getParams()
  const response = await api.users.list(params)
  pagination.value.total = response.total
}

async function handlePageChange(newPage: number) {
  await onCurrentChange(newPage)
  await fetchUsers()
}

async function handleSizeChange(newSize: number) {
  pagination.value.page = 1
  await onSizeChange(newSize)
  await fetchUsers()
}

async function handleSort(column: string, order: string) {
  await onSortChange(column, order)
  pagination.value.page = 1
  await fetchUsers()
}

onMounted(() => {
  fetchUsers()
})
</script>

<template>
  <div>
    <Table 
      :columns="columns"
      :data="data"
      :sorting="sorting"
      @sortingChange="handleSort"
    />
    <Pagination 
      :current="pagination.page"
      :size="pagination.size"
      :total="pagination.total"
      @currentChange="handlePageChange"
      @sizeChange="handleSizeChange"
    />
  </div>
</template>
```
```

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

### Form Item with FaInput

Source: https://github.com/fantastic-admin/basic/blob/main/skills/fa-crud-page-generator/references/templates.md

Vue template for a form item using ElFormItem and FaInput for text-based input.

```vue
<ElFormItem label="{label}" prop="{field}">
  <FaInput v-model="form.{field}" placeholder="请输入{label}" class="w-full" />
</ElFormItem>
```

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

### Nginx Web Server Configuration for HTML5 Mode

Source: https://github.com/fantastic-admin/basic/blob/main/_autodocs/integration-guide.md

Configure Nginx to serve index.html for all routes in HTML5 mode. This ensures that client-side routing works correctly.

```nginx
location / {
  try_files $uri $uri/ /index.html;
}
```

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

### Default Expanded Menu Route

Source: https://github.com/fantastic-admin/basic/blob/main/skills/fa-route-generator/references/examples.md

Sets up a route that should be expanded by default in the navigation menu. The 'expand: true' meta property controls this behavior for both parent and child routes.

```typescript
const routes: RouteRecordRaw = {
  path: '/menu',
  component: Layout,
  name: 'menu',
  meta: {
    title: '菜单示例',
    icon: 'i-ep:menu',
    expand: true, // 默认展开
  },
  children: [
    {
      path: 'always',
      name: 'menuAlways',
      meta: {
        title: '默认展开',
        expand: true,
      },
      children: [
        {
          path: 'item1',
          name: 'menuAlwaysItem1',
          component: () => import('@/views/menu/item1.vue'),
          meta: {
            title: '菜单项 1',
          },
        },
      ],
    },
  ],
}
```

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

### Add Single Permission to Route Meta

Source: https://github.com/fantastic-admin/basic/blob/main/skills/fa-route-generator/references/examples.md

Demonstrates how to add a single permission string to a route's meta configuration. This is used to enforce access control.

```typescript
// 修改前
meta: {
  title: '用户管理',
}

// 修改后
meta: {
  title: '用户管理',
  auth: 'user:view', // 需要 user:view 权限
}
```

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

### FaHoverCard Props

Source: https://github.com/fantastic-admin/basic/blob/main/packages/components/src/basic/hover-card/README.md

Configuration options for the FaHoverCard component.

```APIDOC
## FaHoverCard Props

| Prop Name | Type | Default Value | Description |
|---|---|---|---|
| `align` | `'start' | 'end' | 'center'` | `'center'` | Horizontal alignment mode. |
| `side` | `'top' | 'right' | 'bottom' | 'left'` | `'bottom'` | Pop-up direction. |
| `sideOffset` | `number` | `4` | Offset distance from the trigger element. |
| `alignOffset` | `number` | `0` | Alignment offset. |
| `collisionPadding` | `number` | `0` | Collision padding with viewport edges. |
| `class` | `HTMLAttributes['class']` | - | CSS class for the card. |
```

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

### Refactor Page Structure with Framework Components

Source: https://github.com/fantastic-admin/basic/blob/main/skills/fa-page-optimizer/references/optimization-patterns.md

Replaces a custom page header and content structure with dedicated framework components for improved consistency and maintainability. Ensure to use the correct slots for actions.

```vue
<template>
  <div class="page">
    <div class="page-header">
      <h1>页面标题</h1>
      <div class="actions">
        <button>操作</button>
      </div>
    </div>
    <div class="page-content">
      <!-- 内容 -->
    </div>
  </div>
</template>

<style scoped>
.page {
  padding: 20px;
}
.page-header {
  display: flex;
  justify-content: space-between;
  margin-bottom: 20px;
}
</style>
```

```vue
<template>
  <FaPageHeader title="页面标题">
    <template #actions>
      <FaButton>操作</FaButton>
    </template>
  </FaPageHeader>
  <FaPageMain>
    <!-- 内容 -->
  </FaPageMain>
</template>
```

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

### Mock Data Faker Methods

Source: https://github.com/fantastic-admin/basic/blob/main/skills/fa-crud-page-generator/references/templates.md

Mapping of common data types and meanings to corresponding faker.js methods for mock data generation.

```markdown
| 字段类型/含义 | faker 方法 |
|---------------|------------|
| 标题 | `faker.book.title()` 或 `faker.lorem.words(3)` |
| 名称 | `faker.person.fullName()` 或 `faker.commerce.productName()` |
| 用户名 | `faker.internet.username()` |
| 手机号 | `faker.phone.number()` |
| 邮箱 | `faker.internet.email()` |
| 描述 | `faker.lorem.sentence()` |
| 数量 | `faker.number.int({ min: 1, max: 100 })` |
| 金额 | `faker.number.float({ min: 10, max: 9999, fractionDigits: 2 })` |
| 布尔状态 | `faker.datatype.boolean()` |
| 枚举状态 | `faker.helpers.arrayElement([0, 1, 2])` |
| 日期 | `faker.date.recent().toISOString()` |
```

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

### FaDropdown Usage Notes

Source: https://github.com/fantastic-admin/basic/blob/main/packages/components/src/basic/dropdown/README.md

Important considerations when using the FaDropdown component.

```APIDOC
## Notes

1. **items Structure**: `items` is a 2D array, each subarray is a group, and separators are automatically added between groups.
2. **Icon Consistency**: If any menu item in a group has an icon, the entire group will reserve space for an icon.
3. **Submenus**: Multi-level submenus can be achieved by nesting through the `items` property.
4. **Event Handling**: Click events are handled via the `handle` function.
5. **Destructive Actions**: Setting `variant: 'destructive'` marks a menu item as a destructive action (red).
```