# Alert Dialog

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/alert-dialog
```

```ts
import {
  AdminAlertDialog,
  AdminAlertDialogAction,
  AdminAlertDialogCancel,
  AdminAlertDialogContent,
  AdminAlertDialogDescription,
  AdminAlertDialogFooter,
  AdminAlertDialogHeader,
  AdminAlertDialogTitle,
  AdminAlertDialogTrigger,
} from '@/components/admin/alert-dialog'
```

## 用法

```vue
<script setup lang="ts">
import { cn } from '@/lib/utils'
import {
  AdminAlertDialog,
  AdminAlertDialogAction,
  AdminAlertDialogCancel,
  AdminAlertDialogContent,
  AdminAlertDialogDescription,
  AdminAlertDialogFooter,
  AdminAlertDialogHeader,
  AdminAlertDialogTitle,
  AdminAlertDialogTrigger
} from '@/registry/admin/ui/alert-dialog'
import { AdminButton } from '@/registry/admin/ui/button'
</script>

<template>
  <admin-alert-dialog>
    <admin-alert-dialog-trigger as-child>
      <admin-button>我是觸發按鈕</admin-button>
    </admin-alert-dialog-trigger>
    <admin-alert-dialog-content show-close-button>
      <admin-alert-dialog-header>
        <admin-alert-dialog-title>我是標題</admin-alert-dialog-title>
        <admin-alert-dialog-description>
          我是描述文字，用來向使用者說明這個操作會造成什麼後果。
        </admin-alert-dialog-description>
      </admin-alert-dialog-header>
      <admin-alert-dialog-footer>
        <admin-alert-dialog-cancel
          :class="
            cn(`
              inline-flex h-[44px] items-center justify-center rounded-[8px] border
              border-primary-50 px-3.75 py-2.75 typo-content-medium text-primary-50 transition-all
              hover:bg-primary-60 hover:text-text-10
            `)
          "
        >
          取消
        </admin-alert-dialog-cancel>
        <admin-alert-dialog-action
          :class="
            cn(`
              inline-flex h-[44px] items-center justify-center rounded-[8px] bg-secondary-50 px-3.75
              py-2.75 typo-content-medium text-text-10 transition-all
              hover:bg-secondary-60
            `)
          "
        >
          確認
        </admin-alert-dialog-action>
      </admin-alert-dialog-footer>
    </admin-alert-dialog-content>
  </admin-alert-dialog>
</template>
```

## 場景

### 以 overlay [命令式](https://ui.nuxt.com/docs/composables/use-overlay){rel="&#x22;nofollow&#x22;"}開啟

需要由 composable 驅動時，搭配 [`useOverlay()`](https://component-registry-4d4d86.gitlab.io/docs/admin/overlay)。

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminButton } from '@/registry/admin/ui/button'
import { useOverlay } from '@/registry/admin/ui/overlay'
import AlertDialogOverlayContent from './dialog/alert-dialog-overlay-content.vue'

const overlay = useOverlay()
const status = ref('我是狀態文字')

const confirmDialog = overlay.create(AlertDialogOverlayContent, {
  props: {
    title: '我是標題',
    description: '我是描述文字'
  }
})

async function openAlertDialogOverlay() {
  status.value = '等待使用者回應⋯'
  const result = await confirmDialog.open()
  status.value = result === 'confirmed' ? '使用者按下確認' : '使用者按下取消'
}
</script>

<template>
  <div class="flex w-full max-w-md flex-col gap-4">
    <admin-button class="self-start" @click="openAlertDialogOverlay"> 我是觸發按鈕 </admin-button>
    <p class="text-sm text-text-60">{{ status }}</p>
  </div>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-alert-dialog v-model:open="isOpen">
    <admin-alert-dialog-trigger>觸發</admin-alert-dialog-trigger>
    <admin-alert-dialog-content>
      <admin-alert-dialog-header>
        <admin-alert-dialog-title>標題</admin-alert-dialog-title>
        <admin-alert-dialog-description>說明文字</admin-alert-dialog-description>
      </admin-alert-dialog-header>
      <admin-alert-dialog-footer>
        <admin-alert-dialog-cancel>取消</admin-alert-dialog-cancel>
        <admin-alert-dialog-action>確認</admin-alert-dialog-action>
      </admin-alert-dialog-footer>
    </admin-alert-dialog-content>
  </admin-alert-dialog>
</template>
```

### admin-alert-dialog

::div{data-admin-api-table=""}
#### Props

| 名稱              | 型別                    | 預設值    | 說明                                                                                                                                                                                                                   |
| --------------- | --------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open`          | `boolean | undefined` | —      | The controlled open state of the dialog. Can be binded as \`v-model\:open\`.                                                                                                                                         |
| `defaultOpen`   | `boolean | undefined` | —      | The open state of the dialog when it is initially rendered. Use when you do not need to control its open state.                                                                                                      |
| `unmountOnHide` | `boolean | undefined` | `true` | When set to \`false\`, the dialog content will not be unmounted when closed, but instead hidden with CSS. \<br>Useful for SEO or when you want to improve performance by not remounting the component on every open. |
| `class`         | `unknown`             | —      | —                                                                                                                                                                                                                    |

#### Events

| 名稱            | Payload   | 說明 |
| ------------- | --------- | -- |
| `update:open` | `boolean` | —  |

#### Slots

| 名稱        | Bindings                                | 說明 |
| --------- | --------------------------------------- | -- |
| `default` | `{ open: boolean; close: () => void; }` | —  |
::

### admin-alert-dialog-content

::div{data-admin-api-table=""}
#### Props

| 名稱                            | 型別                                         | 預設值     | 說明                                                                                                                                                                                                                                                                       |
| ----------------------------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `forceMount`                  | `boolean | undefined`                      | —       | Used to force mounting when more control is needed. Useful when\<br>controlling animation with Vue animation libraries.                                                                                                                                                  |
| `as`                          | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                                                                             |
| `asChild`                     | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details.                                                             |
| `disableOutsidePointerEvents` | `boolean | undefined`                      | —       | When \`true\`, hover/focus/click interactions will be disabled on elements outside\<br>the \`DismissableLayer\`. Users will need to click twice on outside elements to\<br>interact with them: once to close the \`DismissableLayer\`, and again to trigger the element. |
| `class`                       | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                                                                             |
| `showCloseButton`             | `boolean | undefined`                      | `true`  | 設為 \`false\` 時隱藏右上角關閉 X 按鈕                                                                                                                                                                                                                                               |

#### Events

| 名稱                   | Payload                                       | 說明 |
| -------------------- | --------------------------------------------- | -- |
| `escapeKeyDown`      | `KeyboardEvent`                               | —  |
| `pointerDownOutside` | `PointerDownOutsideEvent`                     | —  |
| `focusOutside`       | `FocusOutsideEvent`                           | —  |
| `interactOutside`    | `PointerDownOutsideEvent | FocusOutsideEvent` | —  |
| `openAutoFocus`      | `Event`                                       | —  |
| `closeAutoFocus`     | `Event`                                       | —  |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-alert-dialog-action

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-alert-dialog-cancel

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `unknown`                                  | —       | —                                                                                                                                                                                                            |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-alert-dialog-description

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-alert-dialog-footer

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-alert-dialog-header

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-alert-dialog-title

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-alert-dialog-trigger

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `unknown`                                  | —       | —                                                                                                                                                                                                            |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

## 更新紀錄

:admin-changelog{component="AdminAlertDialog"}


# Audio Player

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/audio-player
```

```ts
import {
  AdminAudioPlayer,
  AdminAudioPlayerControls,
  AdminAudioPlayerProgress,
  AdminAudioPlayerSettings,
  AdminAudioPlayerTime,
  AdminAudioPlayerToolbar,
  AdminAudioPlayerVolume
} from '@/components/admin/audio-player'
```

vidstack 是一組 web components（`<media-player>` / `<media-provider>` / …），需要告訴 Vue 編譯器把它們當成 native custom element，否則 dev console 會出現 `[Vue warn]: Failed to resolve component: media-*` 警告。

**Nuxt 3 / 4**

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  vue: {
    compilerOptions: {
      isCustomElement: (tag) => tag.startsWith('media-')
    }
  }
})
```

**Vue 3 + Vite**

```ts [vite.config.ts]
import vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag.startsWith('media-')
        }
      }
    })
  ]
})
```

## 用法

傳入 `src` 即可播放音檔，預設組裝包含進度條、時間顯示、播放控制（播放、快退 10 秒、快進 10 秒）、設定（播放速度）與音量。

```vue
<script setup lang="ts">
import { AdminAudioPlayer } from '@/registry/admin/ui/audio-player'
</script>

<template>
  <admin-audio-player src="https://files.vidstack.io/sprite-fight/audio.mp3" />
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-audio-player>
    <admin-audio-player-progress />
    <admin-audio-player-toolbar>
      <admin-audio-player-time />
      <admin-audio-player-controls />
      <admin-audio-player-settings />
      <admin-audio-player-volume />
    </admin-audio-player-toolbar>
  </admin-audio-player>
</template>
```

### admin-audio-player

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明                             |
| ------- | ------------ | --- | ------------------------------ |
| `src`\* | `MediaSrc`   | —   | 音訊來源（vidstack \`MediaSrc\` 格式） |
| `class` | `ClassValue` | —   | 根元素之自訂 class                   |

*\\\* 代表必填*

#### Events

| 名稱           | Payload  | 說明                      |
| ------------ | -------- | ----------------------- |
| `ended`      | —        | 播放結束時觸發                 |
| `error`      | `Error`  | 載入或播放發生錯誤時觸發            |
| `pause`      | —        | 暫停播放時觸發                 |
| `play`       | —        | 開始播放時觸發                 |
| `timeUpdate` | `number` | 播放進度更新時觸發，payload 為當前秒數 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-audio-player-controls

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |
::

### admin-audio-player-progress

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |
::

### admin-audio-player-settings

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |
::

### admin-audio-player-time

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |
::

### admin-audio-player-toolbar

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-audio-player-volume

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |
::

## 注意事項

- **必須加 `isCustomElement` 設定**：未加上 `vue.compilerOptions.isCustomElement` 規則時，dev console 會對每個 `<media-*>` 元素噴 `Failed to resolve component` 警告。詳細寫法見上方「安裝」章節。
- **不支援 SSR**：vidstack 為 browser-only；元件殼不含 `<ClientOnly>`（engine 仍以 `defineAsyncComponent` 拆 chunk）。Nuxt 請自行以 `<ClientOnly>` 包覆；純 CSR 不需處理。見 [安裝 · SSR](https://component-registry-4d4d86.gitlab.io/docs/get-started/installation#ssr-nuxt)。
- **音量設定跨實例共享**：所有 `<AdminAudioPlayer>` 與 `<AdminVideoPlayer>` 實例共用同一組 `localStorage` key（`admin:player:volume` / `admin:player:muted`）；多個分頁同時開啟時不會即時同步，避免使用者剛調整的音量被其他分頁覆蓋掉。
- **播放速度不記憶**：每次元件 mount 都重設為 `1`；如需專案級記憶請消費端自行包裝。

## 更新紀錄

:admin-changelog{component="AdminAudioPlayer"}


# Avatar

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/avatar
```

```ts
import {
  AdminAvatar,
  AdminAvatarFallback,
  AdminAvatarImage,
} from '@/components/admin/avatar'
```

## 用法

```vue
<script setup lang="ts">
import { AdminAvatar, AdminAvatarFallback, AdminAvatarImage } from '@/registry/admin/ui/avatar'
</script>

<template>
  <admin-avatar>
    <admin-avatar-image alt="@user" src="https://i.pravatar.cc/64" />
    <admin-avatar-fallback>TP</admin-avatar-fallback>
  </admin-avatar>
</template>
```

## 場景

### Fallback 圖示 / 縮寫

載入失敗時回退到 `admin-avatar-fallback`。

```vue
<script setup lang="ts">
import { IconUser } from '@tabler/icons-vue'
import { AdminAvatar, AdminAvatarFallback, AdminAvatarImage } from '@/registry/admin/ui/avatar'
</script>

<template>
  <div class="flex items-center gap-4">
    <admin-avatar>
      <admin-avatar-image alt="broken" src="https://broken.example/does-not-exist.png" />
      <admin-avatar-fallback>AB</admin-avatar-fallback>
    </admin-avatar>
    <admin-avatar>
      <admin-avatar-fallback>CD</admin-avatar-fallback>
    </admin-avatar>
    <admin-avatar>
      <admin-avatar-fallback>
        <icon-user class="size-6" />
      </admin-avatar-fallback>
    </admin-avatar>
  </div>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-avatar>
    <admin-avatar-image src="..." />
    <admin-avatar-fallback>FB</admin-avatar-fallback>
  </admin-avatar>
</template>
```

### admin-avatar

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-avatar-image

::div{data-admin-api-table=""}
#### Props

| 名稱               | 型別                                                 | 預設值     | 說明                                                                                                                                                                                                           |
| ---------------- | -------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `src`\*          | `string`                                           | —       | —                                                                                                                                                                                                            |
| `referrerPolicy` | `HTMLAttributeReferrerPolicy | undefined`          | —       | —                                                                                                                                                                                                            |
| `crossOrigin`    | `"" | "anonymous" | "use-credentials" | undefined` | —       | —                                                                                                                                                                                                            |
| `asChild`        | `boolean | undefined`                              | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`             | `globalThis.Component | AsTag | undefined`         | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`          | `ClassValue`                                       | —       | 根元素之自訂 class                                                                                                                                                                                                 |

*\\\* 代表必填*

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-avatar-fallback

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `delayMs` | `number | undefined`                       | —       | Useful for delaying rendering so it only appears for those with slower connections.                                                                                                                          |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

## 更新紀錄

:admin-changelog{component="AdminAvatar"}


# Badge

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/badge
```

```ts
import { AdminBadge } from '@/components/admin/badge'
```

## 用法

```vue
<script setup lang="ts">
import { AdminBadge } from '@/registry/admin/ui/badge'
</script>

<template>
  <div class="flex items-center gap-2">
    <admin-badge>99</admin-badge>
  </div>
</template>
```

## 場景

### 尺寸

尺寸：`small`（圓點）、`medium`（預設）、`large`（可塞多字）。

```vue
<script setup lang="ts">
import { AdminBadge } from '@/registry/admin/ui/badge'
</script>

<template>
  <div class="flex items-center gap-4">
    <admin-badge size="small" />
    <admin-badge size="medium">3</admin-badge>
    <admin-badge size="large">99+</admin-badge>
  </div>
</template>
```

### 附掛在圖示上

以絕對定位疊在 icon 右上角，做未讀數 / 新訊息提示。

```vue
<script setup lang="ts">
import { AdminBadge } from '@/registry/admin/ui/badge'
</script>

<template>
  <div class="flex items-center gap-6">
    <div class="relative">
      <icon class="text-[2rem]" name="lucide:bell" />
      <admin-badge class="absolute -top-1 -right-1" size="medium">5</admin-badge>
    </div>
    <div class="relative">
      <icon class="text-[2rem]" name="lucide:mail" />
      <admin-badge class="absolute -top-1 -right-1" size="small" />
    </div>
  </div>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-badge>內容</admin-badge>
</template>
```

### admin-badge

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `variant` | `"default" | undefined`                    | —       | 視覺樣式變體                                                                                                                                                                                                       |
| `size`    | `"small" | "medium" | "large" | undefined` | —       | Badge 尺寸                                                                                                                                                                                                     |
| `class`   | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

## 更新紀錄

:admin-changelog{component="AdminBadge"}


# Breadcrumb

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/breadcrumb
```

```ts
import {
  AdminBreadcrumb,
  AdminBreadcrumbItem,
  AdminBreadcrumbLink,
  AdminBreadcrumbList,
  AdminBreadcrumbPage,
  AdminBreadcrumbSeparator,
} from '@/components/admin/breadcrumb'
```

## 用法

```vue
<script setup lang="ts">
import {
  AdminBreadcrumb,
  AdminBreadcrumbItem,
  AdminBreadcrumbLink,
  AdminBreadcrumbList,
  AdminBreadcrumbPage,
  AdminBreadcrumbSeparator
} from '@/registry/admin/ui/breadcrumb'
</script>

<template>
  <admin-breadcrumb>
    <admin-breadcrumb-list>
      <admin-breadcrumb-item>
        <admin-breadcrumb-link href="/">Home</admin-breadcrumb-link>
      </admin-breadcrumb-item>
      <admin-breadcrumb-separator />
      <admin-breadcrumb-item>
        <admin-breadcrumb-page>Component</admin-breadcrumb-page>
      </admin-breadcrumb-item>
    </admin-breadcrumb-list>
  </admin-breadcrumb>
</template>
```

## 場景

### 多層階層

以 `admin-breadcrumb-link` 連接每一層，最後一層用 `admin-breadcrumb-page` 標記當前頁。

```vue
<script setup lang="ts">
import {
  AdminBreadcrumb,
  AdminBreadcrumbItem,
  AdminBreadcrumbLink,
  AdminBreadcrumbList,
  AdminBreadcrumbPage,
  AdminBreadcrumbSeparator
} from '@/registry/admin/ui/breadcrumb'
</script>

<template>
  <admin-breadcrumb>
    <admin-breadcrumb-list>
      <admin-breadcrumb-item>
        <admin-breadcrumb-link href="/">Home</admin-breadcrumb-link>
      </admin-breadcrumb-item>
      <admin-breadcrumb-separator />
      <admin-breadcrumb-item>
        <admin-breadcrumb-link href="/docs/components">Docs</admin-breadcrumb-link>
      </admin-breadcrumb-item>
      <admin-breadcrumb-separator />
      <admin-breadcrumb-item>
        <admin-breadcrumb-link href="#">Components</admin-breadcrumb-link>
      </admin-breadcrumb-item>
      <admin-breadcrumb-separator />
      <admin-breadcrumb-item>
        <admin-breadcrumb-page>Breadcrumb</admin-breadcrumb-page>
      </admin-breadcrumb-item>
    </admin-breadcrumb-list>
  </admin-breadcrumb>
</template>
```

### Theme 變體

`theme` prop 切換 `primary` / `secondary`，當前頁文字會套用對應色系。

```vue
<script setup lang="ts">
import {
  AdminBreadcrumb,
  AdminBreadcrumbItem,
  AdminBreadcrumbLink,
  AdminBreadcrumbList,
  AdminBreadcrumbPage,
  AdminBreadcrumbSeparator
} from '@/registry/admin/ui/breadcrumb'
</script>

<template>
  <div class="flex flex-col gap-3">
    <admin-breadcrumb theme="primary">
      <admin-breadcrumb-list>
        <admin-breadcrumb-item>
          <admin-breadcrumb-link href="/">Home</admin-breadcrumb-link>
        </admin-breadcrumb-item>
        <admin-breadcrumb-separator />
        <admin-breadcrumb-item>
          <admin-breadcrumb-page>Primary 主題</admin-breadcrumb-page>
        </admin-breadcrumb-item>
      </admin-breadcrumb-list>
    </admin-breadcrumb>

    <admin-breadcrumb theme="secondary">
      <admin-breadcrumb-list>
        <admin-breadcrumb-item>
          <admin-breadcrumb-link href="/">Home</admin-breadcrumb-link>
        </admin-breadcrumb-item>
        <admin-breadcrumb-separator />
        <admin-breadcrumb-item>
          <admin-breadcrumb-page>Secondary 主題</admin-breadcrumb-page>
        </admin-breadcrumb-item>
      </admin-breadcrumb-list>
    </admin-breadcrumb>
  </div>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-breadcrumb theme="primary">
    <admin-breadcrumb-list>
      <admin-breadcrumb-item>
        <admin-breadcrumb-link href="/">Home</admin-breadcrumb-link>
      </admin-breadcrumb-item>
      <admin-breadcrumb-separator />
      <admin-breadcrumb-item>
        <admin-breadcrumb-page>Current</admin-breadcrumb-page>
      </admin-breadcrumb-item>
    </admin-breadcrumb-list>
  </admin-breadcrumb>
</template>
```

### admin-breadcrumb

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別                                    | 預設值 | 說明                       |
| ------- | ------------------------------------- | --- | ------------------------ |
| `class` | `ClassValue`                          | —   | 根元素之自訂 class             |
| `theme` | `"primary" | "secondary" | undefined` | —   | 主題色（透過 context 傳遞給所有子元件） |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-breadcrumb-list

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-breadcrumb-item

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-breadcrumb-link

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值   | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —     | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"a"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —     | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-breadcrumb-page

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-breadcrumb-separator

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

## 更新紀錄

:admin-changelog{component="AdminBreadcrumb"}


# Button

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/button
```

```ts
import { AdminButton } from '@/components/admin/button'
```

## 用法

```vue
<script setup lang="ts">
import { AdminButton } from '@/registry/admin/ui/button'
</script>

<template>
  <div class="flex items-center gap-3">
    <admin-button>Primary</admin-button>
    <admin-button variant="outline">Outline</admin-button>
    <admin-button variant="ghost">Ghost</admin-button>
  </div>
</template>
```

## 場景

### 尺寸

尺寸：`medium`（預設）、`small`。

```vue
<script setup lang="ts">
import { AdminButton } from '@/registry/admin/ui/button'
</script>

<template>
  <div class="flex items-center gap-3">
    <admin-button size="medium">Medium</admin-button>
    <admin-button size="small">Small</admin-button>
  </div>
</template>
```

### 樣式

`variant`：`filled`／`outline`／`ghost`；`disabled` 為停用。

```vue
<script setup lang="ts">
import { AdminButton } from '@/registry/admin/ui/button'
</script>

<template>
  <div class="flex items-center gap-3">
    <admin-button variant="filled">Filled</admin-button>
    <admin-button variant="outline">Outline</admin-button>
    <admin-button variant="ghost">Ghost</admin-button>
    <admin-button disabled>Disabled</admin-button>
  </div>
</template>
```

### 顏色

`color`：`primary`（預設）、`secondary`；可與任一 variant 組合。

```vue
<script setup lang="ts">
import { AdminButton } from '@/registry/admin/ui/button'
</script>

<template>
  <div class="flex flex-col gap-4">
    <div class="flex items-center gap-3">
      <admin-button color="primary" variant="filled">Primary Filled</admin-button>
      <admin-button color="primary" variant="outline">Primary Outline</admin-button>
      <admin-button color="primary" variant="ghost">Primary Ghost</admin-button>
    </div>
    <div class="flex items-center gap-3">
      <admin-button color="secondary" variant="filled">Secondary Filled</admin-button>
      <admin-button color="secondary" variant="outline">Secondary Outline</admin-button>
      <admin-button color="secondary" variant="ghost">Secondary Ghost</admin-button>
    </div>
  </div>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-button>按鈕文字</admin-button>
</template>
```

### admin-button

::div{data-admin-api-table=""}
#### Props

| 名稱         | 型別                                             | 預設值        | 說明                                                                                                                                                                                                           |
| ---------- | ---------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `variant`  | `"filled" | "outline" | "ghost" | undefined`   | —          | 視覺樣式變體                                                                                                                                                                                                       |
| `size`     | `"small" | "medium" | undefined`               | —          | 按鈕尺寸                                                                                                                                                                                                         |
| `color`    | `"primary" | "secondary" | "text" | undefined` | —          | 主色系（影響背景與邊框顏色）；\`text\` 為 ghost variant 專屬色階，其他 variant 下無對應樣式                                                                                                                                               |
| `class`    | `ClassValue`                                   | —          | 根元素之自訂 class                                                                                                                                                                                                 |
| `disabled` | `boolean | undefined`                          | —          | 設為 \`true\` 時禁用按鈕並套用視覺停用樣式                                                                                                                                                                                   |
| `type`     | `"reset" | "submit" | "button" | undefined`    | —          | 原生 \`type\` 屬性；未指定時瀏覽器預設為 \`submit\`，表單內之工具按鈕請設為 \`button\`                                                                                                                                                  |
| `asChild`  | `boolean | undefined`                          | —          | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`       | `globalThis.Component | AsTag | undefined`     | `"button"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

## 注意事項

- **`color="text"` 為 ghost 專屬**：`text` 色階僅在 `variant="ghost"` 下有對應樣式（toolbar / dropdown trigger 等次要 icon-only action 場景）；搭配 `filled`／`outline` 時無效果，渲染同該 variant 預設色。
- **表單內請設 `type="button"`**：原生 `type` 未指定時瀏覽器預設為 `submit`，放在 `<form>` 內的工具按鈕會觸發表單送出。

## 更新紀錄

:admin-changelog{component="AdminButton"}


# Checkbox

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/checkbox
```

```ts
import {
  AdminCheckbox,
  AdminCheckboxGroup,
  AdminCheckboxInput,
  AdminCheckboxLabel,
} from '@/components/admin/checkbox'
```

## 用法

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminCheckbox, AdminCheckboxInput, AdminCheckboxLabel } from '@/registry/admin/ui/checkbox'

const checked = ref<boolean | 'indeterminate'>(false)
</script>

<template>
  <admin-checkbox>
    <admin-checkbox-input v-model="checked" />
    <admin-checkbox-label>Accept terms</admin-checkbox-label>
  </admin-checkbox>
</template>
```

## 場景

### 多選群組

以 `admin-checkbox-group` 包住多個 `admin-checkbox`（各 input 帶 `value`），`v-model` 以陣列承接被選中的 value，勾選同步由底層 `CheckboxGroupRoot` 處理。

```vue
<script setup lang="ts">
import { ref } from 'vue'
import {
  AdminCheckbox,
  AdminCheckboxGroup,
  AdminCheckboxInput,
  AdminCheckboxLabel
} from '@/registry/admin/ui/checkbox'

const options = [
  { label: '接收電子報', value: 'newsletter' },
  { label: '接收推播通知', value: 'push' },
  { label: '接收簡訊提醒', value: 'sms' }
]
const selected = ref<string[]>(['newsletter'])
</script>

<template>
  <admin-checkbox-group v-model="selected">
    <admin-checkbox v-for="opt in options" :key="opt.value">
      <admin-checkbox-input :value="opt.value" />
      <admin-checkbox-label>{{ opt.label }}</admin-checkbox-label>
    </admin-checkbox>
  </admin-checkbox-group>
</template>
```

### Indeterminate（不定態）

父層 checkbox 依子項目狀態在 `true` / `false` / `'indeterminate'` 三態間切換。

```vue
<script setup lang="ts">
import { computed, ref } from 'vue'
import { AdminCheckbox, AdminCheckboxInput, AdminCheckboxLabel } from '@/registry/admin/ui/checkbox'

const items = ref<Array<{ label: string; checked: boolean | 'indeterminate' }>>([
  { label: '選項 A', checked: true },
  { label: '選項 B', checked: false },
  { label: '選項 C', checked: true }
])

const allChecked = computed<boolean | 'indeterminate'>(() => {
  const count = items.value.filter((i) => i.checked).length
  if (count === 0) {
    return false
  }
  if (count === items.value.length) {
    return true
  }
  return 'indeterminate'
})

function toggleAll(v: boolean | 'indeterminate') {
  const next = v === true
  items.value.forEach((i) => (i.checked = next))
}
</script>

<template>
  <div class="flex flex-col gap-2">
    <admin-checkbox>
      <admin-checkbox-input :model-value="allChecked" @update:model-value="toggleAll" />
      <admin-checkbox-label>全選 / 反選</admin-checkbox-label>
    </admin-checkbox>
    <div class="ml-5 flex flex-col gap-2">
      <admin-checkbox v-for="item in items" :key="item.label">
        <admin-checkbox-input v-model="item.checked" />
        <admin-checkbox-label>{{ item.label }}</admin-checkbox-label>
      </admin-checkbox>
    </div>
  </div>
</template>
```

### 錯誤狀態

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminCheckbox, AdminCheckboxInput, AdminCheckboxLabel } from '@/registry/admin/ui/checkbox'

const unchecked = ref<boolean | 'indeterminate'>(false)
const checked = ref<boolean | 'indeterminate'>(true)
</script>

<template>
  <div class="flex flex-col gap-3">
    <admin-checkbox>
      <admin-checkbox-input v-model="unchecked" is-error />
      <admin-checkbox-label>未勾選 + error</admin-checkbox-label>
    </admin-checkbox>
    <admin-checkbox>
      <admin-checkbox-input v-model="checked" is-error />
      <admin-checkbox-label>已勾選 + error</admin-checkbox-label>
    </admin-checkbox>
  </div>
</template>
```

## Type-safe 封裝

`AdminCheckboxGroup` 已是 generic（`T extends AcceptableValue`），以較嚴的 ref 綁定 `v-model` 即可收斂為選項 value 的 literal union 陣列。若要讓 value 與清單對齊，可自行封裝：傳入 `options`（建議加 `as const`），由封裝元件以 `options` 為單一事實來源渲染各選項。

如此 `options` 即聯集來源，各選項的 `value` 結構上不可能越界；型別安全落在 `v-model` 與 `defaultValue` 必須對齊 `options` 的 value union（元素型別）。

> 此食譜刻意精簡；需要時可自行 fork 擴充。封裝元件僅為文件示範，不屬 registry 安裝產物。

```vue
<script
  setup
  lang="ts"
  generic="
    TOptions extends ReadonlyArray<{
      value: AcceptableValue
      label: string
      disabled?: boolean
    }>
  "
>
import type { AcceptableValue } from 'reka-ui'
import type { AdminCheckboxGroupEmits, AdminCheckboxGroupProps } from '@/registry/admin/ui/checkbox'
import { reactiveOmit } from '@vueuse/core'
import { useForwardPropsEmits } from 'reka-ui'
import {
  AdminCheckbox,
  AdminCheckboxGroup,
  AdminCheckboxInput,
  AdminCheckboxLabel
} from '@/registry/admin/ui/checkbox'

type TValue = TOptions[number]['value']

const props = defineProps<AdminCheckboxGroupProps<TValue> & { options: TOptions }>()
const emits = defineEmits<AdminCheckboxGroupEmits<TValue>>()

const delegatedProps = reactiveOmit(props, 'options')
const forwarded = useForwardPropsEmits(delegatedProps, emits)
</script>

<template>
  <admin-checkbox-group v-bind="forwarded">
    <admin-checkbox v-for="(option, index) in props.options" :key="`${option.value}-${index}`">
      <admin-checkbox-input :disabled="option.disabled" :value="option.value" />
      <admin-checkbox-label>{{ option.label }}</admin-checkbox-label>
    </admin-checkbox>
  </admin-checkbox-group>
</template>
```

::alert{title="需開啟 strictVModel" type="info"}
型別檢查需開啟 `strictVModel`（若已開啟 `strictTemplates` 則已包含）。設定見 [Type-safe](https://component-registry-4d4d86.gitlab.io/docs/get-started/type-safe)。下列同時含合法綁定與刻意錯誤綁定；錯誤處以 `@vue-expect-error` 標示。
::

```vue
<script setup lang="ts">
import { ref } from 'vue'
import TypedAdminCheckboxGroup from './typed-admin-checkbox-group-demo.vue'

const options = [
  { value: 'newsletter', label: '接收電子報' },
  { value: 'push', label: '接收推播通知' },
  { value: 'sms', label: '接收簡訊提醒' }
] as const

const selected = ref<(typeof options)[number]['value'][]>(['newsletter'])
const wrong = ref(['unknown'])
const wrongDefault = ['unknown']
</script>

<template>
  <div class="flex w-full max-w-md flex-col gap-6">
    <typed-admin-checkbox-group v-model="selected" :options="options" />

    <!-- @vue-expect-error value 不在 options 的 value union 內 -->
    <typed-admin-checkbox-group v-model="wrong" :options="options" />

    <!-- @vue-expect-error defaultValue 不在 options 的 value union 內 -->
    <typed-admin-checkbox-group :default-value="wrongDefault" :options="options" />
  </div>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-checkbox-group v-model="selected">
    <admin-checkbox v-for="opt in options" :key="opt.value">
      <admin-checkbox-input :value="opt.value" />
      <admin-checkbox-label>{{ opt.label }}</admin-checkbox-label>
    </admin-checkbox>
  </admin-checkbox-group>
</template>
```

單顆 checkbox 不需群組時，直接以 `v-model` 綁定 input：

```vue
<template>
  <admin-checkbox>
    <admin-checkbox-input v-model="checked" />
    <admin-checkbox-label>標籤文字</admin-checkbox-label>
  </admin-checkbox>
</template>
```

### admin-checkbox

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別                   | 預設值 | 說明                             |
| ------- | -------------------- | --- | ------------------------------ |
| `class` | `ClassValue`         | —   | 根元素之自訂 class                   |
| `id`    | `string | undefined` | —   | 為內部 input 提供自訂 \`id\`；未指定時自動產生 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-checkbox-group

::div{data-admin-api-table=""}
#### Props

| 名稱             | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| -------------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `class`        | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |
| `defaultValue` | `TValue[] | undefined`                     | —       | The value of the checkbox when it is initially rendered. Use when you do not need to control its value.                                                                                                      |
| `modelValue`   | `TValue[] | undefined`                     | —       | The controlled value of the checkbox. Can be binded with v-model.                                                                                                                                            |
| `rovingFocus`  | `boolean | undefined`                      | —       | When \`false\`, navigating through the items using arrow keys will be disabled.                                                                                                                              |
| `disabled`     | `boolean | undefined`                      | —       | When \`true\`, prevents the user from interacting with the checkboxes                                                                                                                                        |
| `as`           | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `asChild`      | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `dir`          | `Direction$5 | undefined`                  | —       | The direction of navigation between items.                                                                                                                                                                   |
| `orientation`  | `Orientation$1 | undefined`                | —       | The orientation of the group.\<br>Mainly so arrow navigation is done accordingly (left & right vs. up & down)                                                                                                |
| `loop`         | `boolean | undefined`                      | `false` | Whether keyboard navigation should loop around                                                                                                                                                               |
| `name`         | `string | undefined`                       | —       | The name of the field. Submitted with its owning form as part of a name/value pair.                                                                                                                          |
| `required`     | `boolean | undefined`                      | —       | When \`true\`, indicates that the user must set the value before the owning form can be submitted.                                                                                                           |

#### Events

| 名稱                  | Payload    | 說明 |
| ------------------- | ---------- | -- |
| `update:modelValue` | `TValue[]` | —  |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-checkbox-input

::div{data-admin-api-table=""}
#### Props

| 名稱             | 型別                                             | 預設值     | 說明                                                                                                                                                                                                           |
| -------------- | ---------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `defaultValue` | `boolean | "indeterminate" | undefined`        | —       | The value of the checkbox when it is initially rendered. Use when you do not need to control its value.                                                                                                      |
| `modelValue`   | `boolean | "indeterminate" | null | undefined` | —       | The controlled value of the checkbox. Can be binded with v-model.                                                                                                                                            |
| `disabled`     | `boolean | undefined`                          | —       | When \`true\`, prevents the user from interacting with the checkbox                                                                                                                                          |
| `value`        | `AcceptableValue | undefined`                  | `"on"`  | The value given as data when submitted with a \`name\`.                                                                                                                                                      |
| `id`           | `string | undefined`                           | —       | Id of the element                                                                                                                                                                                            |
| `trueValue`    | `boolean | undefined`                          | —       | The value used when the checkbox is checked. Defaults to \`true\`.                                                                                                                                           |
| `falseValue`   | `boolean | undefined`                          | —       | The value used when the checkbox is unchecked. Defaults to \`false\`.                                                                                                                                        |
| `asChild`      | `boolean | undefined`                          | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`           | `globalThis.Component | AsTag | undefined`     | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `name`         | `string | undefined`                           | —       | The name of the field. Submitted with its owning form as part of a name/value pair.                                                                                                                          |
| `required`     | `boolean | undefined`                          | —       | When \`true\`, indicates that the user must set the value before the owning form can be submitted.                                                                                                           |
| `class`        | `ClassValue`                                   | —       | 根元素之自訂 class                                                                                                                                                                                                 |
| `isError`      | `boolean | undefined`                          | —       | 設為 \`true\` 時套用 \`aria-invalid\` 與錯誤態樣式                                                                                                                                                                      |

#### Events

| 名稱                  | Payload                     | 說明 |
| ------------------- | --------------------------- | -- |
| `update:modelValue` | `boolean | "indeterminate"` | —  |

#### Slots

| 名稱     | Bindings                                                                       | 說明                                                                    |
| ------ | ------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
| `icon` | `{ modelValue: boolean | "indeterminate"; state: boolean | "indeterminate"; }` | 自訂指示圖示；接收 CheckboxRoot 之 slot scope props（\`modelValue\` 與 \`state\`） |
::

### admin-checkbox-label

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

## 更新紀錄

:admin-changelog{component="AdminCheckbox"}


# Color Picker

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/color-picker
```

```ts
import type { ColorPickerSwatch } from '@/components/admin/color-picker'
import {
  AdminColorPicker,
  AdminColorPickerContent,
  AdminColorPickerTrigger,
} from '@/components/admin/color-picker'
```

## 用法

```vue
<script setup lang="ts">
import type { ColorPickerSwatch } from '@/registry/admin/ui/color-picker'
import { ref } from 'vue'
import {
  AdminColorPicker,
  AdminColorPickerContent,
  AdminColorPickerTrigger
} from '@/registry/admin/ui/color-picker'

const swatches = [
  { value: 'red', color: '#e1615e' },
  { value: 'orange', color: '#ff7a00' },
  { value: 'green', color: '#7abe53' },
  { value: 'blue', color: '#4567f3' },
  { value: 'violet', color: '#694cfe' }
] as const satisfies readonly ColorPickerSwatch[]

const value = ref<(typeof swatches)[number]['value']>()
</script>

<template>
  <admin-color-picker v-model="value" :swatches="swatches">
    <admin-color-picker-trigger />
    <admin-color-picker-content />
  </admin-color-picker>
</template>
```

## 場景

### 停用狀態

```vue
<script setup lang="ts">
import type { ColorPickerSwatch } from '@/registry/admin/ui/color-picker'
import { ref } from 'vue'
import {
  AdminColorPicker,
  AdminColorPickerContent,
  AdminColorPickerTrigger
} from '@/registry/admin/ui/color-picker'

const swatches = [
  { value: 'red', color: '#e1615e' },
  { value: 'orange', color: '#ff7a00' },
  { value: 'green', color: '#7abe53' },
  { value: 'blue', color: '#4567f3' },
  { value: 'violet', color: '#694cfe' }
] as const satisfies readonly ColorPickerSwatch[]

const value = ref<(typeof swatches)[number]['value'] | undefined>('blue')
</script>

<template>
  <admin-color-picker v-model="value" disabled :swatches="swatches">
    <admin-color-picker-trigger />
    <admin-color-picker-content />
  </admin-color-picker>
</template>
```

### 自訂 trigger

當預設 trigger 樣式不符需求，透過 `AdminColorPickerTrigger` 的 default slot 自行渲染觸發器；slot 內第一個元素會直接成為觸發 DOM。

```vue
<script setup lang="ts">
import type { ColorPickerSwatch } from '@/registry/admin/ui/color-picker'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import {
  AdminColorPicker,
  AdminColorPickerContent,
  AdminColorPickerTrigger
} from '@/registry/admin/ui/color-picker'

const swatches = [
  { value: 'red', color: '#e1615e', label: '紅' },
  { value: 'orange', color: '#ff7a00', label: '橘' },
  { value: 'green', color: '#7abe53', label: '綠' },
  { value: 'blue', color: '#4567f3', label: '藍' },
  { value: 'violet', color: '#694cfe', label: '紫' }
] as const satisfies readonly ColorPickerSwatch[]

const value = ref<(typeof swatches)[number]['value']>()
</script>

<template>
  <admin-color-picker v-model="value" :swatches="swatches">
    <admin-color-picker-trigger v-slot="{ swatch, open, disabled }">
      <button
        type="button"
        :class="
          cn(`
            flex items-center gap-1 rounded-full border border-text-30 bg-bg-90 px-3 py-1
            text-text-90 outline-hidden
            hover:border-text-50
            focus-visible:ring-2 focus-visible:ring-info-40
            data-[state=open]:border-info-40
          `)
        "
        :disabled="disabled"
      >
        <span
          class="size-3 rounded-full"
          :style="{ backgroundColor: swatch?.color ?? 'transparent' }"
        ></span>
        <span class="text-sm">{{ swatch?.label ?? swatch?.value ?? '未選擇' }}</span>
        <span class="text-xs text-text-50">{{ open ? '收合' : '展開' }}</span>
      </button>
    </admin-color-picker-trigger>
    <admin-color-picker-content />
  </admin-color-picker>
</template>
```

## API 參考

`swatches` 中每個 `value` 須唯一，且 `v-model` 綁定值須為其中某個 `value`；若綁定值不在清單內，trigger 會顯示為未選狀態。

以 `as const satisfies readonly ColorPickerSwatch[]` 宣告 `swatches`，`modelValue` 會收斂成各 `value` 的 literal union，綁定清單外的字串即觸發 TypeScript 型別錯誤；未加 `as const` 時 `modelValue` 退回 `string`，維持向後相容。

### 組成

```vue
<script setup lang="ts">
import type { ColorPickerSwatch } from '@/components/admin/color-picker'

const swatches = [
  { value: 'red', color: '#e1615e' },
  { value: 'blue', color: '#4567f3' },
] as const satisfies readonly ColorPickerSwatch[]
const value = ref<(typeof swatches)[number]['value']>()
</script>

<template>
  <admin-color-picker v-model="value" :swatches="swatches">
    <admin-color-picker-trigger />
    <admin-color-picker-content />
  </admin-color-picker>
</template>
```

需要自訂 trigger 時放入 slot 內容：

```vue
<template>
  <admin-color-picker v-model="value" :swatches="swatches">
    <admin-color-picker-trigger v-slot="{ swatch, disabled }">
      <button :disabled="disabled">
        <span v-if="swatch" :style="{ background: swatch.color }"></span>
        <span v-else>選擇顏色</span>
      </button>
    </admin-color-picker-trigger>
    <admin-color-picker-content />
  </admin-color-picker>
</template>
```

### admin-color-picker

::div{data-admin-api-table=""}
#### Props

| 名稱           | 型別                                     | 預設值     | 說明                                                                                                                                    |
| ------------ | -------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `class`      | `unknown`                              | —       | —                                                                                                                                     |
| `modelValue` | `TValue | undefined`                   | —       | 受控值，以 \`v-model\` 綁定；須為 \`swatches\` 中某個 \`value\`，否則 trigger 視為未選                                                                    |
| `swatches`\* | `readonly ColorPickerSwatch<TValue>[]` | —       | 可選顏色清單（必填）；每個 \`value\` 須唯一。以 \`as const satisfies readonly ColorPickerSwatch\[]\` 宣告時，\`modelValue\` 會收斂成各 \`value\` 的 literal union |
| `disabled`   | `boolean | undefined`                  | `false` | 設為 \`true\` 時禁用 picker                                                                                                                |

*\\\* 代表必填*

#### Events

| 名稱                  | Payload              | 說明                                         |
| ------------------- | -------------------- | ------------------------------------------ |
| `update:modelValue` | `TValue | undefined` | modelValue 更新時觸發；未選 / 取消選擇時為 \`undefined\` |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-color-picker-content

::div{data-admin-api-table=""}
#### Props

| 名稱           | 型別                                       | 預設值        | 說明                      |
| ------------ | ---------------------------------------- | ---------- | ----------------------- |
| `align`      | `"start" | "end" | "center" | undefined` | `"center"` | 對齊 trigger 之位置          |
| `sideOffset` | `number | undefined`                     | `4`        | content 與 trigger 之間的距離 |
| `class`      | `ClassValue`                             | —          | 根元素之自訂 class            |
::

### admin-color-picker-trigger

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別        | 預設值 | 說明 |
| ------- | --------- | --- | -- |
| `class` | `unknown` | —   | —  |

#### Slots

| 名稱        | Bindings                                                                                                          | 說明                                                                 |
| --------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `default` | `{ value: string | undefined; swatch: ColorPickerSwatch<string> | undefined; open: boolean; disabled: boolean; }` | 預設 slot；若提供則以自訂內容取代預設 trigger，並傳遞當前值、選中之 swatch、open 與 disabled 狀態 |
::

## 更新紀錄

:admin-changelog{component="AdminColorPicker"}


# Cropper

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/cropper
```

```ts
import type { CropResult } from '@/components/admin/cropper'
import {
  AdminCropper,
  AdminCropperPreview,
  AdminCropperZoom,
  useAdminCropperContext
} from '@/components/admin/cropper'
```

cropperjs v2 是一組 web components（`<cropper-canvas>` / `<cropper-image>` / `<cropper-selection>` …），需要告訴 Vue 編譯器把它們當成 native custom element，否則 dev console 會出現 `[Vue warn]: Failed to resolve component: cropper-*` 警告。視專案類型把下列設定加進去：

**Nuxt 3 / 4**

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  vue: {
    compilerOptions: {
      isCustomElement: (tag) => tag.startsWith('cropper-')
    }
  }
})
```

**Vue 3 + Vite**

```ts [vite.config.ts]
import vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag.startsWith('cropper-')
        }
      }
    })
  ]
})
```

## 用法

```vue
<script setup lang="ts">
import type { CropResult } from '@/registry/admin/ui/cropper'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { AdminCropper, AdminCropperPreview, AdminCropperZoom } from '@/registry/admin/ui/cropper'

const src = ref('https://picsum.photos/id/1018/1200/800')
const result = ref<CropResult>()

function randomize() {
  const id = Math.floor(Math.random() * 1000)
  src.value = `https://picsum.photos/id/${id}/1200/800`
}
</script>

<template>
  <div class="flex flex-col gap-4">
    <div class="flex items-center gap-2">
      <input
        v-model="src"
        placeholder="圖片 URL"
        type="url"
        :class="
          cn(`
            h-9 flex-1 rounded-md border border-text-30 bg-bg-90 px-2 typo-content-medium
            text-text-70
          `)
        "
      />
      <button
        type="button"
        :class="
          cn(`
            h-9 cursor-pointer rounded-md border border-primary-50 bg-bg-90 px-3 typo-content-medium
            text-primary-50
          `)
        "
        @click="randomize"
      >
        隨機 picsum
      </button>
    </div>

    <client-only>
      <admin-cropper v-model:result="result" :src="src">
        <template #default="{ selectionId, zoom, zoomTo, zoomBy, minZoom, maxZoom, zoomable }">
          <admin-cropper-preview class="size-30" :selection="selectionId" />
          <admin-cropper-zoom
            v-if="zoomable"
            :max-zoom="maxZoom"
            :min-zoom="minZoom"
            :zoom="zoom"
            @zoom-by="zoomBy"
            @zoom-to="zoomTo"
          />
        </template>
      </admin-cropper>
    </client-only>
  </div>
</template>
```

## 場景

### 互動 playground

```vue
<script setup lang="ts">
import type {
  AdminCropperMinSelectionSize,
  AdminCropperSelectionWithin,
  AdminCropperSourceTooSmallPayload,
  CropResult
} from '@/registry/admin/ui/cropper'
import { computed, ref, watch } from 'vue'
import { cn } from '@/lib/utils'
import { AdminButton } from '@/registry/admin/ui/button'
import { AdminCropper, AdminCropperPreview, AdminCropperZoom } from '@/registry/admin/ui/cropper'

type Mime = 'image/png' | 'image/jpeg' | 'image/webp'
type Method = 'toCanvas' | 'toDataURL' | 'toBlob'
type MinPreset = 'disabled' | 'preset' | 'custom'

const MIME_OPTIONS: readonly Mime[] = ['image/png', 'image/jpeg', 'image/webp']
const METHOD_OPTIONS: readonly Method[] = ['toCanvas', 'toDataURL', 'toBlob']
const MIN_PRESET_OPTIONS: readonly { value: MinPreset; label: string }[] = [
  { value: 'disabled', label: '關閉' },
  { value: 'preset', label: '1200×630' },
  { value: 'custom', label: '自訂' }
]
const ASPECT_OPTIONS: readonly { label: string; value: number | undefined }[] = [
  { label: '自由', value: undefined },
  { label: '16:9', value: 16 / 9 },
  { label: '4:3', value: 4 / 3 },
  { label: '1:1', value: 1 },
  { label: '3:4', value: 3 / 4 }
]
const WITHIN_OPTIONS: readonly AdminCropperSelectionWithin[] = ['none', 'canvas', 'image']

const src = ref('https://picsum.photos/id/1018/1200/800')
const result = ref<CropResult>()

const aspectRatio = ref<number | undefined>(undefined)
const selectionWithin = ref<AdminCropperSelectionWithin>('none')
const selectionRedrawable = ref(true)

const minPreset = ref<MinPreset>('disabled')
const customMinWidth = ref(800)
const customMinHeight = ref(800)

const mime = ref<Mime>('image/png')
const method = ref<Method>('toBlob')
const width = ref(600)
const height = ref(400)
const quality = ref(0.92)

const minSelectionSize = computed<AdminCropperMinSelectionSize | undefined>(() => {
  if (minPreset.value === 'disabled') {
    return undefined
  }
  if (minPreset.value === 'preset') {
    return { width: 1200, height: 630 }
  }
  return { width: customMinWidth.value, height: customMinHeight.value }
})

const tooSmall = ref<AdminCropperSourceTooSmallPayload>()
const upscaleWarn = ref(false)

function onSourceTooSmall(payload: AdminCropperSourceTooSmallPayload) {
  tooSmall.value = payload
}

watch(src, () => {
  tooSmall.value = undefined
})
watch(minSelectionSize, () => {
  tooSmall.value = undefined
})

const previewUrl = ref<string>()
const summary = ref<string>('尚未匯出')
const actualSize = ref<{ width: number; height: number }>()

const qualityApplies = computed(() => mime.value !== 'image/png')
const sizeMismatch = computed(() => {
  if (!actualSize.value) {
    return false
  }
  return actualSize.value.width !== width.value || actualSize.value.height !== height.value
})

function onPreviewLoad(event: Event) {
  const img = event.target as HTMLImageElement
  actualSize.value = { width: img.naturalWidth, height: img.naturalHeight }
}

function revokePreview() {
  if (previewUrl.value?.startsWith('blob:')) {
    URL.revokeObjectURL(previewUrl.value)
  }
  previewUrl.value = undefined
}

async function exportImage() {
  if (!result.value) {
    return
  }
  revokePreview()
  actualSize.value = undefined

  const size = { width: width.value, height: height.value }

  if (method.value === 'toCanvas') {
    const canvas = await result.value.toCanvas(size)
    previewUrl.value = canvas.toDataURL(mime.value, quality.value)
    summary.value = `toCanvas → ${canvas.width}×${canvas.height} HTMLCanvasElement`
  } else if (method.value === 'toDataURL') {
    const dataUrl = await result.value.toDataURL({
      ...size,
      mime: mime.value,
      quality: quality.value
    })
    previewUrl.value = dataUrl
    summary.value = `toDataURL → ${mime.value}, ${(dataUrl.length / 1024).toFixed(1)} KB（base64 字串）`
  } else {
    const blob = await result.value.toBlob({ ...size, mime: mime.value, quality: quality.value })
    previewUrl.value = URL.createObjectURL(blob)
    summary.value = `toBlob → ${blob.type}, ${(blob.size / 1024).toFixed(1)} KB`
  }

  upscaleWarn.value = result.value.upscale
}

function randomize() {
  const id = Math.floor(Math.random() * 1000)
  src.value = `https://picsum.photos/id/${id}/1200/800`
}
</script>

<template>
  <div class="flex flex-col gap-4">
    <div
      :class="
        cn(`
          flex flex-col gap-2
          sm:flex-row sm:flex-wrap sm:items-center
        `)
      "
    >
      <span class="shrink-0 typo-content-medium text-text-70">aspect-ratio</span>
      <div class="flex flex-wrap gap-1.5">
        <button
          v-for="opt in ASPECT_OPTIONS"
          :key="opt.label"
          type="button"
          :class="
            cn(
              'cursor-pointer rounded-md border px-3 py-1.5 typo-content-medium transition-colors',
              aspectRatio === opt.value
                ? 'border-primary-50 bg-primary-10 text-primary-50'
                : `
                  border-text-30 bg-bg-90 text-text-70
                  hover:border-text-40
                `
            )
          "
          @click="aspectRatio = opt.value"
        >
          {{ opt.label }}
        </button>
      </div>
    </div>

    <div
      :class="
        cn(`
          flex flex-col gap-2
          sm:flex-row sm:flex-wrap sm:items-center
        `)
      "
    >
      <span class="shrink-0 typo-content-medium text-text-70">selection-within</span>
      <div class="flex flex-wrap gap-1.5">
        <button
          v-for="opt in WITHIN_OPTIONS"
          :key="opt"
          type="button"
          :class="
            cn(
              `
                cursor-pointer rounded-md border px-3 py-1.5 typo-content-medium capitalize
                transition-colors
              `,
              selectionWithin === opt
                ? 'border-primary-50 bg-primary-10 text-primary-50'
                : `
                  border-text-30 bg-bg-90 text-text-70
                  hover:border-text-40
                `
            )
          "
          @click="selectionWithin = opt"
        >
          {{ opt }}
        </button>
      </div>
      <label class="flex items-center gap-1.5 typo-content-medium text-text-70">
        <input v-model="selectionRedrawable" type="checkbox" />
        允許暗區重選 (selection-redrawable)
      </label>
    </div>

    <div
      :class="
        cn(`
          flex flex-col gap-2
          sm:flex-row sm:flex-wrap sm:items-center
        `)
      "
    >
      <span class="shrink-0 typo-content-medium text-text-70">min-selection-size</span>
      <div class="flex flex-wrap gap-1.5">
        <button
          v-for="opt in MIN_PRESET_OPTIONS"
          :key="opt.value"
          type="button"
          :class="
            cn(
              'cursor-pointer rounded-md border px-3 py-1.5 typo-content-medium transition-colors',
              minPreset === opt.value
                ? 'border-primary-50 bg-primary-10 text-primary-50'
                : `
                  border-text-30 bg-bg-90 text-text-70
                  hover:border-text-40
                `
            )
          "
          @click="minPreset = opt.value"
        >
          {{ opt.label }}
        </button>
      </div>
      <template v-if="minPreset === 'custom'">
        <label class="flex items-center gap-1.5 typo-content-medium text-text-70">
          min 寬
          <input
            v-model.number="customMinWidth"
            min="1"
            type="number"
            :class="
              cn(`
                h-9 w-24 rounded-md border border-text-30 bg-bg-90 px-2 typo-content-medium
                text-text-90
              `)
            "
          />
        </label>
        <label class="flex items-center gap-1.5 typo-content-medium text-text-70">
          min 高
          <input
            v-model.number="customMinHeight"
            min="1"
            type="number"
            :class="
              cn(`
                h-9 w-24 rounded-md border border-text-30 bg-bg-90 px-2 typo-content-medium
                text-text-90
              `)
            "
          />
        </label>
      </template>
    </div>

    <div
      :class="
        cn(`
          flex flex-col gap-2
          sm:flex-row sm:flex-wrap sm:items-center
        `)
      "
    >
      <span class="shrink-0 typo-content-medium text-text-70">輸出方式</span>
      <div class="flex flex-wrap gap-1.5">
        <button
          v-for="opt in METHOD_OPTIONS"
          :key="opt"
          type="button"
          :class="
            cn(
              'cursor-pointer rounded-md border px-3 py-1.5 typo-content-medium transition-colors',
              method === opt
                ? 'border-primary-50 bg-primary-10 text-primary-50'
                : `
                  border-text-30 bg-bg-90 text-text-70
                  hover:border-text-40
                `
            )
          "
          @click="method = opt"
        >
          {{ opt }}
        </button>
      </div>
      <span class="shrink-0 typo-content-medium text-text-70">格式</span>
      <div class="flex flex-wrap gap-1.5">
        <button
          v-for="opt in MIME_OPTIONS"
          :key="opt"
          type="button"
          :class="
            cn(
              'cursor-pointer rounded-md border px-3 py-1.5 typo-content-medium transition-colors',
              mime === opt
                ? 'border-primary-50 bg-primary-10 text-primary-50'
                : `
                  border-text-30 bg-bg-90 text-text-70
                  hover:border-text-40
                `
            )
          "
          @click="mime = opt"
        >
          {{ opt }}
        </button>
      </div>
    </div>

    <div
      :class="
        cn(`
          flex flex-col gap-2
          sm:flex-row sm:flex-wrap sm:items-center
        `)
      "
    >
      <span class="shrink-0 typo-content-medium text-text-70">輸出尺寸</span>
      <label class="flex items-center gap-1.5 typo-content-medium text-text-70">
        寬
        <input
          v-model.number="width"
          min="1"
          type="number"
          :class="
            cn(`
              h-9 w-24 rounded-md border border-text-30 bg-bg-90 px-2 typo-content-medium
              text-text-90
            `)
          "
        />
      </label>
      <label class="flex items-center gap-1.5 typo-content-medium text-text-70">
        高
        <input
          v-model.number="height"
          min="1"
          type="number"
          :class="
            cn(`
              h-9 w-24 rounded-md border border-text-30 bg-bg-90 px-2 typo-content-medium
              text-text-90
            `)
          "
        />
      </label>
      <label
        :class="
          cn(
            'flex items-center gap-1.5 typo-content-medium text-text-70',
            !qualityApplies && 'opacity-50'
          )
        "
      >
        quality
        <input
          v-model.number="quality"
          max="1"
          min="0"
          step="0.05"
          type="number"
          :class="
            cn(`
              h-9 w-24 rounded-md border border-text-30 bg-bg-90 px-2 typo-content-medium
              text-text-90
              disabled:cursor-not-allowed
            `)
          "
          :disabled="!qualityApplies"
        />
      </label>
      <span v-if="!qualityApplies" class="typo-caption-medium text-text-60">
        PNG 為無損格式，瀏覽器會忽略 quality；改用 JPEG / WebP 才會生效
      </span>
    </div>

    <div class="flex items-center gap-2">
      <input
        v-model="src"
        placeholder="圖片 URL"
        type="url"
        :class="
          cn(`
            h-9 flex-1 rounded-md border border-text-30 bg-bg-90 px-2 typo-content-medium
            text-text-70
          `)
        "
      />
      <button
        type="button"
        :class="
          cn(`
            h-9 shrink-0 cursor-pointer rounded-md border border-primary-50 bg-bg-90 px-3
            typo-content-medium text-primary-50
          `)
        "
        @click="randomize"
      >
        隨機 picsum
      </button>
    </div>

    <client-only>
      <admin-cropper
        v-model:result="result"
        :aspect-ratio="aspectRatio"
        :min-selection-size="minSelectionSize"
        :selection-redrawable="selectionRedrawable"
        :selection-within="selectionWithin"
        :src="src"
        @source-too-small="onSourceTooSmall"
      >
        <template #default="{ selectionId, zoom, zoomTo, zoomBy, minZoom, maxZoom, zoomable }">
          <admin-cropper-preview class="size-30" :selection="selectionId" />
          <admin-cropper-zoom
            v-if="zoomable"
            :max-zoom="maxZoom"
            :min-zoom="minZoom"
            :zoom="zoom"
            @zoom-by="zoomBy"
            @zoom-to="zoomTo"
          />
        </template>
      </admin-cropper>
    </client-only>

    <p v-if="tooSmall" class="typo-caption-medium text-warning-50">
      原圖 {{ tooSmall.source.width }}×{{ tooSmall.source.height }} 小於要求
      {{ tooSmall.min.width }}×{{ tooSmall.min.height }}，請改用較大原圖
    </p>

    <div class="flex flex-wrap items-center gap-3">
      <admin-button @click="exportImage">匯出</admin-button>
      <span class="typo-content-medium text-text-70">{{ summary }}</span>
      <span
        v-if="upscaleWarn"
        :class="
          cn(`
            rounded-md border border-warning-50 bg-warning-10 px-2 py-1 typo-caption-medium
            text-warning-50
          `)
        "
      >
        目前匯出尺寸大於裁切區域，會被放大
      </span>
    </div>

    <div v-if="previewUrl" class="flex flex-col gap-2">
      <span class="typo-content-medium text-text-70">
        輸出預覽
        <template v-if="actualSize">
          —— 實際輸出 {{ actualSize.width }}×{{ actualSize.height }}
        </template>
      </span>
      <span v-if="sizeMismatch" class="typo-caption-medium text-warning-50">
        請求 {{ width }}×{{ height }} 與 selection 比例不一致，cropperjs 以 selection 比例做 contain
        縮放，不會拉伸或二次裁切
      </span>
      <img
        alt="匯出結果"
        class="max-w-full self-center rounded-md border border-text-20 bg-bg-80"
        :src="previewUrl"
        :style="{ maxHeight: `${height}px` }"
        @load="onPreviewLoad"
      />
    </div>
  </div>
</template>
```

### 自訂 zoom 控制

```vue
<script setup lang="ts">
import type { CropResult } from '@/registry/admin/ui/cropper'
import { IconMinus, IconPlus } from '@tabler/icons-vue'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { AdminCropper, AdminCropperPreview } from '@/registry/admin/ui/cropper'

const src = ref('https://picsum.photos/id/1043/1200/800')
const result = ref<CropResult>()
</script>

<template>
  <client-only>
    <admin-cropper v-model:result="result" :src="src">
      <template #default="{ zoom, zoomBy, selectionId }">
        <admin-cropper-preview class="size-30" :selection="selectionId" />
        <div class="flex items-center gap-3 typo-content-medium text-text-70">
          <button
            type="button"
            :class="
              cn(`
                flex size-8 cursor-pointer items-center justify-center rounded-full border
                border-primary-50 text-primary-50 transition-colors
                hover:bg-primary-50 hover:text-text-10
              `)
            "
            @click="zoomBy(-0.1)"
          >
            <icon-minus class="size-4" />
          </button>
          <span class="w-12 text-center font-mono">{{ Math.round(zoom * 100) }}%</span>
          <button
            type="button"
            :class="
              cn(`
                flex size-8 cursor-pointer items-center justify-center rounded-full border
                border-primary-50 text-primary-50 transition-colors
                hover:bg-primary-50 hover:text-text-10
              `)
            "
            @click="zoomBy(0.1)"
          >
            <icon-plus class="size-4" />
          </button>
        </div>
      </template>
    </admin-cropper>
  </client-only>
</template>
```

### 多步驟裁切流程

搭配 `admin-dialog` 與 `admin-stepper` 完成「電腦版裁切 → 手機版裁切 → 預覽結果」三步驟流程；每一步用一個 `<AdminCropper>` instance 鎖定不同 aspect ratio，最後一步直接以 `result.toDataURL()` 顯示成品。

```vue
<script setup lang="ts">
import type { CropResult } from '@/registry/admin/ui/cropper'
import { computed, ref, watch } from 'vue'
import { cn } from '@/lib/utils'
import { AdminButton } from '@/registry/admin/ui/button'
import { AdminCropper, AdminCropperPreview, AdminCropperZoom } from '@/registry/admin/ui/cropper'
import {
  AdminDialog,
  AdminDialogContent,
  AdminDialogDescription,
  AdminDialogFooter,
  AdminDialogTitle,
  AdminDialogTrigger
} from '@/registry/admin/ui/dialog'
import {
  AdminStepper,
  AdminStepperIndicator,
  AdminStepperItem,
  AdminStepperSeparator,
  AdminStepperTitle,
  AdminStepperTrigger
} from '@/registry/admin/ui/stepper'

const open = ref(false)
const step = ref<number | undefined>(1)
const src = ref('https://picsum.photos/id/1019/1200/800')

const pcResult = ref<CropResult>()
const mobileResult = ref<CropResult>()
const pcPreview = ref<string>()
const mobilePreview = ref<string>()

const steps = [
  { value: 1, title: '電腦版素材裁切' },
  { value: 2, title: '手機版素材裁切' },
  { value: 3, title: '預覽裁切結果' }
]

function randomize() {
  const id = Math.floor(Math.random() * 1000)
  src.value = `https://picsum.photos/id/${id}/1200/800`
}

function reset() {
  step.value = 1
  pcResult.value = undefined
  mobileResult.value = undefined
  pcPreview.value = undefined
  mobilePreview.value = undefined
}

async function exportPreview(result: CropResult | undefined) {
  if (!result) {
    return undefined
  }
  if (result.sourceFormat === 'gif') {
    return result.toDataURL({ mime: 'image/gif' })
  }
  return result.toDataURL({ mime: 'image/png' })
}

async function next() {
  if (step.value === 1) {
    pcPreview.value = await exportPreview(pcResult.value)
    step.value = 2
    return
  }
  if (step.value === 2) {
    mobilePreview.value = await exportPreview(mobileResult.value)
    step.value = 3
    return
  }
  open.value = false
}

function back() {
  if (step.value === 1) {
    open.value = false
    return
  }
  if (step.value === 2) {
    step.value = 1
    return
  }
  step.value = 2
}

const primaryLabel = computed(() => (step.value === 3 ? '確定裁切' : '下一步'))
const secondaryLabel = computed(() => (step.value === 1 ? '取消' : '上一步'))

watch(open, (val) => {
  if (val) {
    reset()
  }
})
</script>

<template>
  <admin-dialog v-model:open="open">
    <admin-dialog-trigger as-child>
      <admin-button>編輯素材</admin-button>
    </admin-dialog-trigger>
    <admin-dialog-content>
      <admin-dialog-title class="sr-only">編輯素材</admin-dialog-title>
      <admin-dialog-description class="sr-only">
        分三步驟裁切電腦版與手機版素材，最後預覽兩個尺寸的結果。
      </admin-dialog-description>
      <div class="flex flex-col">
        <div class="flex justify-center px-5 py-6">
          <admin-stepper v-model="step">
            <admin-stepper-item v-for="s in steps" :key="s.value" :step="s.value">
              <admin-stepper-trigger>
                <admin-stepper-indicator>{{ s.value }}</admin-stepper-indicator>
                <admin-stepper-title>{{ s.title }}</admin-stepper-title>
              </admin-stepper-trigger>
              <admin-stepper-separator v-if="s.value !== steps.length" />
            </admin-stepper-item>
          </admin-stepper>
        </div>

        <div class="flex items-center gap-2 px-5 pb-3">
          <input
            v-model="src"
            placeholder="圖片 URL"
            type="url"
            :class="
              cn(`
                h-9 flex-1 rounded-md border border-text-30 bg-bg-90 px-2 typo-content-medium
                text-text-70
              `)
            "
          />
          <button
            type="button"
            :class="
              cn(`
                h-9 cursor-pointer rounded-md border border-primary-50 bg-bg-90 px-3
                typo-content-medium text-primary-50
              `)
            "
            @click="randomize"
          >
            隨機 picsum
          </button>
        </div>

        <client-only>
          <admin-cropper
            v-if="step === 1"
            v-model:result="pcResult"
            class="gap-0"
            :aspect-ratio="5 / 3"
            :src="src"
          >
            <template #default="{ selectionId, zoom, zoomTo, zoomBy, minZoom, maxZoom, zoomable }">
              <admin-cropper-preview
                class="absolute top-1/2 right-6 h-30 w-22 -translate-y-1/2"
                :selection="selectionId"
              />
              <admin-cropper-zoom
                v-if="zoomable"
                :max-zoom="maxZoom"
                :min-zoom="minZoom"
                :zoom="zoom"
                @zoom-by="zoomBy"
                @zoom-to="zoomTo"
              />
            </template>
          </admin-cropper>

          <admin-cropper
            v-else-if="step === 2"
            v-model:result="mobileResult"
            class="gap-0"
            :aspect-ratio="3 / 4"
            :src="src"
          >
            <template #default="{ selectionId, zoom, zoomTo, zoomBy, minZoom, maxZoom, zoomable }">
              <admin-cropper-preview
                class="absolute top-1/2 right-6 h-22 w-37 -translate-y-1/2"
                :selection="selectionId"
              />
              <admin-cropper-zoom
                v-if="zoomable"
                :max-zoom="maxZoom"
                :min-zoom="minZoom"
                :zoom="zoom"
                @zoom-by="zoomBy"
                @zoom-to="zoomTo"
              />
            </template>
          </admin-cropper>
        </client-only>

        <div v-if="step === 3" class="flex flex-1 items-center justify-center gap-8 bg-bg-80 py-12">
          <div class="flex flex-col items-center gap-2">
            <img
              v-if="pcPreview"
              alt="電腦版預覽"
              class="h-46 w-77 object-cover"
              :src="pcPreview"
            />
            <p class="typo-title-small text-text-90">電腦版</p>
          </div>
          <div class="flex flex-col items-center gap-2">
            <img
              v-if="mobilePreview"
              alt="手機版預覽"
              class="h-45 w-34 object-cover"
              :src="mobilePreview"
            />
            <p class="typo-title-small text-text-90">手機版</p>
          </div>
        </div>

        <admin-dialog-footer class="justify-center pt-2 pb-5">
          <admin-button variant="outline" @click="back">{{ secondaryLabel }}</admin-button>
          <admin-button @click="next">{{ primaryLabel }}</admin-button>
        </admin-dialog-footer>
      </div>
    </admin-dialog-content>
  </admin-dialog>
</template>
```

### 裁切 GIF 動畫

呼叫 `result.toBlob('image/gif')` 或 `result.toDataURL('image/gif')` 會走 GIF pipeline，重新解碼所有 frame、依 selection 對每幀做像素裁切、再以 `gifenc` 重新編碼成動畫 GIF。原檔的 frame delay 與動畫長度會被保留。透過 `gif-max-colors` 與 `gif-frame-stride` 兩個 prop 可在畫質與檔案大小之間取捨。

```vue
<script setup lang="ts">
import type { CropResult } from '@/registry/admin/ui/cropper'
import { computed, ref, watch } from 'vue'
import { cn } from '@/lib/utils'
import { AdminCropper, AdminCropperPreview, AdminCropperZoom } from '@/registry/admin/ui/cropper'

const src = ref('/demo/sample.gif')
const result = ref<CropResult>()
const maxColors = ref(128)
const frameStride = ref(1)
const output = ref<string>('')
const error = ref<string>('')
const busy = ref(false)
let lastBlobUrl = ''

const sourceFormatLabel = computed(() =>
  result.value?.sourceFormat === 'gif' ? 'GIF（會輸出動畫）' : '靜態圖片'
)

watch(src, () => {
  output.value = ''
  error.value = ''
})

async function exportGif() {
  if (!result.value) {
    return
  }
  error.value = ''
  busy.value = true
  try {
    const blob = await result.value.toBlob({ mime: 'image/gif' })
    if (lastBlobUrl) {
      URL.revokeObjectURL(lastBlobUrl)
    }
    lastBlobUrl = URL.createObjectURL(blob)
    output.value = lastBlobUrl
  } catch (e) {
    error.value = e instanceof Error ? e.message : String(e)
    output.value = ''
  } finally {
    busy.value = false
  }
}

function onFile(event: Event) {
  const file = (event.target as HTMLInputElement).files?.[0]
  if (!file) {
    return
  }
  if (src.value.startsWith('blob:')) {
    URL.revokeObjectURL(src.value)
  }
  src.value = URL.createObjectURL(file)
}
</script>

<template>
  <div class="flex flex-col gap-4">
    <div class="flex flex-wrap items-center gap-2">
      <input
        accept="image/gif"
        type="file"
        :class="
          cn(`
            h-9 flex-1 rounded-md border border-text-30 bg-bg-90 px-2 typo-content-medium
            text-text-70
            file:mr-2 file:rounded-sm file:border-0 file:bg-primary-50 file:px-3 file:py-1
            file:text-text-10
          `)
        "
        @change="onFile"
      />
      <button
        type="button"
        :class="
          cn(`
            h-9 cursor-pointer rounded-md border border-text-30 bg-bg-90 px-3 typo-content-medium
            text-text-70
            hover:border-primary-50 hover:text-primary-50
          `)
        "
        @click="src = '/demo/sample.gif'"
      >
        還原預設 GIF
      </button>
    </div>

    <div class="flex flex-wrap items-center gap-4 typo-content-medium text-text-70">
      <label class="flex items-center gap-2">
        色盤大小
        <input
          v-model.number="maxColors"
          class="w-32 cursor-pointer accent-primary-50"
          max="256"
          min="4"
          step="4"
          type="range"
        />
        <span class="w-10 text-right">{{ maxColors }}</span>
      </label>
      <label class="flex items-center gap-2">
        每 N 幀取 1
        <input
          v-model.number="frameStride"
          class="w-32 cursor-pointer accent-primary-50"
          max="6"
          min="1"
          step="1"
          type="range"
        />
        <span class="w-6 text-right">{{ frameStride }}</span>
      </label>
      <span class="ml-auto rounded-sm bg-bg-80 px-2 py-1 typo-caption-medium">
        sourceFormat：{{ sourceFormatLabel }}
      </span>
    </div>

    <client-only>
      <admin-cropper
        v-model:result="result"
        :gif-frame-stride="frameStride"
        :gif-max-colors="maxColors"
        :src="src"
      >
        <template #default="{ selectionId, zoom, zoomTo, zoomBy, minZoom, maxZoom, zoomable }">
          <admin-cropper-preview class="size-30" :selection="selectionId" />
          <admin-cropper-zoom
            v-if="zoomable"
            :max-zoom="maxZoom"
            :min-zoom="minZoom"
            :zoom="zoom"
            @zoom-by="zoomBy"
            @zoom-to="zoomTo"
          />
        </template>
      </admin-cropper>
    </client-only>

    <div class="flex flex-wrap items-start gap-4">
      <button
        type="button"
        :class="
          cn(`
            h-9 cursor-pointer rounded-md border border-primary-50 bg-primary-50 px-4
            typo-content-medium text-text-10
            disabled:cursor-not-allowed disabled:opacity-50
          `)
        "
        :disabled="busy || !result"
        @click="exportGif"
      >
        {{ busy ? '產生中…' : '輸出 GIF' }}
      </button>
      <p v-if="error" class="rounded-sm bg-error-10 px-3 py-2 typo-caption-medium text-error-50">
        {{ error }}
      </p>
      <div v-if="output" class="flex flex-col gap-1">
        <span class="typo-caption-medium text-text-50">裁切結果（仍為動畫）</span>
        <img alt="cropped GIF result" class="rounded-sm border border-text-30" :src="output" />
      </div>
    </div>
  </div>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-cropper v-model:result="result" :aspect-ratio :src>
    <template
      #default="{ selectionId, zoom, zoomBy, zoomTo, minZoom, maxZoom, zoomable }"
    >
      <admin-cropper-preview :selection="selectionId" />
      <admin-cropper-zoom
        v-if="zoomable"
        :max-zoom="maxZoom"
        :min-zoom="minZoom"
        :zoom="zoom"
        @zoom-by="zoomBy"
        @zoom-to="zoomTo"
      />
    </template>
  </admin-cropper>
</template>
```

### admin-cropper

::div{data-admin-api-table=""}
#### Props

| 名稱                    | 型別                                         | 預設值      | 說明                                          |
| --------------------- | ------------------------------------------ | -------- | ------------------------------------------- |
| `src`\*               | `string`                                   | —        | 待裁切之來源圖檔 URL 或 dataURL（必填）                  |
| `aspectRatio`         | `number | undefined`                       | —        | 裁切框長寬比；不指定則自由比例                             |
| `minZoom`             | `number | undefined`                       | `0.1`    | 縮放下限                                        |
| `maxZoom`             | `number | undefined`                       | `3`      | 縮放上限                                        |
| `initialZoom`         | `number | undefined`                       | `1`      | 載入後初始縮放倍率                                   |
| `zoomable`            | `boolean | undefined`                      | `true`   | 設為 \`false\` 時隱藏縮放控制                        |
| `gifMaxColors`        | `number | undefined`                       | `256`    | GIF 來源編碼時最大色票數                              |
| `gifFrameStride`      | `number | undefined`                       | `1`      | GIF 來源編碼時跳幀間隔                               |
| `selectionWithin`     | `AdminCropperSelectionWithin | undefined`  | `"none"` | 限制裁切框可移動範圍                                  |
| `selectionRedrawable` | `boolean | undefined`                      | `true`   | 設為 \`false\` 時禁用重新繪製選取框互動                   |
| `minSelectionSize`    | `AdminCropperMinSelectionSize | undefined` | —        | 限制裁切框最小尺寸（避免過小）；觸發時 emit \`sourceTooSmall\` |
| `class`               | `ClassValue`                               | —        | 根元素之自訂 class                                |
| `result`              | `CropResult | undefined`                   | —        | —                                           |

*\\\* 代表必填*

#### Events

| 名稱               | Payload                             | 說明                                 |
| ---------------- | ----------------------------------- | ---------------------------------- |
| `update:result`  | `CropResult | undefined`            | —                                  |
| `sourceTooSmall` | `AdminCropperSourceTooSmallPayload` | 來源圖過小無法滿足 \`minSelectionSize\` 時觸發 |

#### Slots

| 名稱        | Bindings                                                                                                                                                | 說明                                |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| `default` | `{ selectionId: string; zoom: number; zoomTo: (v: number) => void; zoomBy: (d: number) => void; minZoom: number; maxZoom: number; zoomable: boolean; }` | 預設 slot，提供 selection id、縮放控制與當前狀態 |

#### Expose

| 名稱               | 簽名                               | 說明                                          |
| ---------------- | -------------------------------- | ------------------------------------------- |
| `reset`          | `() => void`                     | 重置 selection 到圖片中央、zoom 回到 \`initial-zoom\` |
| `zoomTo`         | `(value: number) => void`        | 縮放到絕對值（會被 clamp 到 min/max）                  |
| `zoomBy`         | `(delta: number) => void`        | 從目前 zoom 加上 delta                           |
| `setAspectRatio` | `(ratio: number | null) => void` | 命令式變更比例；\`null\` 表示自由比例                     |
::

### admin-cropper-zoom

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                   | 預設值    | 說明 |
| --------- | -------------------- | ------ | -- |
| `zoom`\*  | `number`             | —      | —  |
| `minZoom` | `number | undefined` | `0.1`  | —  |
| `maxZoom` | `number | undefined` | `3`    | —  |
| `step`    | `number | undefined` | `0.05` | —  |
| `class`   | `ClassValue`         | —      | —  |

*\\\* 代表必填*

#### Events

| 名稱       | Payload  | 說明                |
| -------- | -------- | ----------------- |
| `zoomTo` | `number` | 透過 slider 設定絕對縮放值 |
| `zoomBy` | `number` | 透過按鈕加減縮放          |
::

### admin-cropper-preview

::div{data-admin-api-table=""}
#### Props

| 名稱          | 型別                   | 預設值 | 說明                                                         |
| ----------- | -------------------- | --- | ---------------------------------------------------------- |
| `selection` | `string | undefined` | —   | 若省略且位於 \`\<AdminCropper>\` 內，則使用 context 的 \`selectionId\` |
| `class`     | `ClassValue`         | —   | —                                                          |
::

## 注意事項

### Selection 行為

- **`selection-within`**：只限制**畫布內的拖動範圍**（軸對齊邊界；旋轉時取可視外包矩形），不影響 `result.region` 仍以原圖像素表達。預設 `'none'` 允許拖到圖外（適合 GIF 透明邊）；要嚴格框在圖內設 `'image'`。
- **`selection-redrawable`**：`true`（預設）可在選框外暗區拖曳重畫；`false` 鎖定為只能調整現有框，避免表單誤觸。
- **`min-selection-size` 與 `aspect-ratio`**：兩者比例不一致時 dev console 會 warn（不 throw），實際能拖到的最小尺寸會被兩個限制夾住、可能比 `min` 還大。建議讓 `min` 寬高直接等於目標輸出尺寸。

### 輸出行為

- **`toCanvas` / `toDataURL` / `toBlob` 皆為 async**，都回傳 Promise。
- **預設不降採樣**：非 GIF 路徑輸出原圖像素座標下的裁切區域，不會因畫面上 selection 較小而縮圖；要刻意縮放請傳 `{ width, height }`。
- **`toCanvas()` 對 GIF 來源只輸出當前一幀**：要保留動畫請改用 `toBlob({ mime: 'image/gif' })` 或 `toDataURL({ mime: 'image/gif' })`。
- **GIF pipeline 跑在 main thread**：解碼／量化／編碼皆同步。建議來源 < 2MB / < 50 frames，超過會凍結 UI 100ms 以上，可用 `gif-frame-stride` 跳幀緩解。
- **部分 GIF 走 lossy 重量化**：僅當來源每一幀皆為 disposal type 2（還原到背景）時才走保留原始色盤的無損裁切路徑；多數含 disposal 0／1 幀的一般 GIF 會改走 composite 後以 `gif-max-colors` 重新量化的路徑，可能出現輕微色帶。此為畫質取捨，非錯誤。

### SSR 與 Vue 設定

- **不支援 SSR**：cropperjs v2 web components 只能在瀏覽器 register；元件殼不含 `<ClientOnly>`。Nuxt 請自行以 `<ClientOnly>` 包覆，其他 SSR 框架用等價機制；純 CSR 不需處理。見 [安裝 · SSR](https://component-registry-4d4d86.gitlab.io/docs/get-started/installation#ssr-nuxt)。
- **必須設定 `isCustomElement`**：否則 dev console 會印 `[Vue warn]: Failed to resolve component: cropper-*`。寫法見上方「安裝」章節。

#### CORS

- **一般輸出**：跨域圖片需回 `Access-Control-Allow-Origin`，否則 `toCanvas` / `toDataURL` / `toBlob` 會 throw `SecurityError`。元件已加 `crossorigin="anonymous"`，picsum 等 CDN 可正常運作。
- **GIF 輸出另需 fetch CORS**：GIF pipeline 會額外 `fetch(src)` 重新取 bytes，server 同樣要回 `Access-Control-Allow-Origin`；`<img>` 顯示成功不代表 fetch 拿得到。

## 更新紀錄

:admin-changelog{component="AdminCropper"}


# Date Picker

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/date-picker
```

```ts
import {
  AdminDatePicker,
  AdminDatePickerRange,
} from '@/components/admin/date-picker'
```

## 用法

`AdminDatePicker` 提供單選日期，`AdminDatePickerRange` 提供區間選擇。兩者共用 ark-ui DatePicker 原生組件，採共享外框 layout 與 date-fns 格式化。

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminDatePicker } from '@/registry/admin/ui/date-picker'

const value = ref<Date | null>(null)
</script>

<template>
  <div class="flex w-full max-w-sm flex-col gap-2">
    <admin-date-picker v-model="value" emit-as="date" format="yyyy/MM/dd" placeholder="選擇日期" />
    <p class="text-sm text-text-50">modelValue: {{ value ?? 'null' }}</p>
  </div>
</template>
```

## 場景

每個元件之 playground 提供完整 props 切換 UI 與即時 `modelValue` JSON 顯示。

### 單選

```vue
<script setup lang="ts">
import { computed, ref } from 'vue'
import { cn } from '@/lib/utils'
import { AdminDatePicker } from '@/registry/admin/ui/date-picker'

interface TimeModel {
  hours?: number
  minutes?: number
  seconds?: number
}

function toTimeModel(h: number | null, m: number | null, s: number | null): TimeModel | undefined {
  const norm = (v: unknown): number | null => {
    if (v == null || v === '' || (typeof v === 'number' && Number.isNaN(v))) {
      return null
    }
    return typeof v === 'number' ? v : Number(v)
  }
  const nh = norm(h)
  const nm = norm(m)
  const ns = norm(s)
  if (nh == null && nm == null && ns == null) {
    return undefined
  }
  const t: TimeModel = {}
  if (nh != null) {
    t.hours = nh
  }
  if (nm != null) {
    t.minutes = nm
  }
  if (ns != null) {
    t.seconds = ns
  }
  return t
}

// withTime=true 時若 format 不含時間 token，round-trip 會把時間段截掉、stepper 看似動了又被 watch 拉回 0；
// playground 自動補時間 token 避免此踩雷。
function ensureTimeTokens(fmt: string, withTime: boolean, enableSeconds: boolean): string {
  if (!withTime) {
    return fmt
  }
  if (fmt.includes('H') || fmt.includes('h') || fmt.includes('m') || fmt.includes('s')) {
    return fmt
  }
  return enableSeconds ? `${fmt} HH:mm:ss` : `${fmt} HH:mm`
}

const FORMAT_PRESETS = [
  'yyyy/MM/dd',
  'dd/MM/yyyy',
  'yyyy-MM-dd',
  'yyyy/MM/dd HH:mm',
  'yyyy/MM/dd HH:mm:ss'
]
const LOCALES = ['zh-TW', 'en-US', 'ja-JP']

const formatPreset = ref('yyyy/MM/dd')
const formatCustom = ref('')
const withTime = ref(false)
const enableSeconds = ref(false)
const disabled = ref(false)
const readonly = ref(false)
const isError = ref(false)
const locale = ref('zh-TW')
const placeholder = ref('選擇日期')
const minDate = ref<Date | null>(null)
const maxDate = ref<Date | null>(null)
const minHour = ref<number | null>(null)
const minMinute = ref<number | null>(null)
const minSecond = ref<number | null>(null)
const maxHour = ref<number | null>(null)
const maxMinute = ref<number | null>(null)
const maxSecond = ref<number | null>(null)
const value = ref<Date | string | number | null>(null)

const format = computed(() =>
  ensureTimeTokens(
    formatCustom.value.trim() || formatPreset.value,
    withTime.value,
    enableSeconds.value
  )
)
const minTime = computed(() => toTimeModel(minHour.value, minMinute.value, minSecond.value))
const maxTime = computed(() => toTimeModel(maxHour.value, maxMinute.value, maxSecond.value))
</script>

<template>
  <section class="w-full space-y-4 rounded-[8px] border border-text-20 bg-bg-90 p-6">
    <div class="grid grid-cols-2 gap-x-4 gap-y-3">
      <label class="flex flex-col gap-1 typo-content-medium text-text-70">
        <span class="typo-caption-small text-text-50">format（preset）</span>
        <select
          v-model="formatPreset"
          :class="
            cn(`
              h-9 rounded-md border border-text-30 bg-bg-90 px-2 typo-content-medium text-text-70
              outline-none
              focus:border-info-40
            `)
          "
        >
          <option v-for="opt in FORMAT_PRESETS" :key="opt" :value="opt">{{ opt }}</option>
        </select>
      </label>
      <label class="flex flex-col gap-1 typo-content-medium text-text-70">
        <span class="typo-caption-small text-text-50">format（自訂，非空覆蓋 preset）</span>
        <input
          v-model="formatCustom"
          placeholder="留空使用 preset"
          type="text"
          :class="
            cn(`
              h-9 rounded-md border border-text-30 bg-bg-90 px-2 typo-content-medium text-text-70
              outline-none
              focus:border-info-40
            `)
          "
        />
      </label>
      <label class="flex flex-col gap-1 typo-content-medium text-text-70">
        <span class="typo-caption-small text-text-50">locale</span>
        <select
          v-model="locale"
          :class="
            cn(`
              h-9 rounded-md border border-text-30 bg-bg-90 px-2 typo-content-medium text-text-70
              outline-none
              focus:border-info-40
            `)
          "
        >
          <option v-for="opt in LOCALES" :key="opt" :value="opt">{{ opt }}</option>
        </select>
      </label>
      <label class="flex flex-col gap-1 typo-content-medium text-text-70">
        <span class="typo-caption-small text-text-50">placeholder</span>
        <input
          v-model="placeholder"
          type="text"
          :class="
            cn(`
              h-9 rounded-md border border-text-30 bg-bg-90 px-2 typo-content-medium text-text-70
              outline-none
              focus:border-info-40
            `)
          "
        />
      </label>
      <div class="flex flex-wrap items-center gap-3 typo-caption-small text-text-70">
        <label class="inline-flex items-center gap-1">
          <input v-model="withTime" type="checkbox" /> withTime
        </label>
        <label class="inline-flex items-center gap-1">
          <input v-model="enableSeconds" type="checkbox" :disabled="!withTime" />
          enableSeconds
        </label>
        <label class="inline-flex items-center gap-1">
          <input v-model="disabled" type="checkbox" /> disabled
        </label>
        <label class="inline-flex items-center gap-1">
          <input v-model="readonly" type="checkbox" /> readonly
        </label>
        <label class="inline-flex items-center gap-1">
          <input v-model="isError" type="checkbox" /> isError
        </label>
      </div>
      <div></div>
      <label class="flex flex-col gap-1 typo-content-medium text-text-70">
        <span class="typo-caption-small text-text-50">minDate</span>
        <admin-date-picker
          v-model="minDate"
          emit-as="date"
          format="yyyy/MM/dd"
          placeholder="無下限"
        />
      </label>
      <label class="flex flex-col gap-1 typo-content-medium text-text-70">
        <span class="typo-caption-small text-text-50">maxDate</span>
        <admin-date-picker
          v-model="maxDate"
          emit-as="date"
          format="yyyy/MM/dd"
          placeholder="無上限"
        />
      </label>
      <label v-if="withTime" class="flex flex-col gap-1 typo-content-medium text-text-70">
        <span class="typo-caption-small text-text-50">
          minTime（時 / 分{{ enableSeconds ? ' / 秒' : '' }}）
        </span>
        <div class="flex items-center gap-1">
          <input
            v-model.number="minHour"
            max="23"
            min="0"
            placeholder="hh"
            type="number"
            :class="
              cn(`
                h-9 w-14 rounded-md border border-text-30 bg-bg-90 px-2 text-center
                typo-content-medium text-text-70 outline-none
                focus:border-info-40
              `)
            "
          />
          <span class="text-text-60">:</span>
          <input
            v-model.number="minMinute"
            max="59"
            min="0"
            placeholder="mm"
            type="number"
            :class="
              cn(`
                h-9 w-14 rounded-md border border-text-30 bg-bg-90 px-2 text-center
                typo-content-medium text-text-70 outline-none
                focus:border-info-40
              `)
            "
          />
          <template v-if="enableSeconds">
            <span class="text-text-60">:</span>
            <input
              v-model.number="minSecond"
              max="59"
              min="0"
              placeholder="ss"
              type="number"
              :class="
                cn(`
                  h-9 w-14 rounded-md border border-text-30 bg-bg-90 px-2 text-center
                  typo-content-medium text-text-70 outline-none
                  focus:border-info-40
                `)
              "
            />
          </template>
        </div>
      </label>
      <label v-if="withTime" class="flex flex-col gap-1 typo-content-medium text-text-70">
        <span class="typo-caption-small text-text-50">
          maxTime（時 / 分{{ enableSeconds ? ' / 秒' : '' }}）
        </span>
        <div class="flex items-center gap-1">
          <input
            v-model.number="maxHour"
            max="23"
            min="0"
            placeholder="hh"
            type="number"
            :class="
              cn(`
                h-9 w-14 rounded-md border border-text-30 bg-bg-90 px-2 text-center
                typo-content-medium text-text-70 outline-none
                focus:border-info-40
              `)
            "
          />
          <span class="text-text-60">:</span>
          <input
            v-model.number="maxMinute"
            max="59"
            min="0"
            placeholder="mm"
            type="number"
            :class="
              cn(`
                h-9 w-14 rounded-md border border-text-30 bg-bg-90 px-2 text-center
                typo-content-medium text-text-70 outline-none
                focus:border-info-40
              `)
            "
          />
          <template v-if="enableSeconds">
            <span class="text-text-60">:</span>
            <input
              v-model.number="maxSecond"
              max="59"
              min="0"
              placeholder="ss"
              type="number"
              :class="
                cn(`
                  h-9 w-14 rounded-md border border-text-30 bg-bg-90 px-2 text-center
                  typo-content-medium text-text-70 outline-none
                  focus:border-info-40
                `)
              "
            />
          </template>
        </div>
      </label>
    </div>
    <div class="border-t border-text-20 pt-4">
      <admin-date-picker
        v-model="value"
        :disabled="disabled"
        :enable-seconds="enableSeconds"
        :format="format"
        :is-error="isError"
        :locale="locale"
        :max-date="maxDate ?? undefined"
        :max-time="maxTime"
        :min-date="minDate ?? undefined"
        :min-time="minTime"
        :placeholder="placeholder"
        :readonly="readonly"
        :with-time="withTime"
      />
      <pre
        :class="
          cn(`
            mt-2 max-h-32 overflow-auto rounded-md bg-bg-70 px-3 py-2 typo-caption-small
            text-text-70
          `)
        "
      >
modelValue: {{ JSON.stringify(value) }}</pre>
    </div>
  </section>
</template>
```

### 區間

兩個 input 於單一外框內並列，共享一個 trigger 與 clear 按鈕；`modelValue` 為 `Date[]`，length 0/1/2 partial 中間態合法（第一次 click cell 之後對外可見）。啟用 `withTime` 後 calendar 下方渲染垂直堆疊之兩組時間 stepper（上 = `modelValue[0]`、下 = `modelValue[1]`），需 modelValue length === 2 才啟用 stepper。

```vue
<script setup lang="ts">
import { computed, ref } from 'vue'
import { cn } from '@/lib/utils'
import { AdminDatePicker, AdminDatePickerRange } from '@/registry/admin/ui/date-picker'

interface TimeModel {
  hours?: number
  minutes?: number
  seconds?: number
}

function toTimeModel(h: number | null, m: number | null, s: number | null): TimeModel | undefined {
  const norm = (v: unknown): number | null => {
    if (v == null || v === '' || (typeof v === 'number' && Number.isNaN(v))) {
      return null
    }
    return typeof v === 'number' ? v : Number(v)
  }
  const nh = norm(h)
  const nm = norm(m)
  const ns = norm(s)
  if (nh == null && nm == null && ns == null) {
    return undefined
  }
  const t: TimeModel = {}
  if (nh != null) {
    t.hours = nh
  }
  if (nm != null) {
    t.minutes = nm
  }
  if (ns != null) {
    t.seconds = ns
  }
  return t
}

function ensureTimeTokens(fmt: string, withTime: boolean, enableSeconds: boolean): string {
  if (!withTime) {
    return fmt
  }
  if (fmt.includes('H') || fmt.includes('h') || fmt.includes('m') || fmt.includes('s')) {
    return fmt
  }
  return enableSeconds ? `${fmt} HH:mm:ss` : `${fmt} HH:mm`
}

const FORMAT_PRESETS = [
  'yyyy/MM/dd',
  'dd/MM/yyyy',
  'yyyy-MM-dd',
  'yyyy/MM/dd HH:mm',
  'yyyy/MM/dd HH:mm:ss'
]
const LOCALES = ['zh-TW', 'en-US', 'ja-JP']

const formatPreset = ref('yyyy/MM/dd')
const formatCustom = ref('')
const withTime = ref(false)
const enableSeconds = ref(false)
const disabled = ref(false)
const readonly = ref(false)
const isError = ref(false)
const locale = ref('zh-TW')
const startPlaceholder = ref('開始日期')
const endPlaceholder = ref('結束日期')
const separator = ref(' - ')
const minDate = ref<Date | null>(null)
const maxDate = ref<Date | null>(null)
const minHour = ref<number | null>(null)
const minMinute = ref<number | null>(null)
const maxHour = ref<number | null>(null)
const maxMinute = ref<number | null>(null)
const value = ref<Date[]>([])

const format = computed(() =>
  ensureTimeTokens(
    formatCustom.value.trim() || formatPreset.value,
    withTime.value,
    enableSeconds.value
  )
)
const minTime = computed(() => toTimeModel(minHour.value, minMinute.value, null))
const maxTime = computed(() => toTimeModel(maxHour.value, maxMinute.value, null))
</script>

<template>
  <section class="w-full space-y-4 rounded-[8px] border border-text-20 bg-bg-90 p-6">
    <div class="grid grid-cols-2 gap-x-4 gap-y-3">
      <label class="flex flex-col gap-1 typo-content-medium text-text-70">
        <span class="typo-caption-small text-text-50">format（preset）</span>
        <select
          v-model="formatPreset"
          :class="
            cn(`
              h-9 rounded-md border border-text-30 bg-bg-90 px-2 typo-content-medium text-text-70
              outline-none
              focus:border-info-40
            `)
          "
        >
          <option v-for="opt in FORMAT_PRESETS" :key="opt" :value="opt">{{ opt }}</option>
        </select>
      </label>
      <label class="flex flex-col gap-1 typo-content-medium text-text-70">
        <span class="typo-caption-small text-text-50">format（自訂）</span>
        <input
          v-model="formatCustom"
          placeholder="留空使用 preset"
          type="text"
          :class="
            cn(`
              h-9 rounded-md border border-text-30 bg-bg-90 px-2 typo-content-medium text-text-70
              outline-none
              focus:border-info-40
            `)
          "
        />
      </label>
      <label class="flex flex-col gap-1 typo-content-medium text-text-70">
        <span class="typo-caption-small text-text-50">locale</span>
        <select
          v-model="locale"
          :class="
            cn(`
              h-9 rounded-md border border-text-30 bg-bg-90 px-2 typo-content-medium text-text-70
              outline-none
              focus:border-info-40
            `)
          "
        >
          <option v-for="opt in LOCALES" :key="opt" :value="opt">{{ opt }}</option>
        </select>
      </label>
      <label class="flex flex-col gap-1 typo-content-medium text-text-70">
        <span class="typo-caption-small text-text-50">separator</span>
        <input
          v-model="separator"
          type="text"
          :class="
            cn(`
              h-9 rounded-md border border-text-30 bg-bg-90 px-2 typo-content-medium text-text-70
              outline-none
              focus:border-info-40
            `)
          "
        />
      </label>
      <label class="flex flex-col gap-1 typo-content-medium text-text-70">
        <span class="typo-caption-small text-text-50">startPlaceholder</span>
        <input
          v-model="startPlaceholder"
          type="text"
          :class="
            cn(`
              h-9 rounded-md border border-text-30 bg-bg-90 px-2 typo-content-medium text-text-70
              outline-none
              focus:border-info-40
            `)
          "
        />
      </label>
      <label class="flex flex-col gap-1 typo-content-medium text-text-70">
        <span class="typo-caption-small text-text-50">endPlaceholder</span>
        <input
          v-model="endPlaceholder"
          type="text"
          :class="
            cn(`
              h-9 rounded-md border border-text-30 bg-bg-90 px-2 typo-content-medium text-text-70
              outline-none
              focus:border-info-40
            `)
          "
        />
      </label>
      <div class="flex flex-wrap items-center gap-3 typo-caption-small text-text-70">
        <label class="inline-flex items-center gap-1">
          <input v-model="withTime" type="checkbox" /> withTime
        </label>
        <label class="inline-flex items-center gap-1">
          <input v-model="enableSeconds" type="checkbox" :disabled="!withTime" />
          enableSeconds
        </label>
        <label class="inline-flex items-center gap-1">
          <input v-model="disabled" type="checkbox" /> disabled
        </label>
        <label class="inline-flex items-center gap-1">
          <input v-model="readonly" type="checkbox" /> readonly
        </label>
        <label class="inline-flex items-center gap-1">
          <input v-model="isError" type="checkbox" /> isError
        </label>
      </div>
      <div></div>
      <label class="flex flex-col gap-1 typo-content-medium text-text-70">
        <span class="typo-caption-small text-text-50">minDate</span>
        <admin-date-picker
          v-model="minDate"
          emit-as="date"
          format="yyyy/MM/dd"
          placeholder="無下限"
        />
      </label>
      <label class="flex flex-col gap-1 typo-content-medium text-text-70">
        <span class="typo-caption-small text-text-50">maxDate</span>
        <admin-date-picker
          v-model="maxDate"
          emit-as="date"
          format="yyyy/MM/dd"
          placeholder="無上限"
        />
      </label>
      <label v-if="withTime" class="flex flex-col gap-1 typo-content-medium text-text-70">
        <span class="typo-caption-small text-text-50">minTime（時 / 分）</span>
        <div class="flex items-center gap-1">
          <input
            v-model.number="minHour"
            max="23"
            min="0"
            placeholder="hh"
            type="number"
            :class="
              cn(`
                h-9 w-14 rounded-md border border-text-30 bg-bg-90 px-2 text-center
                typo-content-medium text-text-70 outline-none
                focus:border-info-40
              `)
            "
          />
          <span class="text-text-60">:</span>
          <input
            v-model.number="minMinute"
            max="59"
            min="0"
            placeholder="mm"
            type="number"
            :class="
              cn(`
                h-9 w-14 rounded-md border border-text-30 bg-bg-90 px-2 text-center
                typo-content-medium text-text-70 outline-none
                focus:border-info-40
              `)
            "
          />
        </div>
      </label>
      <label v-if="withTime" class="flex flex-col gap-1 typo-content-medium text-text-70">
        <span class="typo-caption-small text-text-50">maxTime（時 / 分）</span>
        <div class="flex items-center gap-1">
          <input
            v-model.number="maxHour"
            max="23"
            min="0"
            placeholder="hh"
            type="number"
            :class="
              cn(`
                h-9 w-14 rounded-md border border-text-30 bg-bg-90 px-2 text-center
                typo-content-medium text-text-70 outline-none
                focus:border-info-40
              `)
            "
          />
          <span class="text-text-60">:</span>
          <input
            v-model.number="maxMinute"
            max="59"
            min="0"
            placeholder="mm"
            type="number"
            :class="
              cn(`
                h-9 w-14 rounded-md border border-text-30 bg-bg-90 px-2 text-center
                typo-content-medium text-text-70 outline-none
                focus:border-info-40
              `)
            "
          />
        </div>
      </label>
    </div>
    <div class="border-t border-text-20 pt-4">
      <admin-date-picker-range
        v-model="value"
        emit-as="date"
        :disabled="disabled"
        :enable-seconds="enableSeconds"
        :end-placeholder="endPlaceholder"
        :format="format"
        :is-error="isError"
        :locale="locale"
        :max-date="maxDate ?? undefined"
        :max-time="maxTime"
        :min-date="minDate ?? undefined"
        :min-time="minTime"
        :readonly="readonly"
        :separator="separator"
        :start-placeholder="startPlaceholder"
        :with-time="withTime"
      />
      <pre
        :class="
          cn(`
            mt-2 max-h-32 overflow-auto rounded-md bg-bg-70 px-3 py-2 typo-caption-small
            text-text-70
          `)
        "
      >
modelValue (length {{ value.length }}): {{
          JSON.stringify(value.map((d) => d?.toString?.() ?? d))
        }}</pre>
    </div>
  </section>
</template>
```

### 錯誤狀態

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminDatePicker } from '@/registry/admin/ui/date-picker'

const value = ref<Date | null>(null)
</script>

<template>
  <div class="flex w-full max-w-sm flex-col gap-2">
    <admin-date-picker
      v-model="value"
      emit-as="date"
      format="yyyy/MM/dd"
      placeholder="選擇日期"
      is-error
    />
  </div>
</template>
```

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminDatePickerRange } from '@/registry/admin/ui/date-picker'

const value = ref<Date[]>([])
</script>

<template>
  <div class="flex w-full max-w-md flex-col gap-2">
    <admin-date-picker-range
      v-model="value"
      emit-as="date"
      end-placeholder="結束日期"
      format="yyyy/MM/dd"
      start-placeholder="開始日期"
      is-error
    />
  </div>
</template>
```

## API 參考

### 組成

```vue
<template>
  <!-- single -->
  <admin-date-picker v-model="value" format="yyyy/MM/dd" placeholder="選擇日期" />

  <!-- range -->
  <admin-date-picker-range
    v-model="range"
    end-placeholder="結束"
    format="yyyy/MM/dd"
    start-placeholder="開始"
  />
</template>
```

::alert{title="透傳上游 API" type="info"}
`AdminDatePicker` / `AdminDatePickerRange` 直接以 `@ark-ui/vue` 之 [DatePicker.Input](https://ark-ui.com/vue/docs/components/date-picker){rel=""nofollow""} / `DatePicker.Trigger` / `DatePicker.ClearTrigger` 為 input 元素；下列僅列出 admin 對外承諾之 prop / event / expose。
::

### admin-date-picker

::div{data-admin-api-table=""}
#### Props

| 名稱              | 型別                                        | 預設值                                 | 說明                                                                                                                                  |
| --------------- | ----------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `class`         | `unknown`                                 | —                                   | —                                                                                                                                   |
| `placeholder`   | `string | undefined`                      | `""`                                | 顯示於輸入框未填值時的提示文字                                                                                                                     |
| `disabled`      | `boolean | undefined`                     | `false`                             | 設為 \`true\` 時停用整個欄位，calendar trigger 無法開啟                                                                                           |
| `readonly`      | `boolean | undefined`                     | `false`                             | 設為 \`true\` 時禁止編輯文字但仍可開啟 calendar 檢視                                                                                                |
| `format`\*      | `string`                                  | —                                   | 設定顯示與輸入解析之 date-fns 格式（如 \`yyyy/MM/dd\` 或 \`yyyy/MM/dd HH\:mm\`）                                                                    |
| `emitAs`        | `TEmitAs | undefined`                     | `(() => "string") as () => TEmitAs` | 控制 \`update\:modelValue\` payload 之出口型別；\`'date'\` 回傳 \`Date\`、\`'string'\` 依 \`format\` 回傳字串、\`'timestamp'\` 回傳 epoch milliseconds |
| `withTime`      | `boolean | undefined`                     | `false`                             | 設為 \`true\` 時於 calendar 下方啟用時間選擇 stepper                                                                                            |
| `enableSeconds` | `boolean | undefined`                     | `false`                             | 設為 \`true\` 時於時間 stepper 加入秒欄                                                                                                       |
| `minDate`       | `Date | null | undefined`                 | —                                   | 限定可選日期下限                                                                                                                            |
| `maxDate`       | `Date | null | undefined`                 | —                                   | 限定可選日期上限                                                                                                                            |
| `minTime`       | `TimeModel | undefined`                   | —                                   | 限定可選時間下限                                                                                                                            |
| `maxTime`       | `TimeModel | undefined`                   | —                                   | 限定可選時間上限                                                                                                                            |
| `isError`       | `boolean | undefined`                     | `false`                             | 設為 \`true\` 時切換錯誤狀態樣式並設定 aria-invalid                                                                                               |
| `modelValue`    | `DatePickerModelValue`                    | —                                   | 透過 \`v-model\` 綁定當前選擇值                                                                                                              |
| `messages`      | `Partial<DatePickerMessages> | undefined` | —                                   | 覆寫元件內 a11y 字串；未提供之 key fallback 至預設字典                                                                                               |
| `locale`        | `string | undefined`                      | `"zh-TW"`                           | BCP-47 locale tag（如 \`'zh-TW'\`、\`'en-US'\`、\`'ja-JP'\`）                                                                            |
| `id`            | `string | undefined`                      | —                                   | 綁定至內部輸入元素之 \`id\`；純透傳，未提供時不自動生成                                                                                                     |
| `name`          | `string | undefined`                      | —                                   | 透傳至 ark \`DatePicker\` root 之 \`name\`，產生隱藏提交欄位供原生表單提交使用                                                                            |

*\\\* 代表必填*

#### Events

| 名稱                  | Payload                                     | 說明                                                                  |
| ------------------- | ------------------------------------------- | ------------------------------------------------------------------- |
| `blur`              | `FocusEvent`                                | 輸入框失焦且使用者真正離開元件時觸發（內部 focus 移動不觸發）                                  |
| `invalid`           | `{ reason: AdminDatePickerInvalidReason; }` | 解析失敗或超出 \`minDate\` / \`maxDate\` / \`minTime\` / \`maxTime\` 範圍時觸發 |
| `update:modelValue` | `DatePickerPayload<TEmitAs>`                | 選擇值變更時觸發，payload 型別依 \`emitAs\` 而定                                  |

#### Expose

| 名稱      | 簽名                                                                           | 說明                                              |
| ------- | ---------------------------------------------------------------------------- | ----------------------------------------------- |
| `open`  | `() => datePickerApi.value.setOpen(true)`                                    | 開啟 calendar popover                             |
| `close` | `() => datePickerApi.value.setOpen(false)`                                   | 關閉 calendar popover                             |
| `focus` | `() => {
rootRef.value?.querySelector<HTMLInputElement>('input')?.focus()
}` | 將焦點移至內部輸入框                                      |
| `blur`  | `() => {
rootRef.value?.querySelector<HTMLInputElement>('input')?.blur()
}`  | 將焦點移出內部輸入框                                      |
| `clear` | `() => datePickerApi.value.clearValue()`                                     | 清除目前選擇值並 emit \`update\:modelValue\` 為 \`null\` |
::

### admin-date-picker-range

::div{data-admin-api-table=""}
#### Props

| 名稱              | 型別                                           | 預設值                                 | 說明                                                                                                                                     |
| --------------- | -------------------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `class`         | `unknown`                                    | —                                   | —                                                                                                                                      |
| `placeholder`   | `string | undefined`                         | `""`                                | 輸入框未填值之提示文字                                                                                                                            |
| `separator`     | `string | undefined`                         | `" - "`                             | 顯示時兩端之分隔字元（預設 \`' - '\`）                                                                                                               |
| `disabled`      | `boolean | undefined`                        | `false`                             | 設為 \`true\` 時停用輸入框與 calendar trigger                                                                                                   |
| `readonly`      | `boolean | undefined`                        | `false`                             | 設為 \`true\` 時禁止操作（可開啟 calendar 但無法選取）                                                                                                  |
| `format`\*      | `string`                                     | —                                   | 設定顯示之 date-fns 格式（如 \`yyyy/MM/dd\` 或 \`yyyy/MM/dd HH\:mm\`）                                                                            |
| `emitAs`        | `TEmitAs | undefined`                        | `(() => "string") as () => TEmitAs` | 控制 \`update\:modelValue\` 各端 payload 之出口型別；\`'date'\` 回傳 \`Date\`、\`'string'\` 依 \`format\` 回傳字串、\`'timestamp'\` 回傳 epoch milliseconds |
| `withTime`      | `boolean | undefined`                        | `false`                             | 設為 \`true\` 時於 calendar 下方啟用兩組垂直堆疊之時間 stepper（位置即語意：上 = start、下 = end）                                                                 |
| `enableSeconds` | `boolean | undefined`                        | `false`                             | 設為 \`true\` 時於時間 stepper 加入秒欄                                                                                                          |
| `minDate`       | `Date | null | undefined`                    | —                                   | 限定可選日期下限                                                                                                                               |
| `maxDate`       | `Date | null | undefined`                    | —                                   | 限定可選日期上限                                                                                                                               |
| `minTime`       | `TimeModel | undefined`                      | —                                   | 限定可選時間下限                                                                                                                               |
| `maxTime`       | `TimeModel | undefined`                      | —                                   | 限定可選時間上限                                                                                                                               |
| `isError`       | `boolean | undefined`                        | `false`                             | 設為 \`true\` 時切換錯誤狀態樣式並設定 aria-invalid                                                                                                  |
| `modelValue`    | `DatePickerRangeModelValueInput | undefined` | —                                   | 透過 \`v-model\` 綁定當前選擇值；對外形狀為 \`Date\[]\`（length 由 ark 決定，0/1/2 partial 中間態合法）                                                          |
| `messages`      | `Partial<DatePickerMessages> | undefined`    | —                                   | 覆寫元件內 a11y 字串；未提供之 key fallback 至預設字典                                                                                                  |
| `locale`        | `string | undefined`                         | `"zh-TW"`                           | BCP-47 locale tag（如 \`'zh-TW'\`、\`'en-US'\`、\`'ja-JP'\`）                                                                               |

*\\\* 代表必填*

#### Events

| 名稱                  | Payload                                        | 說明                                                                                               |
| ------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `invalid`           | `{ reason: TimeInvalidReason; index: 0 | 1; }` | 解析失敗或超出時間範圍時觸發                                                                                   |
| `update:modelValue` | `DatePickerRangePayload<TEmitAs>`              | 選擇值變更時觸發，payload 為 \`Date\[]\` / \`string\[]\` / \`number\[]\`（依 \`emitAs\` narrow，length 0/1/2） |

#### Expose

| 名稱      | 簽名                                                                           | 說明                  |
| ------- | ---------------------------------------------------------------------------- | ------------------- |
| `open`  | `() => datePickerApi.value.setOpen(true)`                                    | 開啟 calendar popover |
| `close` | `() => datePickerApi.value.setOpen(false)`                                   | 關閉 calendar popover |
| `focus` | `() => {
rootRef.value?.querySelector<HTMLInputElement>('input')?.focus()
}` | 將焦點移至輸入框            |
| `blur`  | `() => {
rootRef.value?.querySelector<HTMLInputElement>('input')?.blur()
}`  | 將焦點移出輸入框            |
| `clear` | `() => datePickerApi.value.clearValue()`                                     | 清除 modelValue       |
::

## 更新紀錄

:admin-changelog{component="AdminDatePicker"}


# Dialog

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/dialog
```

```ts
import {
  AdminDialog,
  AdminDialogClose,
  AdminDialogContent,
  AdminDialogDescription,
  AdminDialogFooter,
  AdminDialogHeader,
  AdminDialogTitle,
  AdminDialogTrigger,
} from '@/components/admin/dialog'
```

## 用法

以 `v-model:open` 控制顯示狀態；header 與 footer 之間放主要內容，trigger 模式由 `admin-dialog-trigger` 啟動。

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminButton } from '@/registry/admin/ui/button'
import {
  AdminDialog,
  AdminDialogContent,
  AdminDialogDescription,
  AdminDialogFooter,
  AdminDialogHeader,
  AdminDialogTitle,
  AdminDialogTrigger
} from '@/registry/admin/ui/dialog'

const open = ref(false)
</script>

<template>
  <admin-dialog v-model:open="open">
    <admin-dialog-trigger as-child>
      <admin-button>Open dialog</admin-button>
    </admin-dialog-trigger>
    <admin-dialog-content>
      <admin-dialog-header>
        <admin-dialog-title>Confirm action</admin-dialog-title>
        <admin-dialog-description>This will save your changes.</admin-dialog-description>
      </admin-dialog-header>
      <admin-dialog-footer>
        <admin-button variant="outline" @click="open = false">Cancel</admin-button>
        <admin-button @click="open = false">Confirm</admin-button>
      </admin-dialog-footer>
    </admin-dialog-content>
  </admin-dialog>
</template>
```

## 場景

### 帶表單的對話框

搭配 vee-validate 的 `<Field>` 與 `useForm` 做欄位驗證，並以 admin-field 版型（`admin-field` / `admin-field-label` / `admin-field-content` / `admin-field-error`）排版；`<form>` 包住欄位與 footer，透過 `handleSubmit` 攔截提交並在驗證通過後手動關閉 `open`。

```vue
<script setup lang="ts">
import { useForm, Field as VeeField } from 'vee-validate'
import { ref } from 'vue'
import { AdminButton } from '@/registry/admin/ui/button'
import {
  AdminDialog,
  AdminDialogContent,
  AdminDialogDescription,
  AdminDialogFooter,
  AdminDialogHeader,
  AdminDialogTitle,
  AdminDialogTrigger
} from '@/registry/admin/ui/dialog'
import {
  AdminField,
  AdminFieldContent,
  AdminFieldError,
  AdminFieldLabel
} from '@/registry/admin/ui/field'
import { AdminInput } from '@/registry/admin/ui/input'

const open = ref(false)

const { handleSubmit, resetForm } = useForm<{
  name: string
  email: string
}>({
  initialValues: {
    name: '',
    email: ''
  }
})

function validateName(value: unknown) {
  if (typeof value !== 'string' || value.trim().length === 0) {
    return '請輸入名字。'
  }

  return true
}

function validateEmail(value: unknown) {
  if (typeof value !== 'string' || value.length === 0) {
    return '請輸入 Email。'
  }

  if (!value.includes('@') || !value.includes('.')) {
    return '請輸入有效的 Email 格式。'
  }

  return true
}

const onSubmit = handleSubmit(() => {
  open.value = false
})

function onCancel() {
  open.value = false
  resetForm()
}
</script>

<template>
  <admin-dialog v-model:open="open">
    <admin-dialog-trigger as-child>
      <admin-button>編輯個人資料</admin-button>
    </admin-dialog-trigger>
    <admin-dialog-content class="sm:max-w-md">
      <admin-dialog-header>
        <admin-dialog-title>個人資料</admin-dialog-title>
        <admin-dialog-description>更新您的名字與 email。</admin-dialog-description>
      </admin-dialog-header>
      <form class="flex flex-col gap-3 py-2" @submit="onSubmit">
        <vee-field v-slot="{ componentField, errorMessage }" name="name" :rules="validateName">
          <admin-field>
            <admin-field-label class="w-26 shrink-0 py-2.5">Name</admin-field-label>
            <admin-field-content class="min-h-full min-w-0">
              <admin-input
                placeholder="您的名字"
                v-bind="componentField"
                :is-error="!!errorMessage"
              />
              <admin-field-error :errors="errorMessage ? [errorMessage] : undefined" />
            </admin-field-content>
          </admin-field>
        </vee-field>
        <vee-field v-slot="{ componentField, errorMessage }" name="email" :rules="validateEmail">
          <admin-field>
            <admin-field-label class="w-26 shrink-0 py-2.5">Email</admin-field-label>
            <admin-field-content class="min-h-full min-w-0">
              <admin-input
                placeholder="you@example.com"
                type="email"
                v-bind="componentField"
                :is-error="!!errorMessage"
              />
              <admin-field-error :errors="errorMessage ? [errorMessage] : undefined" />
            </admin-field-content>
          </admin-field>
        </vee-field>
        <admin-dialog-footer>
          <admin-button type="button" variant="outline" @click="onCancel">取消</admin-button>
          <admin-button type="submit">儲存</admin-button>
        </admin-dialog-footer>
      </form>
    </admin-dialog-content>
  </admin-dialog>
</template>
```

### 可滾動內容

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminButton } from '@/registry/admin/ui/button'
import {
  AdminDialog,
  AdminDialogContent,
  AdminDialogDescription,
  AdminDialogFooter,
  AdminDialogHeader,
  AdminDialogTitle,
  AdminDialogTrigger
} from '@/registry/admin/ui/dialog'

const open = ref(false)
</script>

<template>
  <admin-dialog v-model:open="open">
    <admin-dialog-trigger as-child>
      <admin-button>查看服務條款</admin-button>
    </admin-dialog-trigger>
    <admin-dialog-content class="sm:max-w-lg">
      <admin-dialog-header>
        <admin-dialog-title>服務條款</admin-dialog-title>
        <admin-dialog-description>請閱讀以下條款後按同意。</admin-dialog-description>
      </admin-dialog-header>
      <div class="max-h-64 overflow-y-auto pr-2 typo-content-medium">
        <p v-for="i in 20" :key="i" class="mb-3">
          第 {{ i }} 條：本條文為範例文字，用以示範捲動式對話框。可以放長篇幅的法務內容或政策說明。
        </p>
      </div>
      <admin-dialog-footer>
        <admin-button variant="outline" @click="open = false">取消</admin-button>
        <admin-button @click="open = false">同意</admin-button>
      </admin-dialog-footer>
    </admin-dialog-content>
  </admin-dialog>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-dialog v-model:open="isOpen">
    <admin-dialog-trigger>開啟</admin-dialog-trigger>
    <admin-dialog-content>
      <admin-dialog-header>
        <admin-dialog-title>標題</admin-dialog-title>
        <admin-dialog-description>說明文字</admin-dialog-description>
      </admin-dialog-header>
      主要內容
      <admin-dialog-footer>
        <admin-dialog-close>取消</admin-dialog-close>
      </admin-dialog-footer>
    </admin-dialog-content>
  </admin-dialog>
</template>
```

### admin-dialog

::div{data-admin-api-table=""}
#### Props

| 名稱              | 型別                    | 預設值    | 說明                                                                                                                                                                                                                   |
| --------------- | --------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open`          | `boolean | undefined` | —      | The controlled open state of the dialog. Can be binded as \`v-model\:open\`.                                                                                                                                         |
| `defaultOpen`   | `boolean | undefined` | —      | The open state of the dialog when it is initially rendered. Use when you do not need to control its open state.                                                                                                      |
| `modal`         | `boolean | undefined` | —      | The modality of the dialog When set to \`true\`, \<br>interaction with outside elements will be disabled and only dialog content will be visible to screen readers.                                                  |
| `unmountOnHide` | `boolean | undefined` | `true` | When set to \`false\`, the dialog content will not be unmounted when closed, but instead hidden with CSS. \<br>Useful for SEO or when you want to improve performance by not remounting the component on every open. |
| `class`         | `unknown`             | —      | —                                                                                                                                                                                                                    |

#### Events

| 名稱            | Payload   | 說明 |
| ------------- | --------- | -- |
| `update:open` | `boolean` | —  |

#### Slots

| 名稱        | Bindings                                | 說明 |
| --------- | --------------------------------------- | -- |
| `default` | `{ open: boolean; close: () => void; }` | —  |
::

### admin-dialog-content

::div{data-admin-api-table=""}
#### Props

| 名稱                            | 型別                                         | 預設值     | 說明                                                                                                                                                                                                                                                                       |
| ----------------------------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `forceMount`                  | `boolean | undefined`                      | —       | Used to force mounting when more control is needed. Useful when\<br>controlling animation with Vue animation libraries.                                                                                                                                                  |
| `as`                          | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                                                                             |
| `asChild`                     | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details.                                                             |
| `disableOutsidePointerEvents` | `boolean | undefined`                      | —       | When \`true\`, hover/focus/click interactions will be disabled on elements outside\<br>the \`DismissableLayer\`. Users will need to click twice on outside elements to\<br>interact with them: once to close the \`DismissableLayer\`, and again to trigger the element. |
| `class`                       | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                                                                             |
| `showCloseButton`             | `boolean | undefined`                      | `true`  | 設為 \`false\` 時隱藏右上角關閉 X 按鈕；admin 預設內嵌 \`\<DialogClose>\` 與 \`IconX\`                                                                                                                                                                                                     |

#### Events

| 名稱                   | Payload                                       | 說明 |
| -------------------- | --------------------------------------------- | -- |
| `escapeKeyDown`      | `KeyboardEvent`                               | —  |
| `pointerDownOutside` | `PointerDownOutsideEvent`                     | —  |
| `focusOutside`       | `FocusOutsideEvent`                           | —  |
| `interactOutside`    | `PointerDownOutsideEvent | FocusOutsideEvent` | —  |
| `openAutoFocus`      | `Event`                                       | —  |
| `closeAutoFocus`     | `Event`                                       | —  |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-dialog-scroll-content

::div{data-admin-api-table=""}
#### Props

| 名稱                            | 型別                                         | 預設值     | 說明                                                                                                                                                                                                                                                                       |
| ----------------------------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `forceMount`                  | `boolean | undefined`                      | —       | Used to force mounting when more control is needed. Useful when\<br>controlling animation with Vue animation libraries.                                                                                                                                                  |
| `as`                          | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                                                                             |
| `asChild`                     | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details.                                                             |
| `disableOutsidePointerEvents` | `boolean | undefined`                      | —       | When \`true\`, hover/focus/click interactions will be disabled on elements outside\<br>the \`DismissableLayer\`. Users will need to click twice on outside elements to\<br>interact with them: once to close the \`DismissableLayer\`, and again to trigger the element. |
| `class`                       | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                                                                             |
| `showCloseButton`             | `boolean | undefined`                      | `true`  | 設為 \`false\` 時隱藏右上角關閉 X 按鈕；admin 預設內嵌 \`\<DialogClose>\` 與 \`IconX\`                                                                                                                                                                                                     |

#### Events

| 名稱                   | Payload                                       | 說明 |
| -------------------- | --------------------------------------------- | -- |
| `escapeKeyDown`      | `KeyboardEvent`                               | —  |
| `pointerDownOutside` | `PointerDownOutsideEvent`                     | —  |
| `focusOutside`       | `FocusOutsideEvent`                           | —  |
| `interactOutside`    | `PointerDownOutsideEvent | FocusOutsideEvent` | —  |
| `openAutoFocus`      | `Event`                                       | —  |
| `closeAutoFocus`     | `Event`                                       | —  |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-dialog-close

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `unknown`                                  | —       | —                                                                                                                                                                                                            |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-dialog-description

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-dialog-footer

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-dialog-header

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-dialog-overlay

::div{data-admin-api-table=""}
#### Props

| 名稱           | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| ------------ | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `forceMount` | `boolean | undefined`                      | —       | Used to force mounting when more control is needed. Useful when\<br>controlling animation with Vue animation libraries.                                                                                      |
| `asChild`    | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`         | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`      | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-dialog-title

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-dialog-trigger

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `unknown`                                  | —       | —                                                                                                                                                                                                            |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

## 更新紀錄

:admin-changelog{component="AdminDialog"}


# Divider

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/divider
```

```ts
import { AdminDivider } from '@/components/admin/divider'
```

## 用法

```vue
<script setup lang="ts">
import { AdminDivider } from '@/registry/admin/ui/divider'
</script>

<template>
  <div class="w-full max-w-xs">
    <p class="typo-content-medium">Above</p>
    <admin-divider />
    <p class="typo-content-medium">Below</p>
  </div>
</template>
```

## 場景

### 垂直分隔線

```vue
<script setup lang="ts">
import { AdminDivider } from '@/registry/admin/ui/divider'
</script>

<template>
  <div class="flex h-10 items-center gap-4">
    <span class="typo-content-medium">編輯</span>
    <admin-divider orientation="vertical" />
    <span class="typo-content-medium">複製</span>
    <admin-divider orientation="vertical" />
    <span class="typo-content-medium">刪除</span>
  </div>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-divider />
</template>
```

### admin-divider

::div{data-admin-api-table=""}
#### Props

| 名稱            | 型別                                         | 預設值            | 說明                                                                                                                                                                                                           |
| ------------- | ------------------------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `orientation` | `DataOrientation | undefined`              | `"horizontal"` | Orientation of the component.\<br>Either \`vertical\` or \`horizontal\`. Defaults to \`horizontal\`.                                                                                                         |
| `decorative`  | `boolean | undefined`                      | `true`         | Whether or not the component is purely decorative. \<br>When \`true\`, accessibility-related attributes\<br>are updated so that that the rendered element is removed from the accessibility tree.            |
| `asChild`     | `boolean | undefined`                      | —              | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`          | `globalThis.Component | AsTag | undefined` | `"div"`        | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`       | `ClassValue`                               | —              | 根元素之自訂 class                                                                                                                                                                                                 |
::

## 更新紀錄

:admin-changelog{component="AdminDivider"}


# Dropdown Menu

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/dropdown-menu
```

```ts
import {
  AdminDropdownMenu,
  AdminDropdownMenuCheckboxItem,
  AdminDropdownMenuContent,
  AdminDropdownMenuGroup,
  AdminDropdownMenuItem,
  AdminDropdownMenuLabel,
  AdminDropdownMenuRadioGroup,
  AdminDropdownMenuRadioItem,
  AdminDropdownMenuSeparator,
  AdminDropdownMenuShortcut,
  AdminDropdownMenuSub,
  AdminDropdownMenuSubContent,
  AdminDropdownMenuSubTrigger,
  AdminDropdownMenuTrigger,
} from '@/components/admin/dropdown-menu'
```

## 用法

點 trigger 顯示 content；items 由鍵盤 ArrowUp / ArrowDown 切換 highlight、Enter 觸發 select、Escape 關閉。

```vue
<script setup lang="ts">
import { AdminButton } from '@/registry/admin/ui/button'
import {
  AdminDropdownMenu,
  AdminDropdownMenuContent,
  AdminDropdownMenuItem,
  AdminDropdownMenuLabel,
  AdminDropdownMenuSeparator,
  AdminDropdownMenuTrigger
} from '@/registry/admin/ui/dropdown-menu'
</script>

<template>
  <admin-dropdown-menu>
    <admin-dropdown-menu-trigger as-child>
      <admin-button variant="outline">開啟選單</admin-button>
    </admin-dropdown-menu-trigger>
    <admin-dropdown-menu-content align="start">
      <admin-dropdown-menu-label>我的帳號</admin-dropdown-menu-label>
      <admin-dropdown-menu-separator />
      <admin-dropdown-menu-item>個人資料</admin-dropdown-menu-item>
      <admin-dropdown-menu-item>帳號設定</admin-dropdown-menu-item>
      <admin-dropdown-menu-item disabled>付費方案(停用)</admin-dropdown-menu-item>
      <admin-dropdown-menu-separator />
      <admin-dropdown-menu-item>登出</admin-dropdown-menu-item>
    </admin-dropdown-menu-content>
  </admin-dropdown-menu>
</template>
```

## 場景

### 操作選單

行內 action menu，含 disabled item 與 separator 分組；常用於列表 row 右側「⋯」按鈕。

```vue
<script setup lang="ts">
import { AdminButton } from '@/registry/admin/ui/button'
import {
  AdminDropdownMenu,
  AdminDropdownMenuContent,
  AdminDropdownMenuItem,
  AdminDropdownMenuSeparator,
  AdminDropdownMenuTrigger
} from '@/registry/admin/ui/dropdown-menu'

function onAction(name: string) {
  // eslint-disable-next-line no-console
  console.log('action:', name)
}
</script>

<template>
  <admin-dropdown-menu>
    <admin-dropdown-menu-trigger as-child>
      <admin-button aria-label="更多操作" size="small" variant="ghost">⋯</admin-button>
    </admin-dropdown-menu-trigger>
    <admin-dropdown-menu-content align="end">
      <admin-dropdown-menu-item @select="onAction('edit')">編輯</admin-dropdown-menu-item>
      <admin-dropdown-menu-item @select="onAction('duplicate')">複製</admin-dropdown-menu-item>
      <admin-dropdown-menu-item @select="onAction('move')">移動到...</admin-dropdown-menu-item>
      <admin-dropdown-menu-separator />
      <admin-dropdown-menu-item disabled>歸檔(停用)</admin-dropdown-menu-item>
      <admin-dropdown-menu-separator />
      <admin-dropdown-menu-item @select="onAction('delete')">刪除</admin-dropdown-menu-item>
    </admin-dropdown-menu-content>
  </admin-dropdown-menu>
</template>
```

### 進階選單

checkbox item（多選）、radio group（單選）、巢狀 sub-menu、快捷鍵提示。

```vue
<script setup lang="ts">
import type { AcceptableValue } from 'reka-ui'
import { ref } from 'vue'
import { AdminButton } from '@/registry/admin/ui/button'
import {
  AdminDropdownMenu,
  AdminDropdownMenuCheckboxItem,
  AdminDropdownMenuContent,
  AdminDropdownMenuGroup,
  AdminDropdownMenuItem,
  AdminDropdownMenuLabel,
  AdminDropdownMenuRadioGroup,
  AdminDropdownMenuRadioItem,
  AdminDropdownMenuSeparator,
  AdminDropdownMenuShortcut,
  AdminDropdownMenuSub,
  AdminDropdownMenuSubContent,
  AdminDropdownMenuSubTrigger,
  AdminDropdownMenuTrigger
} from '@/registry/admin/ui/dropdown-menu'

const showStatusBar = ref(true)
const showActivityBar = ref(false)
const position = ref<AcceptableValue>('bottom')
</script>

<template>
  <admin-dropdown-menu>
    <admin-dropdown-menu-trigger as-child>
      <admin-button variant="outline">檢視選項</admin-button>
    </admin-dropdown-menu-trigger>
    <admin-dropdown-menu-content align="start" class="w-56">
      <admin-dropdown-menu-label>外觀</admin-dropdown-menu-label>
      <admin-dropdown-menu-separator />
      <admin-dropdown-menu-checkbox-item v-model="showStatusBar">
        狀態列
      </admin-dropdown-menu-checkbox-item>
      <admin-dropdown-menu-checkbox-item v-model="showActivityBar">
        活動列
      </admin-dropdown-menu-checkbox-item>
      <admin-dropdown-menu-separator />
      <admin-dropdown-menu-label>面板位置</admin-dropdown-menu-label>
      <admin-dropdown-menu-radio-group v-model="position">
        <admin-dropdown-menu-radio-item value="top">上方</admin-dropdown-menu-radio-item>
        <admin-dropdown-menu-radio-item value="bottom">下方</admin-dropdown-menu-radio-item>
        <admin-dropdown-menu-radio-item value="right">右側</admin-dropdown-menu-radio-item>
      </admin-dropdown-menu-radio-group>
      <admin-dropdown-menu-separator />
      <admin-dropdown-menu-group>
        <admin-dropdown-menu-item>
          新增檔案
          <admin-dropdown-menu-shortcut>⌘N</admin-dropdown-menu-shortcut>
        </admin-dropdown-menu-item>
        <admin-dropdown-menu-sub>
          <admin-dropdown-menu-sub-trigger>更多工具</admin-dropdown-menu-sub-trigger>
          <admin-dropdown-menu-sub-content>
            <admin-dropdown-menu-item>移動到…</admin-dropdown-menu-item>
            <admin-dropdown-menu-item>複製連結</admin-dropdown-menu-item>
            <admin-dropdown-menu-separator />
            <admin-dropdown-menu-sub>
              <admin-dropdown-menu-sub-trigger>匯出為</admin-dropdown-menu-sub-trigger>
              <admin-dropdown-menu-sub-content>
                <admin-dropdown-menu-item>PDF</admin-dropdown-menu-item>
                <admin-dropdown-menu-item>PNG</admin-dropdown-menu-item>
              </admin-dropdown-menu-sub-content>
            </admin-dropdown-menu-sub>
          </admin-dropdown-menu-sub-content>
        </admin-dropdown-menu-sub>
      </admin-dropdown-menu-group>
    </admin-dropdown-menu-content>
  </admin-dropdown-menu>
</template>
```

### 鍵盤導航

| 快捷鍵                     | 行為                                            |
| ----------------------- | --------------------------------------------- |
| `ArrowDown` / `ArrowUp` | 移動 highlight 到下一個 / 上一個 item                  |
| `Enter` / `Space`       | 觸發 highlighted item 的 `select` event 並關閉 menu |
| `Escape`                | 關閉 menu，focus 回 trigger                       |
| `Tab`                   | 關閉 menu，focus 移到下一個 tabbable 元素               |
| `Home` / `End`          | 跳到第一個 / 最後一個 item                             |
| `ArrowRight`            | 在 sub-trigger 上展開子選單並 focus 第一個 item（RTL 相反）  |
| `ArrowLeft`             | 收合子選單，focus 回 sub-trigger（RTL 相反）             |
| 任意可印字元                  | type-ahead 跳到 `textValue` 開頭符合的 item          |

行為由 reka-ui `DropdownMenu` primitive 提供，本元件薄包一層樣式。

### 與其他元件的差別

| 元件                      | 適用情境                                                                     |
| ----------------------- | ------------------------------------------------------------------------ |
| **admin-dropdown-menu** | 觸發後彈出的「**選項列表**」，含鍵盤導航；典型用例：navigation menu、action menu、heading dropdown |
| `admin-popover`         | 任意 **內容浮層**（不限選項列表）；沒有 roving tabindex / arrow key 導航                    |
| `admin-select`          | 表單欄位用的 **單選**，會把選定值寫回 `<input>`                                          |

## API 參考

### 組成

```vue
<template>
  <admin-dropdown-menu>
    <admin-dropdown-menu-trigger>開啟選單</admin-dropdown-menu-trigger>
    <admin-dropdown-menu-content>
      <admin-dropdown-menu-label>群組標題</admin-dropdown-menu-label>
      <admin-dropdown-menu-separator />
      <admin-dropdown-menu-item>
        選項一
        <admin-dropdown-menu-shortcut>⌘K</admin-dropdown-menu-shortcut>
      </admin-dropdown-menu-item>
      <admin-dropdown-menu-checkbox-item v-model="checked">可勾選項</admin-dropdown-menu-checkbox-item>
      <admin-dropdown-menu-radio-group v-model="value">
        <admin-dropdown-menu-radio-item value="a">單選 A</admin-dropdown-menu-radio-item>
        <admin-dropdown-menu-radio-item value="b">單選 B</admin-dropdown-menu-radio-item>
      </admin-dropdown-menu-radio-group>
      <admin-dropdown-menu-sub>
        <admin-dropdown-menu-sub-trigger>更多</admin-dropdown-menu-sub-trigger>
        <admin-dropdown-menu-sub-content>
          <admin-dropdown-menu-item>子選項</admin-dropdown-menu-item>
        </admin-dropdown-menu-sub-content>
      </admin-dropdown-menu-sub>
    </admin-dropdown-menu-content>
  </admin-dropdown-menu>
</template>
```

### admin-dropdown-menu

::div{data-admin-api-table=""}
#### Props

| 名稱            | 型別                        | 預設值 | 說明                                                                                                                                                                       |
| ------------- | ------------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `defaultOpen` | `boolean | undefined`     | —   | The open state of the dropdown menu when it is initially rendered. Use when you do not need to control its open state.                                                   |
| `open`        | `boolean | undefined`     | —   | The controlled open state of the menu. Can be used as \`v-model\:open\`.                                                                                                 |
| `dir`         | `Direction$4 | undefined` | —   | The reading direction of the combobox when applicable.\<br>If omitted, inherits globally from \`ConfigProvider\` or assumes LTR (left-to-right) reading mode.            |
| `modal`       | `boolean | undefined`     | —   | The modality of the dropdown menu.\<br>When set to \`true\`, interaction with outside elements will be disabled and only menu content will be visible to screen readers. |
| `class`       | `unknown`                 | —   | —                                                                                                                                                                        |

#### Events

| 名稱            | Payload   | 說明 |
| ------------- | --------- | -- |
| `update:open` | `boolean` | —  |

#### Slots

| 名稱        | Bindings             | 說明 |
| --------- | -------------------- | -- |
| `default` | `{ open: boolean; }` | —  |
::

### admin-dropdown-menu-trigger

::div{data-admin-api-table=""}
#### Props

| 名稱         | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| ---------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `disabled` | `boolean | undefined`                      | —       | When \`true\`, prevents the user from interacting with item                                                                                                                                                  |
| `asChild`  | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`       | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`    | `ClassValue`                               | —       | —                                                                                                                                                                                                            |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-dropdown-menu-content

::div{data-admin-api-table=""}
#### Props

| 名稱                           | 型別                                                                                  | 預設值           | 說明                                                                                                                                                                                                                                  |
| ---------------------------- | ----------------------------------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `forceMount`                 | `boolean | undefined`                                                               | —             | Used to force mounting when more control is needed. Useful when\<br>controlling animation with Vue animation libraries.                                                                                                             |
| `as`                         | `globalThis.Component | AsTag | undefined`                                          | `"div"`       | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                                        |
| `asChild`                    | `boolean | undefined`                                                               | —             | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details.                        |
| `loop`                       | `boolean | undefined`                                                               | `false`       | When \`true\`, keyboard navigation will loop from last item to first, and vice versa.                                                                                                                                               |
| `align`                      | `"start" | "end" | "center" | undefined`                                            | `"center"`    | The preferred alignment against the trigger.\<br>May change when collisions occur.                                                                                                                                                  |
| `sideOffset`                 | `number | undefined`                                                                | `4`           | The distance in pixels from the trigger.                                                                                                                                                                                            |
| `memoDependencies`           | `unknown[] | undefined`                                                             | —             | Reactive dependencies that should invalidate the memoized content subtree.                                                                                                                                                          |
| `side`                       | `"top" | "right" | "bottom" | "left" | undefined`                                   | `"bottom"`    | The preferred side of the trigger to render against when open.\<br>Will be reversed when collisions occur and avoidCollisions\<br>is enabled.                                                                                       |
| `sideFlip`                   | `boolean | undefined`                                                               | `true`        | Flip to the opposite side when colliding with boundary.                                                                                                                                                                             |
| `alignOffset`                | `number | undefined`                                                                | `0`           | An offset in pixels from the \`start\` or \`end\` alignment options.                                                                                                                                                                |
| `alignFlip`                  | `boolean | undefined`                                                               | `true`        | Flip alignment when colliding with boundary.\<br>May only occur when \`prioritizePosition\` is true.                                                                                                                                |
| `avoidCollisions`            | `boolean | undefined`                                                               | `true`        | When \`true\`, overrides the side and align preferences\<br>to prevent collisions with boundary edges.                                                                                                                              |
| `collisionBoundary`          | `Element | (Element | null)[] | null | undefined`                                   | `[]`          | The element used as the collision boundary. By default\<br>this is the viewport, though you can provide additional\<br>element(s) to be included in this check.                                                                     |
| `collisionPadding`           | `number | Partial<Record<"top" | "right" | "bottom" | "left", number>> | undefined` | `0`           | The distance in pixels from the boundary edges where collision\<br>detection should occur. Accepts a number (same for all sides),\<br>or a partial padding object, for example: { top: 20, left: 20 }.                              |
| `arrowPadding`               | `number | undefined`                                                                | `0`           | The padding between the arrow and the edges of the content.\<br>If your content has border-radius, this will prevent it from\<br>overflowing the corners.                                                                           |
| `hideShiftedArrow`           | `boolean | undefined`                                                               | `true`        | When \`true\`, hides the arrow when it cannot be centered\<br>to the reference element.                                                                                                                                             |
| `sticky`                     | `"partial" | "always" | undefined`                                                  | `"partial"`   | The sticky behavior on the align axis. \`partial\` will keep the\<br>content in the boundary as long as the trigger is at least partially\<br>in the boundary whilst "always" will keep the content in the boundary\<br>regardless. |
| `hideWhenDetached`           | `boolean | undefined`                                                               | `false`       | Whether to hide the content when the trigger becomes fully occluded.                                                                                                                                                                |
| `positionStrategy`           | `"fixed" | "absolute" | undefined`                                                  | —             | The type of CSS position property to use.                                                                                                                                                                                           |
| `updatePositionStrategy`     | `"always" | "optimized" | undefined`                                                | `'optimized'` | Strategy to update the position of the floating element on every animation frame.                                                                                                                                                   |
| `disableUpdateOnLayoutShift` | `boolean | undefined`                                                               | `false`       | Whether to disable the update position for the content when the layout shifted.                                                                                                                                                     |
| `prioritizePosition`         | `boolean | undefined`                                                               | `false`       | Force content to be position within the viewport.\<br>Might overlap the reference element, which may not be desired.                                                                                                                |
| `reference`                  | `ReferenceElement | undefined`                                                      | —             | The custom element or virtual element that will be set as the reference\<br>to position the floating element.\<br>If provided, it will replace the default anchor element.                                                          |
| `class`                      | `ClassValue`                                                                        | —             | —                                                                                                                                                                                                                                   |
| `to`                         | `string | HTMLElement | undefined`                                                  | —             | —                                                                                                                                                                                                                                   |

#### Events

| 名稱                   | Payload                                       | 說明 |
| -------------------- | --------------------------------------------- | -- |
| `escapeKeyDown`      | `KeyboardEvent`                               | —  |
| `pointerDownOutside` | `PointerDownOutsideEvent`                     | —  |
| `focusOutside`       | `FocusOutsideEvent`                           | —  |
| `interactOutside`    | `PointerDownOutsideEvent | FocusOutsideEvent` | —  |
| `closeAutoFocus`     | `Event`                                       | —  |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-dropdown-menu-item

::div{data-admin-api-table=""}
#### Props

| 名稱          | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| ----------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `disabled`  | `boolean | undefined`                      | —       | When \`true\`, prevents the user from interacting with the item.                                                                                                                                             |
| `textValue` | `string | undefined`                       | —       | Optional text used for typeahead purposes. By default the typeahead behavior will use the \`.textContent\` of the item. \<br> Use this when the content is complex, or you have non-textual content inside.  |
| `asChild`   | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`        | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`     | `ClassValue`                               | —       | —                                                                                                                                                                                                            |
| `inset`     | `boolean | undefined`                      | `false` | —                                                                                                                                                                                                            |

#### Events

| 名稱       | Payload | 說明 |
| -------- | ------- | -- |
| `select` | `Event` | —  |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-dropdown-menu-separator

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | —                                                                                                                                                                                                            |
::

### admin-dropdown-menu-label

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | —                                                                                                                                                                                                            |
| `inset`   | `boolean | undefined`                      | `false` | —                                                                                                                                                                                                            |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-dropdown-menu-group

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `unknown`                                  | —       | —                                                                                                                                                                                                            |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-dropdown-menu-checkbox-item

::div{data-admin-api-table=""}
#### Props

| 名稱           | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| ------------ | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `modelValue` | `CheckedState | undefined`                 | —       | The controlled checked state of the item. Can be used as \`v-model\`.                                                                                                                                        |
| `disabled`   | `boolean | undefined`                      | —       | When \`true\`, prevents the user from interacting with the item.                                                                                                                                             |
| `textValue`  | `string | undefined`                       | —       | Optional text used for typeahead purposes. By default the typeahead behavior will use the \`.textContent\` of the item. \<br> Use this when the content is complex, or you have non-textual content inside.  |
| `asChild`    | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`         | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`      | `ClassValue`                               | —       | —                                                                                                                                                                                                            |

#### Events

| 名稱                  | Payload   | 說明 |
| ------------------- | --------- | -- |
| `select`            | `Event`   | —  |
| `update:modelValue` | `boolean` | —  |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-dropdown-menu-radio-group

::div{data-admin-api-table=""}
#### Props

| 名稱           | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| ------------ | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `modelValue` | `AcceptableValue | undefined`              | —       | The value of the selected item in the group.                                                                                                                                                                 |
| `asChild`    | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`         | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`      | `ClassValue`                               | —       | —                                                                                                                                                                                                            |

#### Events

| 名稱                  | Payload           | 說明 |
| ------------------- | ----------------- | -- |
| `update:modelValue` | `AcceptableValue` | —  |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-dropdown-menu-radio-item

::div{data-admin-api-table=""}
#### Props

| 名稱          | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| ----------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `value`\*   | `AcceptableValue`                          | —       | The unique value of the item.                                                                                                                                                                                |
| `disabled`  | `boolean | undefined`                      | —       | When \`true\`, prevents the user from interacting with the item.                                                                                                                                             |
| `textValue` | `string | undefined`                       | —       | Optional text used for typeahead purposes. By default the typeahead behavior will use the \`.textContent\` of the item. \<br> Use this when the content is complex, or you have non-textual content inside.  |
| `asChild`   | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`        | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`     | `ClassValue`                               | —       | —                                                                                                                                                                                                            |

*\\\* 代表必填*

#### Events

| 名稱       | Payload | 說明 |
| -------- | ------- | -- |
| `select` | `Event` | —  |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-dropdown-menu-sub

::div{data-admin-api-table=""}
#### Props

| 名稱            | 型別                    | 預設值 | 說明                                                                                                                     |
| ------------- | --------------------- | --- | ---------------------------------------------------------------------------------------------------------------------- |
| `defaultOpen` | `boolean | undefined` | —   | The open state of the dropdown menu when it is initially rendered. Use when you do not need to control its open state. |
| `open`        | `boolean | undefined` | —   | The controlled open state of the menu. Can be used as \`v-model\:open\`.                                               |
| `class`       | `unknown`             | —   | —                                                                                                                      |

#### Events

| 名稱            | Payload   | 說明 |
| ------------- | --------- | -- |
| `update:open` | `boolean` | —  |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-dropdown-menu-sub-trigger

::div{data-admin-api-table=""}
#### Props

| 名稱          | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| ----------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `disabled`  | `boolean | undefined`                      | —       | When \`true\`, prevents the user from interacting with the item.                                                                                                                                             |
| `textValue` | `string | undefined`                       | —       | Optional text used for typeahead purposes. By default the typeahead behavior will use the \`.textContent\` of the item. \<br> Use this when the content is complex, or you have non-textual content inside.  |
| `asChild`   | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`        | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`     | `ClassValue`                               | —       | —                                                                                                                                                                                                            |
| `inset`     | `boolean | undefined`                      | `false` | —                                                                                                                                                                                                            |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-dropdown-menu-sub-content

::div{data-admin-api-table=""}
#### Props

| 名稱                           | 型別                                                                                  | 預設值           | 說明                                                                                                                                                                                                                                  |
| ---------------------------- | ----------------------------------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `forceMount`                 | `boolean | undefined`                                                               | —             | Used to force mounting when more control is needed. Useful when\<br>controlling animation with Vue animation libraries.                                                                                                             |
| `as`                         | `globalThis.Component | AsTag | undefined`                                          | `"div"`       | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                                        |
| `asChild`                    | `boolean | undefined`                                                               | —             | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details.                        |
| `loop`                       | `boolean | undefined`                                                               | `false`       | When \`true\`, keyboard navigation will loop from last item to first, and vice versa.                                                                                                                                               |
| `sideOffset`                 | `number | undefined`                                                                | `0`           | The distance in pixels from the trigger.                                                                                                                                                                                            |
| `memoDependencies`           | `unknown[] | undefined`                                                             | —             | Reactive dependencies that should invalidate the memoized content subtree.                                                                                                                                                          |
| `sideFlip`                   | `boolean | undefined`                                                               | `true`        | Flip to the opposite side when colliding with boundary.                                                                                                                                                                             |
| `alignOffset`                | `number | undefined`                                                                | `0`           | An offset in pixels from the \`start\` or \`end\` alignment options.                                                                                                                                                                |
| `alignFlip`                  | `boolean | undefined`                                                               | `true`        | Flip alignment when colliding with boundary.\<br>May only occur when \`prioritizePosition\` is true.                                                                                                                                |
| `avoidCollisions`            | `boolean | undefined`                                                               | `true`        | When \`true\`, overrides the side and align preferences\<br>to prevent collisions with boundary edges.                                                                                                                              |
| `collisionBoundary`          | `Element | (Element | null)[] | null | undefined`                                   | `[]`          | The element used as the collision boundary. By default\<br>this is the viewport, though you can provide additional\<br>element(s) to be included in this check.                                                                     |
| `collisionPadding`           | `number | Partial<Record<"top" | "right" | "bottom" | "left", number>> | undefined` | `0`           | The distance in pixels from the boundary edges where collision\<br>detection should occur. Accepts a number (same for all sides),\<br>or a partial padding object, for example: { top: 20, left: 20 }.                              |
| `arrowPadding`               | `number | undefined`                                                                | `0`           | The padding between the arrow and the edges of the content.\<br>If your content has border-radius, this will prevent it from\<br>overflowing the corners.                                                                           |
| `hideShiftedArrow`           | `boolean | undefined`                                                               | `true`        | When \`true\`, hides the arrow when it cannot be centered\<br>to the reference element.                                                                                                                                             |
| `sticky`                     | `"partial" | "always" | undefined`                                                  | `"partial"`   | The sticky behavior on the align axis. \`partial\` will keep the\<br>content in the boundary as long as the trigger is at least partially\<br>in the boundary whilst "always" will keep the content in the boundary\<br>regardless. |
| `hideWhenDetached`           | `boolean | undefined`                                                               | `false`       | Whether to hide the content when the trigger becomes fully occluded.                                                                                                                                                                |
| `positionStrategy`           | `"fixed" | "absolute" | undefined`                                                  | —             | The type of CSS position property to use.                                                                                                                                                                                           |
| `updatePositionStrategy`     | `"always" | "optimized" | undefined`                                                | `'optimized'` | Strategy to update the position of the floating element on every animation frame.                                                                                                                                                   |
| `disableUpdateOnLayoutShift` | `boolean | undefined`                                                               | `false`       | Whether to disable the update position for the content when the layout shifted.                                                                                                                                                     |
| `prioritizePosition`         | `boolean | undefined`                                                               | `false`       | Force content to be position within the viewport.\<br>Might overlap the reference element, which may not be desired.                                                                                                                |
| `reference`                  | `ReferenceElement | undefined`                                                      | —             | The custom element or virtual element that will be set as the reference\<br>to position the floating element.\<br>If provided, it will replace the default anchor element.                                                          |
| `class`                      | `ClassValue`                                                                        | —             | —                                                                                                                                                                                                                                   |

#### Events

| 名稱                   | Payload                                       | 說明 |
| -------------------- | --------------------------------------------- | -- |
| `escapeKeyDown`      | `KeyboardEvent`                               | —  |
| `pointerDownOutside` | `PointerDownOutsideEvent`                     | —  |
| `focusOutside`       | `FocusOutsideEvent`                           | —  |
| `interactOutside`    | `PointerDownOutsideEvent | FocusOutsideEvent` | —  |
| `openAutoFocus`      | `Event`                                       | —  |
| `closeAutoFocus`     | `Event`                                       | —  |
| `entryFocus`         | `Event`                                       | —  |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-dropdown-menu-shortcut

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明 |
| ------- | ------------ | --- | -- |
| `class` | `ClassValue` | —   | —  |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

## 更新紀錄

:admin-changelog{component="AdminDropdownMenu"}


# Field

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/field
```

```ts
import {
  AdminField,
  AdminFieldContent,
  AdminFieldDescription,
  AdminFieldDivider,
  AdminFieldError,
  AdminFieldGroup,
  AdminFieldLabel,
  AdminFieldLegend,
  AdminFieldSet,
  AdminFieldTitle,
} from '@/components/admin/field'
```

## 用法

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminCheckbox } from '@/registry/admin/ui/checkbox'
import {
  AdminField,
  AdminFieldContent,
  AdminFieldDescription,
  AdminFieldDivider,
  AdminFieldError,
  AdminFieldGroup,
  AdminFieldLabel,
  AdminFieldLegend,
  AdminFieldSet,
  AdminFieldTitle
} from '@/registry/admin/ui/field'
import { AdminInput } from '@/registry/admin/ui/input'
import { AdminSwitch } from '@/registry/admin/ui/switch'
import { AdminTextarea } from '@/registry/admin/ui/textarea'

const name = ref<string | number>('王小明')
const email = ref<string | number>('invalid-email')
const bio = ref('')
const newsletter = ref(true)
const marketing = ref(false)
</script>

<template>
  <admin-field-set class="w-full max-w-md">
    <admin-field-legend>個人資料</admin-field-legend>
    <admin-field-group>
      <admin-field orientation="vertical">
        <admin-field-label>姓名</admin-field-label>
        <admin-input v-model="name" placeholder="王小明" />
        <admin-field-description>顯示在個人檔案上的名字。</admin-field-description>
      </admin-field>

      <admin-field orientation="vertical">
        <admin-field-label>Email</admin-field-label>
        <admin-input v-model="email" placeholder="you@example.com" type="email" is-error />
        <admin-field-description>我們不會公開你的 email。</admin-field-description>
        <admin-field-error>請輸入有效的 email 格式。</admin-field-error>
      </admin-field>

      <admin-field orientation="vertical">
        <admin-field-label>自我介紹</admin-field-label>
        <admin-textarea v-model="bio" placeholder="介紹一下你自己…" rows="3" />
        <admin-field-description>100 字以內的簡短說明。</admin-field-description>
      </admin-field>

      <admin-field-divider />

      <admin-field-title>通知偏好</admin-field-title>

      <admin-field orientation="horizontal">
        <admin-field-content>
          <admin-field-label>每週電子報</admin-field-label>
          <admin-field-description>每週一寄送產品更新與技術文章。</admin-field-description>
        </admin-field-content>
        <admin-switch v-model="newsletter" />
      </admin-field>

      <admin-field orientation="horizontal">
        <admin-field-content>
          <admin-field-label>行銷活動通知</admin-field-label>
          <admin-field-description>收到限時優惠與活動邀請。</admin-field-description>
        </admin-field-content>
        <admin-checkbox v-model="marketing" />
      </admin-field>
    </admin-field-group>
  </admin-field-set>
</template>
```

## 場景

### 錯誤訊息

```vue
<script setup lang="ts">
import { AdminField, AdminFieldError, AdminFieldLabel } from '@/registry/admin/ui/field'
import { AdminInput } from '@/registry/admin/ui/input'
</script>

<template>
  <admin-field class="w-72" orientation="vertical">
    <admin-field-label>Email</admin-field-label>
    <admin-input placeholder="you@example.com" is-error />
    <admin-field-error>請輸入有效的 email。</admin-field-error>
  </admin-field>
</template>
```

### 水平 Orientation

```vue
<script setup lang="ts">
import { AdminField, AdminFieldDescription, AdminFieldLabel } from '@/registry/admin/ui/field'
import { AdminInput } from '@/registry/admin/ui/input'
</script>

<template>
  <admin-field class="w-120" orientation="horizontal">
    <admin-field-label>顯示名稱</admin-field-label>
    <admin-input class="w-56" placeholder="暱稱" />
    <admin-field-description>在留言區會顯示這個名字。</admin-field-description>
  </admin-field>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-field-set>
    <admin-field-legend>個人資料</admin-field-legend>
    <admin-field-group>
      <admin-field orientation="vertical">
        <admin-field-label>姓名</admin-field-label>
        <admin-input v-model="name" />
        <admin-field-description>顯示在個人檔案上的名字。</admin-field-description>
      </admin-field>

      <admin-field orientation="vertical">
        <admin-field-label>Email</admin-field-label>
        <admin-input v-model="email" is-error />
        <admin-field-description>我們不會公開你的 email。</admin-field-description>
        <admin-field-error v-if="error">{{ error }}</admin-field-error>
      </admin-field>

      <admin-field-divider />
      <admin-field-title>通知偏好</admin-field-title>

      <admin-field orientation="horizontal">
        <admin-field-content>
          <admin-field-label>每週電子報</admin-field-label>
          <admin-field-description>每週一寄送最新消息。</admin-field-description>
        </admin-field-content>
        <admin-switch v-model="newsletter" />
      </admin-field>
    </admin-field-group>
  </admin-field-set>
</template>
```

| 元件                        | 角色                                                           |
| ------------------------- | ------------------------------------------------------------ |
| `admin-field-set`         | 表單區塊外層，對應 HTML `<fieldset>`，可巢狀使用                            |
| `admin-field-legend`      | 區塊標題，對應 `<legend>`，視覺上為主標題                                   |
| `admin-field-group`       | 欄位群組容器，統一欄位間距與 `@container/field-group` 響應式斷點                |
| `admin-field`             | 單一欄位容器，控制 label / 輸入欄 / 描述 / 錯誤的排版與 `orientation`            |
| `admin-field-label`       | 欄位 label                                                     |
| `admin-field-description` | 欄位輔助說明                                                       |
| `admin-field-error`       | 驗證錯誤訊息，搭配輸入欄位的 `is-error` 樣式                                 |
| `admin-field-content`     | 在橫向欄位中包住 label + description，讓控制元件（switch / checkbox 等）對齊在右側 |
| `admin-field-title`       | 群組內次標題，用於分段但不需 `legend` 語意時                                  |
| `admin-field-divider`     | 群組內分隔線，視覺切分不同區段                                              |

### admin-field

::div{data-admin-api-table=""}
#### Props

| 名稱            | 型別                                  | 預設值 | 說明            |
| ------------- | ----------------------------------- | --- | ------------- |
| `class`       | `ClassValue`                        | —   | 根元素之自訂 class  |
| `orientation` | `AdminFieldOrientation | undefined` | —   | 排列方向（直向 / 橫向） |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-field-set

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-field-legend

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-field-group

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-field-label

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-field-content

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-field-description

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-field-error

::div{data-admin-api-table=""}
#### Props

| 名稱       | 型別                                                                      | 預設值 | 說明                                               |
| -------- | ----------------------------------------------------------------------- | --- | ------------------------------------------------ |
| `class`  | `ClassValue`                                                            | —   | 根元素之自訂 class                                     |
| `errors` | `(string | { message: string | undefined; } | undefined)[] | undefined` | —   | 錯誤訊息陣列，可為字串或具 \`message\` 欄位之物件；單條時顯示為段落、多條時自動列表 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-field-title

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-field-divider

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |
::

## 更新紀錄

:admin-changelog{component="AdminField"}


# File Upload

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/file-upload
```

```ts
import {
  AdminFileUpload,
  AdminFileUploadClear,
  AdminFileUploadDropzone,
  AdminFileUploadItem,
  AdminFileUploadItemDelete,
  AdminFileUploadItemMetadata,
  AdminFileUploadItemPreview,
  AdminFileUploadItemProgress,
  AdminFileUploadList,
  AdminFileUploadTrigger,
} from '@/components/admin/file-upload'
```

## 用法

```vue
<script setup lang="ts">
import type { AdminFileUploadListItem } from '@/registry/admin/ui/file-upload'
import { IconRefresh } from '@tabler/icons-vue'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import {
  AdminFileUpload,
  AdminFileUploadClear,
  AdminFileUploadDropzone,
  AdminFileUploadItem,
  AdminFileUploadItemDelete,
  AdminFileUploadItemMetadata,
  AdminFileUploadItemPreview,
  AdminFileUploadItemProgress,
  AdminFileUploadList,
  AdminFileUploadTrigger
} from '@/registry/admin/ui/file-upload'
import { AdminNotification, errorNotification } from '@/registry/admin/ui/notification'

const items = ref<AdminFileUploadListItem[]>([])

const MAX_FILES = 5
const MAX_SIZE = 5 * 1024 * 1024

function validate(file: File, ctx: { total: number }): true | string {
  if (ctx.total >= MAX_FILES) {
    return `最多 ${MAX_FILES} 個檔案`
  }
  if (file.size > MAX_SIZE) {
    return `檔案超過大小上限（5 MB）`
  }
  return true
}

function onFileReject({ reason, file }: { reason: string; file?: File }) {
  errorNotification('檔案無法加入', file ? `${file.name}：${reason}` : reason)
}

async function handleUpload({ id }: { id: string; file: File }) {
  const findIndex = () => items.value.findIndex((it) => it.id === id)
  const patch = (p: Partial<AdminFileUploadListItem>) => {
    const i = findIndex()
    if (i === -1) {
      return
    }
    const copy = [...items.value]
    copy[i] = { ...copy[i]!, ...p }
    items.value = copy
  }

  const willFail = Math.random() < 0.4
  const failAt = 50

  patch({ status: 'uploading', progress: 0, errorMessage: undefined })

  for (let p = 25; p <= 100; p += 25) {
    await new Promise((r) => setTimeout(r, 180))
    if (willFail && p >= failAt) {
      patch({ status: 'failed', errorMessage: '網路錯誤，請重試' })
      return
    }
    patch({ progress: p })
  }
  patch({ status: 'success', progress: 100 })
}

function retry(item: AdminFileUploadListItem) {
  if (item.source instanceof File) {
    handleUpload({ id: item.id, file: item.source })
  }
}
</script>

<template>
  <admin-notification />
  <admin-file-upload
    v-model="items"
    class="w-full max-w-lg"
    :on-file-validate="validate"
    @file-reject="onFileReject"
    @upload="handleUpload"
  >
    <admin-file-upload-dropzone>
      <p class="typo-title-small text-text-90">拖曳檔案到此或選取檔案</p>
      <admin-file-upload-trigger
        :class="
          cn(`
            rounded-lg border border-primary-50 px-3 py-2 typo-caption-small text-primary-50
            hover:bg-primary-10
          `)
        "
      >
        選擇檔案
      </admin-file-upload-trigger>
    </admin-file-upload-dropzone>
    <admin-file-upload-clear class="self-start" label="清除全部" />
    <admin-file-upload-list v-if="items.length">
      <admin-file-upload-item v-for="it in items" :key="it.id" :item-id="it.id">
        <admin-file-upload-item-preview />
        <div class="flex min-w-0 flex-1 flex-col gap-2">
          <admin-file-upload-item-metadata>
            <p
              v-if="it.status === 'failed' && it.errorMessage"
              class="typo-caption-small text-error-50"
            >
              {{ it.errorMessage }}
            </p>
          </admin-file-upload-item-metadata>
          <admin-file-upload-item-progress
            :labels="{ uploading: '上傳中', success: '上傳成功', failed: '上傳失敗' }"
          />
        </div>
        <button
          v-if="it.status === 'failed'"
          aria-label="重試上傳"
          type="button"
          :class="
            cn(`
              flex size-9 shrink-0 items-center justify-center rounded-lg text-text-50
              hover:bg-bg-70 hover:text-text-90
            `)
          "
          @click="retry(it)"
        >
          <icon-refresh class="size-5" />
        </button>
        <admin-file-upload-item-delete label="移除檔案" />
      </admin-file-upload-item>
    </admin-file-upload-list>
  </admin-file-upload>
</template>
```

## 場景

### 僅按鈕、不要 Dropzone

```vue
<script setup lang="ts">
import type { AdminFileUploadListItem } from '@/registry/admin/ui/file-upload'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import {
  AdminFileUpload,
  AdminFileUploadClear,
  AdminFileUploadItem,
  AdminFileUploadItemDelete,
  AdminFileUploadItemMetadata,
  AdminFileUploadItemPreview,
  AdminFileUploadList,
  AdminFileUploadTrigger
} from '@/registry/admin/ui/file-upload'

const items = ref<AdminFileUploadListItem[]>([])
</script>

<template>
  <admin-file-upload v-model="items" class="w-full max-w-lg" :multiple="false">
    <div class="flex flex-wrap items-center gap-2">
      <admin-file-upload-trigger
        :class="
          cn(`
            rounded-lg bg-primary-50 px-3 py-2 typo-caption-small text-text-10
            hover:opacity-90
          `)
        "
      >
        從電腦上傳
      </admin-file-upload-trigger>
      <span class="typo-caption-small text-text-50">（此 demo 不含 Dropzone，僅 Trigger）</span>
    </div>
    <admin-file-upload-clear v-if="items.length" class="self-start" label="清除全部" />
    <admin-file-upload-list v-if="items.length" class="mt-2">
      <admin-file-upload-item v-for="it in items" :key="it.id" :item-id="it.id">
        <admin-file-upload-item-preview />
        <admin-file-upload-item-metadata />
        <admin-file-upload-item-delete label="移除檔案" />
      </admin-file-upload-item>
    </admin-file-upload-list>
  </admin-file-upload>
</template>
```

### 程式寫入 URL（不經檔案選擇器）

由素材庫、過往上傳紀錄等來源直接寫入 URL 項目，跳過檔案選擇器流程。

```vue
<script setup lang="ts">
import type { AdminFileUploadListItem } from '@/registry/admin/ui/file-upload'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import {
  AdminFileUpload,
  AdminFileUploadClear,
  AdminFileUploadItem,
  AdminFileUploadItemDelete,
  AdminFileUploadItemMetadata,
  AdminFileUploadItemPreview,
  AdminFileUploadList
} from '@/registry/admin/ui/file-upload'

const items = ref<AdminFileUploadListItem[]>([])

function addRemoteImage() {
  items.value = [
    ...items.value,
    {
      id:
        globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(16).slice(2)}`,
      source: 'https://picsum.photos/id/237/200/200',
      status: 'success',
      progress: 100
    }
  ]
}
</script>

<template>
  <admin-file-upload v-model="items" class="w-full max-w-lg">
    <p class="typo-caption-small text-text-50">
      模擬「素材庫」或其它來源：由外層按鈕直接寫入 URL 項目（不經檔案選擇器）。
    </p>
    <button
      type="button"
      :class="
        cn(`
          rounded-lg border border-primary-50 px-3 py-2 typo-caption-small text-primary-50
          hover:bg-primary-10
        `)
      "
      @click="addRemoteImage"
    >
      新增一筆圖片 URL
    </button>
    <admin-file-upload-clear class="self-start" label="清除全部" />
    <admin-file-upload-list v-if="items.length" class="mt-2">
      <admin-file-upload-item v-for="it in items" :key="it.id" :item-id="it.id">
        <admin-file-upload-item-preview />
        <admin-file-upload-item-metadata>
          <p class="typo-caption-small text-text-50">此列為 slot：可放影片時長、上傳日期等</p>
        </admin-file-upload-item-metadata>
        <admin-file-upload-item-delete label="移除檔案" />
      </admin-file-upload-item>
    </admin-file-upload-list>
  </admin-file-upload>
</template>
```

## Type-safe 列表項目

`AdminFileUpload` 已是 generic（`TItem extends AdminFileUploadListItem`），以子型別的 ref 綁定 `v-model` 即可讓列表項目攜帶業務欄位（如後端回傳的資產 id），`update:modelValue` payload 同步收斂為該子型別。

元件自行新增的項目（使用者選檔）僅含 base 欄位（`id`／`source`）；自訂欄位由呼叫端於 `upload` 事件後自行補寫。

::alert{title="需開啟 strictVModel" type="info"}
型別檢查需開啟 `strictVModel`（若已開啟 `strictTemplates` 則已包含）。設定見 [Type-safe](https://component-registry-4d4d86.gitlab.io/docs/get-started/type-safe)。下列同時含合法綁定與刻意錯誤綁定；錯誤處以 `@vue-expect-error` 標示。
::

```vue
<script setup lang="ts">
import type { AdminFileUploadListItem } from '@/registry/admin/ui/file-upload'
import { ref } from 'vue'
import {
  AdminFileUpload,
  AdminFileUploadDropzone,
  AdminFileUploadItem,
  AdminFileUploadItemDelete,
  AdminFileUploadItemMetadata,
  AdminFileUploadItemPreview,
  AdminFileUploadList,
  AdminFileUploadTrigger
} from '@/registry/admin/ui/file-upload'

interface AttachmentItem extends AdminFileUploadListItem {
  /** 上傳完成後由後端回傳之資產 id，由呼叫端於 upload 事件後補寫 */
  assetId?: string
}

const items = ref<AttachmentItem[]>([])
const wrongItems = ref<{ id: string }[]>([])
</script>

<template>
  <div class="flex w-full max-w-md flex-col gap-6">
    <admin-file-upload v-model="items">
      <admin-file-upload-dropzone>
        <admin-file-upload-trigger>選擇檔案</admin-file-upload-trigger>
      </admin-file-upload-dropzone>
      <admin-file-upload-list>
        <admin-file-upload-item v-for="it in items" :key="it.id" :item-id="it.id">
          <admin-file-upload-item-preview />
          <admin-file-upload-item-metadata />
          <admin-file-upload-item-delete />
        </admin-file-upload-item>
      </admin-file-upload-list>
    </admin-file-upload>

    <!-- @vue-expect-error 項目缺 source 必要欄位，不符 AdminFileUploadListItem 約束 -->
    <admin-file-upload v-model="wrongItems" />
  </div>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-file-upload v-model="items" :on-file-validate="validate" @upload="handleUpload">
    <admin-file-upload-dropzone>
      <admin-file-upload-trigger>選擇檔案</admin-file-upload-trigger>
    </admin-file-upload-dropzone>
    <admin-file-upload-clear />
    <admin-file-upload-list>
      <admin-file-upload-item v-for="it in items" :key="it.id" :item-id="it.id">
        <admin-file-upload-item-preview />
        <admin-file-upload-item-metadata />
        <admin-file-upload-item-progress />
        <admin-file-upload-item-delete />
      </admin-file-upload-item>
    </admin-file-upload-list>
  </admin-file-upload>
</template>
```

### admin-file-upload

::div{data-admin-api-table=""}
#### Props

| 名稱               | 型別                                                                                                                               | 預設值     | 說明                                            |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------- |
| `class`          | `ClassValue`                                                                                                                     | —       | 根元素之自訂 class                                  |
| `disabled`       | `boolean | undefined`                                                                                                            | `false` | 設為 \`true\` 時禁用整個上傳互動                         |
| `invalid`        | `boolean | undefined`                                                                                                            | `false` | 設為 \`true\` 時套用錯誤狀態樣式                         |
| `multiple`       | `boolean | undefined`                                                                                                            | `true`  | 設為 \`false\` 時限制單檔上傳                          |
| `accept`         | `string | undefined`                                                                                                             | —       | 可接受之檔案類型（同原生 \`\<input type="file">\` accept） |
| `onFileValidate` | `((file: File, ctx: { index: number; accepted: number; total: number; }) => string | true | Promise<string | true>) | undefined` | —       | 自訂單檔驗證 hook；回傳 \`true\` 為通過，回傳字串為錯誤訊息         |
| `modelValue`     | `TItem[] | undefined`                                                                                                            | `[]`    | —                                             |

#### Events

| 名稱                  | Payload                                        | 說明                                     |
| ------------------- | ---------------------------------------------- | -------------------------------------- |
| `fileReject`        | `{ reason: string; file?: File | undefined; }` | 檔案被拒絕時觸發（驗證失敗或被 \`onFileValidate\` 拒收） |
| `upload`            | `{ id: string; file: File; }`                  | 檔案被接受並加入列表後觸發，可用於啟動實際上傳流程              |
| `update:modelValue` | `TItem[]`                                      | —                                      |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-file-upload-trigger

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值        | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —          | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"button"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —          | —                                                                                                                                                                                                            |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-file-upload-list

::div{data-admin-api-table=""}
#### Props

| 名稱            | 型別                                      | 預設值          | 說明 |
| ------------- | --------------------------------------- | ------------ | -- |
| `orientation` | `"horizontal" | "vertical" | undefined` | `"vertical"` | —  |
| `class`       | `ClassValue`                            | —            | —  |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-file-upload-item

::div{data-admin-api-table=""}
#### Props

| 名稱         | 型別           | 預設值 | 說明 |
| ---------- | ------------ | --- | -- |
| `itemId`\* | `string`     | —   | —  |
| `class`    | `ClassValue` | —   | —  |

*\\\* 代表必填*

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-file-upload-clear

::div{data-admin-api-table=""}
#### Props

| 名稱           | 型別                                         | 預設值           | 說明                                                                                                                                                                                                           |
| ------------ | ------------------------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild`    | `boolean | undefined`                      | —             | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`         | `globalThis.Component | AsTag | undefined` | `"button"`    | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`      | `ClassValue`                               | —             | —                                                                                                                                                                                                            |
| `forceMount` | `boolean | undefined`                      | `false`       | —                                                                                                                                                                                                            |
| `label`      | `string | undefined`                       | `"Clear all"` | —                                                                                                                                                                                                            |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-file-upload-item-delete

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值             | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —               | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"button"`      | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —               | —                                                                                                                                                                                                            |
| `label`   | `string | undefined`                       | `"Remove file"` | —                                                                                                                                                                                                            |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-file-upload-item-progress

::div{data-admin-api-table=""}
#### Props

| 名稱       | 型別                                                      | 預設值 | 說明 |
| -------- | ------------------------------------------------------- | --- | -- |
| `class`  | `ClassValue`                                            | —   | —  |
| `labels` | `Partial<Record<FileUploadStatus, string>> | undefined` | —   | —  |

#### Slots

| 名稱       | Bindings                                       | 說明 |
| -------- | ---------------------------------------------- | -- |
| `status` | `{ label: string; status: FileUploadStatus; }` | —  |
| `icon`   | `{ status: FileUploadStatus; }`                | —  |
::

### admin-file-upload-dropzone

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明 |
| ------- | ------------ | --- | -- |
| `class` | `ClassValue` | —   | —  |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-file-upload-item-metadata

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明 |
| ------- | ------------ | --- | -- |
| `class` | `ClassValue` | —   | —  |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-file-upload-item-preview

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明 |
| ------- | ------------ | --- | -- |
| `class` | `ClassValue` | —   | —  |

#### Slots

| 名稱        | Bindings                                         | 說明 |
| --------- | ------------------------------------------------ | -- |
| `default` | `{ item: AdminFileUploadListItem | undefined; }` | —  |
::

## 注意事項

- 自訂子元件可從 `@/components/admin/file-upload` import `useFileUploadRoot()` / `useFileUploadItem()` 取得內部狀態。
- `useFileUploadRoot()` 的 `modelValue` 為寬型別 `AdminFileUploadListItem[]`；泛型收斂僅作用於 root 的 `v-model` 與 `update:modelValue`。
- 單張圖片欄位使用 [`admin-image-upload`](https://component-registry-4d4d86.gitlab.io/docs/admin/image-upload)，多檔、列表進度、拖曳區使用本元件族。

## 更新紀錄

:admin-changelog{component="AdminFileUpload"}


# Image

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/image
```

```ts
import {
  AdminImage,
  AdminImageFallback,
  AdminImageImg,
  AdminImagePlaceholder,
} from '@/components/admin/image'
```

## 用法

```vue
<script setup lang="ts">
import {
  AdminImage,
  AdminImageFallback,
  AdminImageImg,
  AdminImagePlaceholder
} from '@/registry/admin/ui/image'
</script>

<template>
  <admin-image class="aspect-video w-80 rounded-md">
    <admin-image-img alt="風景照" src="https://picsum.photos/seed/admin-image/800/450" />
    <admin-image-placeholder />
    <admin-image-fallback />
  </admin-image>
</template>
```

## 場景

### 自訂版面與裁切

```vue
<script setup lang="ts">
import {
  AdminImage,
  AdminImageFallback,
  AdminImageImg,
  AdminImagePlaceholder
} from '@/registry/admin/ui/image'

const SRC_LANDSCAPE = 'https://picsum.photos/seed/admin-image-landscape/800/450'
const SRC_PORTRAIT = 'https://picsum.photos/seed/admin-image-portrait/600/800'
const SRC_SQUARE = 'https://picsum.photos/seed/admin-image-square/600/600'
</script>

<template>
  <div class="flex flex-col gap-6">
    <section class="flex flex-col gap-2">
      <span class="typo-caption-small text-text-50">aspect：video / square / [4/3]</span>
      <div class="grid grid-cols-3 gap-4">
        <admin-image class="aspect-video rounded-md">
          <admin-image-img alt="aspect-video" :src="SRC_LANDSCAPE" />
          <admin-image-placeholder />
          <admin-image-fallback />
        </admin-image>
        <admin-image class="aspect-square rounded-md">
          <admin-image-img alt="aspect-square" :src="SRC_SQUARE" />
          <admin-image-placeholder />
          <admin-image-fallback />
        </admin-image>
        <admin-image class="aspect-4/3 rounded-md">
          <admin-image-img alt="aspect-4/3" :src="SRC_LANDSCAPE" />
          <admin-image-placeholder />
          <admin-image-fallback />
        </admin-image>
      </div>
    </section>

    <section class="flex flex-col gap-2">
      <span class="typo-caption-small text-text-50">object-fit：預設 cover / object-contain</span>
      <div class="grid grid-cols-2 gap-4">
        <admin-image class="aspect-video rounded-md bg-bg-80">
          <admin-image-img alt="cover" :src="SRC_PORTRAIT" />
          <admin-image-placeholder />
          <admin-image-fallback />
        </admin-image>
        <admin-image class="aspect-video rounded-md bg-bg-80">
          <admin-image-img alt="contain" class="object-contain" :src="SRC_PORTRAIT" />
          <admin-image-placeholder />
          <admin-image-fallback />
        </admin-image>
      </div>
    </section>

    <section class="flex flex-col gap-2">
      <span class="typo-caption-small text-text-50">rounded：rounded-md / rounded-full</span>
      <div class="flex gap-4">
        <admin-image class="aspect-square w-32 rounded-md">
          <admin-image-img alt="rounded-md" :src="SRC_SQUARE" />
          <admin-image-placeholder />
          <admin-image-fallback />
        </admin-image>
        <admin-image class="aspect-square w-32 rounded-full">
          <admin-image-img alt="rounded-full" :src="SRC_SQUARE" />
          <admin-image-placeholder />
          <admin-image-fallback />
        </admin-image>
      </div>
    </section>
  </div>
</template>
```

### 錯誤態 fallback

故意傳入無效 `src` 觸發 `error`，顯示預設 fallback。

```vue
<script setup lang="ts">
import {
  AdminImage,
  AdminImageFallback,
  AdminImageImg,
  AdminImagePlaceholder
} from '@/registry/admin/ui/image'
</script>

<template>
  <admin-image class="aspect-video w-80 rounded-md">
    <admin-image-img alt="無法載入的圖片" src="/_does-not-exist.png" />
    <admin-image-placeholder />
    <admin-image-fallback />
  </admin-image>
</template>
```

### 自訂 placeholder 與 fallback

::alert{title="子元件渲染條件" type="info"}
`admin-image-placeholder` 僅在 `loading` 狀態渲染，`admin-image-fallback` 僅在 `error` 狀態渲染；不放對應子元件即無該狀態的視覺。
::

```vue
<script setup lang="ts">
import { IconAlertTriangle, IconRefresh } from '@tabler/icons-vue'
import { computed, ref } from 'vue'
import { AdminButton } from '@/registry/admin/ui/button'
import {
  AdminImage,
  AdminImageFallback,
  AdminImageImg,
  AdminImagePlaceholder
} from '@/registry/admin/ui/image'
import { AdminLoading } from '@/registry/admin/ui/loading'

const reloadKey = ref(0)
const customSrc = computed(
  () => `https://picsum.photos/seed/admin-image-custom-${reloadKey.value}/800/450`
)
</script>

<template>
  <div class="flex flex-col gap-3">
    <div>
      <admin-button size="small" variant="outline" @click="reloadKey++">
        <icon-refresh class="size-4" />
        重新載入
      </admin-button>
    </div>

    <div class="flex gap-4">
      <admin-image class="aspect-video w-80 rounded-md">
        <admin-image-img alt="客製 placeholder" :src="customSrc" />
        <admin-image-placeholder>
          <admin-loading mode="inline" />
        </admin-image-placeholder>
        <admin-image-fallback />
      </admin-image>

      <admin-image class="aspect-video w-80 rounded-md">
        <admin-image-img alt="客製 fallback" src="/_does-not-exist.png" />
        <admin-image-placeholder />
        <admin-image-fallback class="flex flex-col gap-2 bg-primary-10 text-error-40">
          <icon-alert-triangle class="size-6" />
          <span class="typo-caption-small">圖片暫時無法顯示</span>
        </admin-image-fallback>
      </admin-image>
    </div>
  </div>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-image>
    <admin-image-img alt="..." src="..." />
    <admin-image-placeholder />
    <admin-image-fallback />
  </admin-image>
</template>
```

### admin-image

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-image-img

::div{data-admin-api-table=""}
#### Props

| 名稱               | 型別                                                 | 預設值 | 說明                                    |
| ---------------- | -------------------------------------------------- | --- | ------------------------------------- |
| `src`\*          | `string`                                           | —   | 圖片 URL（必填）                            |
| `alt`\*          | `string`                                           | —   | 圖片替代文字（必填）                            |
| `loading`        | `"eager" | "lazy" | undefined`                     | —   | 原生 \`\<img>\` 之 \`loading\` 屬性        |
| `decoding`       | `"auto" | "async" | "sync" | undefined`            | —   | 原生 \`\<img>\` 之 \`decoding\` 屬性       |
| `srcset`         | `string | undefined`                               | —   | 響應式圖片之 \`srcset\` 候選清單                |
| `sizes`          | `string | undefined`                               | —   | 響應式圖片之 \`sizes\` 描述                   |
| `referrerpolicy` | `HTMLAttributeReferrerPolicy | undefined`          | —   | 原生 \`\<img>\` 之 \`referrerpolicy\` 屬性 |
| `crossorigin`    | `"" | "anonymous" | "use-credentials" | undefined` | —   | 原生 \`\<img>\` 之 \`crossorigin\` 屬性    |
| `class`          | `ClassValue`                                       | —   | 根元素之自訂 class                          |

*\\\* 代表必填*

#### Events

| 名稱      | Payload | 說明        |
| ------- | ------- | --------- |
| `error` | `Event` | 圖片載入失敗時觸發 |
| `load`  | `Event` | 圖片載入成功時觸發 |
::

### admin-image-placeholder

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-image-fallback

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

## 注意事項

- **CDN 同 URL 不同檔**：若 `src` 字串完全相同但內容換了（CDN 快取），`<img>` 不會自動重抓。父層應在 URL 後加 query string 強制更新。
- 純展示用 `admin-image`；頭像場景改用 `admin-avatar`；表單上傳改用 `admin-image-upload`。

## 更新紀錄

:admin-changelog{component="AdminImage"}


# Image Upload

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/image-upload
```

```ts
import {
  AdminImageUpload,
  AdminImageUploadLoading,
  AdminImageUploadMessage,
  AdminImageUploadPlaceholder,
  AdminImageUploadPreview,
  AdminImageUploadTrigger,
} from '@/components/admin/image-upload'
```

## 用法

```vue
<script setup lang="ts">
import { ref } from 'vue'
import {
  AdminImageUpload,
  AdminImageUploadLoading,
  AdminImageUploadMessage,
  AdminImageUploadPlaceholder,
  AdminImageUploadPreview,
  AdminImageUploadTrigger
} from '@/registry/admin/ui/image-upload'

const value = ref<File | null>(null)
const status = ref<'uploading' | 'failed' | undefined>(undefined)
const isError = ref(false)

function handleReset() {
  value.value = null
  status.value = undefined
  isError.value = false
}
</script>

<template>
  <div class="flex flex-col gap-4">
    <admin-image-upload v-model="value" :is-error="isError" :status="status">
      <admin-image-upload-trigger>
        <admin-image-upload-placeholder />
        <admin-image-upload-preview />
        <admin-image-upload-loading />
      </admin-image-upload-trigger>
      <admin-image-upload-message />
    </admin-image-upload>

    <div class="flex flex-wrap gap-2 typo-content-medium">
      <button class="rounded-sm border border-text-30 px-2 py-1" type="button" @click="handleReset">
        Reset
      </button>
      <button
        class="rounded-sm border border-text-30 px-2 py-1"
        type="button"
        @click="status = status === 'uploading' ? undefined : 'uploading'"
      >
        Toggle uploading
      </button>
      <button
        class="rounded-sm border border-text-30 px-2 py-1"
        type="button"
        @click="status = status === 'failed' ? undefined : 'failed'"
      >
        Toggle failed
      </button>
      <button
        class="rounded-sm border border-text-30 px-2 py-1"
        type="button"
        @click="isError = !isError"
      >
        Toggle is-error
      </button>
    </div>
  </div>
</template>
```

## 場景

### 與表單驗證整合

```vue
<script setup lang="ts">
import { useForm, Field as VeeField } from 'vee-validate'
import { ref } from 'vue'
import { AdminField, AdminFieldContent, AdminFieldLabel } from '@/registry/admin/ui/field'
import {
  AdminImageUpload,
  AdminImageUploadLoading,
  AdminImageUploadMessage,
  AdminImageUploadPlaceholder,
  AdminImageUploadPreview,
  AdminImageUploadTrigger
} from '@/registry/admin/ui/image-upload'

// canonical split：欄位值 cover 是「已持久化的 URL」（送出值），
// 元件 v-model 綁的 file 只承載使用者新選、尚未上傳完成的本地 File。
const { handleSubmit, values, setFieldValue } = useForm<{
  cover: string | null
}>({
  initialValues: {
    cover: null
  }
})

const file = ref<File | null>(null)
const status = ref<'uploading' | 'failed' | undefined>(undefined)
const lastReject = ref<string | undefined>(undefined)

function validateCover(value: unknown) {
  return value ? true : '請上傳商品圖片'
}

// 5MB 上限
function validateFile(f: File): true | string {
  if (f.size > 5 * 1024 * 1024) {
    return '檔案大小超過 5MB'
  }
  return true
}

// 模擬 upload：1.2 秒後隨機成功 / 失敗
async function fakeUpload(payload: { file: File }) {
  status.value = 'uploading'
  await new Promise((resolve) => setTimeout(resolve, 1200))
  if (Math.random() < 0.3) {
    status.value = 'failed'
    return
  }
  // 成功：把回傳的持久化 URL 存進表單欄位、清掉本地選檔，preview 改吃 :src
  setFieldValue('cover', URL.createObjectURL(payload.file))
  file.value = null
  status.value = undefined
}

function onFileReject(payload: { reason: string; file?: File }) {
  lastReject.value = payload.reason
}

const onSubmit = handleSubmit((submitted) => {
  // eslint-disable-next-line no-alert
  alert(`已送出，cover = ${submitted.cover ?? 'null'}`)
})

function handleReset() {
  setFieldValue('cover', null)
  file.value = null
  status.value = undefined
  lastReject.value = undefined
}
</script>

<template>
  <form class="flex w-full max-w-sm flex-col gap-4" @submit.prevent="onSubmit">
    <vee-field v-slot="{ errorMessage }" name="cover" :rules="validateCover">
      <admin-field>
        <admin-field-label class="w-26 shrink-0 py-2.5">商品圖片</admin-field-label>
        <admin-field-content class="min-h-full min-w-0">
          <admin-image-upload
            v-model="file"
            accept="image/*"
            :is-error="!!errorMessage"
            :on-file-validate="validateFile"
            :status="status"
            @file-reject="onFileReject"
            @upload="fakeUpload"
          >
            <admin-image-upload-trigger>
              <admin-image-upload-placeholder v-if="!values.cover" />
              <admin-image-upload-preview :src="values.cover" />
              <admin-image-upload-loading />
            </admin-image-upload-trigger>
            <admin-image-upload-message />
          </admin-image-upload>
        </admin-field-content>
      </admin-field>
    </vee-field>

    <div class="flex gap-2">
      <button
        class="rounded-sm border border-text-30 px-3 py-1.5 typo-content-medium"
        type="submit"
      >
        Submit
      </button>
      <button
        class="rounded-sm border border-text-30 px-3 py-1.5 typo-content-medium"
        type="button"
        @click="handleReset"
      >
        Reset
      </button>
    </div>

    <p class="typo-caption-small text-text-60">
      Cover (persisted): {{ values.cover ?? 'null' }}
      <br />
      Local file: {{ file ? '[File]' : 'null' }}
      <br />
      Status: {{ status ?? '—' }}
      <br />
      Last reject: {{ lastReject ?? '—' }}
    </p>
  </form>
</template>
```

> 以 vee-validate 的 `<Field>` 提供驗證，將 `errorMessage` 是否存在透過 `:is-error` 傳入元件即可；錯誤文字交由元件內建的 `AdminImageUploadMessage` 顯示，無需額外渲染 `admin-field-error`，避免訊息重複。
>
> v-model 綁的是使用者新選的 `File`。已上傳完成的 URL 另外存一個 state，上傳成功後餵給 `AdminImageUploadPreview` 的 `:src`。

### 顯示既有圖片

編輯表單的既有圖片（或上傳完成的持久化 URL）不進 v-model，改由 `AdminImageUploadPreview` 的 `src` 顯示。有選檔（`File`）時 `File` 優先，否則 fallback `src`。因為此時 v-model 為 `null`，需以 `v-if` gate 掉 `AdminImageUploadPlaceholder`，避免與既有圖重疊：

```vue
<template>
  <admin-image-upload v-model="file">
    <admin-image-upload-trigger>
      <admin-image-upload-placeholder v-if="!existingSrc" />
      <admin-image-upload-preview :src="existingSrc" />
      <admin-image-upload-loading />
    </admin-image-upload-trigger>
    <admin-image-upload-message />
  </admin-image-upload>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-image-upload v-model="image">
    <admin-image-upload-trigger>
      <admin-image-upload-placeholder />
      <admin-image-upload-preview />
      <admin-image-upload-loading />
    </admin-image-upload-trigger>
    <admin-image-upload-message />
  </admin-image-upload>
</template>
```

### admin-image-upload

::div{data-admin-api-table=""}
#### Props

| 名稱               | 型別                                                                                                                | 預設值         | 說明                                             |
| ---------------- | ----------------------------------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------- |
| `disabled`       | `boolean | undefined`                                                                                             | `false`     | 設為 \`true\` 時禁用上傳互動                            |
| `isError`        | `boolean | undefined`                                                                                             | `false`     | 設為 \`true\` 時套用錯誤狀態樣式                          |
| `status`         | `"uploading" | "failed" | undefined`                                                                              | —           | 外部驅動之上傳狀態：\`uploading\` 顯示載入態、\`failed\` 顯示錯誤態 |
| `accept`         | `string | undefined`                                                                                              | `"image/*"` | 可接受之檔案類型（同原生 \`\<input type="file">\` accept）  |
| `onFileValidate` | `((file: File, ctx: { index: 0; accepted: 0; total: 0; }) => string | true | Promise<string | true>) | undefined` | —           | 自訂單檔驗證 hook；回傳 \`true\` 為通過，回傳字串為錯誤訊息          |
| `class`          | `ClassValue`                                                                                                      | —           | 根元素之自訂 class                                   |
| `modelValue`     | `File | null | undefined`                                                                                         | `null`      | —                                              |

#### Events

| 名稱                  | Payload                                        | 說明                       |
| ------------------- | ---------------------------------------------- | ------------------------ |
| `update:modelValue` | `File | null`                                  | —                        |
| `fileReject`        | `{ reason: string; file?: File | undefined; }` | 檔案被拒（驗證失敗或拋錯）時觸發         |
| `upload`            | `{ file: File; }`                              | 檔案通過驗證、modelValue 已更新後觸發 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |

#### Expose

| 名稱                   | 簽名           | 說明                               |
| -------------------- | ------------ | -------------------------------- |
| `openFileDialog`     | `() => void` | 程式化開啟系統檔案選擇對話框（disabled 時 no-op） |
| `clearRejectMessage` | `() => void` | 清掉上一次拒絕的訊息                       |
| `clear`              | `() => void` | 把 v-model 設回 null 並清掉 reject 訊息  |
::

### admin-image-upload-trigger

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值        | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —          | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"button"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —          | —                                                                                                                                                                                                            |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-image-upload-loading

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明 |
| ------- | ------------ | --- | -- |
| `class` | `ClassValue` | —   | —  |
::

### admin-image-upload-message

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明 |
| ------- | ------------ | --- | -- |
| `class` | `ClassValue` | —   | —  |
::

### admin-image-upload-placeholder

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明 |
| ------- | ------------ | --- | -- |
| `class` | `ClassValue` | —   | —  |
::

### admin-image-upload-preview

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別                          | 預設值 | 說明                                          |
| ------- | --------------------------- | --- | ------------------------------------------- |
| `src`   | `string | null | undefined` | —   | 既有／已持久化圖片的唯讀顯示來源；有選檔（\`File\`）時 \`File\` 優先 |
| `class` | `ClassValue`                | —   | —                                           |
::

## 注意事項

- **v-model 只認 `File | null`**：既有／已上傳的 URL 字串不進 v-model，改由 `AdminImageUploadPreview` 的 `:src` 顯示（見「顯示既有圖片」）。
- **CDN 同 URL 不同檔**：若上傳成功後 backend 回傳的 URL 與舊圖完全相同（CDN 快取），`<img>` 不會自動重抓。父層應在傳給 `:src` 的 URL 後加 query string（例如 `?v=timestamp`）強制更新。
- **元件不負責上傳**：`@upload` 只通知「使用者選了新檔且通過 validate」，實際 fetch / FormData / endpoint 全由父層處理。

## 更新紀錄

:admin-changelog{component="AdminImageUpload"}


# Input

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/input
```

```ts
import {
  AdminInput,
  AdminInputClear,
  AdminInputPasswordToggle,
  AdminInputWordLimit,
} from '@/components/admin/input'
```

## 用法

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminInput } from '@/registry/admin/ui/input'

const value = ref<string | number>('')
</script>

<template>
  <admin-input v-model="value" class="w-64" placeholder="Type here" />
</template>
```

## 場景

### 可清除內容

輸入框在有值時會顯示清除按鈕。

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminInput, AdminInputClear } from '@/registry/admin/ui/input'

const value = ref<string | number>('Hello')
</script>

<template>
  <admin-input v-model="value" class="w-64" placeholder="輸入關鍵字">
    <template #suffix>
      <admin-input-clear />
    </template>
  </admin-input>
</template>
```

### 密碼欄位與顯示切換

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminInput, AdminInputPasswordToggle } from '@/registry/admin/ui/input'

const password = ref<string | number>('secret-123')
</script>

<template>
  <admin-input v-model="password" class="w-64" placeholder="密碼" type="password">
    <template #suffix>
      <admin-input-password-toggle />
    </template>
  </admin-input>
</template>
```

### 錯誤狀態

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminInput } from '@/registry/admin/ui/input'

const value = ref<string | number>('錯誤內容')
</script>

<template>
  <admin-input v-model="value" class="w-64" placeholder="Type here" is-error />
</template>
```

## Type-safe 封裝

`AdminInput` 採原生 `input` 封裝，`modelValue` 為 `string | number`，不會依 `type` 在 compile-time 與 `v-model` 型別對齊。

開啟 `strictVModel` 或 `strictTemplates` 時，若以更嚴的型別（例如 `number | null`）綁定，容易出現型別錯誤。這屬原生 `input` 的型別行為，而非元件缺漏。

若需要讓 `type` 與 `v-model` 型別對齊，可自行封裝。

範例：

```vue
<script setup lang="ts" generic="TInputType extends InputTypeHTMLAttribute">
import type { InputTypeHTMLAttribute } from 'vue'
import type { AdminInputEmits, AdminInputProps, AdminInputSlots } from '@/registry/admin/ui/input'
import { reactiveOmit } from '@vueuse/core'
import { useForwardPropsEmits } from 'reka-ui'
import { computed } from 'vue'
import { AdminInput } from '@/registry/admin/ui/input'

type TModelValue = [TInputType] extends ['number'] ? number | null : string

defineOptions({
  name: 'typed-admin-input'
})

const props = defineProps<
  Omit<AdminInputProps, 'modelValue' | 'defaultValue' | 'type'> & {
    type?: TInputType
    modelValue?: TModelValue
    defaultValue?: TModelValue
  }
>()

const emits = defineEmits<
  Omit<AdminInputEmits, 'update:modelValue'> & {
    'update:modelValue': [value: TModelValue]
  }
>()

const slots = defineSlots<AdminInputSlots>()

const delegatedProps = reactiveOmit(props, 'modelValue')
const forwardedAll = useForwardPropsEmits(delegatedProps, emits)

const forwarded = computed(() => {
  const { 'onUpdate:modelValue': _, ...rest } = forwardedAll.value
  return rest
})

const innerValue = computed<string | number>({
  get() {
    return props.modelValue ?? ''
  },
  set(value) {
    if (props.type === 'number' && value === '') {
      emits('update:modelValue', null as TModelValue)
      return
    }
    emits('update:modelValue', value as TModelValue)
  }
})
</script>

<template>
  <admin-input v-bind="forwarded" v-model="innerValue">
    <template v-for="(_, name) in slots" #[name]>
      <slot :name="name"></slot>
    </template>
  </admin-input>
</template>
```

::alert{title="number | null 需處理清空" type="warning"}
若型別為 `number | null`，runtime 仍須處理清空：原生 `type="number"` 清空時值會變成空字串 `''`，需轉成 `null`，型別才與實際行為一致。
::

::alert{title="需開啟 strictVModel" type="info"}
型別檢查需開啟 `strictVModel`（若已開啟 `strictTemplates` 則已包含）。設定見 [Type-safe](https://component-registry-4d4d86.gitlab.io/docs/get-started/type-safe)。下列同時含合法綁定與刻意錯誤綁定；錯誤處以 `@vue-expect-error` 標示。
::

```vue
<script setup lang="ts">
import { ref } from 'vue'
import TypedAdminInput from './typed-admin-input-demo.vue'

const numberAndNullValue = ref<number | null>(null)
const stringValue = ref('')
</script>

<template>
  <div class="flex w-full max-w-md flex-col gap-6">
    <!-- number | null -->
    <typed-admin-input v-model="numberAndNullValue" type="number" />
    <!-- @vue-expect-error type 設定成 number，但 value 給 string 就會報錯 -->
    <typed-admin-input v-model="stringValue" type="number" />

    <!-- string -->
    <typed-admin-input v-model="stringValue" />
    <!-- @vue-expect-error type 設定成非 number，但 value 給 number 就會報錯 -->
    <typed-admin-input v-model="numberAndNullValue" type="text" />
  </div>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-input v-model="value" placeholder="輸入文字">
    <template #suffix>
      <admin-input-clear />
    </template>
  </admin-input>
</template>
```

### admin-input

::div{data-admin-api-table=""}
#### Props

| 名稱             | 型別                                   | 預設值      | 說明                                                  |
| -------------- | ------------------------------------ | -------- | --------------------------------------------------- |
| `defaultValue` | `string | number | undefined`        | —        | 初始值（非控制模式）                                          |
| `modelValue`   | `string | number | undefined`        | —        | 受控值，以 \`v-model\` 綁定                                |
| `placeholder`  | `string | undefined`                 | —        | 預設提示文字                                              |
| `disabled`     | `boolean | undefined`                | —        | 設為 \`true\` 時禁用輸入並套用視覺停用樣式                          |
| `readonly`     | `boolean | undefined`                | —        | 設為 \`true\` 時禁止編輯文字，但仍允許 focus 與 selection          |
| `maxlength`    | `number | undefined`                 | —        | 限制最大字元數（並由 \`admin-input-word-limit\` 顯示計數）         |
| `class`        | `ClassValue`                         | —        | 根元素之自訂 class                                        |
| `type`         | `InputTypeHTMLAttribute | undefined` | `"text"` | HTML input type（如 \`text\`、\`password\`、\`number\`） |
| `isError`      | `boolean | undefined`                | —        | 設為 \`true\` 時套用錯誤狀態樣式與 \`aria-invalid\`             |
| `id`           | `string | undefined`                 | —        | 透傳至內層 \`input\` 之 \`id\`；純透傳，未提供時不自動生成              |
| `name`         | `string | undefined`                 | —        | 透傳至內層 \`input\` 之 \`name\`，供原生表單提交使用                |

#### Events

| 名稱                  | Payload           | 說明                                                |
| ------------------- | ----------------- | ------------------------------------------------- |
| `blur`              | `FocusEvent`      | 內層 \`input\` 失焦時轉發之原生事件                           |
| `change`            | `Event`           | 內層 \`input\` 觸發原生 \`change\`（值變更並 commit）時轉發之原生事件 |
| `input`             | `Event`           | 內層 \`input\` 觸發原生 \`input\`（每次輸入）時轉發之原生事件         |
| `update:modelValue` | `string | number` | modelValue 更新時觸發                                  |

#### Slots

| 名稱        | Bindings | 說明                              |
| --------- | -------- | ------------------------------- |
| `default` | `any`    | 預設 slot                         |
| `prefix`  | `any`    | 輸入框前綴 slot，常用於放置 icon           |
| `suffix`  | `any`    | 輸入框後綴 slot，常用於放置 icon、清除按鈕、字數計數 |

#### Expose

| 名稱      | 簽名                        | 說明                                                           |
| ------- | ------------------------- | ------------------------------------------------------------ |
| `input` | `HTMLInputElement | null` | 內部原生 input 元素之 template ref，可用於程式化 focus / blur / select 等操作 |
::

### admin-input-clear

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別        | 預設值 | 說明 |
| ------- | --------- | --- | -- |
| `class` | `unknown` | —   | —  |

#### Events

| 名稱      | Payload | 說明             |
| ------- | ------- | -------------- |
| `clear` | —       | 點擊清除按鈕、值已清空後觸發 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-input-password-toggle

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別        | 預設值 | 說明 |
| ------- | --------- | --- | -- |
| `class` | `unknown` | —   | —  |
::

### admin-input-word-limit

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別        | 預設值 | 說明 |
| ------- | --------- | --- | -- |
| `class` | `unknown` | —   | —  |
::

## 更新紀錄

:admin-changelog{component="AdminInput"}


# Loading

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/loading
```

```ts
import {
  AdminLoading,
  vAdminLoading,
} from '@/components/admin/loading'
```

## 用法

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminButton } from '@/registry/admin/ui/button'
import { AdminLoading } from '@/registry/admin/ui/loading'

const showFullscreen = ref(false)

function triggerFullscreen() {
  showFullscreen.value = true
  setTimeout(() => {
    showFullscreen.value = false
  }, 1500)
}
</script>

<template>
  <div class="flex flex-col items-center gap-6">
    <!-- 容器內 Loading（限制在展示框內） -->
    <div class="relative h-32 w-64 overflow-hidden rounded-[8px] border">
      <admin-loading mode="inline" />
    </div>

    <!-- 全螢幕 Loading（1.5 秒後自動關閉） -->
    <admin-button variant="outline" @click="triggerFullscreen">
      觸發全螢幕 Loading（1.5s）
    </admin-button>

    <teleport to="body">
      <admin-loading v-if="showFullscreen" mode="fullscreen" />
    </teleport>
  </div>
</template>
```

## 場景

### Inline 區塊 loading

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { vAdminLoading } from '@/registry/admin/ui/loading/v-admin-loading'

const loading = ref(true)
</script>

<template>
  <div class="flex flex-col gap-3">
    <button
      class="self-start rounded-md border px-3 py-1 typo-content-medium"
      type="button"
      @click="loading = !loading"
    >
      切換 loading
    </button>
    <div
      v-admin-loading="loading"
      class="relative h-32 w-64 rounded-md border p-4 typo-content-medium"
    >
      被包住的內容區塊，inline mode loading 會以遮罩覆蓋此容器。
    </div>
  </div>
</template>
```

### 命令式全螢幕 loading

多個非同步請求共用一個全螢幕 loading：自行以 `admin-loading` 組裝；全域共享與計數由呼叫端決定。

下面這版用一個 ref-count counter：計數從 0 變 1 才顯示、從 1 變回 0 才隱藏，中間重疊的請求不會重複蓋上去。

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminButton } from '@/registry/admin/ui/button'
import { AdminLoading } from '@/registry/admin/ui/loading'

const isLoading = ref(false)
let pending = 0

function show() {
  if (pending++ === 0) {
    isLoading.value = true
  }
}

function hide() {
  if (pending > 0 && --pending === 0) {
    isLoading.value = false
  }
}

async function fetchData() {
  show()
  try {
    await new Promise((resolve) => setTimeout(resolve, 1500))
  } finally {
    hide()
  }
}

async function fetchInParallel() {
  await Promise.all([fetchData(), fetchData(), fetchData()])
}
</script>

<template>
  <div class="flex flex-wrap gap-3">
    <admin-button variant="outline" @click="fetchData"> 模擬單一請求 </admin-button>
    <admin-button variant="outline" @click="fetchInParallel"> 模擬三個並行請求 </admin-button>
    <admin-loading v-if="isLoading" mode="fullscreen" />
  </div>
</template>
```

> 想讓多個元件共用同一份 loading 狀態，把 counter 包進 `createSharedComposable`（`@vueuse/core`）就行。要不要這樣做，看你。

#### 搭配 useOverlay

如果你已經用 `useOverlay` 在統一管理 overlay，也可以讓它來掛 loading。只是它的 provider 會綁 `open` 和 `after-leave`，而 `admin-loading` 只是純展示元件、沒有這些 emit，所以得先包一層 wrapper 幫它補上：

```vue [loading-overlay-wrapper.vue]
<script setup lang="ts">
import { AdminLoading } from '@/components/admin/loading'

defineOptions({
  name: 'loading-overlay-wrapper'
})

defineProps<{
  open?: boolean
}>()

const emit = defineEmits<{
  'update:open': [value: boolean]
  close: []
  afterLeave: []
}>()
</script>

<template>
  <transition
    enter-active-class="animate-in fade-in-0"
    leave-active-class="animate-out fade-out-0"
    appear
    @after-leave="emit('afterLeave')"
  >
    <admin-loading v-if="open" mode="fullscreen" />
  </transition>
</template>
```

```vue
<script setup lang="ts">
import { AdminButton } from '@/registry/admin/ui/button'
import { useOverlay } from '@/registry/admin/ui/overlay'
import LoadingOverlayWrapper from './loading/loading-overlay-wrapper.vue'

const overlay = useOverlay()
const loading = overlay.create(LoadingOverlayWrapper)

let pending = 0

function show() {
  if (pending++ === 0) {
    loading.open()
  }
}

function hide() {
  if (pending > 0 && --pending === 0) {
    loading.close()
  }
}

async function fetchData() {
  show()
  try {
    await new Promise((resolve) => setTimeout(resolve, 1500))
  } finally {
    hide()
  }
}

async function fetchInParallel() {
  await Promise.all([fetchData(), fetchData(), fetchData()])
}
</script>

<template>
  <div class="flex flex-wrap gap-3">
    <admin-button variant="outline" @click="fetchData"> 模擬單一請求 </admin-button>
    <admin-button variant="outline" @click="fetchInParallel"> 模擬三個並行請求 </admin-button>
  </div>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-loading />
</template>
```

### admin-loading

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別                                    | 預設值     | 說明                                                                      |
| ------- | ------------------------------------- | ------- | ----------------------------------------------------------------------- |
| `mode`  | `"fullscreen" | "inline" | undefined` | —       | 顯示模式變體（\`fullscreen\` / \`inline\`）；未指定時預設為 \`fullscreen\`（fixed 全螢幕遮罩） |
| `label` | `string | undefined`                  | `"載入中"` | 顯示在 spinner 旁的文字標籤                                                      |
| `class` | `ClassValue`                          | —       | 根元素之自訂 class                                                            |

#### Slots

| 名稱        | Bindings             | 說明 |
| --------- | -------------------- | -- |
| `default` | `{ class: string; }` | —  |
::

## 更新紀錄

:admin-changelog{component="AdminLoading"}


# Notification

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/notification
```

```ts
import {
  AdminNotification,
  errorNotification,
  infoNotification,
  successNotification,
  warningNotification,
} from '@/components/admin/notification'
```

## 用法

```vue
<script setup lang="ts">
import { toast } from 'vue-sonner'
import { AdminButton } from '@/registry/admin/ui/button'
</script>

<template>
  <admin-button @click="toast('Saved successfully')">Show notification</admin-button>
</template>
```

## 場景

### 狀態變體

```vue
<script setup lang="ts">
import { AdminButton } from '@/registry/admin/ui/button'
import {
  errorNotification,
  infoNotification,
  successNotification,
  warningNotification
} from '@/registry/admin/ui/notification'
</script>

<template>
  <div class="flex items-center gap-3">
    <admin-button @click="successNotification('儲存成功', '變更已套用至系統。')"
      >Success</admin-button
    >
    <admin-button variant="outline" @click="infoNotification('已複製到剪貼簿', '可直接貼上使用。')"
      >Info</admin-button
    >
    <admin-button variant="outline" @click="warningNotification('空間即將用盡', '請盡快清理檔案。')"
      >Warning</admin-button
    >
    <admin-button variant="outline" @click="errorNotification('儲存失敗', '請檢查網路後重試。')"
      >Error</admin-button
    >
  </div>
</template>
```

### 含操作按鈕

以 `action` 設定按鈕標籤與 callback，適合「復原」這類可逆操作。

```vue
<script setup lang="ts">
import { toast } from 'vue-sonner'
import { AdminButton } from '@/registry/admin/ui/button'
import { successNotification } from '@/registry/admin/ui/notification'

function showUndo() {
  toast.success('已刪除一筆項目', {
    classes: {
      toast:
        'flex items-center rounded-[4px] border-success-20 bg-success-10 p-4 md:w-full md:max-w-60.75',
      icon: 'shrink-0',
      content: 'ml-2 flex flex-1 flex-col gap-y-1',
      title: 'typo-title-small text-text-90',
      description: 'typo-caption-medium text-text-70',
      closeButton: 'order-last ml-4 shrink-0 cursor-pointer'
    },
    description: '30 秒內可以復原。',
    closeButton: true,
    unstyled: true,
    action: {
      label: '復原',
      onClick: () => successNotification('已復原', '項目已成功還原。')
    }
  })
}
</script>

<template>
  <admin-button @click="showUndo">刪除並顯示復原通知</admin-button>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-notification />
</template>
```

`admin-notification` 須在 app root（通常是 `app.vue`）掛載一次；後續以函式呼叫的方式觸發通知。

### admin-notification

::div{data-admin-api-table=""}
#### Props

| 名稱                    | 型別                                   | 預設值 | 說明 |
| --------------------- | ------------------------------------ | --- | -- |
| `id`                  | `string | undefined`                 | —   | —  |
| `invert`              | `boolean | undefined`                | —   | —  |
| `theme`               | `Theme | undefined`                  | —   | —  |
| `position`            | `Position | undefined`               | —   | —  |
| `closeButtonPosition` | `CloseButtonPosition | undefined`    | —   | —  |
| `hotkey`              | `string[] | undefined`               | —   | —  |
| `richColors`          | `boolean | undefined`                | —   | —  |
| `expand`              | `boolean | undefined`                | —   | —  |
| `duration`            | `number | undefined`                 | —   | —  |
| `gap`                 | `number | undefined`                 | —   | —  |
| `visibleToasts`       | `number | undefined`                 | —   | —  |
| `closeButton`         | `boolean | undefined`                | —   | —  |
| `toastOptions`        | `ToastOptions | undefined`           | —   | —  |
| `class`               | `string | undefined`                 | —   | —  |
| `offset`              | `Offset | undefined`                 | —   | —  |
| `mobileOffset`        | `Offset | undefined`                 | —   | —  |
| `dir`                 | `"ltr" | "rtl" | "auto" | undefined` | —   | —  |
| `swipeDirections`     | `SwipeDirection[] | undefined`       | —   | —  |
| `icons`               | `ToastIcons | undefined`             | —   | —  |
| `containerAriaLabel`  | `string | undefined`                 | —   | —  |
::

## 更新紀錄

:admin-changelog{component="AdminNotification"}


# Number Field

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/number-field
```

```ts
import {
  AdminNumberField,
  AdminNumberFieldContent,
  AdminNumberFieldDecrement,
  AdminNumberFieldIncrement,
  AdminNumberFieldInput,
} from '@/components/admin/number-field'
```

## 用法

```vue
<script setup lang="ts">
import { ref } from 'vue'
import {
  AdminNumberField,
  AdminNumberFieldContent,
  AdminNumberFieldDecrement,
  AdminNumberFieldIncrement,
  AdminNumberFieldInput
} from '@/registry/admin/ui/number-field'

const value = ref(1)
</script>

<template>
  <admin-number-field v-model="value" :max="10" :min="0">
    <admin-number-field-content>
      <admin-number-field-decrement />
      <admin-number-field-input />
      <admin-number-field-increment />
    </admin-number-field-content>
  </admin-number-field>
</template>
```

## 場景

### 自訂 step

```vue
<script setup lang="ts">
import { ref } from 'vue'
import {
  AdminNumberField,
  AdminNumberFieldContent,
  AdminNumberFieldDecrement,
  AdminNumberFieldIncrement,
  AdminNumberFieldInput
} from '@/registry/admin/ui/number-field'

const value = ref(10)
</script>

<template>
  <admin-number-field v-model="value" :max="100" :min="0" :step="5">
    <admin-number-field-content>
      <admin-number-field-decrement />
      <admin-number-field-input />
      <admin-number-field-increment />
    </admin-number-field-content>
  </admin-number-field>
</template>
```

### 停用狀態

```vue
<script setup lang="ts">
import { ref } from 'vue'
import {
  AdminNumberField,
  AdminNumberFieldContent,
  AdminNumberFieldDecrement,
  AdminNumberFieldIncrement,
  AdminNumberFieldInput
} from '@/registry/admin/ui/number-field'

const value = ref(5)
</script>

<template>
  <admin-number-field v-model="value" disabled>
    <admin-number-field-content>
      <admin-number-field-decrement />
      <admin-number-field-input />
      <admin-number-field-increment />
    </admin-number-field-content>
  </admin-number-field>
</template>
```

### 錯誤狀態

```vue
<script setup lang="ts">
import { ref } from 'vue'
import {
  AdminNumberField,
  AdminNumberFieldContent,
  AdminNumberFieldDecrement,
  AdminNumberFieldIncrement,
  AdminNumberFieldInput
} from '@/registry/admin/ui/number-field'

const value = ref(1)
</script>

<template>
  <admin-number-field v-model="value" is-error :max="10" :min="0">
    <admin-number-field-content>
      <admin-number-field-decrement />
      <admin-number-field-input />
      <admin-number-field-increment />
    </admin-number-field-content>
  </admin-number-field>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-number-field v-model="value">
    <admin-number-field-content>
      <admin-number-field-decrement />
      <admin-number-field-input />
      <admin-number-field-increment />
    </admin-number-field-content>
  </admin-number-field>
</template>
```

### admin-number-field

::div{data-admin-api-table=""}
#### Props

| 名稱                   | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| -------------------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `defaultValue`       | `number | undefined`                       | —       | —                                                                                                                                                                                                            |
| `modelValue`         | `number | null | undefined`                | —       | —                                                                                                                                                                                                            |
| `min`                | `number | undefined`                       | —       | The smallest value allowed for the input.                                                                                                                                                                    |
| `max`                | `number | undefined`                       | —       | The largest value allowed for the input.                                                                                                                                                                     |
| `step`               | `number | undefined`                       | —       | The amount that the input value changes with each increment or decrement "tick".                                                                                                                             |
| `stepSnapping`       | `boolean | undefined`                      | —       | When \`false\`, prevents the value from snapping to the nearest increment of the step value                                                                                                                  |
| `focusOnChange`      | `boolean | undefined`                      | —       | When \`true\`, the input will be focused when the value changes.                                                                                                                                             |
| `formatOptions`      | `Intl.NumberFormatOptions | undefined`     | —       | Formatting options for the value displayed in the number field. This also affects what characters are allowed to be typed by the user.                                                                       |
| `locale`             | `string | undefined`                       | —       | The locale to use for formatting and currencies                                                                                                                                                              |
| `disabled`           | `boolean | undefined`                      | —       | When \`true\`, prevents the user from interacting with the Number Field.                                                                                                                                     |
| `readonly`           | `boolean | undefined`                      | —       | When \`true\`, the Number Field is read-only.                                                                                                                                                                |
| `disableWheelChange` | `boolean | undefined`                      | —       | When \`true\`, prevents the value from changing on wheel scroll.                                                                                                                                             |
| `invertWheelChange`  | `boolean | undefined`                      | —       | When \`true\`, inverts the direction of the wheel change.                                                                                                                                                    |
| `id`                 | `string | undefined`                       | —       | Id of the element                                                                                                                                                                                            |
| `asChild`            | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`                 | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `name`               | `string | undefined`                       | —       | The name of the field. Submitted with its owning form as part of a name/value pair.                                                                                                                          |
| `required`           | `boolean | undefined`                      | —       | When \`true\`, indicates that the user must set the value before the owning form can be submitted.                                                                                                           |
| `class`              | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |
| `isError`            | `boolean | undefined`                      | —       | 設為 \`true\` 時掛上 \`data-is-error\` 屬性供樣式 hook                                                                                                                                                                 |

#### Events

| 名稱                  | Payload  | 說明 |
| ------------------- | -------- | -- |
| `update:modelValue` | `number` | —  |

#### Slots

| 名稱        | Bindings                                                                    | 說明 |
| --------- | --------------------------------------------------------------------------- | -- |
| `default` | `{ modelValue: number | undefined; textValue: string; readonly: boolean; }` | —  |
::

### admin-number-field-content

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-number-field-input

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |
::

### admin-number-field-increment

::div{data-admin-api-table=""}
#### Props

| 名稱         | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| ---------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `disabled` | `boolean | undefined`                      | —       | —                                                                                                                                                                                                            |
| `asChild`  | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`       | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`    | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-number-field-decrement

::div{data-admin-api-table=""}
#### Props

| 名稱         | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| ---------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `disabled` | `boolean | undefined`                      | —       | —                                                                                                                                                                                                            |
| `asChild`  | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`       | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`    | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

## 更新紀錄

:admin-changelog{component="AdminNumberField"}


# Overlay

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/overlay
```

```ts
import { AdminOverlayProvider, useOverlay } from '@/components/admin/overlay'
```

於 app root（通常是 `app.vue`）掛載 `admin-overlay-provider` 一次；後續以共用 `useOverlay()` 建立的 overlay 會自動註冊到此 provider：

```vue [app.vue]
<script setup lang="ts">
import { AdminOverlayProvider } from '@/components/admin/overlay'
</script>

<template>
  <nuxt-layout>
    <nuxt-page />
  </nuxt-layout>
  <admin-overlay-provider />
</template>
```

## 用法

```vue
<script setup lang="ts">
import { useOverlay } from '@/components/admin/overlay'
import PublishReleaseDialog from '~/components/publish-release-dialog.vue'

const overlay = useOverlay()
const confirmDialog = overlay.create(PublishReleaseDialog, {
  props: {
    title: 'Publish this release?',
    message: 'Confirm before shipping changes to production.',
  },
})

async function handlePublish() {
  const result = await confirmDialog.open()

  if (result === 'confirmed') {
    // continue the workflow
  }
}
</script>
```

## 場景

### 基本開啟流程

觸發 overlay 並在當下根據回傳值處理。

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminButton } from '@/registry/admin/ui/button'
import { useOverlay } from '@/registry/admin/ui/overlay'
import OverlayConfirmDialog from './dialog/overlay-confirm-dialog.vue'

const overlay = useOverlay()
const lastResult = ref('No result yet.')

const confirmDialog = overlay.create(OverlayConfirmDialog, {
  props: {
    title: 'Publish this release?',
    message: 'Confirm or cancel to see the value resolved by the overlay.'
  }
})

function openOverlay() {
  lastResult.value = 'Waiting for a response...'
  confirmDialog.open().then((value) => {
    lastResult.value = value ?? 'dismissed'
  })
}
</script>

<template>
  <div class="flex w-full max-w-md flex-col gap-4">
    <admin-button class="self-start" @click="openOverlay">Open overlay</admin-button>
    <p class="text-sm text-text-60">Last result: {{ lastResult }}</p>
  </div>
</template>
```

### 等待結果回傳

呼叫端需要等使用者 confirm／cancel 後再繼續。

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminButton } from '@/registry/admin/ui/button'
import { useOverlay } from '@/registry/admin/ui/overlay'
import OverlayConfirmDialog from './dialog/overlay-confirm-dialog.vue'

const overlay = useOverlay()
const resolution = ref('No promise resolved yet.')

const confirmDialog = overlay.create(OverlayConfirmDialog, {
  props: {
    title: 'Archive this item?',
    message: 'Await the overlay result to continue the workflow in the same action handler.'
  }
})

async function openWithPromise() {
  resolution.value = 'Awaiting user input...'
  const result = await confirmDialog.open()
  resolution.value = result ?? 'dismissed'
}
</script>

<template>
  <div class="flex w-full max-w-md flex-col gap-4">
    <admin-button class="self-start" variant="outline" @click="openWithPromise">
      Await overlay promise
    </admin-button>
    <p class="text-sm text-text-60">Resolved value: {{ resolution }}</p>
  </div>
</template>
```

### 重用同一個 overlay 並覆寫 props

多個按鈕共用同一個 overlay component、每次 `open()` 直接傳入要覆寫的 props 即可替換文案。

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminButton } from '@/registry/admin/ui/button'
import { useOverlay } from '@/registry/admin/ui/overlay'
import OverlayConfirmDialog from './dialog/overlay-confirm-dialog.vue'

const overlay = useOverlay()
const activeScenario = ref('Choose a scenario to patch the dialog props before opening it.')

const confirmDialog = overlay.create(OverlayConfirmDialog, {
  props: {
    title: 'Default confirmation',
    message: 'Patch the dialog props before each open call to reuse one overlay instance.'
  }
})

function openDangerScenario() {
  activeScenario.value = 'Danger scenario is active.'
  confirmDialog.open({
    title: 'Delete this member?',
    message: 'This action cannot be undone once the overlay closes.'
  })
}

function openSafeScenario() {
  activeScenario.value = 'Safe scenario is active.'
  confirmDialog.open({
    title: 'Save a draft instead?',
    message: 'Reuse the same overlay instance with calmer copy for a lower-risk path.'
  })
}
</script>

<template>
  <div class="flex w-full max-w-md flex-col gap-4">
    <div class="flex flex-wrap gap-3">
      <admin-button class="self-start" @click="openDangerScenario"
        >Open danger scenario</admin-button
      >
      <admin-button class="self-start" variant="outline" @click="openSafeScenario">
        Open safe scenario
      </admin-button>
    </div>
    <p class="text-sm text-text-60">{{ activeScenario }}</p>
  </div>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-overlay-provider />
</template>
```

`admin-overlay-provider` 須在 app root 掛載一次；

### admin-overlay-provider

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別        | 預設值 | 說明 |
| ------- | --------- | --- | -- |
| `class` | `unknown` | —   | —  |
::

## 更新紀錄

:admin-changelog{component="AdminOverlay"}


# Pagination

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/pagination
```

```ts
import {
  AdminPagination,
  AdminPaginationContent,
  AdminPaginationEllipsis,
  AdminPaginationFirst,
  AdminPaginationInfo,
  AdminPaginationItem,
  AdminPaginationLast,
  AdminPaginationNext,
  AdminPaginationPerPage,
  AdminPaginationPrevious,
} from '@/components/admin/pagination'
```

## 用法

```vue
<script setup lang="ts">
import { ref } from 'vue'
import {
  AdminPagination,
  AdminPaginationContent,
  AdminPaginationEllipsis,
  AdminPaginationItem,
  AdminPaginationNext,
  AdminPaginationPrevious
} from '@/registry/admin/ui/pagination'

const page = ref(1)
</script>

<template>
  <admin-pagination
    v-model:page="page"
    :items-per-page="10"
    :show-edges="true"
    :sibling-count="1"
    :total="100"
  >
    <admin-pagination-content v-slot="{ items }">
      <admin-pagination-previous />
      <template v-for="(item, idx) in items" :key="idx">
        <admin-pagination-item v-if="item.type === 'page'" :value="item.value">{{
          item.value
        }}</admin-pagination-item>
        <admin-pagination-ellipsis v-else />
      </template>
      <admin-pagination-next />
    </admin-pagination-content>
  </admin-pagination>
</template>
```

## 場景

### 完整樣式（含資訊 + 每頁筆數）

```vue
<script setup lang="ts">
import { ref, watch } from 'vue'
import {
  AdminPagination,
  AdminPaginationContent,
  AdminPaginationEllipsis,
  AdminPaginationFirst,
  AdminPaginationInfo,
  AdminPaginationItem,
  AdminPaginationLast,
  AdminPaginationNext,
  AdminPaginationPerPage,
  AdminPaginationPrevious
} from '@/registry/admin/ui/pagination'

const page = ref(3)
const itemsPerPage = ref(10)

watch(itemsPerPage, () => {
  page.value = 1
})
</script>

<template>
  <admin-pagination v-model:items-per-page="itemsPerPage" v-model:page="page" :total="235">
    <admin-pagination-info :total="235" />
    <admin-pagination-content v-slot="{ items }">
      <admin-pagination-first />
      <admin-pagination-previous />
      <template v-for="(item, index) in items" :key="index">
        <admin-pagination-item v-if="item.type === 'page'" :value="item.value">
          {{ item.value }}
        </admin-pagination-item>
        <admin-pagination-ellipsis v-else :index="index" />
      </template>
      <admin-pagination-next />
      <admin-pagination-last />
    </admin-pagination-content>
    <admin-pagination-per-page v-model="itemsPerPage" :options="[10, 20, 50, 100]" />
  </admin-pagination>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-pagination v-model:page="page" :items-per-page="perPage" :total="total">
    <admin-pagination-content>
      <admin-pagination-first />
      <admin-pagination-previous />
      <admin-pagination-item :value="1" />
      <admin-pagination-ellipsis />
      <admin-pagination-next />
      <admin-pagination-last />
    </admin-pagination-content>
    <admin-pagination-info />
    <admin-pagination-per-page v-model="perPage" />
  </admin-pagination>
</template>
```

### admin-pagination

::div{data-admin-api-table=""}
#### Props

| 名稱               | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| ---------------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `page`           | `number | undefined`                       | —       | The controlled value of the current page. Can be binded as \`v-model\:page\`.                                                                                                                                |
| `defaultPage`    | `number | undefined`                       | —       | The value of the page that should be active when initially rendered.\<br>Use when you do not need to control the value state.                                                                                |
| `itemsPerPage`\* | `number`                                   | —       | Number of items per page                                                                                                                                                                                     |
| `total`          | `number | undefined`                       | —       | Number of items in your list                                                                                                                                                                                 |
| `siblingCount`   | `number | undefined`                       | —       | Number of sibling should be shown around the current page                                                                                                                                                    |
| `disabled`       | `boolean | undefined`                      | —       | When \`true\`, prevents the user from interacting with item                                                                                                                                                  |
| `showEdges`      | `boolean | undefined`                      | —       | When \`true\`, always show first page, last page, and ellipsis                                                                                                                                               |
| `asChild`        | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`             | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`          | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

*\\\* 代表必填*

#### Events

| 名稱            | Payload  | 說明 |
| ------------- | -------- | -- |
| `update:page` | `number` | —  |

#### Slots

| 名稱        | Bindings                               | 說明 |
| --------- | -------------------------------------- | -- |
| `default` | `{ page: number; pageCount: number; }` | —  |
::

### admin-pagination-item

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `value`\* | `number`                                   | —       | Value for the page                                                                                                                                                                                           |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

*\\\* 代表必填*

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-pagination-info

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別                   | 預設值 | 說明           |
| ------- | -------------------- | --- | ------------ |
| `total` | `number | undefined` | —   | 顯示總筆數        |
| `class` | `ClassValue`         | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings                                             | 說明 |
| --------- | ---------------------------------------------------- | -- |
| `default` | `{ pageCount: number; total?: number | undefined; }` | —  |
::

### admin-pagination-per-page

::div{data-admin-api-table=""}
#### Props

| 名稱             | 型別                                        | 預設值                 | 說明               |
| -------------- | ----------------------------------------- | ------------------- | ---------------- |
| `options`      | `number[] | undefined`                    | `[10, 20, 50, 100]` | 每頁筆數選項           |
| `labelFormat`  | `((value: number) => string) | undefined` | —                   | 自訂選項 label 格式化函式 |
| `class`        | `ClassValue`                              | —                   | 根元素之自訂 class     |
| `modelValue`\* | `number`                                  | —                   | —                |

*\\\* 代表必填*

#### Events

| 名稱                  | Payload  | 說明 |
| ------------------- | -------- | -- |
| `update:modelValue` | `number` | —  |
::

### admin-pagination-content

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings                                                                   | 說明 |
| --------- | -------------------------------------------------------------------------- | -- |
| `default` | `{ items: ({ type: "ellipsis"; } | { type: "page"; value: number; })[]; }` | —  |
::

### admin-pagination-ellipsis

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-pagination-first

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-pagination-last

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-pagination-next

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-pagination-previous

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

## 更新紀錄

:admin-changelog{component="AdminPagination"}


# Pdf Viewer

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/pdf-viewer
```

```ts
import {
  AdminPdfViewer,
  AdminPdfViewerFullscreen,
  AdminPdfViewerPageNav,
  AdminPdfViewerPages,
  AdminPdfViewerToolbar,
  AdminPdfViewerZoom
} from '@/components/admin/pdf-viewer'
```

## 用法

```vue
<script setup lang="ts">
import { AdminPdfViewer } from '@/registry/admin/ui/pdf-viewer'
</script>

<template>
  <admin-pdf-viewer class="h-[640px] w-full" src="https://snippet.embedpdf.com/ebook.pdf" />
</template>
```

## 場景

### 自訂 toolbar 組合

```vue
<script setup lang="ts">
import {
  AdminPdfViewer,
  AdminPdfViewerPageNav,
  AdminPdfViewerPages,
  AdminPdfViewerToolbar,
  AdminPdfViewerZoom
} from '@/registry/admin/ui/pdf-viewer'
</script>

<template>
  <admin-pdf-viewer class="h-[640px] w-full" src="https://snippet.embedpdf.com/ebook.pdf">
    <admin-pdf-viewer-pages />
    <admin-pdf-viewer-toolbar>
      <template #left>
        <admin-pdf-viewer-page-nav />
      </template>
      <template #right>
        <admin-pdf-viewer-zoom />
      </template>
    </admin-pdf-viewer-toolbar>
  </admin-pdf-viewer>
</template>
```

### 外部控制當前頁

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminButton } from '@/registry/admin/ui/button'
import { AdminPdfViewer } from '@/registry/admin/ui/pdf-viewer'

const page = ref<number | undefined>(1)
</script>

<template>
  <div class="flex w-full min-w-0 flex-col gap-3">
    <div class="flex items-center gap-2">
      <admin-button size="small" variant="outline" @click="page = 1">回到首頁</admin-button>
      <admin-button size="small" variant="outline" @click="page = (page ?? 1) + 1"
        >前進 1 頁</admin-button
      >
      <span class="text-sm text-text-70">外部當前頁：{{ page }}</span>
    </div>
    <admin-pdf-viewer
      v-model:page="page"
      class="h-[560px] w-full"
      src="https://snippet.embedpdf.com/ebook.pdf"
    />
  </div>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-pdf-viewer src="...">
    <admin-pdf-viewer-pages />
    <admin-pdf-viewer-toolbar>
      <admin-pdf-viewer-page-nav />
      <admin-pdf-viewer-zoom />
      <admin-pdf-viewer-fullscreen />
    </admin-pdf-viewer-toolbar>
  </admin-pdf-viewer>
</template>
```

### admin-pdf-viewer

::div{data-admin-api-table=""}
#### Props

| 名稱            | 型別                   | 預設值 | 說明                   |
| ------------- | -------------------- | --- | -------------------- |
| `src`\*       | `string`             | —   | PDF 檔案 URL（必填）       |
| `defaultPage` | `number | undefined` | `1` | uncontrolled 模式之初始頁碼 |
| `defaultZoom` | `number | undefined` | —   | 初始縮放百分比              |
| `class`       | `ClassValue`         | —   | 根元素之自訂 class         |
| `page`        | `number | undefined` | —   | —                    |

*\\\* 代表必填*

#### Events

| 名稱            | Payload              | 說明                                 |
| ------------- | -------------------- | ---------------------------------- |
| `error`       | `Error`              | 載入或渲染發生錯誤時觸發                       |
| `load`        | `string`             | PDF 載入完成時觸發，payload 為內部 documentId |
| `update:page` | `number | undefined` | —                                  |
| `pageChange`  | `number`             | 當前頁碼變更時觸發                          |
| `zoomChange`  | `number`             | 縮放百分比變更時觸發                         |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-pdf-viewer-toolbar

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱      | Bindings | 說明 |
| ------- | -------- | -- |
| `left`  | `{}`     | —  |
| `right` | `{}`     | —  |
::

### admin-pdf-viewer-pages

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |
::

### admin-pdf-viewer-fullscreen

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別        | 預設值 | 說明 |
| ------- | --------- | --- | -- |
| `class` | `unknown` | —   | —  |
::

### admin-pdf-viewer-page-nav

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別        | 預設值 | 說明 |
| ------- | --------- | --- | -- |
| `class` | `unknown` | —   | —  |
::

### admin-pdf-viewer-zoom

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別        | 預設值 | 說明 |
| ------- | --------- | --- | -- |
| `class` | `unknown` | —   | —  |
::

## 注意事項

- **不支援 SSR**：PDFium 引擎依賴 WebAssembly 與 Web Worker；元件殼不含 `<ClientOnly>`。Nuxt 請自行以 `<ClientOnly>` 包覆（可加 `#fallback` loading）；純 CSR 不需處理。見 [安裝 · SSR](https://component-registry-4d4d86.gitlab.io/docs/get-started/installation#ssr-nuxt)。PDF 內容不會出現於 server-rendered HTML，無法 SEO。
- **首次掛載需下載 PDFium wasm**：載入時間視網路而定，預期延遲約數百毫秒到數秒；下載期間顯示既有 `admin-loading` 元件。
- **wasm 二進位來源**：PDF 解析使用 PDFium WebAssembly，預設由 EmbedPDF 官方 CDN 動態載入。若部署於離線環境、封閉內網，或資安政策禁止外部 CDN，需自行 host `.wasm` 檔並於 `usePdfiumEngine` 設定中指定來源（參數名請參考 EmbedPDF 文件）。
- **父容器需有明確寬度**：放大時 PDF 頁面可能比 viewer 寬，內部 viewport 自動水平捲動。若元件包在無寬度約束的 flex item（例如 `<div class="flex flex-col gap-3">`）內，PDF 寬度會推擠父容器；需在父 wrapper 加 `w-full` 或 `min-w-0` 確保 viewer 寬度受控。

## 更新紀錄

:admin-changelog{component="AdminPdfViewer"}


# Progress

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/progress
```

```ts
import { AdminProgress } from '@/components/admin/progress'
```

## 用法

```vue
<script setup lang="ts">
import { AdminProgress } from '@/registry/admin/ui/progress'
</script>

<template>
  <admin-progress class="w-64" :model-value="60" />
</template>
```

## 場景

### 動態進度

以 interval 或事件來源更新 `model-value`，進度條會平滑過渡。

```vue
<script setup lang="ts">
import { onMounted, onUnmounted, ref } from 'vue'
import { AdminProgress } from '@/registry/admin/ui/progress'

const value = ref(0)
let timer: ReturnType<typeof setInterval> | null = null

onMounted(() => {
  timer = setInterval(() => {
    value.value = (value.value + 10) % 110
  }, 800)
})

onUnmounted(() => {
  if (timer) {
    clearInterval(timer)
  }
})
</script>

<template>
  <div class="flex w-72 flex-col gap-2">
    <admin-progress :model-value="value" />
    <span class="typo-caption-small text-text-60">{{ value }}%</span>
  </div>
</template>
```

### 多項進度列表

```vue
<script setup lang="ts">
import { AdminProgress } from '@/registry/admin/ui/progress'

const steps = [
  { label: '上傳完成', value: 100 },
  { label: '處理中', value: 60 },
  { label: '等待中', value: 20 }
]
</script>

<template>
  <div class="flex w-72 flex-col gap-4">
    <div v-for="step in steps" :key="step.label" class="flex flex-col gap-1">
      <div class="flex items-center justify-between typo-caption-small">
        <span>{{ step.label }}</span>
        <span class="text-text-60">{{ step.value }}%</span>
      </div>
      <admin-progress :model-value="step.value" />
    </div>
  </div>
</template>
```

### 不確定進度

當進度總量未知時，傳入 `model-value="null"` 進入 indeterminate 狀態：進度條顯示不確定動畫並隱藏百分比文字（此時 `show-value` 不生效）。待取得實際進度後再改回數值即可。

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminButton } from '@/registry/admin/ui/button'
import { AdminProgress } from '@/registry/admin/ui/progress'

const value = ref<number | null>(null)

function toggle() {
  value.value = value.value === null ? 40 : null
}
</script>

<template>
  <div class="flex w-72 flex-col gap-3">
    <admin-progress :model-value="value" />
    <admin-button class="self-start" @click="toggle">
      {{ value === null ? '設為 40%' : '設為 indeterminate' }}
    </admin-button>
  </div>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-progress :model-value="value" />
</template>
```

### admin-progress

::div{data-admin-api-table=""}
#### Props

| 名稱              | 型別                                                                                    | 預設值     | 說明                                                                                                                                                                                                           |
| --------------- | ------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `modelValue`    | `number | null | undefined`                                                           | `0`     | The progress value. Can be bind as \`v-model\`.\<br>進度值。傳入 \`null\` 表示 indeterminate（進度未知），此時顯示不確定動畫並隱藏百分比文字。                                                                                                |
| `max`           | `number | undefined`                                                                  | —       | The maximum progress value.                                                                                                                                                                                  |
| `getValueLabel` | `((value: number | null | undefined, max: number) => string | undefined) | undefined` | —       | A function to get the accessible label text in a human-readable format.\<br> If not provided, the value label will be read as the numeric value as a percentage of the max value.                            |
| `getValueText`  | `((value: number | null | undefined, max: number) => string | undefined) | undefined` | —       | A function to get the accessible value text representing the current value in a human-readable format.                                                                                                       |
| `asChild`       | `boolean | undefined`                                                                 | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`            | `globalThis.Component | AsTag | undefined`                                            | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`         | `ClassValue`                                                                          | —       | 根元素之自訂 class                                                                                                                                                                                                 |
| `showValue`     | `boolean | undefined`                                                                 | `true`  | 設為 \`false\` 時隱藏中央百分比文字                                                                                                                                                                                      |
::

## 更新紀錄

:admin-changelog{component="AdminProgress"}


# Radio Group

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/radio-group
```

```ts
import {
  AdminRadioGroup,
  AdminRadioGroupItem,
  AdminRadioOption,
} from '@/components/admin/radio-group'
```

## 用法

```vue
<script setup lang="ts">
import type { AcceptableValue } from 'reka-ui'
import { ref } from 'vue'
import { AdminRadioGroup, AdminRadioOption } from '@/registry/admin/ui/radio-group'

const value = ref<AcceptableValue>('one')
</script>

<template>
  <admin-radio-group v-model="value" class="flex flex-col gap-2">
    <admin-radio-option label="Option one" value="one" />
    <admin-radio-option label="Option two" value="two" />
  </admin-radio-group>
</template>
```

## 場景

### 多選項群組

```vue
<script setup lang="ts">
import type { AcceptableValue } from 'reka-ui'
import { ref } from 'vue'
import { AdminRadioGroup, AdminRadioOption } from '@/registry/admin/ui/radio-group'

const value = ref<AcceptableValue>('standard')
</script>

<template>
  <admin-radio-group v-model="value" class="flex flex-col gap-2">
    <admin-radio-option label="標準方案" value="standard" />
    <admin-radio-option label="進階方案" value="pro" />
    <admin-radio-option label="企業方案" value="enterprise" />
  </admin-radio-group>
</template>
```

### 停用狀態

```vue
<script setup lang="ts">
import type { AcceptableValue } from 'reka-ui'
import { ref } from 'vue'
import { AdminRadioGroup, AdminRadioOption } from '@/registry/admin/ui/radio-group'

const value = ref<AcceptableValue>('one')
</script>

<template>
  <admin-radio-group v-model="value" class="flex flex-col gap-2">
    <admin-radio-option label="可選項 1" value="one" />
    <admin-radio-option label="可選項 2" value="two" />
    <admin-radio-option label="停用項目" value="three" disabled />
  </admin-radio-group>
</template>
```

## Type-safe 封裝

`AdminRadioGroup` 的 `modelValue` 為 reka-ui 的 `AcceptableValue`，選項則由呼叫端自行放置 `admin-radio-option`，兩者在 compile-time 不會對齊。

若需要讓 `v-model` 與選項 `value` 的 literal union 對齊，可自行封裝：傳入 `options`（建議加 `as const`），由封裝元件渲染 `admin-radio-option`。

範例：

```vue
<script
  setup
  lang="ts"
  generic="
    TOptions extends ReadonlyArray<{
      label: string
      value: AcceptableValue
    }>
  "
>
import type { AcceptableValue } from 'reka-ui'
import type { AdminRadioGroupEmits, AdminRadioGroupProps } from '@/registry/admin/ui/radio-group'
import { reactiveOmit } from '@vueuse/core'
import { useForwardPropsEmits } from 'reka-ui'
import { computed } from 'vue'
import { AdminRadioGroup, AdminRadioOption } from '@/registry/admin/ui/radio-group'

type TModelValue = TOptions[number]['value']

defineOptions({
  name: 'typed-admin-radio-group'
})

const props = defineProps<
  Omit<AdminRadioGroupProps, 'modelValue' | 'defaultValue'> & {
    options: TOptions
    modelValue?: TModelValue
    defaultValue?: TModelValue
  }
>()

const emits = defineEmits<
  Omit<AdminRadioGroupEmits, 'update:modelValue'> & {
    'update:modelValue': [value: TModelValue]
  }
>()

const delegatedProps = reactiveOmit(props, 'modelValue', 'options')
const forwardedAll = useForwardPropsEmits(delegatedProps, emits)

const forwarded = computed(() => {
  const { 'onUpdate:modelValue': _, ...rest } = forwardedAll.value
  return rest
})

const innerValue = computed<AcceptableValue | undefined>({
  get() {
    return props.modelValue
  },
  set(value) {
    emits('update:modelValue', value as TModelValue)
  }
})
</script>

<template>
  <admin-radio-group v-bind="forwarded" v-model="innerValue">
    <admin-radio-option
      v-for="(option, index) in props.options"
      :key="`${option.value}-${index}`"
      :label="option.label"
      :value="option.value"
    />
  </admin-radio-group>
</template>
```

::alert{title="需開啟 strictVModel" type="info"}
型別檢查需開啟 `strictVModel`（若已開啟 `strictTemplates` 則已包含）。設定見 [Type-safe](https://component-registry-4d4d86.gitlab.io/docs/get-started/type-safe)。下列同時含合法綁定與刻意錯誤綁定；錯誤處以 `@vue-expect-error` 標示。
::

```vue
<script setup lang="ts">
import { ref } from 'vue'
import TypedAdminRadioGroup from './typed-admin-radio-group-demo.vue'

const options = [
  { label: 'Draft', value: 'draft' },
  { label: 'Published', value: 'published' }
] as const

const status = ref<(typeof options)[number]['value']>('draft')
const wrong = ref('unknown')
</script>

<template>
  <div class="flex w-full max-w-md flex-col gap-6">
    <typed-admin-radio-group v-model="status" class="flex flex-col gap-2" :options="options" />

    <!-- @vue-expect-error value 不在 options 的 value union 內 -->
    <typed-admin-radio-group v-model="wrong" class="flex flex-col gap-2" :options="options" />
  </div>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-radio-group v-model="value">
    <admin-radio-option
      v-for="option in options"
      :key="option.value"
      :label="option.label"
      :value="option.value"
    />
  </admin-radio-group>
</template>
```

### admin-radio-group

::div{data-admin-api-table=""}
#### Props

| 名稱             | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| -------------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `modelValue`   | `AcceptableValue | undefined`              | —       | The controlled value of the radio item to check. Can be binded as \`v-model\`.                                                                                                                               |
| `defaultValue` | `AcceptableValue | undefined`              | —       | The value of the radio item that should be checked when initially rendered.\<br>Use when you do not need to control the state of the radio items.                                                            |
| `disabled`     | `boolean | undefined`                      | —       | When \`true\`, prevents the user from interacting with radio items.                                                                                                                                          |
| `orientation`  | `DataOrientation | undefined`              | —       | The orientation of the component.                                                                                                                                                                            |
| `dir`          | `Direction | undefined`                    | —       | The reading direction of the combobox when applicable. \<br> If omitted, inherits globally from \`ConfigProvider\` or assumes LTR (left-to-right) reading mode.                                              |
| `loop`         | `boolean | undefined`                      | —       | When \`true\`, keyboard navigation will loop from last item to first, and vice versa.                                                                                                                        |
| `asChild`      | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`           | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `name`         | `string | undefined`                       | —       | The name of the field. Submitted with its owning form as part of a name/value pair.                                                                                                                          |
| `required`     | `boolean | undefined`                      | —       | When \`true\`, indicates that the user must set the value before the owning form can be submitted.                                                                                                           |
| `class`        | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |
| `isError`      | `boolean | undefined`                      | —       | 預留之錯誤狀態旗標（目前無對應視覺實作）                                                                                                                                                                                         |

#### Events

| 名稱                  | Payload           | 說明 |
| ------------------- | ----------------- | -- |
| `update:modelValue` | `AcceptableValue` | —  |

#### Slots

| 名稱        | Bindings                                       | 說明 |
| --------- | ---------------------------------------------- | -- |
| `default` | `{ modelValue: AcceptableValue | undefined; }` | —  |
::

### admin-radio-group-item

::div{data-admin-api-table=""}
#### Props

| 名稱         | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| ---------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`       | `string | undefined`                       | —       | —                                                                                                                                                                                                            |
| `as`       | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `asChild`  | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `required` | `boolean | undefined`                      | —       | When \`true\`, indicates that the user must set the value before the owning form can be submitted.                                                                                                           |
| `disabled` | `boolean | undefined`                      | —       | When \`true\`, prevents the user from interacting with the radio item.                                                                                                                                       |
| `name`     | `string | undefined`                       | —       | The name of the field. Submitted with its owning form as part of a name/value pair.                                                                                                                          |
| `value`    | `AcceptableValue | undefined`              | —       | The value given as data when submitted with a \`name\`.                                                                                                                                                      |
| `class`    | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-radio-option

::div{data-admin-api-table=""}
#### Props

| 名稱           | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| ------------ | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`         | `string | undefined`                       | —       | —                                                                                                                                                                                                            |
| `as`         | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `asChild`    | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `required`   | `boolean | undefined`                      | —       | When \`true\`, indicates that the user must set the value before the owning form can be submitted.                                                                                                           |
| `disabled`   | `boolean | undefined`                      | —       | When \`true\`, prevents the user from interacting with the radio item.                                                                                                                                       |
| `name`       | `string | undefined`                       | —       | The name of the field. Submitted with its owning form as part of a name/value pair.                                                                                                                          |
| `value`      | `AcceptableValue | undefined`              | —       | The value given as data when submitted with a \`name\`.                                                                                                                                                      |
| `label`      | `string | undefined`                       | —       | 顯示於選項旁之文字標籤；不設則不渲染 label                                                                                                                                                                                     |
| `class`      | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |
| `labelClass` | `ClassValue`                               | —       | label 文字之自訂 class                                                                                                                                                                                            |
::

## 更新紀錄

:admin-changelog{component="AdminRadioGroup"}


# Scroll Area

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/scroll-area
```

```ts
import { AdminScrollArea, AdminScrollBar } from '@/components/admin/scroll-area'
```

## 用法

```vue
<script setup lang="ts">
import { AdminScrollArea } from '@/registry/admin/ui/scroll-area'
const count = 20
</script>

<template>
  <admin-scroll-area class="h-48 w-64 rounded-[8px] border p-3">
    <p v-for="i in count" :key="i" class="typo-content-medium">Row {{ i }}</p>
  </admin-scroll-area>
</template>
```

## 場景

### 水平捲動

```vue
<script setup lang="ts">
import { cn } from '@/lib/utils'
import { AdminScrollArea, AdminScrollBar } from '@/registry/admin/ui/scroll-area'
</script>

<template>
  <admin-scroll-area class="w-80 rounded-md border">
    <div class="flex gap-3 p-3">
      <div
        v-for="i in 12"
        :key="i"
        :class="
          cn(`
            flex h-24 w-32 shrink-0 items-center justify-center rounded-md bg-bg-80
            typo-content-medium
          `)
        "
      >
        Card {{ i }}
      </div>
    </div>
    <admin-scroll-bar orientation="horizontal" />
  </admin-scroll-area>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-scroll-area>
    內容
  </admin-scroll-area>
</template>
```

### admin-scroll-area

::div{data-admin-api-table=""}
#### Props

| 名稱                | 型別                                         | 預設值     | 說明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ----------------- | ------------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `class`           | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `type`            | `ScrollType | undefined`                   | —       | Describes the nature of scrollbar visibility, similar to how the scrollbar preferences in MacOS control visibility of native scrollbars.\<br>\`auto\` - means that scrollbars are visible when content is overflowing on the corresponding orientation. \<br>\`always\` - means that scrollbars are always visible regardless of whether the content is overflowing.\<br>\`scroll\` - means that scrollbars are visible when the user is scrolling along its corresponding orientation.\<br>\`hover\` - when the user is scrolling along its corresponding orientation and when the user is hovering over the scroll area.\<br>\`glimpse\` - a hybrid approach that briefly shows scrollbars when the user enters the scroll area, then hides them until further interaction. |
| `dir`             | `Direction$2 | undefined`                  | —       | The reading direction of the combobox when applicable. \<br> If omitted, inherits globally from \`ConfigProvider\` or assumes LTR (left-to-right) reading mode.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `scrollHideDelay` | `number | undefined`                       | —       | If type is set to either \`scroll\` or \`hover\`, this prop determines the length of time, in milliseconds, \<br> before the scrollbars are hidden after the user stops interacting with scrollbars.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `asChild`         | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `as`              | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-scroll-bar

::div{data-admin-api-table=""}
#### Props

| 名稱            | 型別                                         | 預設值          | 說明                                                                                                                                                                                                           |
| ------------- | ------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `orientation` | `"horizontal" | "vertical" | undefined`    | `"vertical"` | The orientation of the scrollbar                                                                                                                                                                             |
| `forceMount`  | `boolean | undefined`                      | —            | Used to force mounting when more control is needed. Useful when\<br>controlling animation with Vue animation libraries.                                                                                      |
| `asChild`     | `boolean | undefined`                      | —            | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`          | `globalThis.Component | AsTag | undefined` | `"div"`      | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`       | `ClassValue`                               | —            | 根元素之自訂 class                                                                                                                                                                                                 |
::

## 更新紀錄

:admin-changelog{component="AdminScrollArea"}


# Select

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/select
```

```ts
import {
  AdminSelect,
  AdminSelectAnchor,
  AdminSelectCancel,
  AdminSelectCounter,
  AdminSelectEmpty,
  AdminSelectGroup,
  AdminSelectIcon,
  AdminSelectInput,
  AdminSelectItem,
  AdminSelectItemIndicator,
  AdminSelectList,
  AdminSelectSeparator,
  AdminSelectTags,
  AdminSelectTrigger,
  AdminSelectValue,
  AdminSelectViewport,
} from '@/components/admin/select'
```

## 用法

```vue
<script setup lang="ts">
import { ref } from 'vue'
import {
  AdminSelect,
  AdminSelectAnchor,
  AdminSelectIcon,
  AdminSelectItem,
  AdminSelectList,
  AdminSelectTrigger,
  AdminSelectValue,
  AdminSelectViewport
} from '@/registry/admin/ui/select'

const options = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
  { label: 'Cherry', value: 'cherry' }
] as const

type Fruit = (typeof options)[number]

const value = ref<Fruit>()
</script>

<template>
  <admin-select v-model="value" by="value" :display-value="(v) => v.label">
    <admin-select-anchor class="w-60">
      <admin-select-trigger>
        <admin-select-value placeholder="選擇水果" />
        <admin-select-icon />
      </admin-select-trigger>
    </admin-select-anchor>
    <admin-select-list>
      <admin-select-viewport>
        <admin-select-item v-for="option in options" :key="option.value" :value="option">
          {{ option.label }}
        </admin-select-item>
      </admin-select-viewport>
    </admin-select-list>
  </admin-select>
</template>
```

## 場景

### 多選

```vue
<script setup lang="ts">
import { ref } from 'vue'
import {
  AdminSelect,
  AdminSelectAnchor,
  AdminSelectCounter,
  AdminSelectIcon,
  AdminSelectItem,
  AdminSelectList,
  AdminSelectTags,
  AdminSelectTrigger,
  AdminSelectValue,
  AdminSelectViewport
} from '@/registry/admin/ui/select'

interface Tech {
  label: string
  value: string
}

const options: Tech[] = [
  { label: 'Vue', value: 'vue' },
  { label: 'Nuxt', value: 'nuxt' },
  { label: 'Pinia', value: 'pinia' },
  { label: 'VueUse', value: 'vueuse' },
  { label: 'Vite', value: 'vite' }
]

const selected = ref<Tech[]>([options[0]!, options[1]!])

function displayTech(value: Tech) {
  return value.label
}

function onSelectedUpdate(value: Tech | Tech[]) {
  selected.value = Array.isArray(value) ? value : [value]
}
</script>

<template>
  <admin-select
    by="value"
    multiple
    :display-value="displayTech"
    :model-value="selected"
    @update:model-value="onSelectedUpdate"
  >
    <admin-select-anchor class="w-80">
      <admin-select-trigger class="h-auto">
        <admin-select-tags />
        <admin-select-value placeholder="選擇技術" />
        <admin-select-counter />
        <admin-select-icon />
      </admin-select-trigger>
    </admin-select-anchor>
    <admin-select-list>
      <admin-select-viewport>
        <admin-select-item v-for="option in options" :key="option.value" :value="option">
          {{ option.label }}
        </admin-select-item>
      </admin-select-viewport>
    </admin-select-list>
  </admin-select>
</template>
```

### 可搜尋

```vue
<script setup lang="ts">
import { ref } from 'vue'
import {
  AdminSelect,
  AdminSelectAnchor,
  AdminSelectEmpty,
  AdminSelectIcon,
  AdminSelectInput,
  AdminSelectItem,
  AdminSelectList,
  AdminSelectTrigger,
  AdminSelectValue,
  AdminSelectViewport
} from '@/registry/admin/ui/select'

const options = [
  { label: 'Taipei 台北', value: 'tpe' },
  { label: 'Taichung 台中', value: 'txg' },
  { label: 'Tainan 台南', value: 'tnn' },
  { label: 'Kaohsiung 高雄', value: 'khh' },
  { label: 'Hsinchu 新竹', value: 'hsz' },
  { label: 'Taoyuan 桃園', value: 'tyn' },
  { label: 'Hualien 花蓮', value: 'hun' }
] as const

type City = (typeof options)[number]

const value = ref<City>()
</script>

<template>
  <admin-select v-model="value" by="value" :display-value="(v) => v.label">
    <admin-select-anchor class="w-72">
      <admin-select-trigger>
        <admin-select-value placeholder="選擇城市" />
        <admin-select-icon />
      </admin-select-trigger>
    </admin-select-anchor>
    <admin-select-list>
      <admin-select-input placeholder="搜尋城市..." />
      <admin-select-viewport>
        <admin-select-empty>找不到符合的城市</admin-select-empty>
        <admin-select-item v-for="option in options" :key="option.value" :value="option">
          {{ option.label }}
        </admin-select-item>
      </admin-select-viewport>
    </admin-select-list>
  </admin-select>
</template>
```

### 錯誤狀態

```vue
<script setup lang="ts">
import { ref } from 'vue'
import {
  AdminSelect,
  AdminSelectAnchor,
  AdminSelectIcon,
  AdminSelectItem,
  AdminSelectList,
  AdminSelectTrigger,
  AdminSelectValue,
  AdminSelectViewport
} from '@/registry/admin/ui/select'

const options = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
  { label: 'Cherry', value: 'cherry' }
] as const

type Fruit = (typeof options)[number]

const value = ref<Fruit>()
</script>

<template>
  <admin-select v-model="value" by="value" is-error :display-value="(v) => v.label">
    <admin-select-anchor class="w-60">
      <admin-select-trigger>
        <admin-select-value placeholder="選擇水果" />
        <admin-select-icon />
      </admin-select-trigger>
    </admin-select-anchor>
    <admin-select-list>
      <admin-select-viewport>
        <admin-select-item v-for="option in options" :key="option.value" :value="option">
          {{ option.label }}
        </admin-select-item>
      </admin-select-viewport>
    </admin-select-list>
  </admin-select>
</template>
```

### 完整組合

子元件：anchor、trigger（tags／value／counter／icon）、list、input（含 cancel）、viewport、empty、group（heading）、separator、item（含 item-indicator）。

```vue
<script setup lang="ts">
import { ref } from 'vue'
import {
  AdminSelect,
  AdminSelectAnchor,
  AdminSelectCancel,
  AdminSelectCounter,
  AdminSelectEmpty,
  AdminSelectGroup,
  AdminSelectIcon,
  AdminSelectInput,
  AdminSelectItem,
  AdminSelectItemIndicator,
  AdminSelectList,
  AdminSelectSeparator,
  AdminSelectTags,
  AdminSelectTrigger,
  AdminSelectValue,
  AdminSelectViewport
} from '@/registry/admin/ui/select'

interface Tech {
  label: string
  value: string
}

const quickPicks: Tech[] = [
  { label: 'Vue', value: 'vue' },
  { label: 'Nuxt', value: 'nuxt' }
]

const groups: { heading: string; items: Tech[] }[] = [
  {
    heading: '前端',
    items: [
      { label: 'Vite', value: 'vite' },
      { label: 'VueUse', value: 'vueuse' }
    ]
  },
  {
    heading: '後端',
    items: [
      { label: 'Node', value: 'node' },
      { label: 'Nitro', value: 'nitro' },
      { label: 'Prisma', value: 'prisma' }
    ]
  }
]

const selected = ref<Tech[]>([quickPicks[0]!, groups[1]!.items[1]!])

function displayTech(value: Tech) {
  return value.label
}

function onSelectedUpdate(value: Tech | Tech[]) {
  selected.value = Array.isArray(value) ? value : [value]
}
</script>

<template>
  <admin-select
    by="value"
    multiple
    :display-value="displayTech"
    :model-value="selected"
    @update:model-value="onSelectedUpdate"
  >
    <admin-select-anchor class="w-80">
      <admin-select-trigger class="h-auto">
        <admin-select-tags />
        <admin-select-value placeholder="選擇技術棧" />
        <admin-select-counter />
        <admin-select-icon />
      </admin-select-trigger>
    </admin-select-anchor>
    <admin-select-list>
      <admin-select-input placeholder="搜尋...">
        <admin-select-cancel />
      </admin-select-input>
      <admin-select-viewport>
        <admin-select-empty>找不到符合的項目</admin-select-empty>
        <admin-select-group>
          <admin-select-item v-for="option in quickPicks" :key="option.value" :value="option">
            {{ option.label }}
            <template #indicator>
              <admin-select-item-indicator />
            </template>
          </admin-select-item>
        </admin-select-group>
        <admin-select-separator />
        <admin-select-group v-for="group in groups" :key="group.heading" :heading="group.heading">
          <admin-select-item v-for="option in group.items" :key="option.value" :value="option">
            {{ option.label }}
            <template #indicator>
              <admin-select-item-indicator />
            </template>
          </admin-select-item>
        </admin-select-group>
      </admin-select-viewport>
    </admin-select-list>
  </admin-select>
</template>
```

## Type-safe 封裝

`AdminSelect` 已是 generic（`T extends AcceptableValue`），可直接以較嚴的 `v-model` 受益。若要讓 `v-model` 與選項清單的 literal union 對齊，可自行封裝：傳入 `options`（建議加 `as const`），由封裝元件以物件為 value 渲染 item，並以 `displayValue` 顯示 label。

封裝再以 `multiple` 為條件式泛型的 discriminant：`multiple` 時 `v-model` 型別收斂為選項陣列、未開時為單一選項，兩種模式共用同一個封裝元件。

範例：

```vue
<script
  setup
  lang="ts"
  generic="
    TOptions extends ReadonlyArray<{
      label: string
      value: string | number | null
    }>,
    TMultiple extends boolean = false
  "
>
import type { HTMLAttributes } from 'vue'
import type { AdminSelectEmits, AdminSelectProps } from '@/registry/admin/ui/select'
import { reactiveOmit } from '@vueuse/core'
import { useForwardPropsEmits } from 'reka-ui'
import { computed } from 'vue'
import {
  AdminSelect,
  AdminSelectAnchor,
  AdminSelectIcon,
  AdminSelectItem,
  AdminSelectList,
  AdminSelectTrigger,
  AdminSelectValue,
  AdminSelectViewport
} from '@/registry/admin/ui/select'

type TOption = TOptions[number]
// modelValue 型別跟著 multiple 走：multiple 時為選項陣列（空選為 []），單選時為單一選項或 null（清除）
type TModelValue = TMultiple extends true ? TOption[] : TOption | null

defineOptions({
  name: 'typed-admin-select'
})

const props = defineProps<
  Omit<AdminSelectProps<TOption>, 'modelValue' | 'defaultValue' | 'displayValue' | 'multiple'> & {
    options: TOptions
    multiple?: TMultiple
    modelValue?: TModelValue
    defaultValue?: TModelValue
    placeholder?: string
    displayValue?: (value: TOption) => string
    class?: HTMLAttributes['class']
  }
>()

const emits = defineEmits<
  Omit<AdminSelectEmits<TOption>, 'update:modelValue'> & {
    'update:modelValue': [value: TModelValue]
  }
>()

const delegatedProps = reactiveOmit(
  props,
  'modelValue',
  'options',
  'placeholder',
  'displayValue',
  'class'
)
const forwardedAll = useForwardPropsEmits(delegatedProps, emits)

const forwarded = computed(() => {
  const { 'onUpdate:modelValue': _, ...rest } = forwardedAll.value
  return rest
})

// 未提供 displayValue 時預設取 option.label（options 型別已約束含 label）
const resolveDisplayValue = computed(() => {
  return props.displayValue ?? ((value: TOption) => value.label)
})

// 內部綁定不含 null（reka modelValue 不接受 null）；null（清除）在此收成 undefined，
// 對外 emit 仍依 multiple 吐 [] / null。模型持有的是 option 物件，`?? undefined` 不會誤傷合法值
const innerValue = computed<TOption | TOption[] | undefined>({
  get() {
    return props.modelValue ?? undefined
  },
  set(value) {
    if (props.multiple) {
      emits('update:modelValue', (value ?? []) as TModelValue)
      return
    }
    emits('update:modelValue', (value ?? null) as TModelValue)
  }
})
</script>

<template>
  <admin-select
    v-bind="forwarded"
    v-model="innerValue"
    by="value"
    :display-value="resolveDisplayValue"
  >
    <admin-select-anchor :class="props.class">
      <admin-select-trigger>
        <admin-select-value :placeholder="props.placeholder" />
        <admin-select-icon />
      </admin-select-trigger>
    </admin-select-anchor>
    <admin-select-list>
      <admin-select-viewport>
        <admin-select-item
          v-for="(option, index) in props.options"
          :key="`${option.value}-${index}`"
          :value="option"
        >
          {{ option.label }}
        </admin-select-item>
      </admin-select-viewport>
    </admin-select-list>
  </admin-select>
</template>
```

::alert{title="需開啟 strictVModel" type="info"}
型別檢查需開啟 `strictVModel`（若已開啟 `strictTemplates` 則已包含）。設定見 [Type-safe](https://component-registry-4d4d86.gitlab.io/docs/get-started/type-safe)。下列同時含合法綁定與刻意錯誤綁定；錯誤處以 `@vue-expect-error` 標示。
::

```vue
<script setup lang="ts">
import { ref } from 'vue'
import TypedAdminSelect from './typed-admin-select-demo.vue'

const options = [
  { label: 'Draft', value: 'draft' },
  { label: 'Published', value: 'published' }
] as const

const status = ref<(typeof options)[number] | null>(options[0])
const wrong = ref({ label: 'Unknown', value: 'unknown' })

const selected = ref<(typeof options)[number][]>([options[0]])
</script>

<template>
  <div class="flex w-full max-w-md flex-col gap-6">
    <typed-admin-select v-model="status" class="w-full" placeholder="選擇狀態" :options="options" />

    <!-- @vue-expect-error value 不在 options 的 value union 內 -->
    <typed-admin-select v-model="wrong" class="w-full" placeholder="選擇狀態" :options="options" />

    <!-- multiple：modelValue 型別跟著收斂為選項陣列 -->
    <typed-admin-select
      v-model="selected"
      class="w-full"
      placeholder="選擇狀態"
      multiple
      :options="options"
    />

    <!-- @vue-expect-error multiple 需要陣列，給單一選項報錯 -->
    <typed-admin-select v-model="status" class="w-full" multiple :options="options" />

    <!-- @vue-expect-error 未開 multiple 需要單一選項，給陣列報錯 -->
    <typed-admin-select v-model="selected" class="w-full" :options="options" />
  </div>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-select
    v-model="value"
    by="value"
    multiple
    :display-value="(v) => v.label"
    :is-error="isError"
  >
    <admin-select-anchor>
      <admin-select-trigger>
        <admin-select-tags />
        <admin-select-value placeholder="..." />
        <admin-select-counter />
        <admin-select-icon />
      </admin-select-trigger>
    </admin-select-anchor>
    <admin-select-list>
      <admin-select-input placeholder="...">
        <admin-select-cancel />
      </admin-select-input>
      <admin-select-viewport>
        <admin-select-empty>無結果</admin-select-empty>
        <admin-select-group heading="群組標題">
          <admin-select-item v-for="o in options" :key="o.value" :value="o">
            {{ o.label }}
          </admin-select-item>
        </admin-select-group>
        <admin-select-separator />
      </admin-select-viewport>
    </admin-select-list>
  </admin-select>
</template>
```

### admin-select

::div{data-admin-api-table=""}
#### Props

| 名稱                        | 型別                                                                   | 預設值           | 說明                                                                                                                                                                                                           |
| ------------------------- | -------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `class`                   | `unknown`                                                            | —             | —                                                                                                                                                                                                            |
| `open`                    | `boolean | undefined`                                                | —             | The controlled open state of the Combobox. Can be binded with \`v-model\:open\`.                                                                                                                             |
| `defaultOpen`             | `boolean | undefined`                                                | —             | The open state of the combobox when it is initially rendered. \<br> Use when you do not need to control its open state.                                                                                      |
| `resetSearchTermOnBlur`   | `boolean | undefined`                                                | `` `true` ``  | Whether to reset the searchTerm when the Combobox input blurred                                                                                                                                              |
| `resetSearchTermOnSelect` | `boolean | undefined`                                                | `` `true` ``  | Whether to reset the searchTerm when the Combobox value is selected                                                                                                                                          |
| `openOnFocus`             | `boolean | undefined`                                                | `` `false` `` | Whether to open the combobox when the input is focused                                                                                                                                                       |
| `openOnClick`             | `boolean | undefined`                                                | `` `false` `` | Whether to open the combobox when the input is clicked                                                                                                                                                       |
| `ignoreFilter`            | `boolean | undefined`                                                | —             | When \`true\`, disable the default filters                                                                                                                                                                   |
| `resetModelValueOnClear`  | `boolean | undefined`                                                | —             | When \`true\` the \`modelValue\` will be reset to \`null\` (or \`\[]\` if \`multiple\`)                                                                                                                      |
| `modelValue`              | `TModelValue | TModelValue[] | undefined`                            | —             | The controlled value of the listbox. Can be binded with \`v-model\`.                                                                                                                                         |
| `as`                      | `globalThis.Component | AsTag | undefined`                           | `"div"`       | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `asChild`                 | `boolean | undefined`                                                | —             | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `required`                | `boolean | undefined`                                                | —             | When \`true\`, indicates that the user must set the value before the owning form can be submitted.                                                                                                           |
| `disabled`                | `boolean | undefined`                                                | —             | When \`true\`, prevents the user from interacting with listbox                                                                                                                                               |
| `dir`                     | `Direction | undefined`                                              | —             | The reading direction of the listbox when applicable. \<br> If omitted, inherits globally from \`ConfigProvider\` or assumes LTR (left-to-right) reading mode.                                               |
| `defaultValue`            | `TModelValue | TModelValue[] | undefined`                            | —             | The value of the listbox when initially rendered. Use when you do not need to control the state of the Listbox                                                                                               |
| `name`                    | `string | undefined`                                                 | —             | The name of the field. Submitted with its owning form as part of a name/value pair.                                                                                                                          |
| `multiple`                | `boolean | undefined`                                                | —             | Whether multiple options can be selected or not.                                                                                                                                                             |
| `highlightOnHover`        | `boolean | undefined`                                                | —             | When \`true\`, hover over item will trigger highlight                                                                                                                                                        |
| `by`                      | `string | ((a: TModelValue, b: TModelValue) => boolean) | undefined` | —             | Use this to compare objects by a particular field, or pass your own comparison function for complete control over how objects are compared.                                                                  |
| `deselectable`            | `boolean | undefined`                                                | `true`        | 已選中之選項是否可再次點擊取消選取                                                                                                                                                                                            |
| `isError`                 | `boolean | undefined`                                                | `false`       | 設為 \`true\` 時為 trigger 套用錯誤狀態邊框                                                                                                                                                                              |
| `displayValue`            | `((value: TModelValue) => string) | undefined`                       | —             | 將已選 value 轉成 trigger／tags 顯示文案；未提供時 fallback 為 \`String(value)\`                                                                                                                                             |

#### Events

| 名稱                  | Payload                                                 | 說明 |
| ------------------- | ------------------------------------------------------- | -- |
| `update:modelValue` | `TModelValue`                                           | —  |
| `update:open`       | `boolean`                                               | —  |
| `highlight`         | `{ ref: HTMLElement; value: TModelValue; } | undefined` | —  |

#### Slots

| 名稱        | Bindings                                                      | 說明 |
| --------- | ------------------------------------------------------------- | -- |
| `default` | `{ open: boolean; modelValue: TModelValue | TModelValue[]; }` | —  |
::

### admin-select-anchor

::div{data-admin-api-table=""}
#### Props

| 名稱          | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| ----------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `reference` | `ReferenceElement | undefined`             | —       | The reference (or anchor) element that is being referred to for positioning.\<br>If not provided will use the current component as anchor.                                                                   |
| `asChild`   | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`        | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`     | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-select-trigger

::div{data-admin-api-table=""}
#### Props

| 名稱         | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| ---------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `disabled` | `boolean | undefined`                      | —       | When \`true\`, prevents the user from interacting with item                                                                                                                                                  |
| `asChild`  | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`       | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`    | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-select-value

::div{data-admin-api-table=""}
#### Props

| 名稱            | 型別                   | 預設值 | 說明            |
| ------------- | -------------------- | --- | ------------- |
| `placeholder` | `string | undefined` | —   | 未選取選項時顯示之提示文字 |
| `class`       | `ClassValue`         | —   | 根元素之自訂 class  |
::

### admin-select-icon

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |
::

### admin-select-list

::div{data-admin-api-table=""}
#### Props

| 名稱                            | 型別                                                                                  | 預設值           | 說明                                                                                                                                                                                                                                                                       |
| ----------------------------- | ----------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `forceMount`                  | `boolean | undefined`                                                               | —             | Used to force mounting when more control is needed. Useful when\<br>controlling animation with Vue animation libraries.                                                                                                                                                  |
| `position`                    | `"inline" | "popper" | undefined`                                                   | `"popper"`    | The positioning mode to use, \<br>\`inline\` is the default and you can control the position using CSS. \<br>\`popper\` positions content in the same way as our other primitives, for example \`Popover\` or \`DropdownMenu\`.                                          |
| `bodyLock`                    | `boolean | undefined`                                                               | —             | The document.body will be lock, and scrolling will be disabled.                                                                                                                                                                                                          |
| `hideWhenEmpty`               | `boolean | undefined`                                                               | `false`       | When \`true\`, hides the content when there are no items matching the filter.                                                                                                                                                                                            |
| `memoDependencies`            | `unknown[] | undefined`                                                             | —             | Reactive dependencies that should invalidate the memoized content subtree.                                                                                                                                                                                               |
| `side`                        | `"top" | "right" | "bottom" | "left" | undefined`                                   | `"bottom"`    | The preferred side of the trigger to render against when open.\<br>Will be reversed when collisions occur and avoidCollisions\<br>is enabled.                                                                                                                            |
| `sideOffset`                  | `number | undefined`                                                                | `4`           | The distance in pixels from the trigger.                                                                                                                                                                                                                                 |
| `sideFlip`                    | `boolean | undefined`                                                               | `true`        | Flip to the opposite side when colliding with boundary.                                                                                                                                                                                                                  |
| `align`                       | `"start" | "end" | "center" | undefined`                                            | `"start"`     | The preferred alignment against the trigger.\<br>May change when collisions occur.                                                                                                                                                                                       |
| `alignOffset`                 | `number | undefined`                                                                | `0`           | An offset in pixels from the \`start\` or \`end\` alignment options.                                                                                                                                                                                                     |
| `alignFlip`                   | `boolean | undefined`                                                               | `true`        | Flip alignment when colliding with boundary.\<br>May only occur when \`prioritizePosition\` is true.                                                                                                                                                                     |
| `avoidCollisions`             | `boolean | undefined`                                                               | `true`        | When \`true\`, overrides the side and align preferences\<br>to prevent collisions with boundary edges.                                                                                                                                                                   |
| `collisionBoundary`           | `Element | (Element | null)[] | null | undefined`                                   | `[]`          | The element used as the collision boundary. By default\<br>this is the viewport, though you can provide additional\<br>element(s) to be included in this check.                                                                                                          |
| `collisionPadding`            | `number | Partial<Record<"top" | "right" | "bottom" | "left", number>> | undefined` | `0`           | The distance in pixels from the boundary edges where collision\<br>detection should occur. Accepts a number (same for all sides),\<br>or a partial padding object, for example: { top: 20, left: 20 }.                                                                   |
| `arrowPadding`                | `number | undefined`                                                                | `0`           | The padding between the arrow and the edges of the content.\<br>If your content has border-radius, this will prevent it from\<br>overflowing the corners.                                                                                                                |
| `hideShiftedArrow`            | `boolean | undefined`                                                               | `true`        | When \`true\`, hides the arrow when it cannot be centered\<br>to the reference element.                                                                                                                                                                                  |
| `sticky`                      | `"partial" | "always" | undefined`                                                  | `"partial"`   | The sticky behavior on the align axis. \`partial\` will keep the\<br>content in the boundary as long as the trigger is at least partially\<br>in the boundary whilst "always" will keep the content in the boundary\<br>regardless.                                      |
| `hideWhenDetached`            | `boolean | undefined`                                                               | `false`       | Whether to hide the content when the trigger becomes fully occluded.                                                                                                                                                                                                     |
| `positionStrategy`            | `"fixed" | "absolute" | undefined`                                                  | —             | The type of CSS position property to use.                                                                                                                                                                                                                                |
| `updatePositionStrategy`      | `"always" | "optimized" | undefined`                                                | `'optimized'` | Strategy to update the position of the floating element on every animation frame.                                                                                                                                                                                        |
| `disableUpdateOnLayoutShift`  | `boolean | undefined`                                                               | `false`       | Whether to disable the update position for the content when the layout shifted.                                                                                                                                                                                          |
| `prioritizePosition`          | `boolean | undefined`                                                               | `false`       | Force content to be position within the viewport.\<br>Might overlap the reference element, which may not be desired.                                                                                                                                                     |
| `reference`                   | `ReferenceElement | undefined`                                                      | —             | The custom element or virtual element that will be set as the reference\<br>to position the floating element.\<br>If provided, it will replace the default anchor element.                                                                                               |
| `dir`                         | `Direction | undefined`                                                             | —             | The reading direction of the popper content when applicable. \<br> If omitted, inherits globally from \`ConfigProvider\` or assumes LTR (left-to-right) reading mode.                                                                                                    |
| `asChild`                     | `boolean | undefined`                                                               | —             | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details.                                                             |
| `as`                          | `globalThis.Component | AsTag | undefined`                                          | `"div"`       | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                                                                             |
| `disableOutsidePointerEvents` | `boolean | undefined`                                                               | —             | When \`true\`, hover/focus/click interactions will be disabled on elements outside\<br>the \`DismissableLayer\`. Users will need to click twice on outside elements to\<br>interact with them: once to close the \`DismissableLayer\`, and again to trigger the element. |
| `class`                       | `ClassValue`                                                                        | —             | 根元素之自訂 class                                                                                                                                                                                                                                                             |
| `to`                          | `string | HTMLElement | undefined`                                                  | —             | 指定 ComboboxPortal 之掛載目標                                                                                                                                                                                                                                                  |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-select-viewport

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `nonce`   | `string | undefined`                       | —       | Will add \`nonce\` attribute to the style tag which can be used by Content Security Policy. \<br> If omitted, inherits globally from \`ConfigProvider\`.                                                     |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-select-input

::div{data-admin-api-table=""}
#### Props

| 名稱             | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| -------------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `displayValue` | `((val: any) => string) | undefined`       | —       | The display value of input for selected item. Does not work with \`multiple\`.                                                                                                                               |
| `modelValue`   | `string | undefined`                       | —       | The controlled value of the filter. Can be binded with v-model.                                                                                                                                              |
| `autoFocus`    | `boolean | undefined`                      | —       | Focus on element when mounted.                                                                                                                                                                               |
| `disabled`     | `boolean | undefined`                      | —       | When \`true\`, prevents the user from interacting with item                                                                                                                                                  |
| `asChild`      | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`           | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`        | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |
| `placeholder`  | `string | undefined`                       | —       | 搜尋輸入框之提示文字                                                                                                                                                                                                   |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `icon`    | `{}`     | —  |
| `default` | `{}`     | —  |
::

### admin-select-cancel

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-select-empty

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-select-group

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |
| `heading` | `string | undefined`                       | —       | 群組標題；提供時於群組頂部渲染 ComboboxLabel                                                                                                                                                                                |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-select-item

::div{data-admin-api-table=""}
#### Props

| 名稱          | 型別                                         | 預設值     | 說明                                                                                                                                                                                                                      |
| ----------- | ------------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `textValue` | `string | undefined`                       | —       | A string representation of the item contents.\<br>If the children are not plain text, then the \`textValue\` prop must also be set to a plain text representation, which will be used for autocomplete in the ComboBox. |
| `value`\*   | `AcceptableValue`                          | —       | The value given as data when submitted with a \`name\`.                                                                                                                                                                 |
| `disabled`  | `boolean | undefined`                      | —       | When \`true\`, prevents the user from interacting with the item.                                                                                                                                                        |
| `asChild`   | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details.            |
| `as`        | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                            |
| `class`     | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                            |

*\\\* 代表必填*

#### Events

| 名稱       | Payload                          | 說明 |
| -------- | -------------------------------- | -- |
| `select` | `SelectEvent$3<AcceptableValue>` | —  |

#### Slots

| 名稱          | Bindings | 說明 |
| ----------- | -------- | -- |
| `default`   | `{}`     | —  |
| `indicator` | `{}`     | —  |
::

### admin-select-item-indicator

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-select-separator

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |
::

### admin-select-tags

::div{data-admin-api-table=""}
#### Props

| 名稱         | 型別           | 預設值 | 說明               |
| ---------- | ------------ | --- | ---------------- |
| `class`    | `ClassValue` | —   | 根元素之自訂 class     |
| `tagClass` | `ClassValue` | —   | 單一 tag 之自訂 class |

#### Slots

| 名稱        | Bindings                                           | 說明 |
| --------- | -------------------------------------------------- | -- |
| `default` | `{ option: AcceptableValue; remove: () => void; }` | —  |
::

### admin-select-counter

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別                   | 預設值  | 說明           |
| ------- | -------------------- | ---- | ------------ |
| `max`   | `number | undefined` | `99` | 顯示計數之上限數字    |
| `class` | `ClassValue`         | —    | 根元素之自訂 class |
::

## 注意事項

- **trigger 需以 `<admin-select-anchor>` 包覆**：anchor 為 popper 定位錨點，list 的展開位置與寬度以 anchor 為參考；欲設定下拉寬度請把寬度 class 下在 `<admin-select-anchor>` 上。
- **搜尋輸入固定於 list 頂部**：`<admin-select-input>` 放在 `<admin-select-list>` 內、`<admin-select-viewport>` 之外時會固定不隨清單捲動；item 清單放入 `<admin-select-viewport>` 提供捲動。
- **物件 value 請設 `by`**：`v-model` 綁 option 物件時，建議 `by="value"`（或自訂比較函式），並以 `:display-value` 決定 trigger／tags 文案。
- **單選的 `deselectable`**：預設 `true`，再次點擊已選項目會清空選擇並關閉下拉；不需此行為時於 root 設 `deselectable=false`。
- **搜尋過濾的 label 來源**：過濾依據是每顆 `<admin-select-item>` 的 `textContent`；若 item 內嵌入 icon / 圖片等非文字節點，建議透過 `text-value` prop 顯式指定可被過濾的字串。

## 更新紀錄

:admin-changelog{component="AdminSelect"}


# Side Menu

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/side-menu
```

```ts
import {
  AdminSideMenu,
  AdminSideMenuContent,
  AdminSideMenuFooter,
  AdminSideMenuGroup,
  AdminSideMenuGroupAction,
  AdminSideMenuGroupContent,
  AdminSideMenuGroupLabel,
  AdminSideMenuHeader,
  AdminSideMenuInput,
  AdminSideMenuInset,
  AdminSideMenuList,
  AdminSideMenuListAction,
  AdminSideMenuListBadge,
  AdminSideMenuListButton,
  AdminSideMenuListButtonChild,
  AdminSideMenuListItem,
  AdminSideMenuListSkeleton,
  AdminSideMenuListSub,
  AdminSideMenuListSubButton,
  AdminSideMenuListSubItem,
  AdminSideMenuProvider,
  AdminSideMenuRail,
  AdminSideMenuSeparator,
  AdminSideMenuTrigger,
  useSideMenu,
} from '@/components/admin/side-menu'
```

## 用法

外層需先以 `admin-side-menu-provider` 提供 context，再以 `admin-side-menu` 結合 group / list / item / button 組合導覽結構。

```vue
<script setup lang="ts">
import {
  IconChevronDown,
  IconChevronRight,
  IconComponents,
  IconLayoutDashboard,
  IconSettings
} from '@tabler/icons-vue'
import { ref } from 'vue'
import {
  AdminSideMenu,
  AdminSideMenuContent,
  AdminSideMenuGroup,
  AdminSideMenuList,
  AdminSideMenuListButton,
  AdminSideMenuListItem,
  AdminSideMenuListSub,
  AdminSideMenuListSubButton,
  AdminSideMenuListSubItem,
  AdminSideMenuProvider
} from '@/registry/admin/ui/side-menu'

const componentsExpanded = ref(true)
</script>

<template>
  <admin-side-menu-provider class="block h-72 w-60">
    <admin-side-menu collapsible="none">
      <admin-side-menu-content>
        <admin-side-menu-group>
          <admin-side-menu-list>
            <admin-side-menu-list-item>
              <admin-side-menu-list-button>
                <icon-layout-dashboard class="size-4 shrink-0" />
                Dashboard
              </admin-side-menu-list-button>
            </admin-side-menu-list-item>

            <admin-side-menu-list-item>
              <admin-side-menu-list-button
                is-active
                @click="componentsExpanded = !componentsExpanded"
              >
                <icon-components class="size-4 shrink-0" />
                <span class="flex-1">Components</span>
                <icon-chevron-down v-if="componentsExpanded" class="size-4 shrink-0" />
                <icon-chevron-right v-else class="size-4 shrink-0" />
              </admin-side-menu-list-button>

              <admin-side-menu-list-sub v-show="componentsExpanded">
                <admin-side-menu-list-sub-item>
                  <admin-side-menu-list-sub-button is-active
                    >Button</admin-side-menu-list-sub-button
                  >
                </admin-side-menu-list-sub-item>
                <admin-side-menu-list-sub-item>
                  <admin-side-menu-list-sub-button>Input</admin-side-menu-list-sub-button>
                </admin-side-menu-list-sub-item>
                <admin-side-menu-list-sub-item>
                  <admin-side-menu-list-sub-button>Dialog</admin-side-menu-list-sub-button>
                </admin-side-menu-list-sub-item>
              </admin-side-menu-list-sub>
            </admin-side-menu-list-item>

            <admin-side-menu-list-item>
              <admin-side-menu-list-button>
                <icon-settings class="size-4 shrink-0" />
                Settings
              </admin-side-menu-list-button>
            </admin-side-menu-list-item>
          </admin-side-menu-list>
        </admin-side-menu-group>
      </admin-side-menu-content>
    </admin-side-menu>
  </admin-side-menu-provider>
</template>
```

## 場景

### 基本結構

```vue
<script setup lang="ts">
import { IconComponents, IconLayoutDashboard, IconSettings } from '@tabler/icons-vue'
import {
  AdminSideMenu,
  AdminSideMenuContent,
  AdminSideMenuGroup,
  AdminSideMenuList,
  AdminSideMenuListButton,
  AdminSideMenuListItem,
  AdminSideMenuProvider
} from '@/registry/admin/ui/side-menu'

const items = [
  { key: 'dashboard', label: 'Dashboard', icon: IconLayoutDashboard, active: false },
  { key: 'components', label: 'Components', icon: IconComponents, active: true },
  { key: 'settings', label: 'Settings', icon: IconSettings, active: false }
]
</script>

<template>
  <admin-side-menu-provider class="block h-64 w-60">
    <admin-side-menu collapsible="none">
      <admin-side-menu-content>
        <admin-side-menu-group>
          <admin-side-menu-list>
            <admin-side-menu-list-item v-for="item in items" :key="item.key">
              <admin-side-menu-list-button :is-active="item.active">
                <component :is="item.icon" class="size-4 shrink-0" />
                {{ item.label }}
              </admin-side-menu-list-button>
            </admin-side-menu-list-item>
          </admin-side-menu-list>
        </admin-side-menu-group>
      </admin-side-menu-content>
    </admin-side-menu>
  </admin-side-menu-provider>
</template>
```

### 完整組成

header／footer／group-label／group-action／list-badge／list-action／separator／input／skeleton。

```vue
<script setup lang="ts">
import {
  IconDots,
  IconInbox,
  IconLayoutDashboard,
  IconPlus,
  IconSearch,
  IconSettings,
  IconUserCircle
} from '@tabler/icons-vue'
import {
  AdminSideMenu,
  AdminSideMenuContent,
  AdminSideMenuFooter,
  AdminSideMenuGroup,
  AdminSideMenuGroupAction,
  AdminSideMenuGroupContent,
  AdminSideMenuGroupLabel,
  AdminSideMenuHeader,
  AdminSideMenuInput,
  AdminSideMenuList,
  AdminSideMenuListAction,
  AdminSideMenuListBadge,
  AdminSideMenuListButton,
  AdminSideMenuListItem,
  AdminSideMenuListSkeleton,
  AdminSideMenuProvider,
  AdminSideMenuSeparator
} from '@/registry/admin/ui/side-menu'

const keyword = ref('')

const items = [
  { key: 'dashboard', label: 'Dashboard', icon: IconLayoutDashboard, active: true, badge: '' },
  { key: 'inbox', label: 'Inbox', icon: IconInbox, active: false, badge: '12' },
  { key: 'settings', label: 'Settings', icon: IconSettings, active: false, badge: '' }
]
</script>

<template>
  <admin-side-menu-provider class="block h-96 w-64">
    <admin-side-menu collapsible="none">
      <admin-side-menu-header>
        <admin-side-menu-input v-model="keyword" placeholder="搜尋…">
          <template #prefix>
            <icon-search class="size-4 shrink-0 text-text-50" />
          </template>
        </admin-side-menu-input>
      </admin-side-menu-header>

      <admin-side-menu-separator />

      <admin-side-menu-content>
        <admin-side-menu-group>
          <admin-side-menu-group-label>導覽</admin-side-menu-group-label>
          <admin-side-menu-group-action aria-label="新增">
            <icon-plus />
          </admin-side-menu-group-action>
          <admin-side-menu-group-content>
            <admin-side-menu-list>
              <admin-side-menu-list-item v-for="item in items" :key="item.key">
                <admin-side-menu-list-button :is-active="item.active">
                  <component :is="item.icon" class="size-4 shrink-0" />
                  {{ item.label }}
                </admin-side-menu-list-button>
                <admin-side-menu-list-badge v-if="item.badge">{{
                  item.badge
                }}</admin-side-menu-list-badge>
                <admin-side-menu-list-action v-else aria-label="更多">
                  <icon-dots />
                </admin-side-menu-list-action>
              </admin-side-menu-list-item>
            </admin-side-menu-list>
          </admin-side-menu-group-content>
        </admin-side-menu-group>

        <admin-side-menu-group>
          <admin-side-menu-group-label>載入中</admin-side-menu-group-label>
          <admin-side-menu-group-content>
            <admin-side-menu-list>
              <admin-side-menu-list-item v-for="n in 3" :key="n">
                <admin-side-menu-list-skeleton show-icon />
              </admin-side-menu-list-item>
            </admin-side-menu-list>
          </admin-side-menu-group-content>
        </admin-side-menu-group>
      </admin-side-menu-content>

      <admin-side-menu-footer>
        <admin-side-menu-list>
          <admin-side-menu-list-item>
            <admin-side-menu-list-button>
              <icon-user-circle class="size-4 shrink-0" />
              帳號
            </admin-side-menu-list-button>
          </admin-side-menu-list-item>
        </admin-side-menu-list>
      </admin-side-menu-footer>
    </admin-side-menu>
  </admin-side-menu-provider>
</template>
```

### 變體與收合

`variant`：`default`／`floating`／`inset`；`collapsible`：`icon`／`offcanvas`。以 `admin-side-menu-trigger` 或 `admin-side-menu-rail` 切換展開／收合。

```vue
<script setup lang="ts">
import type { AdminSideMenuProps } from '@/registry/admin/ui/side-menu'
import {
  IconFolder,
  IconInbox,
  IconLayoutDashboard,
  IconLayoutSidebar,
  IconSettings
} from '@tabler/icons-vue'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import {
  AdminSideMenu,
  AdminSideMenuContent,
  AdminSideMenuFooter,
  AdminSideMenuGroup,
  AdminSideMenuHeader,
  AdminSideMenuInset,
  AdminSideMenuList,
  AdminSideMenuListBadge,
  AdminSideMenuListButton,
  AdminSideMenuListItem,
  AdminSideMenuProvider,
  AdminSideMenuRail,
  AdminSideMenuTrigger
} from '@/registry/admin/ui/side-menu'

type Variant = NonNullable<AdminSideMenuProps['variant']>
type Collapsible = 'icon' | 'offcanvas'

const VARIANT_OPTIONS: readonly Variant[] = ['default', 'floating', 'inset']
const COLLAPSIBLE_OPTIONS: readonly Collapsible[] = ['icon', 'offcanvas']

const variant = ref<Variant>('default')
const collapsible = ref<Collapsible>('icon')
const mobileSheet = ref(true)

const items = [
  { key: 'dashboard', label: 'Dashboard', icon: IconLayoutDashboard, active: true, badge: '' },
  { key: 'inbox', label: 'Inbox', icon: IconInbox, active: false, badge: '8' },
  { key: 'projects', label: 'Projects', icon: IconFolder, active: false, badge: '' },
  { key: 'settings', label: 'Settings', icon: IconSettings, active: false, badge: '' }
]

const rowClass = 'flex flex-col gap-2 sm:flex-row sm:items-center'
const brandIconClass =
  'flex size-8 shrink-0 items-center justify-center rounded-md bg-primary-50 text-text-10'
const brandTextClass = 'truncate typo-title-small text-text-90 group-data-[collapsible=icon]:hidden'
const userTextClass =
  'truncate typo-content-medium text-text-70 group-data-[collapsible=icon]:hidden'
const triggerClass =
  'flex size-8 cursor-pointer items-center justify-center rounded-md text-text-70 hover:bg-bg-60'

const optionClass = (selected: boolean) =>
  cn(
    'cursor-pointer rounded-md border px-3 py-1.5 typo-content-medium transition-colors',
    selected
      ? 'border-primary-50 bg-primary-10 text-primary-50'
      : `
        border-text-30 bg-bg-90 text-text-70
        hover:border-text-40
      `
  )
</script>

<template>
  <div class="flex flex-col gap-4">
    <div class="flex flex-col gap-3">
      <div :class="rowClass">
        <span class="w-24 shrink-0 typo-content-medium text-text-70">variant</span>
        <div class="flex flex-wrap gap-1.5">
          <button
            v-for="opt in VARIANT_OPTIONS"
            :key="opt"
            type="button"
            :class="optionClass(variant === opt)"
            @click="variant = opt"
          >
            {{ opt }}
          </button>
        </div>
      </div>

      <div :class="rowClass">
        <span class="w-24 shrink-0 typo-content-medium text-text-70">collapsible</span>
        <div class="flex flex-wrap gap-1.5">
          <button
            v-for="opt in COLLAPSIBLE_OPTIONS"
            :key="opt"
            type="button"
            :class="optionClass(collapsible === opt)"
            @click="collapsible = opt"
          >
            {{ opt }}
          </button>
        </div>
      </div>

      <div :class="rowClass">
        <span class="w-24 shrink-0 typo-content-medium text-text-70">mobileSheet</span>
        <div class="flex flex-wrap gap-1.5">
          <button type="button" :class="optionClass(mobileSheet)" @click="mobileSheet = true">
            true
          </button>
          <button type="button" :class="optionClass(!mobileSheet)" @click="mobileSheet = false">
            false
          </button>
        </div>
      </div>
    </div>

    <div
      :class="
        cn(
          'relative h-96 w-full overflow-hidden rounded-lg border border-text-20',
          'transform-[translateZ(0)]'
        )
      "
    >
      <admin-side-menu-provider class="size-full min-h-0" :mobile-sheet="mobileSheet">
        <admin-side-menu :collapsible="collapsible" :variant="variant">
          <admin-side-menu-header>
            <div class="flex h-11 items-center gap-2 px-1">
              <div :class="brandIconClass">
                <icon-layout-sidebar class="size-5" />
              </div>
              <span :class="brandTextClass">Admin</span>
            </div>
          </admin-side-menu-header>

          <admin-side-menu-content>
            <admin-side-menu-group>
              <admin-side-menu-list>
                <admin-side-menu-list-item v-for="item in items" :key="item.key">
                  <admin-side-menu-list-button :is-active="item.active" :tooltip="item.label">
                    <component :is="item.icon" class="size-4 shrink-0" />
                    <span>{{ item.label }}</span>
                  </admin-side-menu-list-button>
                  <admin-side-menu-list-badge v-if="item.badge">{{
                    item.badge
                  }}</admin-side-menu-list-badge>
                </admin-side-menu-list-item>
              </admin-side-menu-list>
            </admin-side-menu-group>
          </admin-side-menu-content>

          <admin-side-menu-footer>
            <div class="flex h-11 items-center gap-2 px-1">
              <div class="size-8 shrink-0 rounded-full bg-bg-60"></div>
              <span :class="userTextClass">paul.chen</span>
            </div>
          </admin-side-menu-footer>

          <admin-side-menu-rail />
        </admin-side-menu>

        <admin-side-menu-inset>
          <div class="flex h-12 shrink-0 items-center gap-2 border-b border-text-20 px-3">
            <admin-side-menu-trigger :class="triggerClass">
              <icon-layout-sidebar class="size-5" />
            </admin-side-menu-trigger>
            <span class="typo-title-small text-text-90">主內容</span>
          </div>
          <div class="flex-1 p-4 typo-content-medium text-text-50">
            切換上方 variant / collapsible，或點左上角按鈕與側邊 rail 觀察收合效果。mobileSheet
            僅在瀏覽器視窗寬度 &lt; 768px 時生效：true 於手機以 Sheet 呈現，false 則維持電腦版
            offcanvas 樣式。
          </div>
        </admin-side-menu-inset>
      </admin-side-menu-provider>
    </div>
  </div>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-side-menu-provider>
    <admin-side-menu>
      <admin-side-menu-content>
        <admin-side-menu-group>
          <admin-side-menu-list>
            <admin-side-menu-list-item>
              <admin-side-menu-list-button>導覽項目</admin-side-menu-list-button>
            </admin-side-menu-list-item>
          </admin-side-menu-list>
        </admin-side-menu-group>
      </admin-side-menu-content>
    </admin-side-menu>
    <admin-side-menu-inset>
      <admin-side-menu-trigger />
      主內容
    </admin-side-menu-inset>
  </admin-side-menu-provider>
</template>
```

### admin-side-menu

::div{data-admin-api-table=""}
#### Props

| 名稱            | 型別                                             | 預設值         | 說明                               |
| ------------- | ---------------------------------------------- | ----------- | -------------------------------- |
| `side`        | `"right" | "left" | undefined`                 | `"left"`    | 側選單對齊方向                          |
| `variant`     | `"default" | "inset" | "floating" | undefined` | `"default"` | 視覺樣式變體                           |
| `collapsible` | `"none" | "icon" | "offcanvas" | undefined`    | `"icon"`    | 收合行為（offcanvas / icon / none 之一） |
| `class`       | `ClassValue`                                   | —           | 根元素之自訂 class                     |

#### Slots

| 名稱        | Bindings                                                  | 說明 |
| --------- | --------------------------------------------------------- | -- |
| `default` | `{ isMobile: boolean; state: "expanded" | "collapsed"; }` | —  |
::

### admin-side-menu-content

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings                               | 說明 |
| --------- | -------------------------------------- | -- |
| `default` | `{ state: "expanded" | "collapsed"; }` | —  |
::

### admin-side-menu-group

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-side-menu-inset

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-side-menu-list

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-side-menu-list-button

::div{data-admin-api-table=""}
#### Props

| 名稱         | 型別                                          | 預設值        | 說明                                                                                                                                                                                                           |
| ---------- | ------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild`  | `boolean | undefined`                       | `false`    | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`       | `globalThis.Component | AsTag | undefined`  | `"button"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `isActive` | `boolean | undefined`                       | `false`    | 設為 \`true\` 時套用 active 狀態樣式                                                                                                                                                                                  |
| `class`    | `ClassValue`                                | —          | 根元素之自訂 class                                                                                                                                                                                                 |
| `tooltip`  | `string | globalThis.Component | undefined` | —          | 收合狀態（collapsed icon-only）時顯示之 tooltip 文字或元件                                                                                                                                                                  |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-side-menu-list-button-child

::div{data-admin-api-table=""}
#### Props

| 名稱         | 型別                                         | 預設值        | 說明                                                                                                                                                                                                           |
| ---------- | ------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild`  | `boolean | undefined`                      | —          | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`       | `globalThis.Component | AsTag | undefined` | `"button"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `isActive` | `boolean | undefined`                      | —          | 設為 \`true\` 時套用 active 狀態樣式                                                                                                                                                                                  |
| `class`    | `ClassValue`                               | —          | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-side-menu-list-item

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-side-menu-list-sub

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-side-menu-list-sub-button

::div{data-admin-api-table=""}
#### Props

| 名稱         | 型別                                         | 預設值   | 說明                                                                                                                                                                                                           |
| ---------- | ------------------------------------------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild`  | `boolean | undefined`                      | —     | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`       | `globalThis.Component | AsTag | undefined` | `"a"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `isActive` | `boolean | undefined`                      | —     | 設為 \`true\` 時套用 active 狀態樣式                                                                                                                                                                                  |
| `class`    | `ClassValue`                               | —     | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-side-menu-list-sub-item

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-side-menu-provider

::div{data-admin-api-table=""}
#### Props

| 名稱            | 型別                    | 預設值    | 說明                                                                                                  |
| ------------- | --------------------- | ------ | --------------------------------------------------------------------------------------------------- |
| `defaultOpen` | `boolean | undefined` | `true` | uncontrolled 模式之初始開啟狀態                                                                              |
| `open`        | `boolean | undefined` | —      | controlled 模式之開啟狀態（以 \`v-model\:open\` 綁定）                                                          |
| `mobileSheet` | `boolean | undefined` | `true` | 手機（\`< 768px\`）是否以 Sheet 渲染；設為 \`false\` 時關閉手機 Sheet，所有 variant/collapsible 在全寬度維持電腦版樣式，預設 \`true\` |
| `class`       | `ClassValue`          | —      | 根元素之自訂 class                                                                                        |

#### Events

| 名稱            | Payload   | 說明        |
| ------------- | --------- | --------- |
| `update:open` | `boolean` | 開啟狀態變更時觸發 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-side-menu-trigger

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值        | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —          | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"button"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —          | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-side-menu-rail

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-side-menu-header

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-side-menu-footer

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-side-menu-group-label

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | `false` | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-side-menu-group-content

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-side-menu-group-action

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值        | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | `false`    | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"button"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —          | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-side-menu-list-action

::div{data-admin-api-table=""}
#### Props

| 名稱            | 型別                                         | 預設值        | 說明                                                                                                                                                                                                           |
| ------------- | ------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild`     | `boolean | undefined`                      | `false`    | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`          | `globalThis.Component | AsTag | undefined` | `"button"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `showOnHover` | `boolean | undefined`                      | `false`    | 設為 \`true\` 時僅在項目 hover / focus / 開啟狀態顯示                                                                                                                                                                     |
| `class`       | `ClassValue`                               | —          | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-side-menu-list-badge

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-side-menu-input

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |
::

### admin-side-menu-separator

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |
::

### admin-side-menu-list-skeleton

::div{data-admin-api-table=""}
#### Props

| 名稱         | 型別                    | 預設值     | 說明                                    |
| ---------- | --------------------- | ------- | ------------------------------------- |
| `showIcon` | `boolean | undefined` | `false` | 是否顯示前置 icon 佔位                        |
| `width`    | `string | undefined`  | `"70%"` | 文字佔位寬度（固定值，避免 SSR hydration mismatch） |
| `class`    | `ClassValue`          | —       | 根元素之自訂 class                          |
::

## 更新紀錄

:admin-changelog{component="AdminSideMenu"}


# Stepper

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/stepper
```

```ts
import {
  AdminStepper,
  AdminStepperDescription,
  AdminStepperIndicator,
  AdminStepperItem,
  AdminStepperSeparator,
  AdminStepperTitle,
  AdminStepperTrigger,
} from '@/components/admin/stepper'
```

## 用法

```vue
<script setup lang="ts">
import { ref } from 'vue'
import {
  AdminStepper,
  AdminStepperIndicator,
  AdminStepperItem,
  AdminStepperSeparator,
  AdminStepperTitle,
  AdminStepperTrigger
} from '@/registry/admin/ui/stepper'

const step = ref<number | undefined>(1)
const steps = [
  { value: 1, title: 'Details' },
  { value: 2, title: 'Review' },
  { value: 3, title: 'Done' }
]
</script>

<template>
  <admin-stepper v-model="step" class="w-full max-w-md">
    <admin-stepper-item v-for="s in steps" :key="s.value" :step="s.value">
      <admin-stepper-trigger>
        <admin-stepper-indicator>{{ s.value }}</admin-stepper-indicator>
        <admin-stepper-title>{{ s.title }}</admin-stepper-title>
      </admin-stepper-trigger>
      <admin-stepper-separator v-if="s.value !== steps.length" />
    </admin-stepper-item>
  </admin-stepper>
</template>
```

## 場景

### 線性三步驟

```vue
<script setup lang="ts">
import { ref } from 'vue'
import {
  AdminStepper,
  AdminStepperIndicator,
  AdminStepperItem,
  AdminStepperSeparator,
  AdminStepperTitle,
  AdminStepperTrigger
} from '@/registry/admin/ui/stepper'

const step = ref<number | undefined>(1)
const steps = [
  { value: 1, title: '填寫資料' },
  { value: 2, title: '確認' },
  { value: 3, title: '完成' }
]
</script>

<template>
  <admin-stepper v-model="step" class="w-full max-w-md">
    <admin-stepper-item v-for="(s, index) in steps" :key="s.value" :step="s.value">
      <admin-stepper-trigger>
        <admin-stepper-indicator>{{ s.value }}</admin-stepper-indicator>
        <admin-stepper-title>{{ s.title }}</admin-stepper-title>
      </admin-stepper-trigger>
      <admin-stepper-separator v-if="index < steps.length - 1" />
    </admin-stepper-item>
  </admin-stepper>
</template>
```

### 停用尚未開放的步驟

```vue
<script setup lang="ts">
import { ref } from 'vue'
import {
  AdminStepper,
  AdminStepperIndicator,
  AdminStepperItem,
  AdminStepperSeparator,
  AdminStepperTitle,
  AdminStepperTrigger
} from '@/registry/admin/ui/stepper'

const step = ref<number | undefined>(2)
</script>

<template>
  <admin-stepper v-model="step" class="w-full max-w-md">
    <admin-stepper-item :step="1">
      <admin-stepper-trigger>
        <admin-stepper-indicator>1</admin-stepper-indicator>
        <admin-stepper-title>已完成</admin-stepper-title>
      </admin-stepper-trigger>
      <admin-stepper-separator />
    </admin-stepper-item>
    <admin-stepper-item :step="2">
      <admin-stepper-trigger>
        <admin-stepper-indicator>2</admin-stepper-indicator>
        <admin-stepper-title>進行中</admin-stepper-title>
      </admin-stepper-trigger>
      <admin-stepper-separator />
    </admin-stepper-item>
    <admin-stepper-item disabled :step="3">
      <admin-stepper-trigger>
        <admin-stepper-indicator>3</admin-stepper-indicator>
        <admin-stepper-title>尚未開放</admin-stepper-title>
      </admin-stepper-trigger>
    </admin-stepper-item>
  </admin-stepper>
</template>
```

### 步驟附說明文字

```vue
<script setup lang="ts">
import { ref } from 'vue'
import {
  AdminStepper,
  AdminStepperDescription,
  AdminStepperIndicator,
  AdminStepperItem,
  AdminStepperSeparator,
  AdminStepperTitle,
  AdminStepperTrigger
} from '@/registry/admin/ui/stepper'

const step = ref<number | undefined>(1)
const steps = [
  { value: 1, title: '帳號', description: '建立登入資訊' },
  { value: 2, title: '付款', description: '選擇付款方式' },
  { value: 3, title: '完成', description: '確認並送出' }
]
</script>

<template>
  <admin-stepper v-model="step" class="w-full max-w-lg">
    <admin-stepper-item v-for="s in steps" :key="s.value" :step="s.value">
      <admin-stepper-trigger>
        <admin-stepper-indicator>{{ s.value }}</admin-stepper-indicator>
        <div class="flex flex-col items-start">
          <admin-stepper-title>{{ s.title }}</admin-stepper-title>
          <admin-stepper-description>{{ s.description }}</admin-stepper-description>
        </div>
      </admin-stepper-trigger>
      <admin-stepper-separator v-if="s.value !== steps.length" />
    </admin-stepper-item>
  </admin-stepper>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-stepper v-model="currentStep">
    <admin-stepper-item :step="1">
      <admin-stepper-trigger>
        <admin-stepper-indicator>1</admin-stepper-indicator>
        <div class="flex flex-col items-start">
          <admin-stepper-title>步驟一</admin-stepper-title>
          <admin-stepper-description>建立登入資訊</admin-stepper-description>
        </div>
      </admin-stepper-trigger>
    </admin-stepper-item>
    <admin-stepper-separator />
    <admin-stepper-item :step="2">
      <admin-stepper-trigger>
        <admin-stepper-indicator>2</admin-stepper-indicator>
        <admin-stepper-title>步驟二</admin-stepper-title>
      </admin-stepper-trigger>
    </admin-stepper-item>
  </admin-stepper>
</template>
```

### admin-stepper

::div{data-admin-api-table=""}
#### Props

| 名稱             | 型別                                         | 預設值          | 說明                                                                                                                                                                                                           |
| -------------- | ------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `defaultValue` | `number | undefined`                       | —            | The value of the step that should be active when initially rendered. Use when you do not need to control the state of the steps.                                                                             |
| `orientation`  | `DataOrientation | undefined`              | `horizontal` | The orientation the steps are laid out.\<br>Mainly so arrow navigation is done accordingly (left & right vs. up & down).                                                                                     |
| `dir`          | `Direction | undefined`                    | —            | The reading direction of the combobox when applicable. \<br> If omitted, inherits globally from \`ConfigProvider\` or assumes LTR (left-to-right) reading mode.                                              |
| `modelValue`   | `number | undefined`                       | —            | The controlled value of the step to activate. Can be bound as \`v-model\`.                                                                                                                                   |
| `linear`       | `boolean | undefined`                      | —            | Whether or not the steps must be completed in order.                                                                                                                                                         |
| `asChild`      | `boolean | undefined`                      | —            | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`           | `globalThis.Component | AsTag | undefined` | `"div"`      | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`        | `ClassValue`                               | —            | 根元素之自訂 class                                                                                                                                                                                                 |

#### Events

| 名稱                  | Payload              | 說明 |
| ------------------- | -------------------- | -- |
| `update:modelValue` | `number | undefined` | —  |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-stepper-item

::div{data-admin-api-table=""}
#### Props

| 名稱          | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| ----------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `step`\*    | `number`                                   | —       | A unique value that associates the stepper item with an index                                                                                                                                                |
| `disabled`  | `boolean | undefined`                      | —       | When \`true\`, prevents the user from interacting with the step.                                                                                                                                             |
| `completed` | `boolean | undefined`                      | —       | Shows whether the step is completed.                                                                                                                                                                         |
| `asChild`   | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`        | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`     | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

*\\\* 代表必填*

#### Slots

| 名稱        | Bindings                   | 說明 |
| --------- | -------------------------- | -- |
| `default` | `{ state: StepperState; }` | —  |
::

### admin-stepper-trigger

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-stepper-indicator

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings            | 說明 |
| --------- | ------------------- | -- |
| `default` | `{ step: number; }` | —  |
::

### admin-stepper-title

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-stepper-description

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-stepper-separator

::div{data-admin-api-table=""}
#### Props

| 名稱            | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| ------------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `orientation` | `DataOrientation | undefined`              | —       | Orientation of the component.\<br>Either \`vertical\` or \`horizontal\`. Defaults to \`horizontal\`.                                                                                                         |
| `decorative`  | `boolean | undefined`                      | —       | Whether or not the component is purely decorative. \<br>When \`true\`, accessibility-related attributes\<br>are updated so that that the rendered element is removed from the accessibility tree.            |
| `asChild`     | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`          | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`       | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |
::

## 更新紀錄

:admin-changelog{component="AdminStepper"}


# Switch

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/switch
```

```ts
import { AdminSwitch } from '@/components/admin/switch'
```

## 用法

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminSwitch } from '@/registry/admin/ui/switch'

const on = ref(false)
</script>

<template>
  <admin-switch v-model="on" />
</template>
```

## 場景

### 帶文字標籤

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminSwitch } from '@/registry/admin/ui/switch'

const on = ref(true)
</script>

<template>
  <admin-switch v-model="on" checked-text="ON" unchecked-text="OFF" />
</template>
```

### 停用狀態

```vue
<script setup lang="ts">
import { AdminSwitch } from '@/registry/admin/ui/switch'
</script>

<template>
  <div class="flex items-center gap-6">
    <admin-switch disabled :model-value="false" />
    <admin-switch disabled :model-value="true" />
  </div>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-switch v-model="value" />
</template>
```

### admin-switch

::div{data-admin-api-table=""}
#### Props

| 名稱              | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `defaultValue`  | `boolean | undefined`                      | —       | The state of the switch when it is initially rendered. Use when you do not need to control its state.                                                                                                        |
| `modelValue`    | `boolean | null | undefined`               | —       | The controlled state of the switch. Can be bind as \`v-model\`.                                                                                                                                              |
| `disabled`      | `boolean | undefined`                      | —       | When \`true\`, prevents the user from interacting with the switch.                                                                                                                                           |
| `id`            | `string | undefined`                       | —       | —                                                                                                                                                                                                            |
| `value`         | `string | undefined`                       | —       | The value given as data when submitted with a \`name\`.                                                                                                                                                      |
| `trueValue`     | `boolean | undefined`                      | —       | The value used when the switch is on. Defaults to \`true\`.                                                                                                                                                  |
| `falseValue`    | `boolean | undefined`                      | —       | The value used when the switch is off. Defaults to \`false\`.                                                                                                                                                |
| `asChild`       | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`            | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `name`          | `string | undefined`                       | —       | The name of the field. Submitted with its owning form as part of a name/value pair.                                                                                                                          |
| `required`      | `boolean | undefined`                      | —       | When \`true\`, indicates that the user must set the value before the owning form can be submitted.                                                                                                           |
| `class`         | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |
| `checkedText`   | `string | undefined`                       | —       | 開啟狀態顯示的文字（亦可用 \`#checkedText\` slot）                                                                                                                                                                         |
| `uncheckedText` | `string | undefined`                       | —       | 關閉狀態顯示的文字（亦可用 \`#uncheckedText\` slot）                                                                                                                                                                       |
| `isError`       | `boolean | undefined`                      | —       | 設為 \`true\` 時套用錯誤狀態樣式（顯示 \`data-is-error\` 屬性供樣式 hook）                                                                                                                                                       |

#### Events

| 名稱                  | Payload   | 說明 |
| ------------------- | --------- | -- |
| `update:modelValue` | `boolean` | —  |

#### Slots

| 名稱              | Bindings                   | 說明                                      |
| --------------- | -------------------------- | --------------------------------------- |
| `checkedText`   | `any`                      | 自訂開啟狀態文字內容（取代 \`checkedText\` prop）     |
| `uncheckedText` | `any`                      | 自訂關閉狀態文字內容（取代 \`uncheckedText\` prop）   |
| `thumb`         | `{ modelValue: boolean; }` | 自訂 thumb 內容，bindings 含當前 \`modelValue\` |
::

## 更新紀錄

:admin-changelog{component="AdminSwitch"}


# Tabs

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/tabs
```

```ts
import {
  AdminTabs,
  AdminTabsContent,
  AdminTabsList,
  AdminTabsTrigger,
} from '@/components/admin/tabs'
```

## 用法

```vue
<script setup lang="ts">
import {
  AdminTabs,
  AdminTabsContent,
  AdminTabsList,
  AdminTabsTrigger
} from '@/registry/admin/ui/tabs'
</script>

<template>
  <admin-tabs class="w-80" default-value="a">
    <admin-tabs-list>
      <admin-tabs-trigger value="a">Account</admin-tabs-trigger>
      <admin-tabs-trigger value="b">Password</admin-tabs-trigger>
    </admin-tabs-list>
    <admin-tabs-content class="pt-3" value="a">Account panel</admin-tabs-content>
    <admin-tabs-content class="pt-3" value="b">Password panel</admin-tabs-content>
  </admin-tabs>
</template>
```

## 場景

### 受控模式

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminButton } from '@/registry/admin/ui/button'
import {
  AdminTabs,
  AdminTabsContent,
  AdminTabsList,
  AdminTabsTrigger
} from '@/registry/admin/ui/tabs'

const active = ref<string | number>('account')
</script>

<template>
  <div class="flex flex-col gap-3">
    <div class="flex items-center gap-2">
      <span class="typo-content-medium">目前分頁：{{ active }}</span>
      <admin-button size="small" @click="active = active === 'account' ? 'password' : 'account'">
        外部切換
      </admin-button>
    </div>
    <admin-tabs v-model="active" class="w-80">
      <admin-tabs-list>
        <admin-tabs-trigger value="account">Account</admin-tabs-trigger>
        <admin-tabs-trigger value="password">Password</admin-tabs-trigger>
      </admin-tabs-list>
      <admin-tabs-content class="pt-3" value="account">Account panel</admin-tabs-content>
      <admin-tabs-content class="pt-3" value="password">Password panel</admin-tabs-content>
    </admin-tabs>
  </div>
</template>
```

## Type-safe 封裝

`AdminTabs` 已是 generic（`T extends StringOrNumber`），以較嚴的 ref 綁定 `v-model` 即可收斂為 tab value 的 literal union。若要讓 value 與清單對齊、並讓每個 tab 的內容仍保有完整彈性，可自行封裝：傳入 `items`（建議加 `as const`），由封裝元件以 `items` 為單一事實來源渲染各 trigger 與 content shell，content 由使用端以 `#panel-<value>` 具名 slot 填入。

如此 `items` 即聯集來源，各 trigger 的 `value` 結構上不可能越界；型別安全落在 `v-model` 與 `defaultValue` 必須對齊 `items` 的 value union（允許 `undefined` 表未選）。封裝再以 `defineSlots` 將 content slot 收斂為 `panel-<value>` 聯集，填入不在清單內的 slot 名亦會編譯期報錯。

> 此食譜刻意精簡，未透出 trigger 的 `badge`／`badgeValue`；需要時可自行 fork 擴充。封裝元件僅為文件示範，不屬 registry 安裝產物。

```vue
<script
  setup
  lang="ts"
  generic="
    TItems extends ReadonlyArray<{
      value: string | number
      label: string
      disabled?: boolean
    }>
  "
>
import type { AdminTabsEmits, AdminTabsProps } from '@/registry/admin/ui/tabs'
import { reactiveOmit } from '@vueuse/core'
import { useForwardPropsEmits } from 'reka-ui'
import {
  AdminTabs,
  AdminTabsContent,
  AdminTabsList,
  AdminTabsTrigger
} from '@/registry/admin/ui/tabs'

type TItem = TItems[number]
// v-model / defaultValue 型別跟著 items 走：允許 undefined 表初始未選
type TValue = TItem['value']

defineOptions({
  name: 'typed-admin-tabs'
})

const props = defineProps<
  AdminTabsProps<TValue> & {
    items: TItems
  }
>()

const emits = defineEmits<
  Omit<AdminTabsEmits<TValue>, 'update:modelValue'> & {
    'update:modelValue': [value: TValue]
  }
>()

defineSlots<Partial<Record<`panel-${TValue}`, (props: Record<string, never>) => unknown>>>()

const delegatedProps = reactiveOmit(props, 'items')
const forwarded = useForwardPropsEmits(delegatedProps, emits)
</script>

<template>
  <admin-tabs v-bind="forwarded">
    <admin-tabs-list>
      <admin-tabs-trigger
        v-for="item in props.items"
        :key="item.value"
        :disabled="item.disabled"
        :value="item.value"
      >
        {{ item.label }}
      </admin-tabs-trigger>
    </admin-tabs-list>
    <admin-tabs-content v-for="item in props.items" :key="item.value" :value="item.value">
      <slot :name="`panel-${item.value}` as `panel-${TValue}`"></slot>
    </admin-tabs-content>
  </admin-tabs>
</template>
```

::alert{title="需開啟 strictVModel" type="info"}
型別檢查需開啟 `strictVModel`（若已開啟 `strictTemplates` 則已包含）。設定見 [Type-safe](https://component-registry-4d4d86.gitlab.io/docs/get-started/type-safe)。下列同時含合法綁定與刻意錯誤綁定；錯誤處以 `@vue-expect-error` 標示。
::

```vue
<script setup lang="ts">
import { ref } from 'vue'
import TypedAdminTabs from './typed-admin-tabs-demo.vue'

const items = [
  { value: 'overview', label: '總覽' },
  { value: 'settings', label: '設定' }
] as const

const active = ref<(typeof items)[number]['value']>('overview')
const wrong = ref('unknown')
const wrongDefault = 'unknown'
</script>

<template>
  <div class="flex w-full max-w-md flex-col gap-6">
    <typed-admin-tabs v-model="active" :items="items">
      <template #panel-overview>總覽內容</template>
      <template #panel-settings>設定內容</template>
    </typed-admin-tabs>

    <!-- @vue-expect-error value 不在 items 的 value union 內 -->
    <typed-admin-tabs v-model="wrong" :items="items">
      <template #panel-overview>總覽內容</template>
      <template #panel-settings>設定內容</template>
    </typed-admin-tabs>

    <!-- @vue-expect-error defaultValue 不在 items 的 value union 內 -->
    <typed-admin-tabs :default-value="wrongDefault" :items="items">
      <template #panel-overview>總覽內容</template>
      <template #panel-settings>設定內容</template>
    </typed-admin-tabs>

    <typed-admin-tabs v-model="active" :items="items">
      <template #panel-overview>總覽內容</template>
      <template #panel-settings>設定內容</template>
      <!-- @vue-expect-error slot 名不在 items 的 panel-<value> 聯集內 -->
      <template #panel-typo>不存在的 slot</template>
    </typed-admin-tabs>
  </div>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-tabs default-value="overview">
    <admin-tabs-list>
      <admin-tabs-trigger value="overview">概覽</admin-tabs-trigger>
      <admin-tabs-trigger value="details">明細</admin-tabs-trigger>
    </admin-tabs-list>
    <admin-tabs-content value="overview">概覽內容</admin-tabs-content>
    <admin-tabs-content value="details">明細內容</admin-tabs-content>
  </admin-tabs>
</template>
```

### admin-tabs

::div{data-admin-api-table=""}
#### Props

| 名稱               | 型別                                         | 預設值          | 說明                                                                                                                                                                                                           |
| ---------------- | ------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `class`          | `ClassValue`                               | —            | 根元素之自訂 class                                                                                                                                                                                                 |
| `defaultValue`   | `TModelValue | undefined`                  | —            | The value of the tab that should be active when initially rendered. Use when you do not need to control the state of the tabs                                                                                |
| `orientation`    | `DataOrientation | undefined`              | `horizontal` | The orientation the tabs are laid out.\<br>Mainly so arrow navigation is done accordingly (left & right vs. up & down)                                                                                       |
| `dir`            | `Direction | undefined`                    | —            | The reading direction of the combobox when applicable. \<br> If omitted, inherits globally from \`ConfigProvider\` or assumes LTR (left-to-right) reading mode.                                              |
| `activationMode` | `"automatic" | "manual" | undefined`       | `automatic`  | Whether a tab is activated automatically (on focus) or manually (on click).                                                                                                                                  |
| `modelValue`     | `TModelValue | undefined`                  | —            | The controlled value of the tab to activate. Can be bind as \`v-model\`.                                                                                                                                     |
| `unmountOnHide`  | `boolean | undefined`                      | `` `true` `` | When \`true\`, the element will be unmounted on closed state.                                                                                                                                                |
| `asChild`        | `boolean | undefined`                      | —            | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`             | `globalThis.Component | AsTag | undefined` | `"div"`      | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `size`           | `"xs" | "sm" | undefined`                  | `"xs"`       | tabs trigger 尺寸（透過 context 傳遞給所有 trigger）                                                                                                                                                                    |

#### Events

| 名稱                  | Payload       | 說明 |
| ------------------- | ------------- | -- |
| `update:modelValue` | `TModelValue` | —  |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-tabs-list

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `loop`    | `boolean | undefined`                      | —       | When \`true\`, keyboard navigation will loop from last tab to first, and vice versa.                                                                                                                         |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-tabs-trigger

::div{data-admin-api-table=""}
#### Props

| 名稱           | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| ------------ | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `value`\*    | `StringOrNumber`                           | —       | A unique value that associates the trigger with a content.                                                                                                                                                   |
| `disabled`   | `boolean | undefined`                      | —       | When \`true\`, prevents the user from interacting with the tab.                                                                                                                                              |
| `asChild`    | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`         | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`      | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |
| `badge`      | `boolean | undefined`                      | `false` | 設為 \`true\` 時於 trigger 右側顯示 badge                                                                                                                                                                            |
| `badgeValue` | `number | undefined`                       | —       | badge 顯示的數字（搭配 \`badge: true\` 使用）                                                                                                                                                                           |

*\\\* 代表必填*

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-tabs-content

::div{data-admin-api-table=""}
#### Props

| 名稱           | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| ------------ | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `value`\*    | `StringOrNumber`                           | —       | A unique value that associates the content with a trigger.                                                                                                                                                   |
| `forceMount` | `boolean | undefined`                      | —       | Used to force mounting when more control is needed. Useful when\<br>controlling animation with Vue animation libraries.                                                                                      |
| `asChild`    | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`         | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`      | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

*\\\* 代表必填*

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

## 更新紀錄

:admin-changelog{component="AdminTabs"}


# Tag

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/tag
```

```ts
import { AdminTag } from '@/components/admin/tag'
```

## 用法

```vue
<script setup lang="ts">
import { AdminTag } from '@/registry/admin/ui/tag'
</script>

<template>
  <div class="flex items-center gap-2">
    <admin-tag>Vue</admin-tag>
    <admin-tag>Nuxt</admin-tag>
  </div>
</template>
```

## 場景

### 圓角變體

```vue
<script setup lang="ts">
import { AdminTag } from '@/registry/admin/ui/tag'
</script>

<template>
  <div class="flex items-center gap-2">
    <admin-tag rounded="square-filled">Square</admin-tag>
    <admin-tag rounded="round-filled">Rounded</admin-tag>
  </div>
</template>
```

### 搭配 icon

```vue
<script setup lang="ts">
import { AdminTag } from '@/registry/admin/ui/tag'
</script>

<template>
  <div class="flex items-center gap-2">
    <admin-tag rounded="round-filled">
      <icon name="lucide:check" />
      完成
    </admin-tag>
    <admin-tag rounded="round-filled">
      <icon name="lucide:clock" />
      進行中
    </admin-tag>
    <admin-tag rounded="square-filled">
      <icon name="lucide:tag" />
      標籤
    </admin-tag>
  </div>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-tag>標籤文字</admin-tag>
</template>
```

### admin-tag

::div{data-admin-api-table=""}
#### Props

| 名稱         | 型別                                             | 預設值 | 說明                    |
| ---------- | ---------------------------------------------- | --- | --------------------- |
| `class`    | `ClassValue`                                   | —   | 根元素之自訂 class          |
| `rounded`  | `"round-filled" | "square-filled" | undefined` | —   | 圓角樣式變體                |
| `closable` | `boolean | undefined`                          | —   | 設為 \`true\` 時顯示右側關閉按鈕 |

#### Events

| 名稱      | Payload | 說明          |
| ------- | ------- | ----------- |
| `close` | —       | 點擊右側關閉按鈕時觸發 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

## 更新紀錄

:admin-changelog{component="AdminTag"}


# Textarea

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/textarea
```

```ts
import {
  AdminTextarea,
  AdminTextareaWordLimit,
} from '@/components/admin/textarea'
```

## 用法

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminTextarea } from '@/registry/admin/ui/textarea'

const value = ref('')
</script>

<template>
  <admin-textarea v-model="value" class="w-64" placeholder="Write something..." />
</template>
```

## 場景

### 帶字數限制

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminTextarea, AdminTextareaWordLimit } from '@/registry/admin/ui/textarea'

const value = ref('')
</script>

<template>
  <admin-textarea v-model="value" class="w-72" placeholder="最多 120 個字" :maxlength="120">
    <template #footer>
      <admin-textarea-word-limit />
    </template>
  </admin-textarea>
</template>
```

### 停用狀態

```vue
<script setup lang="ts">
import { AdminTextarea } from '@/registry/admin/ui/textarea'
</script>

<template>
  <admin-textarea
    class="w-72"
    model-value="這個欄位目前被停用，無法編輯。"
    placeholder="停用狀態"
    disabled
  />
</template>
```

### 錯誤狀態

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminTextarea } from '@/registry/admin/ui/textarea'

const value = ref('錯誤內容')
</script>

<template>
  <admin-textarea v-model="value" class="w-64" placeholder="Write something..." is-error />
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-textarea v-model="value" placeholder="輸入內容" :maxlength="200">
    <admin-textarea-word-limit />
  </admin-textarea>
</template>
```

### admin-textarea

::div{data-admin-api-table=""}
#### Props

| 名稱             | 型別                    | 預設值     | 說明                                             |
| -------------- | --------------------- | ------- | ---------------------------------------------- |
| `defaultValue` | `string | undefined`  | —       | 初始值（非控制模式）                                     |
| `modelValue`   | `string | undefined`  | —       | 受控值，以 \`v-model\` 綁定                           |
| `placeholder`  | `string | undefined`  | —       | 預設提示文字                                         |
| `disabled`     | `boolean | undefined` | —       | 設為 \`true\` 時禁用輸入並套用視覺停用樣式                     |
| `maxlength`    | `number | undefined`  | —       | 限制最大字元數（並由 \`admin-textarea-word-limit\` 顯示計數） |
| `class`        | `ClassValue`          | —       | 根元素之自訂 class                                   |
| `isError`      | `boolean | undefined` | `false` | 設為 \`true\` 時套用錯誤狀態樣式與 \`aria-invalid\`        |
| `id`           | `string | undefined`  | —       | 透傳至內層 \`textarea\` 之 \`id\`；純透傳，未提供時不自動生成      |
| `name`         | `string | undefined`  | —       | 透傳至內層 \`textarea\` 之 \`name\`，供原生表單提交使用        |

#### Events

| 名稱                  | Payload      | 說明                                                   |
| ------------------- | ------------ | ---------------------------------------------------- |
| `blur`              | `FocusEvent` | 內層 \`textarea\` 失焦時轉發之原生事件                           |
| `change`            | `Event`      | 內層 \`textarea\` 觸發原生 \`change\`（值變更並 commit）時轉發之原生事件 |
| `input`             | `Event`      | 內層 \`textarea\` 觸發原生 \`input\`（每次輸入）時轉發之原生事件         |
| `update:modelValue` | `string`     | —                                                    |

#### Slots

| 名稱       | Bindings | 說明 |
| -------- | -------- | -- |
| `footer` | `{}`     | —  |

#### Expose

| 名稱            | 簽名                           | 說明                                                              |
| ------------- | ---------------------------- | --------------------------------------------------------------- |
| `textareaRef` | `HTMLTextAreaElement | null` | 內部原生 textarea 元素之 template ref，可用於程式化 focus / blur / select 等操作 |
::

### admin-textarea-word-limit

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別        | 預設值 | 說明 |
| ------- | --------- | --- | -- |
| `class` | `unknown` | —   | —  |
::

## 更新紀錄

:admin-changelog{component="AdminTextarea"}


# Timeline

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/timeline
```

```ts
import {
  AdminTimeline,
  AdminTimelineContent,
  AdminTimelineDate,
  AdminTimelineHeader,
  AdminTimelineIndicator,
  AdminTimelineItem,
  AdminTimelineSeparator,
  AdminTimelineTitle,
} from '@/components/admin/timeline'
```

## 用法

```vue
<script setup lang="ts">
import type { TimelineItemStatus } from '@/registry/admin/ui/timeline'
import {
  AdminTimeline,
  AdminTimelineContent,
  AdminTimelineDate,
  AdminTimelineHeader,
  AdminTimelineIndicator,
  AdminTimelineItem,
  AdminTimelineSeparator,
  AdminTimelineTitle
} from '@/registry/admin/ui/timeline'

const events: {
  status: TimelineItemStatus
  date: string
  label: string
  title: string
  content: string
}[] = [
  {
    status: 'completed',
    date: '2026-03-01',
    label: '3 月 1 日',
    title: '專案啟動',
    content: '建立 repo 與初始 stakeholder 名單，完成 kick-off 會議。'
  },
  {
    status: 'completed',
    date: '2026-04-12',
    label: '4 月 12 日',
    title: '需求審查通過',
    content: '產品需求書經 PM/Tech Lead 簽核，進入設計階段。'
  },
  {
    status: 'current',
    date: '2026-05-09',
    label: '5 月 9 日',
    title: '開發中',
    content: '前後端並行開發，預計於月底進入測試。'
  },
  {
    status: 'pending',
    date: '2026-06-30',
    label: '6 月 30 日',
    title: '發佈',
    content: '完成上線審核並公開發佈。'
  }
]
</script>

<template>
  <admin-timeline class="w-full max-w-md">
    <admin-timeline-item v-for="event in events" :key="event.title" :status="event.status">
      <admin-timeline-header>
        <admin-timeline-date :datetime="event.date">{{ event.label }}</admin-timeline-date>
        <admin-timeline-title>{{ event.title }}</admin-timeline-title>
      </admin-timeline-header>
      <admin-timeline-indicator />
      <admin-timeline-separator />
      <admin-timeline-content>{{ event.content }}</admin-timeline-content>
    </admin-timeline-item>
  </admin-timeline>
</template>
```

## 場景

### 自訂 indicator（icon）

```vue
<script setup lang="ts">
import type { TimelineItemStatus } from '@/registry/admin/ui/timeline'
import { IconCheck, IconCircle, IconClock, IconX } from '@tabler/icons-vue'
import {
  AdminTimeline,
  AdminTimelineDate,
  AdminTimelineHeader,
  AdminTimelineIndicator,
  AdminTimelineItem,
  AdminTimelineSeparator,
  AdminTimelineTitle
} from '@/registry/admin/ui/timeline'

const iconMap = {
  completed: IconCheck,
  current: IconClock,
  error: IconX,
  pending: IconCircle
}

const events: { status: TimelineItemStatus; date: string; label: string; title: string }[] = [
  { status: 'completed', date: '2026-04-15', label: '已提交', title: '提交申請' },
  { status: 'completed', date: '2026-04-22', label: '已審核', title: '主管審核通過' },
  { status: 'error', date: '2026-05-01', label: '已退件', title: '財務複核退回' },
  { status: 'current', date: '2026-05-09', label: '處理中', title: '重新送審' },
  { status: 'pending', date: '2026-05-16', label: '待撥款', title: '撥款' }
]
</script>

<template>
  <admin-timeline class="w-full max-w-md">
    <admin-timeline-item v-for="event in events" :key="event.title" :status="event.status">
      <admin-timeline-header>
        <admin-timeline-date :datetime="event.date">{{ event.label }}</admin-timeline-date>
        <admin-timeline-title>{{ event.title }}</admin-timeline-title>
      </admin-timeline-header>
      <admin-timeline-indicator class="flex items-center justify-center" as-child>
        <component :is="iconMap[event.status]" :stroke-width="2.5" />
      </admin-timeline-indicator>
      <admin-timeline-separator />
    </admin-timeline-item>
  </admin-timeline>
</template>
```

### 水平 orientation

```vue
<script setup lang="ts">
import type { TimelineItemStatus } from '@/registry/admin/ui/timeline'
import {
  AdminTimeline,
  AdminTimelineDate,
  AdminTimelineHeader,
  AdminTimelineIndicator,
  AdminTimelineItem,
  AdminTimelineSeparator,
  AdminTimelineTitle
} from '@/registry/admin/ui/timeline'

const steps: { status: TimelineItemStatus; date: string; title: string }[] = [
  { status: 'completed', date: '04/01', title: '受理' },
  { status: 'completed', date: '04/15', title: '審核' },
  { status: 'current', date: '04/28', title: '處理' },
  { status: 'pending', date: '05/05', title: '完成' },
  { status: 'pending', date: '05/10', title: '結案' }
]
</script>

<template>
  <admin-timeline class="w-full" orientation="horizontal">
    <admin-timeline-item v-for="s in steps" :key="s.title" :status="s.status">
      <admin-timeline-header>
        <admin-timeline-date>{{ s.date }}</admin-timeline-date>
        <admin-timeline-title>{{ s.title }}</admin-timeline-title>
      </admin-timeline-header>
      <admin-timeline-indicator />
      <admin-timeline-separator />
    </admin-timeline-item>
  </admin-timeline>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-timeline>
    <admin-timeline-item status="completed">
      <admin-timeline-header>
        <admin-timeline-indicator />
        <admin-timeline-date datetime="2026-05-01">2026/05/01</admin-timeline-date>
      </admin-timeline-header>
      <admin-timeline-separator />
      <admin-timeline-content>
        <admin-timeline-title>建立訂單</admin-timeline-title>
      </admin-timeline-content>
    </admin-timeline-item>
  </admin-timeline>
</template>
```

### admin-timeline

::div{data-admin-api-table=""}
#### Props

| 名稱            | 型別                                | 預設值          | 說明           |
| ------------- | --------------------------------- | ------------ | ------------ |
| `orientation` | `TimelineOrientation | undefined` | `"vertical"` | 時間軸方向        |
| `class`       | `ClassValue`                      | —            | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-timeline-item

::div{data-admin-api-table=""}
#### Props

| 名稱       | 型別                               | 預設值         | 說明                                      |
| -------- | -------------------------------- | ----------- | --------------------------------------- |
| `status` | `TimelineItemStatus | undefined` | `"pending"` | 該 item 的狀態；決定 indicator 與 separator 的配色 |
| `class`  | `ClassValue`                     | —           | 根元素之自訂 class                            |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-timeline-date

::div{data-admin-api-table=""}
#### Props

| 名稱         | 型別                                         | 預設值      | 說明                                                                                                                                                                                                           |
| ---------- | ------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild`  | `boolean | undefined`                      | —        | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`       | `globalThis.Component | AsTag | undefined` | `"time"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `datetime` | `string | undefined`                       | —        | 對應 \`\<time datetime>\`；機器可讀的日期／時間字串                                                                                                                                                                         |
| `class`    | `ClassValue`                               | —        | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-timeline-indicator

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| --------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`      | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`   | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-timeline-content

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-timeline-header

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-timeline-separator

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |
::

### admin-timeline-title

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

## 注意事項

- 每個 `admin-timeline-item` 以 `status` 各自標註狀態（`pending` / `current` / `completed` / `error`，預設 `pending`）；狀態由呼叫方依實際資料指定，root 不持有 active step。
- 配色對應：`completed` 綠、`current` 藍（實心 + ring）、`pending` 灰、`error` 紅；連接線於 `completed` 轉綠、`error` 轉紅。
- `status` 為**純視覺**（indicator 帶 `aria-hidden`）。為確保無障礙，狀態語意務必同時以 `admin-timeline-title` / `admin-timeline-content` 的文字表達，勿只靠顏色。
- `AdminTimelineDate` 與 `AdminTimelineIndicator` 支援 `as-child`，其他 sub-component 不支援。
- Indicator **不建議**塞 interactive 元素（`<button>`、`<a>` 等）。Timeline 的定位是視覺呈現，需要互動式步驟切換請改用 [`admin-stepper`](https://component-registry-4d4d86.gitlab.io/docs/admin/stepper)。

## 更新紀錄

:admin-changelog{component="AdminTimeline"}


# Tooltip

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/tooltip
```

```ts
import {
  AdminTooltip,
  AdminTooltipContent,
  AdminTooltipProvider,
  AdminTooltipTrigger,
} from '@/components/admin/tooltip'
```

## 用法

```vue
<script setup lang="ts">
import { AdminButton } from '@/registry/admin/ui/button'
import {
  AdminTooltip,
  AdminTooltipContent,
  AdminTooltipProvider,
  AdminTooltipTrigger
} from '@/registry/admin/ui/tooltip'
</script>

<template>
  <admin-tooltip-provider>
    <admin-tooltip>
      <admin-tooltip-trigger as-child>
        <admin-button>Hover me</admin-button>
      </admin-tooltip-trigger>
      <admin-tooltip-content>Tooltip content</admin-tooltip-content>
    </admin-tooltip>
  </admin-tooltip-provider>
</template>
```

## 場景

### 四向擺放

```vue
<script setup lang="ts">
import { AdminButton } from '@/registry/admin/ui/button'
import {
  AdminTooltip,
  AdminTooltipContent,
  AdminTooltipProvider,
  AdminTooltipTrigger
} from '@/registry/admin/ui/tooltip'
</script>

<template>
  <admin-tooltip-provider>
    <div class="flex items-center gap-3">
      <admin-tooltip>
        <admin-tooltip-trigger as-child>
          <admin-button size="small" variant="outline">Top</admin-button>
        </admin-tooltip-trigger>
        <admin-tooltip-content side="top">出現在上方</admin-tooltip-content>
      </admin-tooltip>

      <admin-tooltip>
        <admin-tooltip-trigger as-child>
          <admin-button size="small" variant="outline">Right</admin-button>
        </admin-tooltip-trigger>
        <admin-tooltip-content side="right">出現在右方</admin-tooltip-content>
      </admin-tooltip>

      <admin-tooltip>
        <admin-tooltip-trigger as-child>
          <admin-button size="small" variant="outline">Bottom</admin-button>
        </admin-tooltip-trigger>
        <admin-tooltip-content side="bottom">出現在下方</admin-tooltip-content>
      </admin-tooltip>

      <admin-tooltip>
        <admin-tooltip-trigger as-child>
          <admin-button size="small" variant="outline">Left</admin-button>
        </admin-tooltip-trigger>
        <admin-tooltip-content side="left">出現在左方</admin-tooltip-content>
      </admin-tooltip>
    </div>
  </admin-tooltip-provider>
</template>
```

### 富文字內容

```vue
<script setup lang="ts">
import { AdminButton } from '@/registry/admin/ui/button'
import {
  AdminTooltip,
  AdminTooltipContent,
  AdminTooltipProvider,
  AdminTooltipTrigger
} from '@/registry/admin/ui/tooltip'
</script>

<template>
  <admin-tooltip-provider>
    <admin-tooltip>
      <admin-tooltip-trigger as-child>
        <admin-button variant="outline">Hover for details</admin-button>
      </admin-tooltip-trigger>
      <admin-tooltip-content class="max-w-60">
        <div class="flex flex-col gap-1">
          <span class="typo-title-small">預約提示</span>
          <span class="typo-caption-small">
            預約成立後系統會寄送確認信，可在個人頁面查看與取消。
          </span>
        </div>
      </admin-tooltip-content>
    </admin-tooltip>
  </admin-tooltip-provider>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-tooltip-provider>
    <admin-tooltip>
      <admin-tooltip-trigger>觸發元素</admin-tooltip-trigger>
      <admin-tooltip-content>說明文字</admin-tooltip-content>
    </admin-tooltip>
  </admin-tooltip-provider>
</template>
```

### admin-tooltip-provider

::div{data-admin-api-table=""}
#### Props

| 名稱                        | 型別                                | 預設值     | 說明                                                                                                                                                                                                                                            |
| ------------------------- | --------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `delayDuration`           | `number | undefined`              | `0`     | The duration from when the pointer enters the trigger until the tooltip gets opened.                                                                                                                                                          |
| `skipDelayDuration`       | `number | undefined`              | `300`   | How much time a user has to enter another trigger without incurring a delay again.                                                                                                                                                            |
| `disableHoverableContent` | `boolean | undefined`             | `false` | When \`true\`, trying to hover the content will result in the tooltip closing as the pointer leaves the trigger.                                                                                                                              |
| `disableClosingTrigger`   | `boolean | undefined`             | `false` | When \`true\`, clicking on trigger will not close the content.                                                                                                                                                                                |
| `disabled`                | `boolean | undefined`             | `false` | When \`true\`, disable tooltip                                                                                                                                                                                                                |
| `ignoreNonKeyboardFocus`  | `boolean | undefined`             | `false` | Prevent the tooltip from opening if the focus did not come from\<br>the keyboard by matching against the \`:focus-visible\` selector.\<br>This is useful if you want to avoid opening it when switching\<br>browser tabs or closing a dialog. |
| `content`                 | `TooltipContentProps | undefined` | —       | Default settings that will be used by all tooltip components.                                                                                                                                                                                 |
| `class`                   | `unknown`                         | —       | —                                                                                                                                                                                                                                             |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-tooltip

::div{data-admin-api-table=""}
#### Props

| 名稱                        | 型別                    | 預設值     | 說明                                                                                                                                                                                                                                            |
| ------------------------- | --------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `defaultOpen`             | `boolean | undefined` | —       | The open state of the tooltip when it is initially rendered.\<br>Use when you do not need to control its open state.                                                                                                                          |
| `open`                    | `boolean | undefined` | —       | The controlled open state of the tooltip.                                                                                                                                                                                                     |
| `delayDuration`           | `number | undefined`  | `700`   | Override the duration given to the \`Provider\` to customise\<br>the open delay for a specific tooltip.                                                                                                                                       |
| `disableHoverableContent` | `boolean | undefined` | —       | Prevents Tooltip.Content from remaining open when hovering.\<br>Disabling this has accessibility consequences. Inherits\<br>from Tooltip.Provider.                                                                                            |
| `disableClosingTrigger`   | `boolean | undefined` | `false` | When \`true\`, clicking on trigger will not close the content.                                                                                                                                                                                |
| `disabled`                | `boolean | undefined` | `false` | When \`true\`, disable tooltip                                                                                                                                                                                                                |
| `ignoreNonKeyboardFocus`  | `boolean | undefined` | `false` | Prevent the tooltip from opening if the focus did not come from\<br>the keyboard by matching against the \`:focus-visible\` selector.\<br>This is useful if you want to avoid opening it when switching\<br>browser tabs or closing a dialog. |
| `class`                   | `unknown`             | —       | —                                                                                                                                                                                                                                             |

#### Events

| 名稱            | Payload   | 說明 |
| ------------- | --------- | -- |
| `update:open` | `boolean` | —  |

#### Slots

| 名稱        | Bindings             | 說明 |
| --------- | -------------------- | -- |
| `default` | `{ open: boolean; }` | —  |
::

### admin-tooltip-content

::div{data-admin-api-table=""}
#### Props

| 名稱                       | 型別                                                                                  | 預設值           | 說明                                                                                                                                                                                                                                  |
| ------------------------ | ----------------------------------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `forceMount`             | `boolean | undefined`                                                               | —             | Used to force mounting when more control is needed. Useful when\<br>controlling animation with Vue animation libraries.                                                                                                             |
| `ariaLabel`              | `string | undefined`                                                                | `String`      | By default, screenreaders will announce the content inside\<br>the component. If this is not descriptive enough, or you have\<br>content that cannot be announced, use aria-label as a more\<br>descriptive label.                  |
| `asChild`                | `boolean | undefined`                                                               | —             | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details.                        |
| `as`                     | `globalThis.Component | AsTag | undefined`                                          | `"div"`       | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                                        |
| `align`                  | `"start" | "end" | "center" | undefined`                                            | `"center"`    | The preferred alignment against the trigger.\<br>May change when collisions occur.                                                                                                                                                  |
| `sideOffset`             | `number | undefined`                                                                | `4`           | The distance in pixels from the trigger.                                                                                                                                                                                            |
| `side`                   | `"top" | "right" | "bottom" | "left" | undefined`                                   | `"bottom"`    | The preferred side of the trigger to render against when open.\<br>Will be reversed when collisions occur and avoidCollisions\<br>is enabled.                                                                                       |
| `alignOffset`            | `number | undefined`                                                                | `0`           | An offset in pixels from the \`start\` or \`end\` alignment options.                                                                                                                                                                |
| `avoidCollisions`        | `boolean | undefined`                                                               | `true`        | When \`true\`, overrides the side and align preferences\<br>to prevent collisions with boundary edges.                                                                                                                              |
| `collisionBoundary`      | `Element | (Element | null)[] | null | undefined`                                   | `[]`          | The element used as the collision boundary. By default\<br>this is the viewport, though you can provide additional\<br>element(s) to be included in this check.                                                                     |
| `collisionPadding`       | `number | Partial<Record<"top" | "right" | "bottom" | "left", number>> | undefined` | `0`           | The distance in pixels from the boundary edges where collision\<br>detection should occur. Accepts a number (same for all sides),\<br>or a partial padding object, for example: { top: 20, left: 20 }.                              |
| `arrowPadding`           | `number | undefined`                                                                | `0`           | The padding between the arrow and the edges of the content.\<br>If your content has border-radius, this will prevent it from\<br>overflowing the corners.                                                                           |
| `sticky`                 | `"partial" | "always" | undefined`                                                  | `"partial"`   | The sticky behavior on the align axis. \`partial\` will keep the\<br>content in the boundary as long as the trigger is at least partially\<br>in the boundary whilst "always" will keep the content in the boundary\<br>regardless. |
| `hideWhenDetached`       | `boolean | undefined`                                                               | `false`       | Whether to hide the content when the trigger becomes fully occluded.                                                                                                                                                                |
| `positionStrategy`       | `"fixed" | "absolute" | undefined`                                                  | —             | The type of CSS position property to use.                                                                                                                                                                                           |
| `updatePositionStrategy` | `"always" | "optimized" | undefined`                                                | `'optimized'` | Strategy to update the position of the floating element on every animation frame.                                                                                                                                                   |
| `class`                  | `ClassValue`                                                                        | —             | 根元素之自訂 class                                                                                                                                                                                                                        |

#### Events

| 名稱                   | Payload         | 說明 |
| -------------------- | --------------- | -- |
| `escapeKeyDown`      | `KeyboardEvent` | —  |
| `pointerDownOutside` | `Event`         | —  |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-tooltip-trigger

::div{data-admin-api-table=""}
#### Props

| 名稱          | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| ----------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `reference` | `ReferenceElement | undefined`             | —       | The reference (or anchor) element that is being referred to for positioning.\<br>If not provided will use the current component as anchor.                                                                   |
| `asChild`   | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`        | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `class`     | `unknown`                                  | —       | —                                                                                                                                                                                                            |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

## 更新紀錄

:admin-changelog{component="AdminTooltip"}


# Tree

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/tree
```

```ts
import { AdminTree, AdminTreeItem } from '@/components/admin/tree'
```

## 用法

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminTree, AdminTreeItem } from '@/registry/admin/ui/tree'

interface Node {
  id: string
  label: string
  children?: Node[]
}

const items: Node[] = [
  {
    id: '1',
    label: '標題名稱',
    children: [
      { id: '1-1', label: '項目名稱' },
      { id: '1-2', label: '項目名稱' },
      {
        id: '1-3',
        label: '標題名稱',
        children: [
          { id: '1-3-1', label: '項目名稱' },
          { id: '1-3-2', label: '項目名稱' },
          {
            id: '1-3-3',
            label: '標題名稱',
            children: [
              { id: '1-3-3-1', label: '項目名稱' },
              { id: '1-3-3-2', label: '項目名稱' },
              {
                id: '1-3-3-3',
                label: '標題名稱',
                children: [{ id: '1-3-3-3-1', label: '項目名稱' }]
              }
            ]
          }
        ]
      }
    ]
  }
]

const expanded = ref<string[]>(['1', '1-3', '1-3-3'])
const selected = ref<Node | undefined>()
</script>

<template>
  <admin-tree
    v-model="selected"
    v-model:expanded="expanded"
    class="w-[18rem] border border-text-30"
    :get-key="(node: Node) => node.id"
    :items
  >
    <template #default="{ flattenItems }">
      <admin-tree-item
        v-for="item in flattenItems"
        :key="item._id"
        v-bind="item.bind"
        :has-children="item.hasChildren"
      >
        {{ item.value.label }}
      </admin-tree-item>
    </template>
  </admin-tree>
</template>
```

## 場景

### 多選與 Checkbox

```vue
<script setup lang="ts">
import { IconCaretDownFilled, IconCaretRightFilled } from '@tabler/icons-vue'
import { ref } from 'vue'
import { AdminCheckbox, AdminCheckboxInput } from '@/registry/admin/ui/checkbox'
import { AdminTree, AdminTreeItem } from '@/registry/admin/ui/tree'

interface Node {
  id: string
  label: string
  children?: Node[]
}

const items: Node[] = [
  {
    id: 'a',
    label: '標題名稱',
    children: [
      { id: 'a-1', label: '項目名稱' },
      { id: 'a-2', label: '項目名稱' }
    ]
  },
  {
    id: 'b',
    label: '標題名稱',
    children: [
      { id: 'b-1', label: '項目名稱' },
      { id: 'b-2', label: '項目名稱' },
      {
        id: 'b-3',
        label: '標題名稱',
        children: [
          { id: 'b-3-1', label: '項目名稱' },
          { id: 'b-3-2', label: '項目名稱' }
        ]
      }
    ]
  }
]

const expanded = ref<string[]>(['a', 'b', 'b-3'])
const selected = ref<Node[]>([])
</script>

<template>
  <admin-tree
    v-model="selected"
    v-model:expanded="expanded"
    class="w-[18rem] border border-text-30"
    bubble-select
    multiple
    propagate-select
    :get-key="(node: Node) => node.id"
    :items
  >
    <template #default="{ flattenItems }">
      <admin-tree-item
        v-for="item in flattenItems"
        :key="item._id"
        v-bind="item.bind"
        :has-children="item.hasChildren"
        @select="(ev) => item.hasChildren && ev.preventDefault()"
      >
        <template #prefix="{ isSelected, isIndeterminate, isExpanded, hasChildren, handleSelect }">
          <admin-checkbox class="shrink-0 cursor-pointer" @click.stop="handleSelect()">
            <admin-checkbox-input
              class="pointer-events-none"
              tabindex="-1"
              :model-value="isIndeterminate ? 'indeterminate' : isSelected"
            />
          </admin-checkbox>
          <icon-caret-down-filled
            v-if="hasChildren && isExpanded"
            class="size-4 shrink-0 text-text-90"
          />
          <icon-caret-right-filled v-else-if="hasChildren" class="size-4 shrink-0 text-text-90" />
        </template>
        {{ item.value.label }}
      </admin-tree-item>
    </template>
  </admin-tree>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-tree v-slot="{ flattenItems }" :get-key="(item) => item.id" :items="data">
    <admin-tree-item
      v-for="item in flattenItems"
      :key="item._id"
      v-bind="item.bind"
      :has-children="item.hasChildren"
    >
      {{ item.value.label }}
    </admin-tree-item>
  </admin-tree>
</template>
```

### admin-tree

::div{data-admin-api-table=""}
#### Props

| 名稱                  | 型別                                                        | 預設值     | 說明                                                                                                                                                                                                           |
| ------------------- | --------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `class`             | `ClassValue`                                              | —       | 根元素之自訂 class                                                                                                                                                                                                 |
| `modelValue`        | `(Multiple extends true ? TValue[] : TValue) | undefined` | —       | The controlled value of the tree. Can be binded with \`v-model\`.                                                                                                                                            |
| `defaultValue`      | `(Multiple extends true ? TValue[] : TValue) | undefined` | —       | The value of the tree when initially rendered. Use when you do not need to control the state of the tree                                                                                                     |
| `items`             | `TItem[] | undefined`                                     | —       | List of items                                                                                                                                                                                                |
| `expanded`          | `string[] | undefined`                                    | —       | The controlled value of the expanded item. Can be binded with \`v-model\`.                                                                                                                                   |
| `defaultExpanded`   | `string[] | undefined`                                    | —       | The value of the expanded tree when initially rendered. Use when you do not need to control the state of the expanded tree                                                                                   |
| `getKey`\*          | `(val: TItem) => string`                                  | —       | This function is passed the index of each item and should return a unique key for that item                                                                                                                  |
| `getChildren`       | `((val: TItem) => TItem[] | undefined) | undefined`       | —       | This function is passed the index of each item and should return a list of children for that item                                                                                                            |
| `selectionBehavior` | `"toggle" | "replace" | undefined`                        | —       | How multiple selection should behave in the collection.                                                                                                                                                      |
| `multiple`          | `boolean | Multiple | undefined`                          | —       | Whether multiple options can be selected or not.                                                                                                                                                             |
| `dir`               | `Direction | undefined`                                   | —       | The reading direction of the listbox when applicable. \<br> If omitted, inherits globally from \`ConfigProvider\` or assumes LTR (left-to-right) reading mode.                                               |
| `disabled`          | `boolean | undefined`                                     | —       | When \`true\`, prevents the user from interacting with tree                                                                                                                                                  |
| `propagateSelect`   | `boolean | undefined`                                     | —       | When \`true\`, selecting parent will select the descendants. Requires \`multiple\` to be \`true\`.                                                                                                           |
| `bubbleSelect`      | `boolean | undefined`                                     | —       | When \`true\`, selecting children will update the parent state. Requires \`multiple\` to be \`true\`.                                                                                                        |
| `asChild`           | `boolean | undefined`                                     | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`                | `globalThis.Component | AsTag | undefined`                | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |

*\\\* 代表必填*

#### Events

| 名稱                  | Payload                                     | 說明 |
| ------------------- | ------------------------------------------- | -- |
| `update:modelValue` | `Multiple extends true ? TValue[] : TValue` | —  |
| `update:expanded`   | `string[]`                                  | —  |

#### Slots

| 名稱        | Bindings                                                                                                               | 說明                                                     |
| --------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `default` | `{ flattenItems: FlattenedItem<TItem>[]; modelValue: Multiple extends true ? TValue[] : TValue; expanded: string[]; }` | 預設 slot，提供樹狀資料展開後之 flattened items、當前 modelValue 與展開狀態 |
::

### admin-tree-item

::div{data-admin-api-table=""}
#### Props

| 名稱            | 型別                                         | 預設值     | 說明                                                                                                                                                                                                           |
| ------------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `class`       | `ClassValue`                               | —       | 根元素之自訂 class                                                                                                                                                                                                 |
| `value`\*     | `TItem`                                    | —       | Value given to this item                                                                                                                                                                                     |
| `level`\*     | `number`                                   | —       | Level of depth                                                                                                                                                                                               |
| `disabled`    | `boolean | undefined`                      | —       | When \`true\`, prevents the user from interacting with the item.                                                                                                                                             |
| `asChild`     | `boolean | undefined`                      | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.\<br>Read our \[Composition]\(https\://www\.reka-ui.com/docs/guides/composition) guide for more details. |
| `as`          | `globalThis.Component | AsTag | undefined` | `"div"` | The element or component this component should render as. Can be overwritten by \`asChild\`.                                                                                                                 |
| `hasChildren` | `boolean | undefined`                      | —       | 設為 \`true\` 時顯示展開／收合 caret icon                                                                                                                                                                              |

*\\\* 代表必填*

#### Events

| 名稱       | Payload              | 說明 |
| -------- | -------------------- | -- |
| `select` | `SelectEvent<TItem>` | —  |
| `toggle` | `ToggleEvent<TItem>` | —  |

#### Slots

| 名稱        | Bindings                                                                                                                                                                    | 說明                            |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| `default` | `{ isExpanded: boolean; isSelected: boolean; isIndeterminate: boolean | undefined; }`                                                                                       | 預設 slot，提供節點互動狀態              |
| `prefix`  | `{ isExpanded: boolean; isSelected: boolean; isIndeterminate: boolean | undefined; hasChildren: boolean | undefined; handleToggle: () => void; handleSelect: () => void; }` | 節點前綴 slot（預設渲染展開 caret），可覆蓋自訂 |
::

## 更新紀錄

:admin-changelog{component="AdminTree"}


# Video Player

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/video-player
```

```ts
import {
  AdminVideoPlayer,
  AdminVideoPlayerControls,
  AdminVideoPlayerFullscreen,
  AdminVideoPlayerPlay,
  AdminVideoPlayerProgress,
  AdminVideoPlayerSettings,
  AdminVideoPlayerTime,
  AdminVideoPlayerToolbar,
  AdminVideoPlayerVolume
} from '@/components/admin/video-player'
```

vidstack 是一組 web components，需要在專案 build 設定告訴 Vue compiler 把 `media-*` 開頭的 tag 當成 native custom element：

**Nuxt 3 / 4**

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  vue: {
    compilerOptions: {
      isCustomElement: (tag) => tag.startsWith('media-')
    }
  }
})
```

**Vue 3 + Vite**

```ts [vite.config.ts]
import vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag.startsWith('media-')
        }
      }
    })
  ]
})
```

## 用法

傳入 `src` 即可播放，元件根據 src 字串自動辨識 provider：YouTube URL → YouTube provider、`.m3u8` → HLS、其他 → native MP4 / WebM

```vue
<script setup lang="ts">
import { AdminVideoPlayer } from '@/registry/admin/ui/video-player'
</script>

<template>
  <admin-video-player
    poster="https://files.vidstack.io/sprite-fight/poster.webp"
    src="https://files.vidstack.io/sprite-fight/720p.mp4"
  />
</template>
```

## 場景

### HLS 串流（含解析度切換）

來源為 `.m3u8` 時，齒輪設定菜單會出現「解析度」區塊，列出 vidstack qualities 過濾後的 480 / 720 / 1080 選項；切換後寫入 `localStorage` key `admin:player:resolution`，下次播放新 HLS 影片自動套用同設定。

```vue
<script setup lang="ts">
import { AdminVideoPlayer } from '@/registry/admin/ui/video-player'
</script>

<template>
  <admin-video-player
    poster="https://files.vidstack.io/sprite-fight/poster.webp"
    src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"
  />
</template>
```

### YouTube

`src` 為 YouTube URL（`youtube.com/...` / `youtu.be/...`）或 `youtube/<id>` 時自動切換到 YouTube provider；齒輪菜單不顯示解析度區塊（YouTube provider 不支援切換）。

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { AdminVideoPlayer } from '@/registry/admin/ui/video-player'

const presets = [
  'https://www.youtube.com/watch?v=_cMxraX_5RE',
  'https://www.youtube-nocookie.com/watch?v=_cMxraX_5RE',
  'https://www.youtube.com/embed/_cMxraX_5RE',
  'https://youtu.be/_cMxraX_5RE',
  'youtube/_cMxraX_5RE'
] as const

const src = ref<string>(presets[0])
const draft = ref<string>(presets[0])

function applyDraft() {
  const trimmed = draft.value.trim()
  if (trimmed) {
    src.value = trimmed
  }
}
</script>

<template>
  <div class="flex w-full flex-col gap-3">
    <form class="flex gap-2" @submit.prevent="applyDraft">
      <input
        v-model="draft"
        placeholder="貼上 YouTube URL…"
        type="text"
        :class="
          cn(`
            flex-1 rounded-md border border-bg-60 bg-bg-90 px-3 py-1.5 text-content-medium
            text-text-90 outline-none
            focus:border-primary-50
          `)
        "
      />
      <button
        type="submit"
        :class="
          cn(`
            rounded-md bg-primary-50 px-3 py-1.5 text-content-medium text-white
            hover:bg-primary-60
          `)
        "
      >
        套用
      </button>
    </form>
    <div class="flex flex-wrap gap-2">
      <button
        v-for="preset in presets"
        :key="preset"
        type="button"
        :class="
          cn(`
            rounded-md border border-bg-60 bg-bg-90 px-2 py-1 text-caption-medium text-text-70
            transition-colors
            hover:bg-bg-70
          `)
        "
        @click="
          () => {
            draft = preset
            applyDraft()
          }
        "
      >
        {{ preset }}
      </button>
    </div>
    <admin-video-player :key="src" :src="src" />
  </div>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-video-player :poster :src>
    <admin-video-player-toolbar>
      <admin-video-player-play />
      <admin-video-player-time />
      <admin-video-player-controls />
      <admin-video-player-progress />
      <admin-video-player-settings />
      <admin-video-player-volume />
      <admin-video-player-fullscreen />
    </admin-video-player-toolbar>
  </admin-video-player>
</template>
```

### admin-video-player

::div{data-admin-api-table=""}
#### Props

| 名稱       | 型別                   | 預設值 | 說明                             |
| -------- | -------------------- | --- | ------------------------------ |
| `src`\*  | `MediaSrc`           | —   | 影片來源（vidstack \`MediaSrc\` 格式） |
| `poster` | `string | undefined` | —   | 載入前顯示之封面圖 URL                  |
| `class`  | `ClassValue`         | —   | 根元素之自訂 class                   |

*\\\* 代表必填*

#### Events

| 名稱                 | Payload   | 說明                          |
| ------------------ | --------- | --------------------------- |
| `ended`            | —         | 播放結束時觸發                     |
| `error`            | `Error`   | 載入或播放發生錯誤時觸發                |
| `pause`            | —         | 暫停播放時觸發                     |
| `play`             | —         | 開始播放時觸發                     |
| `timeUpdate`       | `number`  | 播放進度更新時觸發，payload 為當前秒數     |
| `fullscreenChange` | `boolean` | 全螢幕狀態變更時觸發                  |
| `qualityChange`    | `number`  | 解析度變更時觸發，payload 為當前 height |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-video-player-controls

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |
::

### admin-video-player-fullscreen

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |
::

### admin-video-player-play

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |
::

### admin-video-player-progress

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |
::

### admin-video-player-settings

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |
::

### admin-video-player-time

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |
::

### admin-video-player-toolbar

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

### admin-video-player-volume

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |
::

## 注意事項

- **必須加 `isCustomElement` 設定**：未加上時 dev console 會對 `<media-*>` 元素噴 warning，詳細寫法見「安裝」章節。
- **不支援 SSR**：vidstack 為 browser-only；元件殼不含 `<ClientOnly>`。Nuxt 請自行以 `<ClientOnly>` 包覆；純 CSR 不需處理。見 [安裝 · SSR](https://component-registry-4d4d86.gitlab.io/docs/get-started/installation#ssr-nuxt)。
- **YouTube 解析度不可切**：vidstack YouTube provider 不暴露 quality API，齒輪菜單會自動隱藏解析度區塊。
- **MP4 解析度不可切**：單一 MP4 來源沒有 quality 變體，齒輪菜單也不會顯示解析度區塊；如需多解析度切換，請改用 HLS 串流。
- **HLS qualities 載入時序**：`.m3u8` manifest 下載前 `qualities` 為空陣列，UI 顯示「載入中…」；manifest 解析後自動填入並依 `localStorage` key `admin:player:resolution` 套用最接近且 ≤ 目標的 quality。
- **音量、解析度跨實例共享**：所有 player 實例（含 audio-player）共用 `admin:player:*` namespace；多 tab 不互相同步避免操作被覆蓋。
- **全螢幕請求失敗**：若 iframe 沒給 `allow="fullscreen"` 或瀏覽器拒絕，`toggleFullscreen` 不會 throw，會 emit `error` 事件供消費端處理。

## 更新紀錄

:admin-changelog{component="AdminVideoPlayer"}


# Vxe Table

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/vxe-table
```

```ts
import {
  AdminVxeTable,
  AdminVxeTableCheckbox,
  AdminVxeTableDragIcon,
  AdminVxeTableSorter,
  AdminVxeTableText,
  AdminVxeTableTextButton,
  AdminVxeTableTextButtonGroup,
  AdminVxeTableTextImage,
  useVxeTable
} from '@/components/admin/vxe-table'
```

## 用法

基本欄位與資料即可渲染表格。

```vue
<script setup lang="ts">
import type { VxeTableDefines } from 'vxe-table'
import { ref } from 'vue'
import { AdminVxeTable } from '@/registry/admin/ui/vxe-table'

interface User {
  id: number
  name: string
  role: string
  email: string
}

const columns = [
  { type: 'seq', width: 60, title: '#' },
  { field: 'name', title: '名稱', minWidth: 120 },
  { field: 'role', title: '角色', minWidth: 120 },
  { field: 'email', title: 'Email', minWidth: 200 }
] as const satisfies readonly VxeTableDefines.ColumnOptions<User>[]

const data = ref<User[]>([
  { id: 1, name: 'Alice', role: 'Admin', email: 'alice@example.com' },
  { id: 2, name: 'Bob', role: 'Editor', email: 'bob@example.com' },
  { id: 3, name: 'Carol', role: 'Viewer', email: 'carol@example.com' }
])
</script>

<template>
  <admin-vxe-table class="w-full" :columns="columns" :data="data" />
</template>
```

## 場景

### 排序

以 `AdminVxeTableSorter` 取代上游預設排序圖示，並關閉 `sort-config.showIcon`。

```vue
<script setup lang="ts">
import type { VxeTableDefines } from 'vxe-table'
import { ref } from 'vue'
import { AdminVxeTable, AdminVxeTableSorter } from '@/registry/admin/ui/vxe-table'

interface Product {
  id: number
  name: string
  price: number
  stock: number
}

const columns = [
  { type: 'seq', width: 60, title: '#' },
  {
    field: 'name',
    title: '商品',
    minWidth: 160,
    sortable: true,
    slots: { header: 'nameHeader' }
  },
  {
    field: 'price',
    title: '價格',
    minWidth: 120,
    sortable: true,
    slots: { header: 'priceHeader' }
  },
  {
    field: 'stock',
    title: '庫存',
    minWidth: 100,
    sortable: true,
    slots: { header: 'stockHeader' }
  }
] as const satisfies readonly VxeTableDefines.ColumnOptions<Product>[]

const data = ref<Product[]>([
  { id: 1, name: '無線耳機', price: 3200, stock: 42 },
  { id: 2, name: '藍牙鍵盤', price: 2500, stock: 18 },
  { id: 3, name: '螢幕支架', price: 1800, stock: 73 },
  { id: 4, name: 'USB-C Hub', price: 1600, stock: 120 }
])
</script>

<template>
  <admin-vxe-table
    class="w-full"
    :columns="columns"
    :data="data"
    :sort-config="{ showIcon: false }"
  >
    <template #nameHeader="{ column }">
      <span>商品</span>
      <admin-vxe-table-sorter :column="column" />
    </template>
    <template #priceHeader="{ column }">
      <span>價格</span>
      <admin-vxe-table-sorter :column="column" />
    </template>
    <template #stockHeader="{ column }">
      <span>庫存</span>
      <admin-vxe-table-sorter :column="column" />
    </template>
  </admin-vxe-table>
</template>
```

### 勾選與多選

啟用 checkbox 欄並監聽勾選變更，顯示目前選取筆數。

```vue
<script setup lang="ts">
import type { VxeTableDefines } from 'vxe-table'
import { ref } from 'vue'
import { AdminVxeTable } from '@/registry/admin/ui/vxe-table'

interface Task {
  id: number
  title: string
  owner: string
  status: string
}

const columns = [
  { type: 'checkbox', width: 56 },
  { type: 'seq', width: 60, title: '#' },
  { field: 'title', title: '任務', minWidth: 200 },
  { field: 'owner', title: '負責人', minWidth: 120 },
  { field: 'status', title: '狀態', minWidth: 100 }
] as const satisfies readonly VxeTableDefines.ColumnOptions<Task>[]

const data = ref<Task[]>([
  { id: 1, title: '撰寫 RFC 文件', owner: 'Alice', status: 'In progress' },
  { id: 2, title: '補齊單元測試', owner: 'Bob', status: 'Todo' },
  { id: 3, title: '檢查無障礙', owner: 'Carol', status: 'Done' },
  { id: 4, title: '部署到 staging', owner: 'David', status: 'Blocked' }
])

const selected = ref<Task[]>([])

function onCheckboxChange({ records }: { records: Task[] }) {
  selected.value = records
}
</script>

<template>
  <div class="flex flex-col gap-3">
    <admin-vxe-table
      class="w-full"
      :columns="columns"
      :data="data"
      @checkbox-all="onCheckboxChange"
      @checkbox-change="onCheckboxChange"
    />
    <p class="typo-caption-small text-text-50">
      已選 {{ selected.length }} 筆：{{ selected.map((t) => t.title).join('、') || '—' }}
    </p>
  </div>
</template>
```

### 分頁

需要底部頁碼與每頁筆數選擇時，開啟 `pagination` 並綁定目前頁資料與全量筆數。

```vue
<script setup lang="ts">
import type { VxeTableDefines } from 'vxe-table'
import { computed, ref } from 'vue'
import { AdminVxeTable } from '@/registry/admin/ui/vxe-table'

interface Order {
  id: number
  title: string
  owner: string
  amount: number
}

const columns = [
  { type: 'seq', width: 60, title: '#' },
  { field: 'title', title: '訂單', minWidth: 200 },
  { field: 'owner', title: '負責人', minWidth: 120 },
  { field: 'amount', title: '金額', minWidth: 100 }
] as const satisfies readonly VxeTableDefines.ColumnOptions<Order>[]

const allRows = Array.from({ length: 48 }, (_, i) => ({
  id: i + 1,
  title: `訂單 #${String(i + 1).padStart(3, '0')}`,
  owner: ['Alice', 'Bob', 'Carol', 'David'][i % 4]!,
  amount: 1000 + i * 50
}))

const page = ref(1)
const itemsPerPage = ref(10)

const pageRows = computed(() => {
  const start = (page.value - 1) * itemsPerPage.value
  return allRows.slice(start, start + itemsPerPage.value)
})
</script>

<template>
  <admin-vxe-table
    v-model:items-per-page="itemsPerPage"
    v-model:page="page"
    class="w-full"
    pagination
    :columns="columns"
    :data="pageRows"
    :total="allRows.length"
  />
</template>
```

### 所有子組件總覽

全部搭配子元件的版型一覽。

```vue
<script setup lang="ts">
import type { VxeTableDefines } from 'vxe-table'
import { ref } from 'vue'
import {
  AdminVxeTable,
  AdminVxeTableCheckbox,
  AdminVxeTableDragIcon,
  AdminVxeTableSorter,
  AdminVxeTableText,
  AdminVxeTableTextButton,
  AdminVxeTableTextButtonGroup,
  AdminVxeTableTextImage
} from '@/registry/admin/ui/vxe-table'

interface Product {
  id: number
  image: string
  name: string
  sku: string
  category: string
  price: number
  stock: number
}

const columns = [
  {
    type: 'checkbox',
    width: 56,
    slots: { checkbox: 'rowCheckbox', header: 'headerCheckbox' }
  },
  {
    width: 44,
    title: '',
    dragSort: true
  },
  {
    field: 'product',
    title: '商品',
    minWidth: 240,
    slots: { default: 'product' }
  },
  {
    field: 'category',
    title: '分類',
    minWidth: 180,
    slots: { default: 'category' }
  },
  {
    field: 'stock',
    title: '庫存',
    minWidth: 120,
    sortable: true,
    slots: { header: 'stockHeader' }
  },
  {
    field: 'actions',
    title: '操作',
    minWidth: 160,
    slots: { default: 'actions' }
  }
] as const satisfies readonly VxeTableDefines.ColumnOptions<Product>[]

const data = ref<Product[]>([
  {
    id: 1,
    image: 'https://picsum.photos/seed/headphones/80/60',
    name: '無線降噪耳機',
    sku: 'SKU-00001',
    category: '音訊',
    price: 4990,
    stock: 32
  },
  {
    id: 2,
    image: 'https://picsum.photos/seed/keyboard/80/60',
    name: '機械式鍵盤',
    sku: 'SKU-00002',
    category: '周邊',
    price: 2890,
    stock: 18
  },
  {
    id: 3,
    image: 'https://picsum.photos/seed/monitor/80/60',
    name: '4K 顯示器',
    sku: 'SKU-00003',
    category: '顯示',
    price: 12990,
    stock: 7
  }
])

function onView(_row: Product) {}
function onEdit(_row: Product) {}
</script>

<template>
  <div class="w-full overflow-x-auto">
    <admin-vxe-table
      class="w-full"
      :columns="columns"
      :data="data"
      :row-config="{ keyField: 'id', drag: true }"
      :sort-config="{ showIcon: false }"
    >
      <template #headerCheckbox="{ checked, indeterminate }">
        <admin-vxe-table-checkbox :checked="checked" :indeterminate="indeterminate" />
      </template>

      <template #rowCheckbox="{ row, checked, indeterminate }">
        <admin-vxe-table-checkbox :checked="checked" :indeterminate="indeterminate" :row="row" />
      </template>

      <template #rowDragIcon>
        <admin-vxe-table-drag-icon />
      </template>

      <template #product="{ row }">
        <admin-vxe-table-text-image :image="row.image" :name="row.name" />
      </template>

      <template #category="{ row }">
        <admin-vxe-table-text>
          <template #title>{{ row.category }}</template>
          <template #subtitle>{{ row.sku }}</template>
        </admin-vxe-table-text>
      </template>

      <template #stockHeader="{ column }">
        <span>庫存</span>
        <admin-vxe-table-sorter :column="column" />
      </template>

      <template #actions="{ row }">
        <admin-vxe-table-text-button-group>
          <admin-vxe-table-text-button @click="onView(row)">檢視</admin-vxe-table-text-button>
          <admin-vxe-table-text-button @click="onEdit(row)">編輯</admin-vxe-table-text-button>
        </admin-vxe-table-text-button-group>
      </template>
    </admin-vxe-table>
  </div>
</template>
```

## API 參考

### 組成

```vue
<template>
  <admin-vxe-table :columns="columns" :data="data" :sort-config="{ showIcon: false }">
    <template #headerCheckbox="{ checked, indeterminate }">
      <admin-vxe-table-checkbox :checked="checked" :indeterminate="indeterminate" />
    </template>
    <template #rowCheckbox="{ row, checked, indeterminate }">
      <admin-vxe-table-checkbox :checked="checked" :indeterminate="indeterminate" :row="row" />
    </template>
    <template #rowDragIcon>
      <admin-vxe-table-drag-icon />
    </template>
    <template #stockHeader="{ column }">
      <span>庫存</span>
      <admin-vxe-table-sorter :column="column" />
    </template>
    <template #product="{ row }">
      <admin-vxe-table-text-image :image="row.image" :name="row.name" />
    </template>
    <template #category="{ row }">
      <admin-vxe-table-text>
        <template #title>{{ row.category }}</template>
        <template #subtitle>{{ row.sku }}</template>
      </admin-vxe-table-text>
    </template>
    <template #actions>
      <admin-vxe-table-text-button-group>
        <admin-vxe-table-text-button>編輯</admin-vxe-table-text-button>
        <admin-vxe-table-text-button>刪除</admin-vxe-table-text-button>
      </admin-vxe-table-text-button-group>
    </template>
  </admin-vxe-table>
</template>
```

### admin-vxe-table

::div{data-admin-api-table=""}
#### Props

| 名稱                            | 型別                                                         | 預設值                 | 說明                                                                      |
| ----------------------------- | ---------------------------------------------------------- | ------------------- | ----------------------------------------------------------------------- |
| `class`                       | `ClassValue`                                               | —                   | 根元素之自訂 class                                                            |
| `id`                          | `VxeTablePropTypes.ID<T> | undefined`                      | —                   | 唯一标识
\<br>当使用某个特定功能时，需要设置才能生效                                       |
| `size`                        | `VxeComponentSizeType | undefined`                         | —                   | —                                                                       |
| `align`                       | `VxeComponentAlignType | undefined`                        | —                   | 所有的列对齐方式                                                                |
| `data`                        | `VxeTablePropTypes.Data<T> | undefined`                    | —                   | 表格数据
\<br>与 loadData 行为一致，更新数据是不会重置状态                               |
| `loading`                     | `boolean | undefined`                                      | —                   | 表格是否显示加载中                                                               |
| `mergeCells`                  | `VxeTablePropTypes.MergeCells<T> | undefined`              | —                   | 临时合并指定的单元格 (不能用于展开行)                                                    |
| `layouts`                     | `VxeGridPropTypes.Layouts | undefined`                     | —                   | —                                                                       |
| `proxyConfig`                 | `VxeGridPropTypes.ProxyConfig<T> | undefined`              | —                   | —                                                                       |
| `toolbarConfig`               | `VxeGridPropTypes.ToolbarConfig | undefined`               | —                   | —                                                                       |
| `formConfig`                  | `VxeGridPropTypes.FormConfig | undefined`                  | —                   | —                                                                       |
| `zoomConfig`                  | `VxeGridPropTypes.ZoomConfig | undefined`                  | —                   | —                                                                       |
| `height`                      | `VxeTablePropTypes.Height | undefined`                     | —                   | 表格的高度；支持铺满父容器或者固定高度，如果设置 auto 为铺满父容器（如果设置为 auto，则必须确保存在父节点且不允许存在相邻元素）   |
| `minHeight`                   | `VxeTablePropTypes.MinHeight | undefined`                  | —                   | 表格最小高度                                                                  |
| `maxHeight`                   | `VxeTablePropTypes.MaxHeight | undefined`                  | —                   | max-height                                                              |
| `stripe`                      | `boolean | undefined`                                      | —                   | 是否带有斑马纹（需要注意的是，在可编辑表格场景下，临时插入的数据不会有斑马纹样式）                               |
| `padding`                     | `boolean | undefined`                                      | —                   | 已废弃，被 cell-config.padding 替换                                            |
| `round`                       | `boolean | undefined`                                      | —                   | 是否为圆角边框                                                                 |
| `border`                      | `VxeTablePropTypes.Border | undefined`                     | —                   | 是否带有边框                                                                  |
| `headerAlign`                 | `VxeComponentAlignType | undefined`                        | —                   | 所有的表头列的对齐方式                                                             |
| `footerAlign`                 | `VxeComponentAlignType | undefined`                        | —                   | 所有的表尾列的对齐方式                                                             |
| `showHeader`                  | `boolean | undefined`                                      | —                   | 是否显示表头                                                                  |
| `showFooter`                  | `boolean | undefined`                                      | —                   | 是否显示表尾                                                                  |
| `footerData`                  | `VxeTablePropTypes.FooterData | undefined`                 | —                   | 表尾数据                                                                    |
| `footerMethod`                | `VxeTablePropTypes.FooterMethod<T> | undefined`            | —                   | 表尾的数据获取方法，返回一个二维数组                                                      |
| `rowClassName`                | `VxeTablePropTypes.RowClassName<T> | undefined`            | —                   | 给行附加 className                                                          |
| `cellClassName`               | `VxeTablePropTypes.CellClassName<T> | undefined`           | —                   | 给单元格附加 className                                                        |
| `headerRowClassName`          | `VxeTablePropTypes.HeaderRowClassName<T> | undefined`      | —                   | 给表头的行附加 className                                                       |
| `headerCellClassName`         | `VxeTablePropTypes.HeaderCellClassName<T> | undefined`     | —                   | 给表头的单元格附加 className                                                     |
| `footerRowClassName`          | `VxeTablePropTypes.FooterRowClassName<T> | undefined`      | —                   | 给表尾的行附加 className                                                       |
| `footerCellClassName`         | `VxeTablePropTypes.FooterCellClassName<T> | undefined`     | —                   | 给表尾的单元格附加 className                                                     |
| `cellStyle`                   | `VxeTablePropTypes.CellStyle<T> | undefined`               | —                   | 给单元格附加样式                                                                |
| `rowStyle`                    | `VxeTablePropTypes.RowStyle<T> | undefined`                | —                   | 给行附加样式，也可以是函数                                                           |
| `headerCellStyle`             | `VxeTablePropTypes.HeaderCellStyle<T> | undefined`         | —                   | 给表头单元格附加样式                                                              |
| `headerRowStyle`              | `VxeTablePropTypes.HeaderRowStyle<T> | undefined`          | —                   | 给表头行附加样式                                                                |
| `footerRowStyle`              | `VxeTablePropTypes.FooterRowStyle<T> | undefined`          | —                   | 给表尾行附加样式                                                                |
| `footerCellStyle`             | `VxeTablePropTypes.FooterCellStyle<T> | undefined`         | —                   | 给表尾单元格附加样式                                                              |
| `showCustomHeader`            | `boolean | undefined`                                      | —                   | 用于分组表头，显示为自定义列头，配合 mergeHeaderCells 灵活实现自定义合并                           |
| `mergeHeaderCells`            | `VxeTablePropTypes.MergeHeaderCells | undefined`           | —                   | 临时合并指定的表头单元格                                                            |
| `mergeFooterCells`            | `VxeTablePropTypes.MergeFooterCells<T> | undefined`        | —                   | 临时合并指定的表尾单元格                                                            |
| `mergeFooterItems`            | `VxeTablePropTypes.MergeFooterItems<T> | undefined`        | —                   | —                                                                       |
| `spanMethod`                  | `VxeTablePropTypes.SpanMethod<T> | undefined`              | —                   | 自定义合并函数，返回计算后的值（如果是虚拟滚动、展开行，不建议用于固定列、树形结构的场景，不能同时跨行与跨列）                 |
| `footerSpanMethod`            | `VxeTablePropTypes.FooterSpanMethod<T> | undefined`        | —                   | 表尾合并行或列，返回计算后的值（如果是虚拟滚动、展开行，不建议用于固定列、树形结构的场景，不能同时跨行与跨列）                 |
| `showOverflow`                | `VxeTablePropTypes.ShowOverflow | undefined`               | —                   | 设置所有内容过长时显示为省略号（如果是固定列建议设置该值，提升渲染速度）                                    |
| `showHeaderOverflow`          | `VxeTablePropTypes.ShowOverflow | undefined`               | —                   | 设置表头所有内容过长时显示为省略号                                                       |
| `showFooterOverflow`          | `VxeTablePropTypes.ShowOverflow | undefined`               | —                   | 设置表尾所有内容过长时显示为省略号                                                       |
| `keepSource`                  | `boolean | undefined`                                      | —                   | 保持原始值的状态，被某些功能所依赖，比如编辑状态、还原数据等                                          |
| `autoResize`                  | `boolean | undefined`                                      | —                   | 自动监听父元素的变化去重新计算表格（对于父元素可能存在动态变化、显示隐藏的容器中、列宽异常等场景中的可能会用到）                |
| `syncResize`                  | `VxeTablePropTypes.SyncResize | undefined`                 | —                   | 自动跟随某个属性的变化去重新计算表格，和手动调用 recalculate 方法是一样的效果（对于通过某个属性来控制显示/隐藏切换时可能会用到） |
| `columnConfig`                | `VxeTablePropTypes.ColumnConfig<T> | undefined`            | —                   | 列配置信息                                                                   |
| `rowConfig`                   | `VxeTablePropTypes.RowConfig<T> | undefined`               | —                   | 行配置信息                                                                   |
| `cellConfig`                  | `VxeTablePropTypes.CellConfig<T> | undefined`              | —                   | 单元格配置信息                                                                 |
| `headerCellConfig`            | `VxeTablePropTypes.HeaderCellConfig<T> | undefined`        | —                   | 表头单元格配置信息                                                               |
| `footerCellConfig`            | `VxeTablePropTypes.FooterCellConfig<T> | undefined`        | —                   | 表尾单元格配置信息                                                               |
| `aggregateConfig`             | `VxeTablePropTypes.AggregateConfig<T> | undefined`         | —                   | 数据聚合配置项                                                                 |
| `aggregateAccuracyConfig`     | `VxeTablePropTypes.AggregateAccuracyConfig<T> | undefined` | —                   | 聚合函数计算精度配置项                                                             |
| `rowGroupConfig`              | `VxeTablePropTypes.RowGroupConfig<T> | undefined`          | —                   | 已废弃，请使用 aggregateConfig                                                 |
| `currentRowConfig`            | `VxeTablePropTypes.CurrentRowConfig<T> | undefined`        | —                   | 当前行配置项                                                                  |
| `currentColumnConfig`         | `VxeTablePropTypes.CurrentColumnConfig<T> | undefined`     | —                   | 当前列配置项                                                                  |
| `dragConfig`                  | `VxeTablePropTypes.DragConfig<T> | undefined`              | —                   | 已废弃，被 rowDragConfig 替换                                                  |
| `rowDragConfig`               | `VxeTablePropTypes.RowDragConfig<T> | undefined`           | —                   | 行拖拽排序配置项                                                                |
| `columnDragConfig`            | `VxeTablePropTypes.ColumnDragConfig<T> | undefined`        | —                   | 列拖拽排序配置项                                                                |
| `customConfig`                | `VxeTablePropTypes.CustomConfig<T> | undefined`            | —                   | 个性化信息配置项                                                                |
| `resizeConfig`                | `VxeTablePropTypes.ResizeConfig | undefined`               | —                   | 响应式布局配置项                                                                |
| `resizableConfig`             | `VxeTablePropTypes.ResizableConfig<T> | undefined`         | —                   | 调整列宽和行高整配置项                                                             |
| `seqConfig`                   | `VxeTablePropTypes.SeqConfig<T> | undefined`               | —                   | /\*\*
\<br> 序号配置项                                                   |
| `sortConfig`                  | `VxeTablePropTypes.SortConfig<T> | undefined`              | —                   | 排序配置项                                                                   |
| `filterConfig`                | `VxeTablePropTypes.FilterConfig<T> | undefined`            | —                   | 筛选配置项                                                                   |
| `floatingFilterConfig`        | `VxeTablePropTypes.FloatingFilterConfig<T> | undefined`    | —                   | 浮动筛选配置项                                                                 |
| `radioConfig`                 | `VxeTablePropTypes.RadioConfig<T> | undefined`             | —                   | 单选框配置项                                                                  |
| `checkboxConfig`              | `VxeTablePropTypes.CheckboxConfig<T> | undefined`          | —                   | 复选框配置项                                                                  |
| `headerTooltipConfig`         | `VxeTablePropTypes.HeaderTooltipConfig<T> | undefined`     | —                   | 表头工具提示配置项                                                               |
| `tooltipConfig`               | `VxeTablePropTypes.TooltipConfig<T> | undefined`           | —                   | 工具提示配置项                                                                 |
| `footerTooltipConfig`         | `VxeTablePropTypes.FooterTooltipConfig<T> | undefined`     | —                   | 表尾工具提示配置项                                                               |
| `exportConfig`                | `VxeTablePropTypes.ExportConfig<T> | undefined`            | —                   | 导出配置项                                                                   |
| `importConfig`                | `VxeTablePropTypes.ImportConfig<T> | undefined`            | —                   | 导入配置项                                                                   |
| `printConfig`                 | `VxeTablePropTypes.PrintConfig<T> | undefined`             | —                   | 打印配置项                                                                   |
| `expandConfig`                | `VxeTablePropTypes.ExpandConfig<T> | undefined`            | —                   | 展开行配置项                                                                  |
| `treeConfig`                  | `VxeTablePropTypes.TreeConfig<T> | undefined`              | —                   | 树形结构配置项                                                                 |
| `menuConfig`                  | `VxeTablePropTypes.MenuConfig<T> | undefined`              | —                   | 右键菜单配置项                                                                 |
| `mouseConfig`                 | `VxeTablePropTypes.MouseConfig | undefined`                | —                   | 鼠标配置项                                                                   |
| `areaConfig`                  | `VxeTablePropTypes.AreaConfig<T> | undefined`              | —                   | 区域选取配置项                                                                 |
| `fnrConfig`                   | `VxeTablePropTypes.FnrConfig<T> | undefined`               | —                   | 查找/替换配置项                                                                |
| `keyboardConfig`              | `VxeTablePropTypes.KeyboardConfig<T> | undefined`          | —                   | 按键配置项                                                                   |
| `clipConfig`                  | `VxeTablePropTypes.ClipConfig<T> | undefined`              | —                   | 复制/粘贴配置项                                                                |
| `editConfig`                  | `VxeTablePropTypes.EditConfig<T> | undefined`              | —                   | 可编辑配置项                                                                  |
| `editDirtyConfig`             | `VxeTablePropTypes.EditDirtyConfig | undefined`            | —                   | 数据状态监听配置项                                                               |
| `validConfig`                 | `VxeTablePropTypes.ValidConfig<T> | undefined`             | —                   | 校验配置项                                                                   |
| `editRules`                   | `VxeTablePropTypes.EditRules<T> | undefined`               | —                   | 校验规则配置项                                                                 |
| `undoRedoHistoryConfig`       | `VxeTablePropTypes.UndoRedoHistoryConfig | undefined`      | —                   | 撤销/恢复历史配置项                                                              |
| `emptyText`                   | `string | undefined`                                       | —                   | 空数据时显示的内容                                                               |
| `emptyRender`                 | `VxeTablePropTypes.EmptyRender | undefined`                | —                   | 空内容渲染配置项，empty-render 的优先级大于 empty-text                                 |
| `loadingConfig`               | `VxeTablePropTypes.LoadingConfig | undefined`              | —                   | 加载中配置项                                                                  |
| `scrollX`                     | `VxeTablePropTypes.ScrollX | undefined`                    | —                   | 已废弃，不建议使用，被 virtual-x-config 替换                                         |
| `scrollY`                     | `VxeTablePropTypes.ScrollY | undefined`                    | —                   | 已废弃，不建议使用，被 virtual-y-config 替换                                         |
| `virtualXConfig`              | `VxeTablePropTypes.VirtualXConfig | undefined`             | —                   | 横向虚拟滚动配置                                                                |
| `virtualYConfig`              | `VxeTablePropTypes.VirtualYConfig | undefined`             | —                   | 纵向虚拟滚动配置                                                                |
| `scrollbarConfig`             | `VxeTablePropTypes.ScrollbarConfig | undefined`            | —                   | 滚动条配置项                                                                  |
| `params`                      | `any`                                                      | —                   | 自定义参数（可以用来存放一些自定义的数据）                                                   |
| `zIndex`                      | `number | undefined`                                       | —                   | —                                                                       |
| `resizable`                   | `boolean | undefined`                                      | —                   | 已废弃，不建议使用，被 column-config.resizable 替换                                  |
| `highlightCurrentRow`         | `boolean | undefined`                                      | —                   | 已废弃，不建议使用，被 row-config.isCurrent 替换                                     |
| `highlightHoverRow`           | `boolean | undefined`                                      | —                   | 已废弃，不建议使用，被 row-config.isHover 替换                                       |
| `highlightCurrentColumn`      | `boolean | undefined`                                      | —                   | 已废弃，不建议使用，被 column-config.isCurrent 替换                                  |
| `highlightHoverColumn`        | `boolean | undefined`                                      | —                   | 已废弃，不建议使用，被 column-config.isHover 替换                                    |
| `highlightCell`               | `boolean | undefined`                                      | —                   | 已废弃                                                                     |
| `columnKey`                   | `boolean | undefined`                                      | —                   | 已废弃，请使用 column-config.useKey                                            |
| `rowKey`                      | `boolean | undefined`                                      | —                   | 已废弃，请使用 row-config.useKey                                               |
| `rowId`                       | `string | undefined`                                       | —                   | 已废弃，请使用 row-config.keyField                                             |
| `fit`                         | `boolean | undefined`                                      | —                   | 已废弃，已废弃                                                                 |
| `animat`                      | `boolean | undefined`                                      | —                   | 已废弃，已废弃                                                                 |
| `delayHover`                  | `number | undefined`                                       | —                   | 已废弃，已废弃                                                                 |
| `onPaste`                     | `VxeGridEvents.Paste<T> | undefined`                       | —                   | —                                                                       |
| `onCopy`                      | `VxeGridEvents.Copy<T> | undefined`                        | —                   | —                                                                       |
| `onCut`                       | `VxeGridEvents.Cut<T> | undefined`                         | —                   | —                                                                       |
| `onKeydown`                   | `VxeGridEvents.Keydown<T> | undefined`                     | —                   | —                                                                       |
| `onScroll`                    | `VxeGridEvents.Scroll<T> | undefined`                      | —                   | —                                                                       |
| `onReady`                     | `VxeGridEvents.Ready<T> | undefined`                       | —                   | —                                                                       |
| `onInitRendered`              | `VxeGridEvents.InitRendered<T> | undefined`                | —                   | —                                                                       |
| `onDataRendered`              | `VxeGridEvents.DataRendered<T> | undefined`                | —                   | —                                                                       |
| `onKeydownStart`              | `VxeGridEvents.KeydownStart<T> | undefined`                | —                   | —                                                                       |
| `onKeydownEnd`                | `VxeGridEvents.KeydownEnd<T> | undefined`                  | —                   | —                                                                       |
| `onUndo`                      | `VxeGridEvents.Undo<T> | undefined`                        | —                   | —                                                                       |
| `onRedo`                      | `VxeGridEvents.Redo<T> | undefined`                        | —                   | —                                                                       |
| `onContextMenu`               | `VxeGridEvents.ContextMenu<T> | undefined`                 | —                   | —                                                                       |
| `onColumnsChange`             | `VxeGridEvents.ColumnsChange<T> | undefined`               | —                   | —                                                                       |
| `onDataChange`                | `VxeGridEvents.DataChange<T> | undefined`                  | —                   | —                                                                       |
| `onFooterDataChange`          | `VxeGridEvents.FooterDataChange<T> | undefined`            | —                   | —                                                                       |
| `onCurrentRowChange`          | `VxeGridEvents.CurrentRowChange<T> | undefined`            | —                   | —                                                                       |
| `onCurrentRowDisabled`        | `VxeGridEvents.CurrentRowDisabled<T> | undefined`          | —                   | —                                                                       |
| `onCurrentColumnChange`       | `VxeGridEvents.CurrentColumnChange<T> | undefined`         | —                   | —                                                                       |
| `onCurrentColumnDisabled`     | `VxeGridEvents.CurrentColumnDisabled<T> | undefined`       | —                   | —                                                                       |
| `onRadioChange`               | `VxeGridEvents.RadioChange<T> | undefined`                 | —                   | —                                                                       |
| `onCheckboxChange`            | `VxeGridEvents.CheckboxChange<T> | undefined`              | —                   | —                                                                       |
| `onCheckboxAll`               | `VxeGridEvents.CheckboxAll<T> | undefined`                 | —                   | —                                                                       |
| `onCheckboxRangeStart`        | `VxeGridEvents.CheckboxRangeStart<T> | undefined`          | —                   | —                                                                       |
| `onCheckboxRangeChange`       | `VxeGridEvents.CheckboxRangeChange<T> | undefined`         | —                   | —                                                                       |
| `onCheckboxRangeEnd`          | `VxeGridEvents.CheckboxRangeEnd<T> | undefined`            | —                   | —                                                                       |
| `onCheckboxRangeSelect`       | `VxeGridEvents.CheckboxRangeSelect<T> | undefined`         | —                   | —                                                                       |
| `onCellClick`                 | `VxeGridEvents.CellClick<T> | undefined`                   | —                   | —                                                                       |
| `onCellDblclick`              | `VxeGridEvents.CellDblclick<T> | undefined`                | —                   | —                                                                       |
| `onCellMenu`                  | `VxeGridEvents.CellMenu<T> | undefined`                    | —                   | —                                                                       |
| `onCellMouseenter`            | `VxeGridEvents.CellMouseenter<T> | undefined`              | —                   | —                                                                       |
| `onCellMouseleave`            | `VxeGridEvents.CellMouseleave<T> | undefined`              | —                   | —                                                                       |
| `onHeaderCellClick`           | `VxeGridEvents.HeaderCellClick<T> | undefined`             | —                   | —                                                                       |
| `onHeaderCellDblclick`        | `VxeGridEvents.HeaderCellDblclick<T> | undefined`          | —                   | —                                                                       |
| `onHeaderCellMenu`            | `VxeGridEvents.HeaderCellMenu<T> | undefined`              | —                   | —                                                                       |
| `onFooterCellClick`           | `VxeGridEvents.FooterCellClick<T> | undefined`             | —                   | —                                                                       |
| `onFooterCellDblclick`        | `VxeGridEvents.FooterCellDblclick<T> | undefined`          | —                   | —                                                                       |
| `onFooterCellMenu`            | `VxeGridEvents.FooterCellMenu<T> | undefined`              | —                   | —                                                                       |
| `onSortChange`                | `VxeGridEvents.SortChange<T> | undefined`                  | —                   | —                                                                       |
| `onClearSort`                 | `VxeGridEvents.ClearSort<T> | undefined`                   | —                   | —                                                                       |
| `onClearAllSort`              | `VxeGridEvents.ClearAllSort<T> | undefined`                | —                   | —                                                                       |
| `onFilterChange`              | `VxeGridEvents.FilterChange<T> | undefined`                | —                   | —                                                                       |
| `onClearFilter`               | `VxeGridEvents.ClearFilter<T> | undefined`                 | —                   | —                                                                       |
| `onClearAllFilter`            | `VxeGridEvents.ClearAllFilter<T> | undefined`              | —                   | —                                                                       |
| `onFilterVisible`             | `VxeGridEvents.FilterVisible<T> | undefined`               | —                   | —                                                                       |
| `onResizableChange`           | `VxeGridEvents.ResizableChange<T> | undefined`             | —                   | —                                                                       |
| `onToggleRowGroupExpand`      | `VxeGridEvents.ToggleRowGroupExpand<T> | undefined`        | —                   | —                                                                       |
| `onToggleRowExpand`           | `VxeGridEvents.ToggleRowExpand<T> | undefined`             | —                   | —                                                                       |
| `onToggleTreeExpand`          | `VxeGridEvents.ToggleTreeExpand<T> | undefined`            | —                   | —                                                                       |
| `onMenuClick`                 | `VxeGridEvents.MenuClick<T> | undefined`                   | —                   | —                                                                       |
| `onEditClosed`                | `VxeGridEvents.EditClosed<T> | undefined`                  | —                   | —                                                                       |
| `onEditActivated`             | `VxeGridEvents.EditActivated<T> | undefined`               | —                   | —                                                                       |
| `onEditDisabled`              | `VxeGridEvents.EditDisabled<T> | undefined`                | —                   | —                                                                       |
| `onValidError`                | `VxeGridEvents.ValidError<T> | undefined`                  | —                   | —                                                                       |
| `onScrollBoundary`            | `VxeGridEvents.ScrollBoundary<T> | undefined`              | —                   | —                                                                       |
| `onCustom`                    | `VxeGridEvents.Custom<T> | undefined`                      | —                   | —                                                                       |
| `onCustomOpen`                | `VxeGridEvents.CustomOpen<T> | undefined`                  | —                   | —                                                                       |
| `onCustomClose`               | `VxeGridEvents.CustomClose<T> | undefined`                 | —                   | —                                                                       |
| `onCustomCancel`              | `VxeGridEvents.CustomCancel<T> | undefined`                | —                   | —                                                                       |
| `onCustomReset`               | `VxeGridEvents.CustomReset<T> | undefined`                 | —                   | —                                                                       |
| `onCustomConfirm`             | `VxeGridEvents.CustomConfirm<T> | undefined`               | —                   | —                                                                       |
| `onRowDragstart`              | `VxeGridEvents.RowDragstart<T> | undefined`                | —                   | —                                                                       |
| `onRowDragover`               | `VxeGridEvents.RowDragover<T> | undefined`                 | —                   | —                                                                       |
| `onRowDragend`                | `VxeGridEvents.RowDragend<T> | undefined`                  | —                   | —                                                                       |
| `onRowRemoveDragend`          | `VxeGridEvents.RowRemoveDragend<T> | undefined`            | —                   | —                                                                       |
| `onRowInsertDragend`          | `VxeGridEvents.RowInsertDragend<T> | undefined`            | —                   | —                                                                       |
| `onColumnDragstart`           | `VxeGridEvents.ColumnDragstart<T> | undefined`             | —                   | —                                                                       |
| `onColumnDragover`            | `VxeGridEvents.ColumnDragover<T> | undefined`              | —                   | —                                                                       |
| `onColumnDragend`             | `VxeGridEvents.ColumnDragend<T> | undefined`               | —                   | —                                                                       |
| `onEnterAppendRow`            | `VxeGridEvents.EnterAppendRow<T> | undefined`              | —                   | —                                                                       |
| `onTabAppendRow`              | `VxeGridEvents.TabAppendRow<T> | undefined`                | —                   | —                                                                       |
| `onProxyQuery`                | `VxeGridEvents.ProxyQuery<T> | undefined`                  | —                   | —                                                                       |
| `onProxyDelete`               | `VxeGridEvents.ProxyDelete<T> | undefined`                 | —                   | —                                                                       |
| `onProxySave`                 | `VxeGridEvents.ProxySave<T> | undefined`                   | —                   | —                                                                       |
| `onFormSubmit`                | `VxeGridEvents.FormSubmit<T> | undefined`                  | —                   | —                                                                       |
| `onFormSubmitInvalid`         | `VxeGridEvents.FormSubmitInvalid<T> | undefined`           | —                   | —                                                                       |
| `onFormReset`                 | `VxeGridEvents.FormReset<T> | undefined`                   | —                   | —                                                                       |
| `onFormCollapse`              | `VxeGridEvents.FormCollapse<T> | undefined`                | —                   | —                                                                       |
| `onToolbarButtonClick`        | `VxeGridEvents.ToolbarButtonClick<T> | undefined`          | —                   | —                                                                       |
| `onToolbarToolClick`          | `VxeGridEvents.ToolbarToolClick<T> | undefined`            | —                   | —                                                                       |
| `onZoom`                      | `VxeGridEvents.Zoom<T> | undefined`                        | —                   | —                                                                       |
| `onEditActived`               | `VxeGridEvents.EditActivated<T> | undefined`               | —                   | 已废弃，请使用 onEditActivated                                                 |
| `onOpenFnr`                   | `VxeGridEvents.OpenFnr<T> | undefined`                     | —                   | —                                                                       |
| `onFnrChange`                 | `VxeGridEvents.FnrChange<T> | undefined`                   | —                   | —                                                                       |
| `onFnrFind`                   | `VxeGridEvents.FnrFind<T> | undefined`                     | —                   | —                                                                       |
| `onFnrFindAll`                | `VxeGridEvents.FnrFindAll<T> | undefined`                  | —                   | —                                                                       |
| `onFnrReplace`                | `VxeGridEvents.FnrReplace<T> | undefined`                  | —                   | —                                                                       |
| `onFnrReplaceAll`             | `VxeGridEvents.FnrReplaceAll<T> | undefined`               | —                   | —                                                                       |
| `onCellAreaCopy`              | `VxeGridEvents.CellAreaCopy<T> | undefined`                | —                   | —                                                                       |
| `onCellAreaCut`               | `VxeGridEvents.CellAreaCut<T> | undefined`                 | —                   | —                                                                       |
| `onCellAreaPaste`             | `VxeGridEvents.CellAreaPaste<T> | undefined`               | —                   | —                                                                       |
| `onCellAreaMerge`             | `VxeGridEvents.CellAreaMerge<T> | undefined`               | —                   | —                                                                       |
| `onClearCellAreaMerge`        | `VxeGridEvents.ClearCellAreaMerge<T> | undefined`          | —                   | —                                                                       |
| `onClearCellAreaSelection`    | `VxeGridEvents.ClearCellAreaSelection<T> | undefined`      | —                   | —                                                                       |
| `onHeaderCellAreaSelection`   | `VxeGridEvents.HeaderCellAreaSelection<T> | undefined`     | —                   | —                                                                       |
| `onCellAreaSelectionInvalid`  | `VxeGridEvents.CellAreaSelectionInvalid<T> | undefined`    | —                   | —                                                                       |
| `onCellAreaSelectionStart`    | `VxeGridEvents.CellAreaSelectionStart<T> | undefined`      | —                   | —                                                                       |
| `onCellAreaSelectionDrag`     | `VxeGridEvents.CellAreaSelectionDrag<T> | undefined`       | —                   | —                                                                       |
| `onCellAreaSelectionEnd`      | `VxeGridEvents.CellAreaSelectionEnd<T> | undefined`        | —                   | —                                                                       |
| `onCellAreaExtensionStart`    | `VxeGridEvents.CellAreaExtensionStart<T> | undefined`      | —                   | —                                                                       |
| `onCellAreaExtensionDrag`     | `VxeGridEvents.CellAreaExtensionDrag<T> | undefined`       | —                   | —                                                                       |
| `onCellAreaExtensionEnd`      | `VxeGridEvents.CellAreaExtensionEnd<T> | undefined`        | —                   | —                                                                       |
| `onCellAreaExtensionFill`     | `VxeGridEvents.CellAreaExtensionFill<T> | undefined`       | —                   | —                                                                       |
| `onCellAreaSelectionAllStart` | `VxeGridEvents.CellAreaSelectionAllStart<T> | undefined`   | —                   | —                                                                       |
| `onCellAreaSelectionAllEnd`   | `VxeGridEvents.CellAreaSelectionAllEnd<T> | undefined`     | —                   | —                                                                       |
| `onCellAreaArrowsStart`       | `VxeGridEvents.CellAreaArrowsStart<T> | undefined`         | —                   | —                                                                       |
| `onCellAreaArrowsEnd`         | `VxeGridEvents.CellAreaArrowsEnd<T> | undefined`           | —                   | —                                                                       |
| `onCellAreaFillCopy`          | `VxeGridEvents.CellAreaFillCopy<T> | undefined`            | —                   | —                                                                       |
| `onActiveCellChangeStart`     | `VxeGridEvents.ActiveCellChangeStart<T> | undefined`       | —                   | —                                                                       |
| `onActiveCellChangeEnd`       | `VxeGridEvents.ActiveCellChangeEnd<T> | undefined`         | —                   | —                                                                       |
| `columns`                     | `C | undefined`                                            | —                   | 表格欄位定義（型別會被泛型 C 收斂以推導 column slots 名稱）                                  |
| `pagination`                  | `boolean | undefined`                                      | —                   | 啟用分頁                                                                    |
| `page`                        | `number | undefined`                                       | —                   | 當前頁碼 (v-model\:page)                                                    |
| `itemsPerPage`                | `number | undefined`                                       | —                   | 每頁筆數 (v-model\:items-per-page)                                          |
| `total`                       | `number | undefined`                                       | —                   | 總筆數                                                                     |
| `perPageOptions`              | `number[] | undefined`                                     | `[10, 20, 50, 100]` | 每頁筆數選項                                                                  |
| `showPaginationInfo`          | `boolean | undefined`                                      | `true`              | 顯示分頁資訊                                                                  |
| `showPerPageSelector`         | `boolean | undefined`                                      | `true`              | 顯示每頁筆數選擇器                                                               |

#### Events

| 名稱                    | Payload  | 說明                                 |
| --------------------- | -------- | ---------------------------------- |
| `update:page`         | `number` | 使用者切換頁碼時觸發                         |
| `update:itemsPerPage` | `number` | 使用者切換每頁筆數時觸發；切換後 \`page\` 會自動重置為 1 |

#### Slots

| 名稱               | Bindings                                                                                   | 說明                                     |
| ---------------- | ------------------------------------------------------------------------------------------ | -------------------------------------- |
| `empty`          | `VxeGridSlotTypes.EmptySlotParams<T>`                                                      | 自定义空数据时显示模板                            |
| `loading`        | `VxeGridSlotTypes.LoadingSlotParams<T>`                                                    | 自定义加载中模板                               |
| `form`           | `VxeGridSlotTypes.FormSlotParams<T>`                                                       | 自定义表单模板                                |
| `toolbar`        | `VxeGridSlotTypes.ToolbarSlotParams<T>`                                                    | 自定义工具栏模板                               |
| `top`            | `VxeGridSlotTypes.TopSlotParams<T>`                                                        | 自定义表格顶部模板                              |
| `bottom`         | `VxeGridSlotTypes.BottomSlotParams<T>`                                                     | 自定义表格底部模板                              |
| `left`           | `VxeGridSlotTypes.LeftSlotParams<T>`                                                       | 自定义表格左边模板                              |
| `right`          | `VxeGridSlotTypes.RightSlotParams<T>`                                                      | 自定义表格边侧模板                              |
| `asideLeft`      | `VxeGridSlotTypes.AsideLeftSlotParams<T>`                                                  | 自定义左侧模板                                |
| `asideRight`     | `VxeGridSlotTypes.AsideRightSlotParams<T>`                                                 | 自定义右侧模板                                |
| `pager`          | `VxeGridSlotTypes.PagerSlotParams<T>`                                                      | 自定义分页模板                                |
| `rowDragIcon`    | `VxeGridSlotTypes.RowDragIconSlotParams<T>`                                                | 只对 row-config.drag 开启后有效，自定义行拖拽按钮图标    |
| `columnDragIcon` | `VxeGridSlotTypes.RowDragIconSlotParams<T> | VxeGridSlotTypes.ColumnDragIconSlotParams<T>` | 只对 column-config.drag 开启后有效，自定义列拖拽按钮图标 |
::

### admin-vxe-table-checkbox

::div{data-admin-api-table=""}
#### Props

| 名稱              | 型別                                | 預設值 | 說明                    |
| --------------- | --------------------------------- | --- | --------------------- |
| `checked`       | `boolean | undefined`             | —   | 顯示為已勾選狀態              |
| `indeterminate` | `boolean | undefined`             | —   | 顯示為「部分選取」中間態          |
| `row`           | `Record<string, any> | undefined` | —   | 帶入該列資料時點擊切換該列；省略則切換全選 |
| `class`         | `unknown`                         | —   | —                     |
::

### admin-vxe-table-sorter

::div{data-admin-api-table=""}
#### Props

| 名稱         | 型別                                | 預設值 | 說明                                      |
| ---------- | --------------------------------- | --- | --------------------------------------- |
| `column`\* | `VxeTableDefines.ColumnInfo<any>` | —   | 帶入 header slot 提供的 \`column\`，驅動三階段排序切換 |
| `class`    | `unknown`                         | —   | —                                       |

*\\\* 代表必填*
::

### admin-vxe-table-text-image

::div{data-admin-api-table=""}
#### Props

| 名稱        | 型別        | 預設值 | 說明          |
| --------- | --------- | --- | ----------- |
| `image`\* | `string`  | —   | 圖片 URL      |
| `name`\*  | `string`  | —   | 圖片右側顯示的名稱文字 |
| `class`   | `unknown` | —   | —           |

*\\\* 代表必填*
::

### admin-vxe-table-text-button

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明      |
| --------- | -------- | ------- |
| `default` | `any`    | 按鈕文字或內容 |
::

### admin-vxe-table-text-button-group

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別           | 預設值 | 說明           |
| ------- | ------------ | --- | ------------ |
| `class` | `ClassValue` | —   | 根元素之自訂 class |

#### Slots

| 名稱        | Bindings | 說明     |
| --------- | -------- | ------ |
| `default` | `any`    | 一組文字按鈕 |
::

### admin-vxe-table-drag-icon

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別        | 預設值 | 說明 |
| ------- | --------- | --- | -- |
| `class` | `unknown` | —   | —  |
::

### admin-vxe-table-text

::div{data-admin-api-table=""}
#### Props

| 名稱      | 型別        | 預設值 | 說明 |
| ------- | --------- | --- | -- |
| `class` | `unknown` | —   | —  |

#### Slots

| 名稱         | Bindings | 說明    |
| ---------- | -------- | ----- |
| `title`    | `any`    | 主標題文字 |
| `subtitle` | `any`    | 副標題文字 |
::

## 注意事項

- **不支援 SSR**：`vxe-table` 依賴瀏覽器 DOM；元件殼不含 `<ClientOnly>`。Nuxt 請自行以 `<ClientOnly>`（或其他框架等價機制）包覆；純 CSR 不需處理。見 [安裝 · SSR](https://component-registry-4d4d86.gitlab.io/docs/get-started/installation#ssr-nuxt)。
- **`loading` 由 admin overlay 接管**：傳入 `loading` 時會顯示 `v-admin-loading` 遮罩，不會轉發至 `vxe-grid` 原生 loading／loading slot。
- **自訂 cell 子元件須置於 `AdminVxeTable` 內**：`AdminVxeTableCheckbox`、`AdminVxeTableSorter` 等透過 `useVxeTable` 取得內部 `gridRef`；寫自訂 cell 時也可直接呼叫 `useVxeTable()`。
- **分頁資料由消費端切片**：`pagination` 只負責 UI 與 `page`／`itemsPerPage` 雙向綁定；表格 `data` 仍須傳入當前頁資料，`total` 為全量筆數。

## 更新紀錄

:admin-changelog{component="AdminVxeTable"}


# llms.txt

本站有 [`llms.txt`](https://llmstxt.org){rel="&#x22;nofollow&#x22;"} 格式索引，可把文件接給 ChatGPT、Claude、Cursor 等。

> **選路：** client 有 MCP（Claude Code、Cursor）→ 用 [MCP](https://component-registry-4d4d86.gitlab.io/docs/ai/mcp) 可直接裝元件；只有 web fetch、或不想設 server → 用本頁。

部署網域：`https://component-registry-4d4d86.gitlab.io`（與 `nuxt.config.ts` 的 `site.url` 同步）。下文 `/llms.txt`、`/llms-full.txt` 皆相對此網域。

## 兩個檔

| 檔案                                                                            | 內容                           | 何時用        |
| ----------------------------------------------------------------------------- | ---------------------------- | ---------- |
| [`/llms.txt`](https://component-registry-4d4d86.gitlab.io/llms.txt)           | 各文件頁標題與 description          | 先掃有哪些元件再深入 |
| [`/llms-full.txt`](https://component-registry-4d4d86.gitlab.io/llms-full.txt) | 每頁完整 markdown + demo + API 表 | 直接依文件寫程式   |

## 怎麼用

以 Cursor、Claude 為例；其他能 web fetch 的工具同理。

### Cursor

在 Docs／`@Docs` 把 `https://component-registry-4d4d86.gitlab.io/llms.txt` 加為來源，prompt 裡用 `@Docs` 引用。

### Claude

請 Claude 用 Web Fetch 讀 [`llms-full.txt`](https://component-registry-4d4d86.gitlab.io/llms-full.txt){rel="&#x22;nofollow&#x22;"}，再依文件回答或產生範例。

## 與 shadcn-vue CLI

1. 把 `/llms-full.txt` 餵給 LLM。
2. 說明需求（例如「含 loading 的確認按鈕」）。
3. 取得元件名（如 `admin-button`）與範例。
4. 依[安裝](https://component-registry-4d4d86.gitlab.io/docs/get-started/installation)設好 `@admin`，確認 `components.json` 的 `iconLibrary` 為 `tabler`，再執行 `pnpm dlx shadcn-vue add @admin/<component>`。
5. 貼上程式碼並調整。

提示可加：「只用 Admin Registry 已收錄元件，並先列出需 `npx shadcn-vue add` 的清單」。

> 有 MCP 時可改走 [MCP](https://component-registry-4d4d86.gitlab.io/docs/ai/mcp)。Agent 工作流見 [Agent skill](https://component-registry-4d4d86.gitlab.io/docs/ai/skills)。


# MCP

Admin Registry 相容 shadcn-vue registry，可接官方 [MCP](https://www.shadcn-vue.com/docs/mcp){rel="&#x22;nofollow&#x22;"}（`npx shadcn-vue@latest mcp`）。需 Node.js 22 以上，見[安裝](https://component-registry-4d4d86.gitlab.io/docs/get-started/installation)。

## 在 components.json 註冊

MCP 讀專案根目錄 `components.json`。需有 `@admin`：

```json
{
  "iconLibrary": "tabler",
  "registries": {
    "@admin": {
      "url": "https://component-registry-4d4d86.gitlab.io/r/styles/admin/{name}.json"
    }
  }
}
```

`iconLibrary` 須為 `tabler`。MCP 安裝走同一個 CLI；若是 `lucide`，不會裝上 `@tabler/icons-vue`。做法見[安裝](https://component-registry-4d4d86.gitlab.io/docs/get-started/installation)。

重啟 MCP client 後，對話可用 `@admin/<component>`。

## Prompt 範例

- 「列出所有 `@admin` 元件，依用途分組」
- 「安裝 `@admin/button`、`@admin/dialog`、`@admin/input`」
- 「用 `@admin` 寫含 loading 的登入表單；先列 `@admin/<x>` 再給程式碼」

要求「先列清單再給程式碼」可減少一次產出大量不可用內容。

## 查詢範例

`get_item_examples_from_registries` 可查到已發佈的 demo，以 `@admin` 為 registry，用 `<component>-demo`（例如 `button-demo`）或 `<component> example`（例如 `dialog example`）查詢。

目前已發佈 13 個：`badge`、`button`、`checkbox`、`dialog`、`divider`、`input`、`progress`、`select`、`switch`、`tabs`、`tag`、`textarea`、`tooltip`。其他元件尚未發佈，請改看文件站，或讀 `/llms-full.txt`。

## 已知限制

以 shadcn-vue 2.8.2 為準：

- `list_items_in_registries`、`search_items_in_registries` 回傳的 Add command 欄位會顯示 `[object Promise]`（上游 bug）。請改用 `get_add_command_for_items` 取得安裝指令。

## 與 llms.txt

| 方式                                                                           | 何時用                                |
| ---------------------------------------------------------------------------- | ---------------------------------- |
| **MCP**                                                                      | 要 AI 執行 `shadcn-vue add`、列元件、依需求安裝 |
| **[llms.txt](https://component-registry-4d4d86.gitlab.io/docs/ai/llms-txt)** | 只要讀文件（web fetch）；無 MCP 或不想設 server |

可並用：MCP 裝元件，`/llms-full.txt` 補 API／demo。工作流規則見 [Agent skill](https://component-registry-4d4d86.gitlab.io/docs/ai/skills)。


# Agent skill

`admin-registry` 是給消費端專案的 agent skill，用 [`npx skills`](https://skills.sh){rel="&#x22;nofollow&#x22;"} 安裝。結構對齊 shadcn-vue skill 的 Setup／Install／Compose，只補 `@admin` 規則；官方 shadcn-vue skill 仍需保留。

## 安裝

需要 GitLab repo `tpi-dtd/component-registry` 讀取權限。

```bash
npx skills add https://gitlab.com/tpi-dtd/component-registry
```

只裝這一個：

```bash
npx skills add https://gitlab.com/tpi-dtd/component-registry --skill admin-registry
```

## 與 MCP、llms.txt

| 方式                                                                           | 何時用                                              |
| ---------------------------------------------------------------------------- | ------------------------------------------------ |
| **[MCP](https://component-registry-4d4d86.gitlab.io/docs/ai/mcp)**           | AI 執行 `shadcn-vue add`、掃 registry                |
| **[llms.txt](https://component-registry-4d4d86.gitlab.io/docs/ai/llms-txt)** | AI 只讀文件（web fetch）                               |
| **本 skill**                                                                  | 接 `@admin`、裝元件、組畫面時套用 tokens、naming、Headed UI 規則 |

可並用：MCP 裝東西，llms 補 API，skill 管工作流。


# AIO 編輯器總覽

`@admin/aio-editor` 是 config 驅動的 all-in-one tiptap 編輯器：consumer 不需要在 template 組裝任何子元件，傳一份 config 決定啟用哪些 extension、toolbar 按鈕、bubble menu 與 drag handle。

```vue
<template>
  <admin-aio-editor v-model="content" />
</template>
```

## 系列組成

| 文件                                                                                            | 用途                        |
| --------------------------------------------------------------------------------------------- | ------------------------- |
| [AioEditor](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/editor)               | 主元件：demo、API 參考、注意事項      |
| [Extensions](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/overview) | 全部 extension 逐一列出，含完整選項說明 |

Registry 單元只有一個：`@admin/aio-editor`。UI 與邏輯核心（extensions、預設 config、`useAioEditor`）同屬此單元（核心置於元件內 `core/` 子目錄），安裝即取得完整編輯器；config 型別、enums 與各 `default*Config` 皆自 `@admin/aio-editor` 匯出。

## 與編輯器（editor-\*）系列的差異

|      | [編輯器系列](https://component-registry-4d4d86.gitlab.io/docs/editor/overview) | AIO 編輯器系列             |
| ---- | ------------------------------------------------------------------------- | --------------------- |
| 組裝方式 | template 組裝子元件                                                            | config 驅動，單一元件        |
| 適合情境 | 需要細部客製 UI 結構                                                              | 裝上就要一套完整編輯器           |
| 功能取捨 | 要什麼裝什麼（opt-in 包）                                                          | 預設全開，用 `exclude` 關閉   |
| 相依關係 | —                                                                         | 與 editor-\* 零耦合，可獨立安裝 |

## 安裝

```bash
pnpm dlx shadcn-vue@latest add @admin/aio-editor
```

## config 快速心智模型

```ts
const config: AioEditorConfig = {
  features: [],         // 唯一宣告來源：按鈕排列 = 功能載入（未宣告即不載入）
  include: [],          // 無按鈕載入能力（保 Ctrl+Z、輸入規則、Mention…；自動補齊硬依賴）
  exclude: [],          // 排除任意 extension（一律生效、分級警告、同名替換）
  extensionsConfig: {}, // 各 extension 選項覆寫（深層 merge；陣列與 instance 整值取代、null 清除預設）
  extraExtensions: [],  // 自訂 extension / 同名替換（優先權最高）
  toolbarOptions: {},   // 標籤 / 字級字體清單 / 色票 / requestUrl / requestColor
  bubbles: {},          // 掛載跟隨 features；個別 false 停用、物件覆寫、slot 替換
  dragHandle: false,    // false 停用或物件覆寫
  paste: {},            // 貼上行為（純文字 / 清圖 / transform hooks）
  silence: false        // 靜音內部警告
}
```

所有欄位皆可省略；未指定 `features` 時使用完整預設排列（35 顆）。按鈕依 extension 啟用狀態自動隱藏，不會出現壞按鈕。

## 兩層客製路徑

1. **config 層**（推薦）：`features` / `include` / `exclude` / `extensionsConfig` / `extraExtensions` 同名替換——客製全部留在你自己的程式碼，vendored 檔保持乾淨，未來 `shadcn add` 更新零衝突
2. **改 vendored 源碼**：shadcn 精神的最終逃生口——升級時需人工合併，建議只在 config 層做不到時使用各 extension 之完整選項見 [Extensions 總覽](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/overview)。


# AioEditor

## 安裝

```bash
pnpm dlx shadcn-vue@latest add @admin/aio-editor
```

安裝即取得 UI 與邏輯核心（tiptap extensions、預設 config、`useAioEditor`），核心置於元件內 `core/` 子目錄，無需另裝其他單元。

## 用法

預設 config 即包含完整功能：36 個 extensions、35 顆 toolbar 控制項、7 種情境 bubble menu 與 drag handle。

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminAioEditor } from '@/registry/admin/ui/aio-editor'

const content = ref(`
  <h2>AioEditor</h2>
  <p>config 驅動的富文本編輯器，預設 toolbar 即包含<strong>格式</strong>、<em>樣式</em>、清單與區塊工具。</p>
  <ul>
    <li>項目清單</li>
    <li>支援 <code>行內程式碼</code> 與 <mark>螢光標記</mark></li>
  </ul>
  <blockquote><p>引用區塊</p></blockquote>
`)
</script>

<template>
  <admin-aio-editor v-model="content" />
</template>
```

## 場景

### 自訂 toolbar 與 Custom 按鈕

`config.features` 以宣告陣列決定按鈕集合與順序（同時決定 extension 載入），`Divider` 分組；`Custom` 功能可帶 icon / slot / 自帶 extensions。bubble 跟隨宣告自動掛載，`dragHandle` 可停用。

```vue
<script setup lang="ts">
import type { AioEditorConfig } from '@/registry/admin/ui/aio-editor'
import { IconSparkles } from '@tabler/icons-vue'
import { ref } from 'vue'
import { AdminAioEditor, AioEditorFeature } from '@/registry/admin/ui/aio-editor'

const content = ref('<p>精簡 toolbar：只放常用按鈕，並示範 Custom 按鈕。</p>')

const config: AioEditorConfig = {
  features: [
    AioEditorFeature.FontBold,
    AioEditorFeature.FontItalic,
    AioEditorFeature.Highlight,
    AioEditorFeature.Divider,
    AioEditorFeature.BulletList,
    AioEditorFeature.Blockquote,
    AioEditorFeature.Divider,
    {
      kind: AioEditorFeature.Custom,
      label: '插入問候',
      icon: IconSparkles,
      run: (editor) => editor.chain().focus().insertContent('👋 你好！').run()
    }
  ],
  // bubble 跟隨 features 宣告自動掛載（此處僅 BulletList 會帶 List bubble）；drag handle 另關
  dragHandle: false
}
</script>

<template>
  <admin-aio-editor v-model="content" :config="config" />
</template>
```

### 表格

`Table` 功能載入 `TableKit`（Table / TableRow / TableCell / TableHeader）。游標進入表格時依位置掛載 Table / TableColumn / TableRow 三種 bubble，欄寬可拖曳框線調整。

```vue
<script setup lang="ts">
import type { AioEditorConfig } from '@/registry/admin/ui/aio-editor'
import { ref } from 'vue'
import { AdminAioEditor, AioEditorFeature } from '@/registry/admin/ui/aio-editor'

const content = ref(`
  <p>將游標移入表格即出現欄 / 列控制 bubble：可增刪欄列、合併與拆分儲存格。</p>
  <table>
    <tbody>
      <tr>
        <th>項目</th>
        <th>說明</th>
      </tr>
      <tr>
        <td>欄寬</td>
        <td>拖曳框線調整（resizable）</td>
      </tr>
      <tr>
        <td>控制項</td>
        <td>Table / TableColumn / TableRow 三種 bubble 跟隨游標位置</td>
      </tr>
    </tbody>
  </table>
`)

const config: AioEditorConfig = {
  features: [
    AioEditorFeature.Undo,
    AioEditorFeature.Redo,
    AioEditorFeature.Divider,
    AioEditorFeature.FontBold,
    AioEditorFeature.Divider,
    AioEditorFeature.Table
  ]
}
</script>

<template>
  <admin-aio-editor v-model="content" :config="config" />
</template>
```

### 圖片與 requestUrl

`Image` 功能之插入來源走 `config.toolbarOptions.requestUrl`（Link / Video 共用同一入口，以 `kind` 區分）；未提供時 fallback 為 `window.prompt`。實務上在此接上傳對話框或素材庫，回傳 `null` 即取消。點選圖片出現 Image bubble，可切換對齊與寬度。

```vue
<script setup lang="ts">
import type { AioEditorConfig } from '@/registry/admin/ui/aio-editor'
import { ref } from 'vue'
import { AdminAioEditor, AioEditorFeature } from '@/registry/admin/ui/aio-editor'

const content = ref(`
  <p>點選圖片即出現 Image bubble：可切換對齊、調整寬度或移除。</p>
  <img src="/demo/sample.gif" alt="範例圖片" />
`)

// requestUrl 為 Link / Image / Video 之 URL 輸入來源；未提供時 fallback 為 window.prompt。
// 實務上這裡接上傳對話框或素材庫，回傳 null 代表取消。
const config: AioEditorConfig = {
  features: [
    AioEditorFeature.Undo,
    AioEditorFeature.Redo,
    AioEditorFeature.Divider,
    AioEditorFeature.AlignLeft,
    AioEditorFeature.AlignCenter,
    AioEditorFeature.Divider,
    AioEditorFeature.Image
  ],
  toolbarOptions: {
    requestUrl: ({ kind, previous }) => {
      if (kind !== 'image') {
        return previous ?? null
      }
      return '/demo/sample.gif'
    }
  }
}
</script>

<template>
  <admin-aio-editor v-model="content" :config="config" />
</template>
```

### 前台渲染輸出 HTML

編輯器內容樣式已拆為共通 prose 樣式 `adminAioEditorProseClass`：前台（或任何唯讀情境）渲染編輯器產出的 HTML 時，把它套在容器上即可對齊編輯時外觀，不需掛編輯器。

```vue
<script setup lang="ts">
import { adminAioEditorProseClass } from '@/components/admin/aio-editor'
import { cn } from '@/lib/utils'
</script>

<template>
  <div :class="cn(adminAioEditorProseClass)" v-html="htmlFromEditor"></div>
</template>
```

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { AdminAioEditor, adminAioEditorProseClass } from '@/registry/admin/ui/aio-editor'

const content = ref(`
  <h3>發布預覽</h3>
  <p>左側編輯，右側即為<strong>前台渲染</strong>結果——同一份 prose 樣式。</p>
  <ul>
    <li>清單與 <code>行內程式碼</code></li>
  </ul>
  <blockquote><p>引用區塊</p></blockquote>
`)
</script>

<template>
  <div
    :class="`
      grid w-full gap-4
      lg:grid-cols-2
    `"
  >
    <admin-aio-editor v-model="content" />
    <div
      :class="cn(`rounded-[6px] border border-dashed border-text-30 p-3`, adminAioEditorProseClass)"
      v-html="content"
    ></div>
  </div>
</template>
```

### Mention（opt-in）

`Mention` / `HashTag` 不在預設集合——需經 `config.include` 啟用，並以 `mentionSuggestion` 的 runtime hooks 提供選單渲染實作（選單 UI 由 consumer 全權決定）。

```vue
<script setup lang="ts">
import type { SuggestionProps } from '@tiptap/suggestion'
import type { AioEditorConfig } from '@/registry/admin/ui/aio-editor'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import {
  AdminAioEditor,
  AioEditorCoreExtension,
  AioEditorFeature,
  mentionSuggestion
} from '@/registry/admin/ui/aio-editor'

const content = ref('<p>輸入 @ 觸發 mention 選單。</p>')

const MEMBERS = ['王小明', '陳美麗', '林大同', '張雅婷']

// mention 選單為 consumer 自行實作：以 runtime hooks 掛一個最小清單 UI
function renderMenu(mountEl: HTMLElement, props: SuggestionProps) {
  mountEl.innerHTML = ''
  const items = MEMBERS.filter((name) => name.includes(props.query))
  for (const name of items) {
    const button = document.createElement('button')
    button.type = 'button'
    button.textContent = name
    button.className = 'aio-mention-option'
    button.addEventListener('mousedown', (event) => {
      event.preventDefault()
      props.command({ id: name, label: name })
    })
    mountEl.appendChild(button)
  }
  return mountEl
}

const config: AioEditorConfig = {
  include: [AioEditorCoreExtension.Mention],
  extensionsConfig: {
    Mention: {
      suggestion: {
        ...mentionSuggestion({
          onRender: (props, mountEl) => renderMenu(mountEl!, props as SuggestionProps),
          onUpdate: (props, componentEl) => {
            if (componentEl) {
              renderMenu(componentEl, props as SuggestionProps)
            }
          }
        }),
        items: ({ query }) => MEMBERS.filter((name) => name.includes(query))
      }
    }
  },
  features: [AioEditorFeature.FontBold, AioEditorFeature.FontItalic],
  dragHandle: false
}
</script>

<template>
  <admin-aio-editor
    v-model="content"
    :class="
      cn(`
        [&_.aio-mention-option]:block [&_.aio-mention-option]:w-full
        [&_.aio-mention-option]:rounded-[4px] [&_.aio-mention-option]:px-3
        [&_.aio-mention-option]:py-1 [&_.aio-mention-option]:text-left
        [&_.aio-mention-option]:hover:bg-bg-70
        [&_.editor-mention]:text-primary-40
        [&_.editor-suggestion]:z-10 [&_.editor-suggestion]:rounded-[6px]
        [&_.editor-suggestion]:border [&_.editor-suggestion]:border-text-30
        [&_.editor-suggestion]:bg-bg-90 [&_.editor-suggestion]:p-1 [&_.editor-suggestion]:shadow-md
      `)
    "
    :config="config"
  />
</template>
```

## API 參考

### aio-editor

::div{data-admin-api-table=""}
#### Props

| 名稱                 | 型別                                                                                                                                    | 預設值     | 說明                                                                      |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------- |
| `config`           | `AioEditorConfig | undefined`                                                                                                         | —       | 編輯器設定：features / extensions / 選項覆寫，未指定欄位取預設值                            |
| `modelValue`       | `string | JSONContent | undefined`                                                                                                    | —       | 內容（v-model）：依 contentType 解讀；未指定 contentType 時 string 視為 html、物件視為 json |
| `contentType`      | `"json" | "html" | undefined`                                                                                                         | —       | 內容型別（顯式優先於自動推斷）                                                         |
| `editable`         | `boolean | undefined`                                                                                                                 | `true`  | 是否可編輯                                                                   |
| `id`               | `string | undefined`                                                                                                                  | —       | 元件 id：多編輯器頁面之辨識，寫入 hooks context 與 editor.storage.aio.id；未提供自動產生        |
| `autofocus`        | `FocusPosition | undefined`                                                                                                           | `false` | 掛載後自動聚焦位置（true = 'start'；false 不聚焦）                                     |
| `enableInputRules` | `boolean | ((names: string[]) => boolean | string[]) | undefined`                                                                     | `true`  | 是否啟用輸入規則；函式形接收最終 extension 名單，回傳 boolean 或要啟用的名稱陣列                      |
| `enablePasteRules` | `boolean | ((names: string[]) => boolean | string[]) | undefined`                                                                     | `true`  | 是否啟用貼上規則；函式形同 enableInputRules                                          |
| `toolbar`          | `boolean | undefined`                                                                                                                 | `true`  | 是否顯示工具列（false 隱藏，extensions 照常載入）                                       |
| `toolbarTarget`    | `string | HTMLElement | undefined`                                                                                                    | —       | 工具列外掛目標：CSS selector 或 HTMLElement（Teleport），未指定渲染於編輯器頂部                |
| `ui`               | `{ base?: string | undefined; content?: string | undefined; toolbar?: string | undefined; bubble?: string | undefined; } | undefined` | —       | 各部位 class 覆寫                                                            |
| `class`            | `ClassValue`                                                                                                                          | —       | root 之 class                                                            |

#### Events

| 名稱                  | Payload | 說明 |
| ------------------- | ------- | -- |
| `blur`              | `any`   | —  |
| `focus`             | `any`   | —  |
| `keydown`           | `any`   | —  |
| `update:modelValue` | `any`   | —  |
| `create`            | `any`   | —  |
| `update`            | `any`   | —  |
| `selectionUpdate`   | `any`   | —  |
| `destroy`           | `any`   | —  |
| `contentError`      | `any`   | —  |

#### Slots

| 名稱        | Bindings                                            | 說明                                                     |
| --------- | --------------------------------------------------- | ------------------------------------------------------ |
| `default` | `{ editor: Editor | undefined; editorId: string; }` | 預設 slot：置於內容區之後，暴露 editor 實例供進階操作                      |
| `footer`  | `{ editor: Editor | undefined; editorId: string; }` | 底部列：預設渲染字數統計（設定 CharacterCount limit 時），提供此 slot 可完全自訂 |

#### Expose

| 名稱       | 簽名                   | 說明                                     |
| -------- | -------------------- | -------------------------------------- |
| `editor` | `Editor | undefined` | tiptap Editor 實例（mounted 前為 undefined） |
::

`config` 之完整型別（`AioEditorConfig`、`AioEditorExtensionsConfig`、enums 與各 `default*Config`）由 `@admin/aio-editor` 匯出，各 extension 的完整選項說明見 [Extensions 總覽](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/overview)。

## 注意事項

- **URL 輸入來源**：Link / Image / Video 按鈕預設以 `window.prompt` 取得 URL；提供 `config.toolbarOptions.requestUrl`（ctx 帶 `editor` / `editorId` / `target`）即可換成自訂 UI。連結編輯已內建於 LinkTips bubble 的 inline 輸入框。
- **不允許的連結網址**：網址被 Link extension 的 `isAllowedUri` 拒絕（如 `javascript:`）時不會套用，LinkTips 輸入框還原為原網址；提供 `config.toolbarOptions.onInvalidLink`（ctx 帶 `url`，LinkTips 觸發時 `target` 為輸入框）即可顯示自訂提示。選取範圍本身不能加連結（程式碼區塊、行內程式碼）時同樣不會套用，但不屬網址問題，不會呼叫 `onInvalidLink`。
- **色盤**：TextColor / Highlight 內建 `@admin/color-picker` 色票（`toolbarOptions.textColorSwatches / highlightSwatches` 自訂調色盤）；要自由取色提供 `requestColor`。`value: ''` 為清除項；完全透明之色票（`transparent`、`#0000`、`rgba(…, 0)` 等）於浮層中會加上外框以便辨識。
- **工具列版面**：`toolbar: false` 隱藏（extensions 照載）；`toolbarTarget` 可把工具列 Teleport 到任意容器（多編輯器共用一條、頂部固定列、浮動容器）。
- **事件**：`create / update / selectionUpdate / focus / blur / destroy / contentError / keydown` 透傳，payload 統一帶 `{ editor, editorId }`——多編輯器頁面以 `editorId`（或 `id` prop）辨識來源。
- **圖片 / 影片上傳**：貼上與拖放檔案會觸發 `extensionsConfig.Image.pasteAndDropHandle` / `extensionsConfig.Video.pasteAndDropHandle`，上傳邏輯由 consumer 實作後回呼 `afterImageUpload` / `afterVideoUpload`。未實作時僅於 console 提示。
- **Mention / HashTag**：無按鈕功能，經 `config.include` 啟用並提供 suggestion `onRender` 實作。UndoRedo / Code 同理——未宣告按鈕時要保留能力就 `include`。
- **v-model 型別**：綁 `string` 視為 HTML、綁物件視為 JSON（tiptap `JSONContent`）。不掛編輯器的轉換用 `editorJson2Html` / `editorHtml2Json`（瀏覽器環境限定）。
- **外部寫入不觸發事件**：父層透過 v-model 寫入內容、或切換 `editable` 時，不會 emit `update:modelValue` 與 `update`——父層拿到的值維持原樣，不會被換成編輯器正規化後的 HTML，表單載入後也不會被判為已修改。只有使用者編輯（含透過 `editor` 實例執行之 command）才會觸發；字數統計則一律隨內容更新。
- **exclude 一律生效**：`exclude` 對任何 extension（含 schema 必備之 Document / Text / Paragraph）都會生效、不自動保留。排除後以 `extraExtensions` 或 Custom `extensions` 提供同名 extension 即視為替換、不警告；未替換且有依賴者受影響時 console 警告；schema 必備項於最終清單缺席時給最強警告（編輯器將無法初始化）。toolbar 按鈕依 extension 啟用狀態自動隱藏。

## 更新紀錄

:admin-changelog{component="AdminAioEditor"}


# Extensions 總覽

**宣告驅動**：`config.features` 是唯一宣告來源——宣告哪些按鈕，就載入哪些 extension（**未宣告即不載入**）；`Require`（Document / Text / Paragraph）與 `Basic`（8 個純基建）恆載。各 extension 的選項經 `config.extensionsConfig` 覆寫（深層 merge：plain object 遞迴合併；陣列、function、instance 整值取代；`null` 清除預設、`undefined` 忽略），`bubbles` 與 `dragHandle` 亦同；各 `default*Config` 皆由 `@admin/aio-editor` 匯出。

```ts
import { AioEditorCoreExtension, AioEditorFeature } from '@/components/admin/aio-editor'

const config: AioEditorConfig = {
  features: [AioEditorFeature.FontBold, AioEditorFeature.BulletList], // 宣告 = 按鈕 + 載入
  include: [AioEditorCoreExtension.UndoRedo], // 無按鈕保 Ctrl+Z
  exclude: [AioEditorCoreExtension.CopyData], // 精準排除（一律生效，分級警告）
  extensionsConfig: {
    Heading: { levels: [1, 2, 3] },
    CharacterCount: { limit: 500 }
  }
}
```

## 三種載入路徑（依生命週期選對入口）

| 你要載入的東西                         | 正確路徑                       | 生命週期           |
| ------------------------------- | -------------------------- | -------------- |
| 有 UI 的自訂能力（按鈕＋它的 extension）     | `CustomFeature.extensions` | 跟隨 feature 宣告  |
| 無 UI 的內建能力（保快捷鍵 / 輸入規則、Mention） | `include`                  | 無條件載入，自動補齊硬依賴  |
| 無 UI 的自訂能力、同名替換                 | `extraExtensions`          | 無條件載入；同名時優先權最高 |

`exclude` 對三者一律生效（含 Require），不連鎖卸載——依賴者靜默失效、對應按鈕自動隱藏。排除後提供同名 extension 視為替換、不警告；未替換且有依賴者受影響時 console 警告。Require（Document / Text / Paragraph）於三路徑合併後檢查，最終集合缺席才給最強警告。

> 標「自製」者為本系列移植之客製 extension，帶有與官方套件不同的行為，詳見各頁說明。

每頁的「載入途徑 / 排除影響」段落取自 `app/registry/admin/aio/aio-feature-map.json`，該檔為手動維護；調整 `FEATURE_DEFS`、`extensionDependencies` 或恆載層後須一併更新。

## 文字 mark

| Extension                                                                                         | 用途                                        |
| ------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| [Bold](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/bold)               | 粗體                                        |
| [Italic](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/italic)           | 斜體                                        |
| [Strike](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/strike)           | 刪除線                                       |
| [Underline](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/underline)     | 底線                                        |
| [Code](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/code)               | 行內程式碼                                     |
| [TextStyle](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/text-style)    | 行內樣式載體（Color / FontFamily / FontSize 之基底） |
| [Color](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/color)             | 文字顏色                                      |
| [Highlight](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/highlight)     | 螢光標記                                      |
| [Subscript](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/subscript)     | 下標                                        |
| [Superscript](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/superscript) | 上標                                        |

## 區塊

| Extension                                                                                                         | 用途                  |
| ----------------------------------------------------------------------------------------------------------------- | ------------------- |
| [Document / Text / Gapcursor](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/schema-base) | schema 基底與游標行為（無選項） |
| [Paragraph](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/paragraph)                     | 段落                  |
| [Heading](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/heading)                         | 標題 h1–h6            |
| [Blockquote](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/blockquote)                   | 引用區塊                |
| [HorizontalRule](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/horizontal-rule)          | 水平線                 |
| [HardBreak](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/hard-break)                    | 強制斷行                |
| [CodeBlock](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/code-block)（自製）                | 程式碼區塊（lowlight 高亮）  |

## 清單

| Extension                                                                                            | 用途     |
| ---------------------------------------------------------------------------------------------------- | ------ |
| [BulletList](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/bullet-list)     | 項目清單   |
| [OrderedList](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/ordered-list)   | 編號清單   |
| [ListItem](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/list-item)         | 清單項    |
| [TaskList](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/task-list)         | 待辦清單   |
| [TaskItem](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/task-item)         | 待辦清單項  |
| [ListKeyMap](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/list-keymap)（自製） | 清單鍵盤行為 |

## 排版

| Extension                                                                                            | 用途   |
| ---------------------------------------------------------------------------------------------------- | ---- |
| [TextAlign](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/text-align)       | 文字對齊 |
| [Indent](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/indent)（自製）          | 區塊縮排 |
| [LineHeight](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/line-height)（自製） | 行高   |
| [FontFamily](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/font-family)     | 字體   |
| [FontSize](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/font-size)（自製）     | 字級   |

## 行為

| Extension                                                                                                    | 用途              |
| ------------------------------------------------------------------------------------------------------------ | --------------- |
| [UndoRedo](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/undo-redo)                 | 編輯歷史            |
| [Dropcursor](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/dropcursor)              | 拖放位置指示線         |
| [Placeholder](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/placeholder)            | 空內容提示           |
| [CharacterCount](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/character-count)（自製） | 字數統計與上限（IME 保護） |
| [KeydownHandler](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/keydown-handler)（自製） | 鍵盤事件 hook       |
| [AutoJoiner](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/auto-joiner)             | 相鄰清單自動合併        |
| [CopyData](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/copy-data)（自製）             | data-copy 屬性保留  |

## 內容節點

| Extension                                                                                        | 用途               |
| ------------------------------------------------------------------------------------------------ | ---------------- |
| [Link](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/link)              | 超連結              |
| [Image](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/image)（自製）        | 圖片（拖曳縮放、上傳 hook） |
| [Video](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/video)（自製）        | 影片               |
| [TableKit](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/table-kit)（自製） | 表格（grip 選取）      |

## Opt-in（須經 `include` 啟用）

| Extension                                                                                      | 用途     |
| ---------------------------------------------------------------------------------------------- | ------ |
| [Mention](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/mention)（自製）  | `@` 提及 |
| [HashTag](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/hash-tag)（自製） | `#` 標籤 |

## UI 附加（不走 `extensionsConfig`）

| 項目                                                                                                    | 設定入口                |
| ----------------------------------------------------------------------------------------------------- | ------------------- |
| [Bubble Menu](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/bubble-menu)（自製） | `config.bubbles`    |
| [Drag Handle](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/drag-handle)（自製） | `config.dragHandle` |

## Feature → Extension 對映總表

:aio-feature-map

## 樣式補充

- **CodeBlock 高亮配色**：輸出帶 hljs class，配色主題由 consumer 自行引入（同 Svelte 版作法），例如 `import 'highlight.js/styles/github-dark.css'`
- **Mention / HashTag 建議樣式**：節點 class 為 `editor-mention` / `editor-hashtag`、選單容器 class 為 `editor-suggestion`——參考主元件頁 Mention demo 的樣式片段


# Subscript

下標文字標記（`sub` 元素），與 Superscript 互斥。

- **config key**：`AioEditorCoreExtension.Subscript`
- **來源**：`@tiptap/extension-subscript`

:aio-extension-impact{extension="Subscript"}

## 選項

| 欄位               | 型別                    | 預設值  | 說明               |
| ---------------- | --------------------- | ---- | ---------------- |
| `HTMLAttributes` | `Record<string, any>` | `{}` | 渲染輸出時附加之 HTML 屬性 |

## Commands

| Command             | 說明   |
| ------------------- | ---- |
| `setSubscript()`    | 套用下標 |
| `toggleSubscript()` | 切換下標 |
| `unsetSubscript()`  | 移除下標 |

## 快捷鍵

| 按鍵      | 行為   |
| ------- | ---- |
| `Mod-,` | 切換下標 |


# Superscript

上標文字標記（`sup` 元素），與 Subscript 互斥。

- **config key**：`AioEditorCoreExtension.Superscript`
- **來源**：`@tiptap/extension-superscript`

:aio-extension-impact{extension="Superscript"}

## 選項

| 欄位               | 型別                    | 預設值  | 說明               |
| ---------------- | --------------------- | ---- | ---------------- |
| `HTMLAttributes` | `Record<string, any>` | `{}` | 渲染輸出時附加之 HTML 屬性 |

## Commands

| Command               | 說明   |
| --------------------- | ---- |
| `setSuperscript()`    | 套用上標 |
| `toggleSuperscript()` | 切換上標 |
| `unsetSuperscript()`  | 移除上標 |

## 快捷鍵

| 按鍵      | 行為   |
| ------- | ---- |
| `Mod-.` | 切換上標 |


# Document / Text / Gapcursor

三個無選項的基礎 extension：`Document` 定義文件根節點、`Text` 定義文字節點（兩者為 schema 必備，`exclude` 它們會使編輯器無法運作）；`Gapcursor` 讓游標能停在無法輸入文字的位置（如相鄰兩張圖片之間）。

- **config key**：`Document` / `Text` / `Gapcursor`（預設啟用）
- **來源**：`@tiptap/extension-document`、`@tiptap/extension-text`、`@tiptap/extensions`（`Gapcursor`）

## 選項

此 extension 無可設定選項。


# Paragraph

段落節點（`p` 元素），文件的預設區塊。

- **config key**：`AioEditorCoreExtension.Paragraph`
- **來源**：`@tiptap/extension-paragraph`

:aio-extension-impact{extension="Paragraph"}

## 選項

| 欄位               | 型別                    | 預設值  | 說明               |
| ---------------- | --------------------- | ---- | ---------------- |
| `HTMLAttributes` | `Record<string, any>` | `{}` | 渲染輸出時附加之 HTML 屬性 |

## Commands

| Command          | 說明        |
| ---------------- | --------- |
| `setParagraph()` | 將目前區塊轉為段落 |

## 快捷鍵

| 按鍵          | 行為   |
| ----------- | ---- |
| `Mod-Alt-0` | 轉為段落 |


# Heading

標題節點（`h1`–`h6`）。

- **config key**：`AioEditorCoreExtension.Heading`
- **來源**：`@tiptap/extension-heading`

:aio-extension-impact{extension="Heading"}

## 選項

| 欄位               | 型別                    | 預設值                  | 說明                   |
| ---------------- | --------------------- | -------------------- | -------------------- |
| `levels`         | `Level[]`             | `[1, 2, 3, 4, 5, 6]` | 允許之標題層級；不在清單內之層級無法設定 |
| `HTMLAttributes` | `Record<string, any>` | `{}`                 | 渲染輸出時附加之 HTML 屬性     |

## Commands

| Command                    | 說明       |
| -------------------------- | -------- |
| `setHeading({ level })`    | 設為指定層級標題 |
| `toggleHeading({ level })` | 切換指定層級標題 |

## 快捷鍵

| 按鍵                      | 行為       |
| ----------------------- | -------- |
| `Mod-Alt-1 … Mod-Alt-6` | 切換對應層級標題 |

## 覆寫範例

```ts
const config: AioEditorConfig = {
  extensionsConfig: {
    Heading: { levels: [1, 2, 3] }
  }
}
```

輸入規則：行首 `#`～`######` ＋空白自動轉為對應層級標題。


# Blockquote

引用區塊（`blockquote` 元素）。

- **config key**：`AioEditorCoreExtension.Blockquote`
- **來源**：`@tiptap/extension-blockquote`

:aio-extension-impact{extension="Blockquote"}

## 選項

| 欄位               | 型別                    | 預設值  | 說明               |
| ---------------- | --------------------- | ---- | ---------------- |
| `HTMLAttributes` | `Record<string, any>` | `{}` | 渲染輸出時附加之 HTML 屬性 |

## Commands

| Command              | 說明     |
| -------------------- | ------ |
| `setBlockquote()`    | 包成引用區塊 |
| `toggleBlockquote()` | 切換引用區塊 |
| `unsetBlockquote()`  | 解除引用區塊 |

## 快捷鍵

| 按鍵            | 行為     |
| ------------- | ------ |
| `Mod-Shift-B` | 切換引用區塊 |

輸入規則：行首 `>` ＋空白自動轉為引用。


# HorizontalRule

水平分隔線（`hr` 元素）。

- **config key**：`AioEditorCoreExtension.HorizontalRule`
- **來源**：`@tiptap/extension-horizontal-rule`

:aio-extension-impact{extension="HorizontalRule"}

## 選項

| 欄位               | 型別                    | 預設值  | 說明               |
| ---------------- | --------------------- | ---- | ---------------- |
| `HTMLAttributes` | `Record<string, any>` | `{}` | 渲染輸出時附加之 HTML 屬性 |

## Commands

| Command               | 說明    |
| --------------------- | ----- |
| `setHorizontalRule()` | 插入水平線 |

輸入規則：行首 `---` 自動轉為水平線。


# HardBreak

強制斷行（`br` 元素），不產生新段落。

- **config key**：`AioEditorCoreExtension.HardBreak`
- **來源**：`@tiptap/extension-hard-break`

:aio-extension-impact{extension="HardBreak"}

## 選項

| 欄位               | 型別                    | 預設值    | 說明                      |
| ---------------- | --------------------- | ------ | ----------------------- |
| `keepMarks`      | `boolean`             | `true` | 斷行後是否延續目前的 mark（粗體、斜體等） |
| `HTMLAttributes` | `Record<string, any>` | `{}`   | 渲染輸出時附加之 HTML 屬性        |

## Commands

| Command          | 說明   |
| ---------------- | ---- |
| `setHardBreak()` | 插入斷行 |

## 快捷鍵

| 按鍵            | 行為   |
| ------------- | ---- |
| `Shift-Enter` | 插入斷行 |
| `Mod-Enter`   | 插入斷行 |


# CodeBlock

程式碼區塊，**自製變體**：基於 `CodeBlockLowlight`，`renderHTML` 直接內嵌 hljs 高亮結構——輸出的 HTML 在非編輯情境（郵件、前台）不需再跑一次高亮。

- **config key**：`AioEditorCoreExtension.CodeBlock`
- **來源**：自製（基於 `@tiptap/extension-code-block-lowlight` ＋ `lowlight`）

:aio-extension-impact{extension="CodeBlock"}

## 選項

| 欄位                     | 型別                                  | 預設值                   | 說明                                                  |
| ---------------------- | ----------------------------------- | --------------------- | --------------------------------------------------- |
| `lowlight`             | `ReturnType<typeof createLowlight>` | `createLowlight(all)` | 語法高亮引擎；預設載入 highlight.js 全語言，追求 bundle 可自建僅含所需語言之實例 |
| `languageClassPrefix`  | `string`                            | `'language-'`         | `code` 元素之語言 class 前綴                               |
| `defaultLanguage`      | `string 或 null`                     | `null`                | 未指定語言時之預設；`null` 為自動偵測                              |
| `exitOnTripleEnter`    | `boolean`                           | `true`                | 連按三次 Enter 離開區塊                                     |
| `exitOnArrowDown`      | `boolean`                           | `true`                | 區塊尾按 ↓ 離開                                           |
| `enableTabIndentation` | `boolean`                           | `true`                | 區塊內 Tab 輸入縮排                                        |
| `tabSize`              | `number`                            | `4`                   | Tab 縮排寬度                                            |
| `HTMLAttributes`       | `Record<string, any>`               | `{ class: 'hljs' }`   | 渲染輸出時附加之 HTML 屬性                                    |

## Commands

| Command                          | 說明      |
| -------------------------------- | ------- |
| `setCodeBlock({ language? })`    | 轉為程式碼區塊 |
| `toggleCodeBlock({ language? })` | 切換程式碼區塊 |

## 快捷鍵

| 按鍵          | 行為      |
| ----------- | ------- |
| `Mod-Alt-C` | 切換程式碼區塊 |

## 覆寫範例

```ts
const config: AioEditorConfig = {
  extensionsConfig: {
    CodeBlock: { defaultLanguage: 'typescript', tabSize: 2 }
  }
}
```

輸入規則：行首 ` ``` `（可接語言名）自動轉為程式碼區塊。位於區塊內時會出現 [CodeBlock bubble](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/bubble-menu)。


# BulletList

無序清單（`ul` 元素）。

- **config key**：`AioEditorCoreExtension.BulletList`
- **來源**：`@tiptap/extension-list`（`BulletList`）

:aio-extension-impact{extension="BulletList"}

## 選項

| 欄位               | 型別                    | 預設值          | 說明               |
| ---------------- | --------------------- | ------------ | ---------------- |
| `itemTypeName`   | `string`              | `'listItem'` | 清單項之節點名          |
| `HTMLAttributes` | `Record<string, any>` | `{}`         | 渲染輸出時附加之 HTML 屬性 |
| `keepMarks`      | `boolean`             | `false`      | 切換清單時保留文字 mark   |
| `keepAttributes` | `boolean`             | `false`      | 切換清單時保留節點屬性      |

## Commands

| Command              | 說明     |
| -------------------- | ------ |
| `toggleBulletList()` | 切換項目清單 |

## 快捷鍵

| 按鍵            | 行為     |
| ------------- | ------ |
| `Mod-Shift-8` | 切換項目清單 |

輸入規則：行首 `-`、`*` 或 `+` ＋空白自動轉為項目清單。


# Bold

粗體文字標記。

- **config key**：`AioEditorCoreExtension.Bold`
- **來源**：`@tiptap/extension-bold`

:aio-extension-impact{extension="Bold"}

## 選項

| 欄位               | 型別                    | 預設值  | 說明               |
| ---------------- | --------------------- | ---- | ---------------- |
| `HTMLAttributes` | `Record<string, any>` | `{}` | 渲染輸出時附加之 HTML 屬性 |

## Commands

| Command        | 說明   |
| -------------- | ---- |
| `setBold()`    | 套用粗體 |
| `toggleBold()` | 切換粗體 |
| `unsetBold()`  | 移除粗體 |

## 快捷鍵

| 按鍵      | 行為   |
| ------- | ---- |
| `Mod-B` | 切換粗體 |

## 覆寫範例

```ts
const config: AioEditorConfig = {
  extensionsConfig: {
    Bold: { HTMLAttributes: { class: 'my-bold' } }
  }
}
```

輸入規則：`**文字**` 或 `__文字__` 自動轉為粗體。


# OrderedList

有序清單（`ol` 元素）。

- **config key**：`AioEditorCoreExtension.OrderedList`
- **來源**：`@tiptap/extension-list`（`OrderedList`）

:aio-extension-impact{extension="OrderedList"}

## 選項

| 欄位               | 型別                    | 預設值          | 說明               |
| ---------------- | --------------------- | ------------ | ---------------- |
| `itemTypeName`   | `string`              | `'listItem'` | 清單項之節點名          |
| `HTMLAttributes` | `Record<string, any>` | `{}`         | 渲染輸出時附加之 HTML 屬性 |
| `keepMarks`      | `boolean`             | `false`      | 切換清單時保留文字 mark   |
| `keepAttributes` | `boolean`             | `false`      | 切換清單時保留節點屬性      |

## Commands

| Command               | 說明     |
| --------------------- | ------ |
| `toggleOrderedList()` | 切換編號清單 |

## 快捷鍵

| 按鍵            | 行為     |
| ------------- | ------ |
| `Mod-Shift-7` | 切換編號清單 |

輸入規則：行首 `1.` ＋空白自動轉為編號清單。


# ListItem

清單項（`li` 元素），供 BulletList / OrderedList 使用。

- **config key**：`AioEditorCoreExtension.ListItem`
- **來源**：`@tiptap/extension-list`（`ListItem`）

:aio-extension-impact{extension="ListItem"}

## 選項

| 欄位                    | 型別                    | 預設值             | 說明               |
| --------------------- | --------------------- | --------------- | ---------------- |
| `HTMLAttributes`      | `Record<string, any>` | `{}`            | 渲染輸出時附加之 HTML 屬性 |
| `bulletListTypeName`  | `string`              | `'bulletList'`  | 所屬無序清單之節點名       |
| `orderedListTypeName` | `string`              | `'orderedList'` | 所屬有序清單之節點名       |

## 快捷鍵

| 按鍵          | 行為        |
| ----------- | --------- |
| `Enter`     | 分割清單項     |
| `Tab`       | 降一層（sink） |
| `Shift-Tab` | 升一層（lift） |


# TaskList

待辦清單（`ul[data-type="taskList"]`）。

- **config key**：`AioEditorCoreExtension.TaskList`
- **來源**：`@tiptap/extension-list`（`TaskList`）

:aio-extension-impact{extension="TaskList"}

## 選項

| 欄位               | 型別                    | 預設值          | 說明               |
| ---------------- | --------------------- | ------------ | ---------------- |
| `itemTypeName`   | `string`              | `'taskItem'` | 清單項之節點名          |
| `HTMLAttributes` | `Record<string, any>` | `{}`         | 渲染輸出時附加之 HTML 屬性 |

## Commands

| Command            | 說明     |
| ------------------ | ------ |
| `toggleTaskList()` | 切換待辦清單 |

## 快捷鍵

| 按鍵            | 行為     |
| ------------- | ------ |
| `Mod-Shift-9` | 切換待辦清單 |


# TaskItem

帶 checkbox 的待辦清單項。

- **config key**：`AioEditorCoreExtension.TaskItem`
- **來源**：`@tiptap/extension-list`（`TaskItem`）

:aio-extension-impact{extension="TaskItem"}

## 選項

| 欄位                  | 型別                           | 預設值          | 說明                          |
| ------------------- | ---------------------------- | ------------ | --------------------------- |
| `nested`            | `boolean`                    | `true`       | 允許巢狀待辦清單                    |
| `HTMLAttributes`    | `Record<string, any>`        | `{}`         | 渲染輸出時附加之 HTML 屬性            |
| `taskListTypeName`  | `string`                     | `'taskList'` | 所屬待辦清單之節點名                  |
| `onReadOnlyChecked` | `(node, checked) => boolean` | `undefined`  | 唯讀模式下勾選時之攔截；回傳 `false` 阻止變更 |

輸入規則：行首 `[ ]` 或 `[x]` ＋空白自動轉為待辦項。


# ListKeyMap

清單之 Backspace / Delete 合併行為，**自製變體**：前一個清單項帶有子清單時不觸發合併（避免誤併進深層結構），其餘行為同官方 `ListKeymap`。

- **config key**：`AioEditorCoreExtension.ListKeyMap`
- **來源**：自製（基於 `@tiptap/extension-list` 之 `ListKeymap`）

:aio-extension-impact{extension="ListKeyMap"}

## 選項

| 欄位          | 型別                                               | 預設值                      | 說明                                 |
| ----------- | ------------------------------------------------ | ------------------------ | ---------------------------------- |
| `listTypes` | `{ itemName: string; wrapperNames: string[] }[]` | `listItem ＋ taskItem 兩組` | 套用行為之清單型別；`wrapperNames` 為其外層清單節點名 |

## 覆寫範例

```ts
const config: AioEditorConfig = {
  extensionsConfig: {
    ListKeyMap: { listTypes: [{ itemName: 'listItem', wrapperNames: ['bulletList', 'orderedList'] }] }
  }
}
```


# TextAlign

區塊文字對齊（輸出 `text-align` style）。

- **config key**：`AioEditorCoreExtension.TextAlign`
- **來源**：`@tiptap/extension-text-align`

:aio-extension-impact{extension="TextAlign"}

## 選項

| 欄位                 | 型別         | 預設值                                      | 說明                    |
| ------------------ | ---------- | ---------------------------------------- | --------------------- |
| `types`            | `string[]` | `['heading', 'paragraph']`               | 可對齊之節點型別              |
| `alignments`       | `string[]` | `['left', 'center', 'right', 'justify']` | 允許之對齊值；不在清單內之值無法設定    |
| `defaultAlignment` | `string`   | `'left'`                                 | 預設對齊（等於預設值時不輸出 style） |

## Commands

| Command                      | 說明     |
| ---------------------------- | ------ |
| `setTextAlign(alignment)`    | 設定對齊   |
| `unsetTextAlign()`           | 回復預設對齊 |
| `toggleTextAlign(alignment)` | 切換對齊   |

## 快捷鍵

| 按鍵            | 行為   |
| ------------- | ---- |
| `Mod-Shift-L` | 靠左   |
| `Mod-Shift-E` | 置中   |
| `Mod-Shift-R` | 靠右   |
| `Mod-Shift-J` | 兩端對齊 |


# Indent

區塊縮排（輸出 `margin-left` style），**自製 extension**。清單內會優先操作 `sinkListItem` / `liftListItem`，離開清單後才走縮排；清單項上的縮排值會被自動歸零。

- **config key**：`AioEditorCoreExtension.Indent`
- **來源**：自製

:aio-extension-impact{extension="Indent"}

## 選項

| 欄位                   | 型別                      | 預設值                        | 說明           |
| -------------------- | ----------------------- | -------------------------- | ------------ |
| `names`              | `string[]`              | `['heading', 'paragraph']` | 可縮排之節點型別     |
| `indentRange`        | `number`                | `24`                       | 每次縮排之增減量（px） |
| `minIndentLevel`     | `number`                | `0`                        | 縮排下限（px）     |
| `maxIndentLevel`     | `number`                | `240`                      | 縮排上限（px）     |
| `defaultIndentLevel` | `number`                | `0`                        | 預設縮排值        |
| `HTMLAttributes`     | `Record<string, never>` | `{}`                       | 保留欄位，目前未使用   |

## Commands

| Command     | 說明   |
| ----------- | ---- |
| `indent()`  | 增加縮排 |
| `outdent()` | 減少縮排 |

## 快捷鍵

| 按鍵          | 行為           |
| ----------- | ------------ |
| `Tab`       | 增加縮排（清單內為降層） |
| `Shift-Tab` | 減少縮排（清單內為升層） |
| `Backspace` | 行首時減少縮排      |
| `Mod-]`     | 增加縮排         |
| `Mod-[`     | 減少縮排         |

解析既有 HTML 時會合併 `margin-left` 與 `text-indent`（支援 px / pt 單位）作為初始縮排值。


# LineHeight

段落行高（輸出 `line-height` style），**自製 extension**。

- **config key**：`AioEditorCoreExtension.LineHeight`
- **來源**：自製

:aio-extension-impact{extension="LineHeight"}

## 選項

| 欄位                  | 型別         | 預設值                      | 說明                                               |
| ------------------- | ---------- | ------------------------ | ------------------------------------------------ |
| `types`             | `string[]` | `['paragraph']`          | 可調行高之節點型別                                        |
| `heights`           | `string[]` | `['1', '1.1', …, '2.0']` | 允許值清單；`setLineHeight` 帶入清單外的值會失敗                 |
| `defaultLineHeight` | `string`   | `''`                     | 預設行高；含 `--` 時輸出 `var()`（可接 CSS 變數），空字串則不輸出 style |

## Commands

| Command                 | 說明                   |
| ----------------------- | -------------------- |
| `setLineHeight(height)` | 設定行高（須在 heights 清單內） |
| `unsetLineHeight()`     | 重設為預設行高              |

## 覆寫範例

```ts
const config: AioEditorConfig = {
  extensionsConfig: {
    LineHeight: { heights: ['1', '1.5', '2'], defaultLineHeight: '1.5' }
  }
}
```


# FontFamily

文字字體（輸出 `font-family` style），樣式掛於 [TextStyle](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/text-style) mark。

- **config key**：`AioEditorCoreExtension.FontFamily`
- **來源**：`@tiptap/extension-text-style`（`FontFamily`）

:aio-extension-impact{extension="FontFamily"}

## 選項

| 欄位      | 型別         | 預設值             | 說明              |
| ------- | ---------- | --------------- | --------------- |
| `types` | `string[]` | `['textStyle']` | 樣式套用之目標 mark 型別 |

## Commands

| Command                     | 說明     |
| --------------------------- | ------ |
| `setFontFamily(fontFamily)` | 設定字體   |
| `unsetFontFamily()`         | 移除字體設定 |


# FontSize

文字字級（輸出 `font-size` style），**自製 extension**，樣式掛於 [TextStyle](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/text-style) mark。

- **config key**：`AioEditorCoreExtension.FontSize`
- **來源**：自製

:aio-extension-impact{extension="FontSize"}

## 選項

| 欄位                | 型別         | 預設值             | 說明                                          |
| ----------------- | ---------- | --------------- | ------------------------------------------- |
| `types`           | `string[]` | `['textStyle']` | 樣式套用之目標 mark 型別                             |
| `defaultFontSize` | `string`   | `''`            | `unsetFontSize` 之回復值；空字串代表直接移除 font-size 樣式 |

## Commands

| Command                 | 說明                   |
| ----------------------- | -------------------- |
| `setFontSize(fontSize)` | 設定字級（CSS 值，如 '14px'） |
| `unsetFontSize()`       | 回復預設字級               |

## 覆寫範例

```ts
const config: AioEditorConfig = {
  extensionsConfig: {
    FontSize: { defaultFontSize: '16px' }
  }
}
```


# Italic

斜體文字標記。

- **config key**：`AioEditorCoreExtension.Italic`
- **來源**：`@tiptap/extension-italic`

:aio-extension-impact{extension="Italic"}

## 選項

| 欄位               | 型別                    | 預設值  | 說明               |
| ---------------- | --------------------- | ---- | ---------------- |
| `HTMLAttributes` | `Record<string, any>` | `{}` | 渲染輸出時附加之 HTML 屬性 |

## Commands

| Command          | 說明   |
| ---------------- | ---- |
| `setItalic()`    | 套用斜體 |
| `toggleItalic()` | 切換斜體 |
| `unsetItalic()`  | 移除斜體 |

## 快捷鍵

| 按鍵      | 行為   |
| ------- | ---- |
| `Mod-I` | 切換斜體 |

輸入規則：`*文字*` 或 `_文字_` 自動轉為斜體。


# UndoRedo

編輯歷史（undo / redo）。即 tiptap v2 之 `History`，v3 更名。

- **config key**：`AioEditorCoreExtension.UndoRedo`
- **來源**：`@tiptap/extensions`（`UndoRedo`）

:aio-extension-impact{extension="UndoRedo"}

## 選項

| 欄位              | 型別       | 預設值   | 說明                   |
| --------------- | -------- | ----- | -------------------- |
| `depth`         | `number` | `200` | 歷史堆疊深度（可復原步數）        |
| `newGroupDelay` | `number` | `100` | 間隔多少 ms 內的連續輸入合併為同一步 |

## Commands

| Command  | 說明 |
| -------- | -- |
| `undo()` | 復原 |
| `redo()` | 重做 |

## 快捷鍵

| 按鍵            | 行為 |
| ------------- | -- |
| `Mod-Z`       | 復原 |
| `Mod-Shift-Z` | 重做 |
| `Mod-Y`       | 重做 |


# Dropcursor

拖曳內容時顯示的插入位置指示線。

- **config key**：`AioEditorCoreExtension.Dropcursor`
- **來源**：`@tiptap/extensions`（`Dropcursor`）

:aio-extension-impact{extension="Dropcursor"}

## 選項

| 欄位      | 型別       | 預設值              | 說明           |
| ------- | -------- | ---------------- | ------------ |
| `color` | `string` | `'currentColor'` | 指示線顏色        |
| `width` | `number` | `1`              | 指示線寬度（px）    |
| `class` | `string` | `undefined`      | 指示線元素之 class |


# Placeholder

編輯器（或節點）為空時顯示的提示文字。

- **config key**：`AioEditorCoreExtension.Placeholder`
- **來源**：`@tiptap/extensions`（`Placeholder`）

:aio-extension-impact{extension="Placeholder"}

## 選項

| 欄位                     | 型別                           | 預設值                   | 說明                  |
| ---------------------- | ---------------------------- | --------------------- | ------------------- |
| `placeholder`          | `string 或 (props) => string` | `'Write something …'` | 提示文字；函式形式可依節點回傳不同提示 |
| `emptyEditorClass`     | `string`                     | `'is-editor-empty'`   | 整份文件為空時加在首節點之 class |
| `emptyNodeClass`       | `string`                     | `'is-empty'`          | 空節點之 class          |
| `showOnlyWhenEditable` | `boolean`                    | `true`                | 僅於可編輯狀態顯示           |
| `showOnlyCurrent`      | `boolean`                    | `true`                | 僅於游標所在節點顯示          |
| `includeChildren`      | `boolean`                    | `false`               | 子節點也套用提示            |

## 覆寫範例

```ts
const config: AioEditorConfig = {
  extensionsConfig: {
    Placeholder: { placeholder: '輸入內容…' }
  }
}
```

提示文字經 CSS `::before` 之 `content: attr(data-placeholder)` 呈現。


# CharacterCount

字數統計與輸入上限，**自製變體**：IME composition（注音 / 拼音組字）期間不套用上限裁切，於 `compositionend` 才截斷超出內容——避免組字過程被攔腰截斷。初始內容超限時自動裁切並於 console 警告。

- **config key**：`AioEditorCoreExtension.CharacterCount`
- **來源**：自製（基於 `@tiptap/extensions` 之 `CharacterCount`）

:aio-extension-impact{extension="CharacterCount"}

## 選項

| 欄位            | 型別                         | 預設值           | 說明                    |
| ------------- | -------------------------- | ------------- | --------------------- |
| `limit`       | `number 或 null`            | `null`        | 字數上限；`null` 或 `0` 不限制 |
| `mode`        | `'textSize' 或 'nodeSize'`  | `'textSize'`  | 計數模式：純文字字數或文件節點大小     |
| `textCounter` | `(text: string) => number` | `text.length` | 自訂字數計算                |
| `wordCounter` | `(text: string) => number` | `以空白切詞`       | 自訂詞數計算                |

## 覆寫範例

```ts
const config: AioEditorConfig = {
  extensionsConfig: {
    CharacterCount: { limit: 500 }
  }
}
```

讀值走 storage：`editor.storage.characterCount.characters()` 與 `editor.storage.characterCount.words()`。


# KeydownHandler

把編輯器內全部 keydown 事件透傳給 consumer 的 hook，**自製 extension**——常用於攔截自訂快捷鍵或整合外部行為。不影響既有快捷鍵。

- **config key**：`AioEditorCoreExtension.KeydownHandler`
- **來源**：自製

:aio-extension-impact{extension="KeydownHandler"}

## 選項

| 欄位             | 型別                               | 預設值        | 說明            |
| -------------- | -------------------------------- | ---------- | ------------- |
| `eventHandler` | `(event: KeyboardEvent) => void` | `() => {}` | 每次 keydown 觸發 |

## 覆寫範例

```ts
const config: AioEditorConfig = {
  extensionsConfig: {
    KeydownHandler: { eventHandler: (event) => console.log(event.key) }
  }
}
```


# AutoJoiner

相鄰的同型清單自動合併為一個——例如 drag handle 把清單項拖到另一個清單旁時。

- **config key**：`AioEditorCoreExtension.AutoJoiner`
- **來源**：`tiptap-extension-auto-joiner`

:aio-extension-impact{extension="AutoJoiner"}

## 選項

| 欄位               | 型別         | 預設值                                         | 說明         |
| ---------------- | ---------- | ------------------------------------------- | ---------- |
| `elementsToJoin` | `string[]` | `['bulletList', 'orderedList', 'taskList']` | 會自動合併之節點型別 |


# CopyData

解析來源 HTML 時保留節點上的 `data-copy` 屬性，**自製 extension**——供貼上內容之來源追溯。

- **config key**：`AioEditorCoreExtension.CopyData`
- **來源**：自製

:aio-extension-impact{extension="CopyData"}

## 選項

| 欄位      | 型別         | 預設值             | 說明        |
| ------- | ---------- | --------------- | --------- |
| `types` | `string[]` | `['paragraph']` | 保留屬性之節點型別 |


# Link

超連結標記（`a` 元素）。游標位於連結內時會出現 [LinkTips bubble](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/bubble-menu)（開啟 / 編輯 / 移除）。

- **config key**：`AioEditorCoreExtension.Link`
- **來源**：`@tiptap/extension-link`

:aio-extension-impact{extension="Link"}

## 選項

| 欄位                | 型別                                         | 預設值                                                                      | 說明                |
| ----------------- | ------------------------------------------ | ------------------------------------------------------------------------ | ----------------- |
| `openOnClick`     | `boolean`                                  | `false`                                                                  | 編輯中點擊連結即開啟        |
| `linkOnPaste`     | `boolean`                                  | `true`                                                                   | 選取文字時貼上 URL 自動成連結 |
| `autolink`        | `boolean`                                  | `true`                                                                   | 輸入 URL 自動轉為連結     |
| `protocols`       | `(string 或 { scheme, optionalSlashes })[]` | `[]`                                                                     | 額外允許之協定           |
| `defaultProtocol` | `string`                                   | `'http'`                                                                 | autolink 之預設協定    |
| `HTMLAttributes`  | `Record<string, any>`                      | `{ target: '_blank', rel: 'noopener noreferrer nofollow', class: null }` | 渲染輸出時附加之 HTML 屬性  |
| `isAllowedUri`    | `(url, ctx) => boolean`                    | `依 protocols 驗證`                                                         | URL 白名單驗證         |
| `validate`        | `(url) => boolean`                         | `非空即通過`                                                                  | autolink 前之驗證     |
| `shouldAutoLink`  | `(url) => boolean`                         | `非空即通過`                                                                  | 已通過驗證後是否自動成連結     |

## Commands

| Command                      | 說明   |
| ---------------------------- | ---- |
| `setLink({ href, target? })` | 套用連結 |
| `toggleLink({ href })`       | 切換連結 |
| `unsetLink()`                | 移除連結 |

## 覆寫範例

```ts
const config: AioEditorConfig = {
  extensionsConfig: {
    Link: { HTMLAttributes: { target: '_self', rel: null } }
  }
}
```


# Image

圖片節點，**自製變體**：node view 帶八向 resize 把手（拖曳後回寫 `width` / `height` 屬性）；貼上 / 拖放圖檔會觸發上傳 hook；貼上 Excel / Word 內容時跳過圖片攔截，交由表格 / 文字流程。圖片被選取時會出現 [Image bubble](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/bubble-menu)。

- **config key**：`AioEditorCoreExtension.Image`
- **來源**：自製（基於 `@tiptap/extension-image`）

:aio-extension-impact{extension="Image"}

## 選項

| 欄位                    | 型別                                            | 預設值             | 說明                                                                     |
| --------------------- | --------------------------------------------- | --------------- | ---------------------------------------------------------------------- |
| `inline`              | `boolean`                                     | `false`         | 行內圖片或區塊圖片                                                              |
| `allowBase64`         | `boolean`                                     | `false`         | 允許 base64 圖片來源                                                         |
| `HTMLAttributes`      | `Record<string, any>`                         | `{}`            | 渲染輸出時附加之 HTML 屬性                                                       |
| `pasteAndDropHandle`  | `(options: PasteAndDropImageOptions) => void` | `console 提示未實作` | 貼上 / 拖放圖檔時觸發：consumer 上傳後呼叫 `options.afterImageUpload(imageInfo)` 插入圖片 |
| `clickHandle`         | `(options: ClickImageOptions) => void`        | `console 提示未實作` | 點擊圖片時觸發（`{ src, alt }`），常用於開燈箱                                         |
| `keepRatioWhenResize` | `boolean`                                     | `false`         | 拖曳把手時鎖定長寬比                                                             |

## Commands

| Command                   | 說明                                                                  |
| ------------------------- | ------------------------------------------------------------------- |
| `setExtendImage(options)` | 插入圖片（`src` 必填，可帶 `alt` / `title` / `width` / `height` / `htmlData`） |

## 覆寫範例

```ts
const config: AioEditorConfig = {
  extensionsConfig: {
    Image: {
      pasteAndDropHandle: async ({ files, afterImageUpload }) => {
        const url = await uploadToServer(files[0]!)
        afterImageUpload({ src: url })
      }
    }
  }
}
```

額外節點屬性：`width` / `height`（resize 回寫）、`htmlData`（`data-*` 屬性透傳，解析與輸出自動轉 kebab-case）。輸入規則：`![alt](src "title")`。


# Video

影片節點（`video` 元素，強制 `controls`），**自製 extension**。貼上 / 拖放影片檔會觸發上傳 hook。

- **config key**：`AioEditorCoreExtension.Video`
- **來源**：自製

:aio-extension-impact{extension="Video"}

## 選項

| 欄位                   | 型別                                            | 預設值             | 說明                                                                    |
| -------------------- | --------------------------------------------- | --------------- | --------------------------------------------------------------------- |
| `HTMLAttributes`     | `Record<string, any>`                         | `{}`            | 渲染輸出時附加之 HTML 屬性                                                      |
| `pasteAndDropHandle` | `(options: PasteAndDropVideoOptions) => void` | `console 提示未實作` | 貼上 / 拖放影片檔時觸發：consumer 上傳後呼叫 `options.afterVideoUpload(options)` 插入影片 |

## Commands

| Command                | 說明                                                |
| ---------------------- | ------------------------------------------------- |
| `setAioVideo(options)` | 插入影片（`src` 必填，可帶 `width` / `height` / `htmlData`） |
| `toggleAioVideo()`     | 影片節點與段落間切換                                        |

command 命名為 `setAioVideo` 而非 `setVideo`：editor-\* 系列已宣告 `Commands['video']` 且形狀不同，同名會產生 TS declaration merge 衝突。


# Strike

刪除線文字標記。

- **config key**：`AioEditorCoreExtension.Strike`
- **來源**：`@tiptap/extension-strike`

:aio-extension-impact{extension="Strike"}

## 選項

| 欄位               | 型別                    | 預設值  | 說明               |
| ---------------- | --------------------- | ---- | ---------------- |
| `HTMLAttributes` | `Record<string, any>` | `{}` | 渲染輸出時附加之 HTML 屬性 |

## Commands

| Command          | 說明    |
| ---------------- | ----- |
| `setStrike()`    | 套用刪除線 |
| `toggleStrike()` | 切換刪除線 |
| `unsetStrike()`  | 移除刪除線 |

## 快捷鍵

| 按鍵            | 行為    |
| ------------- | ----- |
| `Mod-Shift-S` | 切換刪除線 |

輸入規則：`~~文字~~` 自動轉為刪除線。


# TableKit

表格族（table / row / cell / header）一次註冊。**自製變體**：cell / header 帶 grip decoration——hover 表格首欄 / 首列會出現把手，點擊即整列 / 整欄選取，並觸發 [TableRow / TableColumn bubble](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/bubble-menu)。

- **config key**：`AioEditorCoreExtension.TableKit`
- **來源**：自製（基於 `@tiptap/extension-table` 之 `TableKit`）

:aio-extension-impact{extension="TableKit"}

## 選項

| 欄位                              | 型別                                    | 預設值                      | 說明                                     |
| ------------------------------- | ------------------------------------- | ------------------------ | -------------------------------------- |
| `table.resizable`               | `boolean`                             | `true`                   | 欄寬可拖曳調整                                |
| `table.handleWidth`             | `number`                              | `5`                      | 欄寬拖曳把手寬度（px）                           |
| `table.cellMinWidth`            | `number`                              | `25`                     | 儲存格最小寬度（px）                            |
| `table.lastColumnResizable`     | `boolean`                             | `true`                   | 最後一欄可調寬                                |
| `table.allowTableNodeSelection` | `boolean`                             | `true`                   | 允許選取整個表格節點                             |
| `table.HTMLAttributes`          | `Record<string, any>`                 | `{}`                     | 表格之 HTML 屬性（`resizable: true` 時編輯中會失效） |
| `tableRow`                      | `Partial<TableRowOptions> 或 false`    | `{ HTMLAttributes: {} }` | 列設定；`false` 停用                         |
| `tableCell`                     | `Partial<TableCellOptions> 或 false`   | `{ HTMLAttributes: {} }` | 儲存格設定；`false` 停用                       |
| `tableHeader`                   | `Partial<TableHeaderOptions> 或 false` | `{ HTMLAttributes: {} }` | 標題儲存格設定；`false` 停用                     |

## Commands

| Command                                                         | 說明                                                     |
| --------------------------------------------------------------- | ------------------------------------------------------ |
| `insertTable({ rows, cols, withHeaderRow })`                    | 插入表格                                                   |
| `addRowBefore() / addRowAfter() / deleteRow()`                  | 列操作                                                    |
| `addColumnBefore() / addColumnAfter() / deleteColumn()`         | 欄操作                                                    |
| `mergeCells() / splitCell() / mergeOrSplit()`                   | 合併 / 拆分儲存格                                             |
| `toggleHeaderRow() / toggleHeaderColumn() / toggleHeaderCell()` | 標題列 / 欄 / 儲存格切換                                        |
| `setCellAttribute(name, value)`                                 | 設定儲存格屬性（如 `verticalAlign`：'top' / 'middle' / 'bottom'） |
| `deleteTable()`                                                 | 刪除表格                                                   |

cell / header 額外支援 `verticalAlign` 屬性（輸出 `vertical-align` style），Table bubble 之垂直對齊按鈕即操作此屬性。


# Mention

`@` 提及節點與 suggestion 選單。**不在預設集合**——須經 `config.include` 啟用，並提供 `suggestion.onRender` 實作（選單 UI 由 consumer 全權決定，見 [AioEditor 之 Mention demo](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/editor)）。自製變體額外支援 `htmlData` 屬性（`data-*` 透傳）。

- **config key**：`AioEditorCoreExtension.Mention`
- **來源**：自製（基於 `@tiptap/extension-mention`）

:aio-extension-impact{extension="Mention"}

## 選項

| 欄位                           | 型別                                  | 預設值                           | 說明                                   |
| ---------------------------- | ----------------------------------- | ----------------------------- | ------------------------------------ |
| `HTMLAttributes`             | `Record<string, any>`               | `{ class: 'editor-mention' }` | 節點之 HTML 屬性                          |
| `deleteTriggerWithBackspace` | `boolean`                           | `false`                       | Backspace 刪除節點時是否還原觸發字元              |
| `renderText`                 | `(props) => string`                 | `觸發字元＋label`                  | 純文字輸出格式                              |
| `renderHTML`                 | `(props) => DOMOutputSpec`          | `span 包觸發字元＋label`            | HTML 輸出格式                            |
| `suggestion`                 | `Omit<SuggestionOptions, "editor">` | `mentionSuggestion({ … })`    | suggestion 行為（觸發字元、items、選單渲染 hooks） |

## suggestion 選單 hooks

選單以 `mentionSuggestion(hooks)` 建立，定位由 floating-ui 處理，渲染交給 consumer：

```ts
interface MentionSuggestionRuntimeEvent {
  /** 必要：建立選單，回傳選單元素 */
  onRender: (props: unknown, mountEl?: HTMLElement) => HTMLElement | void
  /** 自訂掛載位置（預設掛編輯器容器） */
  onAppend?: (target: HTMLElement, componentEl?: HTMLElement) => void
  /** query 變更時更新選單 */
  onUpdate?: (props: unknown, componentEl?: HTMLElement) => void
  /** 鍵盤導航（回傳 true 表示已處理） */
  onKeyDown?: (props: unknown, componentEl?: HTMLElement) => boolean
  /** 選單關閉清理 */
  onDestroy?: (componentEl?: HTMLElement) => void
}
```

搭配 `suggestion.items: ({ query }) => item[]` 提供候選資料；選單內以 `props.command({ id, label })` 插入節點。


# HashTag

`#` 標籤節點——[Mention](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/mention) 之改名變體（節點名 `hashtag`、觸發字元 `#`），選項與 suggestion hooks 完全相同。**不在預設集合**——須經 `config.include` 啟用。

- **config key**：`AioEditorCoreExtension.HashTag`
- **來源**：自製（基於 Mention）

:aio-extension-impact{extension="HashTag"}

## 選項

| 欄位                           | 型別                                  | 預設值                           | 說明                      |
| ---------------------------- | ----------------------------------- | ----------------------------- | ----------------------- |
| `HTMLAttributes`             | `Record<string, any>`               | `{ class: 'editor-hashtag' }` | 節點之 HTML 屬性             |
| `deleteTriggerWithBackspace` | `boolean`                           | `false`                       | Backspace 刪除節點時是否還原觸發字元 |
| `renderText / renderHTML`    | `同 Mention`                         | `同 Mention`                   | 輸出格式                    |
| `suggestion`                 | `Omit<SuggestionOptions, "editor">` | `hashTagSuggestion({ … })`    | 同 Mention，觸發字元固定 `#`    |


# Bubble Menu

依游標位置浮現的操作選單。&#x2A;*不走 `extensionsConfig`**——由 `config.bubbles` 設定，key 為 `AioEditorBubbleKind`：`false` 停用該情境、物件覆寫預設；掛載預設跟隨 features 宣告，設 `true` 或物件可單獨啟用未宣告 feature 的情境。唯讀（`editable: false`）時一律不顯示。定位以 floating-ui 實作（自製 `BubbleMenuView` 子類，支援 arrow 與表格虛擬定位）。

- **config key**：`config.bubbles` 設定（預設全數啟用）
- **來源**：自製（基於 `@tiptap/extension-bubble-menu`）

## 七種情境

| kind          | 觸發時機          | 內建按鈕                                                               |
| ------------- | ------------- | ------------------------------------------------------------------ |
| `CodeBlock`   | 游標在程式碼區塊內     | 語言切換下拉（自動偵測＋ 10 種語言）、刪除程式碼區塊                                       |
| `Image`       | 圖片被選取         | 更新圖片（走 `toolbarOptions.requestUrl`）、另開分頁開啟、刪除圖片                    |
| `LinkTips`    | 游標在連結內        | 開啟連結、編輯連結、移除連結                                                     |
| `List`        | 游標在清單項內       | 刪除清單項                                                              |
| `Table`       | 游標在表格內        | 合併 / 拆分（僅可合併時顯示，合併中高亮）、標題儲存格（active 高亮）、垂直對齊（上 / 中 / 下，當前值高亮）、刪除表格 |
| `TableRow`    | 點擊列 grip 整列選取 | 上 / 下插入列、刪除列                                                       |
| `TableColumn` | 點擊欄 grip 整欄選取 | 左 / 右插入欄、刪除欄                                                       |

## 共同選項（BubbleMenuConfigType）

| 欄位                                                                                 | 型別                              | 預設值          | 說明                                          |
| ---------------------------------------------------------------------------------- | ------------------------------- | ------------ | ------------------------------------------- |
| `pluginKey`                                                                        | `string`                        | 各情境固定值       | plugin 識別，覆寫時勿與其他 bubble 重複                 |
| `updateDelay`                                                                      | `number`                        | `250`        | 更新節流（ms）                                    |
| `resizeDelay`                                                                      | `number`                        | `60`         | resize 節流（ms）                               |
| `shouldShow`                                                                       | `(props) => boolean`            | 各情境內建        | 顯示條件（如 `editor.isActive('table')`）          |
| `targetElement`                                                                    | `(props) => HTMLElement 或 null` | 各情境內建        | 定位錨點；未提供時以選取範圍定位                            |
| `isTableGrid`                                                                      | `boolean`                       | `false`      | 表格列 / 欄選取之虛擬定位（CellSelection 之範圍矩形）         |
| `options.placement`                                                                | `Placement`                     | 各情境內建        | floating-ui 位置（`top-end`、`right`、`bottom`…） |
| `options.strategy`                                                                 | `'absolute' 或 'fixed'`          | `'absolute'` | 定位策略                                        |
| `options.offset` / `flip` / `shift` / `size` / `autoPlacement` / `hide` / `inline` | `boolean 或 middleware 參數`       | 各情境內建        | floating-ui middleware：`false` 停用、物件傳參數     |
| `options.arrow`                                                                    | `(() => HTMLElement) 或 false`   | `false`      | 箭頭元素                                        |
| `options.onShow` / `onHide` / `onUpdate` / `onDestroy`                             | `() => void`                    | —            | 生命週期 hooks                                  |

## 覆寫範例

```ts
const config: AioEditorConfig = {
  bubbles: {
    List: false, // 停用清單 bubble
    Table: {
      options: { placement: 'top-end' }
    }
  }
}
```

`element` 欄位由 UI 層注入（Teleport 掛載），consumer 不需設定。


# Drag Handle

hover 區塊時浮現的拖曳把手，可拖動整個區塊重排。&#x2A;*不走 `extensionsConfig`**——由 `config.dragHandle` 設定：`false` 停用、物件覆寫預設。拖曳清單項離開清單時會自動包回對應的 `ul` / `ol`（配合 [AutoJoiner](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/auto-joiner) 合併相鄰清單）。

- **config key**：`config.dragHandle` 設定（預設啟用）
- **來源**：自製

## 選項（DragHandleConfigType）

| 欄位                  | 型別                                                                                                  | 預設值            | 說明                                 |
| ------------------- | --------------------------------------------------------------------------------------------------- | -------------- | ---------------------------------- |
| `scrollThreshold`   | `number`                                                                                            | `100`          | 拖曳至視窗上下邊緣多少 px 內自動捲動               |
| `excludedTags`      | `string[]`                                                                                          | `[]`           | 不顯示把手之 HTML 標籤                     |
| `isChildNode`       | `(nodeName: string) => boolean`                                                                     | `undefined`    | 自訂「視為子節點」判定（子節點拖曳時以父層為單位）          |
| `updateDelay`       | `number`                                                                                            | `250`          | 更新節流（ms）                           |
| `resizeDelay`       | `number`                                                                                            | `60`           | resize 節流（ms）                      |
| `options.placement` | `Placement`                                                                                         | `'left-start'` | 把手相對區塊之位置                          |
| `options.offset`    | `number`                                                                                            | `13`           | 與區塊之間距                             |
| 其餘 `options.*`      | 同 [Bubble Menu](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/bubble-menu) | —              | floating-ui middleware 與生命週期 hooks |

## 覆寫範例

```ts
const config: AioEditorConfig = {
  dragHandle: {
    scrollThreshold: 60,
    excludedTags: ['hr']
  }
}
```

`element` 欄位由 UI 層注入（Teleport 掛載），consumer 不需設定。


# Underline

底線文字標記。

- **config key**：`AioEditorCoreExtension.Underline`
- **來源**：`@tiptap/extension-underline`

:aio-extension-impact{extension="Underline"}

## 選項

| 欄位               | 型別                    | 預設值  | 說明               |
| ---------------- | --------------------- | ---- | ---------------- |
| `HTMLAttributes` | `Record<string, any>` | `{}` | 渲染輸出時附加之 HTML 屬性 |

## Commands

| Command             | 說明   |
| ------------------- | ---- |
| `setUnderline()`    | 套用底線 |
| `toggleUnderline()` | 切換底線 |
| `unsetUnderline()`  | 移除底線 |

## 快捷鍵

| 按鍵      | 行為   |
| ------- | ---- |
| `Mod-U` | 切換底線 |


# Code

行內程式碼標記（`code` 元素）。區塊層級的程式碼見 [CodeBlock](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/code-block)。

- **config key**：`AioEditorCoreExtension.Code`
- **來源**：`@tiptap/extension-code`

:aio-extension-impact{extension="Code"}

## 選項

| 欄位               | 型別                    | 預設值  | 說明               |
| ---------------- | --------------------- | ---- | ---------------- |
| `HTMLAttributes` | `Record<string, any>` | `{}` | 渲染輸出時附加之 HTML 屬性 |

## Commands

| Command        | 說明      |
| -------------- | ------- |
| `setCode()`    | 套用行內程式碼 |
| `toggleCode()` | 切換行內程式碼 |
| `unsetCode()`  | 移除行內程式碼 |

## 快捷鍵

| 按鍵      | 行為      |
| ------- | ------- |
| `Mod-E` | 切換行內程式碼 |

輸入規則：`` `文字` `` 自動轉為行內程式碼。


# TextStyle

以 `span` 承載行內樣式屬性的基底 mark——[Color](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/color)、[FontFamily](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/font-family)、[FontSize](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/font-size) 都把樣式掛在此 mark 上，**停用它會連帶使三者失效**。

- **config key**：`AioEditorCoreExtension.TextStyle`
- **來源**：`@tiptap/extension-text-style`

:aio-extension-impact{extension="TextStyle"}

## 選項

| 欄位                      | 型別                    | 預設值     | 說明                      |
| ----------------------- | --------------------- | ------- | ----------------------- |
| `HTMLAttributes`        | `Record<string, any>` | `{}`    | 渲染輸出時附加之 HTML 屬性        |
| `mergeNestedSpanStyles` | `boolean`             | `false` | 解析巢狀 span 時是否把外層樣式合併進內層 |

## Commands

| Command                  | 說明                          |
| ------------------------ | --------------------------- |
| `removeEmptyTextStyle()` | 移除不帶任何樣式屬性的空 textStyle mark |


# Color

文字顏色，樣式掛於 [TextStyle](https://component-registry-4d4d86.gitlab.io/docs/aio-editor/extensions/text-style) mark。toolbar 之 `TextColor` 按鈕即操作此 extension。

- **config key**：`AioEditorCoreExtension.Color`
- **來源**：`@tiptap/extension-text-style`（`Color`）

:aio-extension-impact{extension="Color"}

## 選項

| 欄位      | 型別         | 預設值             | 說明              |
| ------- | ---------- | --------------- | --------------- |
| `types` | `string[]` | `['textStyle']` | 樣式套用之目標 mark 型別 |

## Commands

| Command           | 說明             |
| ----------------- | -------------- |
| `setColor(color)` | 設定文字顏色（CSS 色值） |
| `unsetColor()`    | 移除文字顏色         |

## 覆寫範例

```ts
const config: AioEditorConfig = {
  extensionsConfig: {
    Color: { types: ['textStyle'] }
  }
}
```


# Highlight

文字底色標記（`mark` 元素）。

- **config key**：`AioEditorCoreExtension.Highlight`
- **來源**：`@tiptap/extension-highlight`

:aio-extension-impact{extension="Highlight"}

## 選項

| 欄位               | 型別                    | 預設值    | 說明                                       |
| ---------------- | --------------------- | ------ | ---------------------------------------- |
| `multicolor`     | `boolean`             | `true` | 允許以 `data-color` 指定多種底色；`false` 時僅單一預設底色 |
| `HTMLAttributes` | `Record<string, any>` | `{}`   | 渲染輸出時附加之 HTML 屬性                         |

## Commands

| Command                       | 說明                       |
| ----------------------------- | ------------------------ |
| `setHighlight({ color? })`    | 套用螢光標記（multicolor 時可帶色值） |
| `toggleHighlight({ color? })` | 切換螢光標記                   |
| `unsetHighlight()`            | 移除螢光標記                   |

## 快捷鍵

| 按鍵            | 行為     |
| ------------- | ------ |
| `Mod-Shift-H` | 切換螢光標記 |

輸入規則：`==文字==` 自動轉為螢光標記。


# 編輯器總覽

預設用 `@admin/rich-editor`；要更多功能再裝下方擴充包。客製見[自訂指南](https://component-registry-4d4d86.gitlab.io/docs/editor/customization)。

## 核心

| 文件                                                                                      | 用途                   |
| --------------------------------------------------------------------------------------- | -------------------- |
| [Editor](https://component-registry-4d4d86.gitlab.io/docs/editor/core/editor)           | 空白核心，自行加 extension   |
| [Rich Editor](https://component-registry-4d4d86.gitlab.io/docs/editor/core/rich-editor) | 內建 StarterKit 的文字編輯器 |
| [Editor Toolbar](https://component-registry-4d4d86.gitlab.io/docs/editor/core/toolbar)  | 工具列                  |

## 擴充功能

| 包                                                                                                               | 用途                   |
| --------------------------------------------------------------------------------------------------------------- | -------------------- |
| [Image](https://component-registry-4d4d86.gitlab.io/docs/editor/addons/image)                                   | 圖片顯示 / 插入            |
| [Markdown](https://component-registry-4d4d86.gitlab.io/docs/editor/addons/markdown)                             | Markdown 內容格式        |
| [Text Color](https://component-registry-4d4d86.gitlab.io/docs/editor/addons/text-color)                         | 文字顏色                 |
| [Highlight](https://component-registry-4d4d86.gitlab.io/docs/editor/addons/highlight)                           | 文字底色                 |
| [Text Align](https://component-registry-4d4d86.gitlab.io/docs/editor/addons/text-align)                         | 左中右對齊                |
| [Placeholder](https://component-registry-4d4d86.gitlab.io/docs/editor/addons/placeholder)                       | 空編輯器提示文字             |
| [Task List](https://component-registry-4d4d86.gitlab.io/docs/editor/addons/task-list)                           | 任務清單 checkbox        |
| [Indent](https://component-registry-4d4d86.gitlab.io/docs/editor/addons/indent)                                 | 段落縮排                 |
| [Mention](https://component-registry-4d4d86.gitlab.io/docs/editor/addons/mention)                               | `@` 提及選單             |
| [Emoji](https://component-registry-4d4d86.gitlab.io/docs/editor/addons/emoji)                                   | `:` 表情選單             |
| [Suggestion](https://component-registry-4d4d86.gitlab.io/docs/editor/addons/suggestion)                         | `/` slash command 選單 |
| [Link Bubble](https://component-registry-4d4d86.gitlab.io/docs/editor/addons/link-bubble)                       | 連結浮層（檢視 / 編輯 / 移除）   |
| [List Trash](https://component-registry-4d4d86.gitlab.io/docs/editor/addons/list-trash)                         | 清單項刪除鈕               |
| [Drag Handle](https://component-registry-4d4d86.gitlab.io/docs/editor/addons/drag-handle)                       | 區塊拖曳把手               |
| [Table](https://component-registry-4d4d86.gitlab.io/docs/editor/addons/table)                                   | 表格                   |
| [Superscript / Subscript](https://component-registry-4d4d86.gitlab.io/docs/editor/addons/superscript-subscript) | 上標 / 下標              |
| [Video](https://component-registry-4d4d86.gitlab.io/docs/editor/addons/video)                                   | 影片                   |
| [YouTube](https://component-registry-4d4d86.gitlab.io/docs/editor/addons/youtube)                               | YouTube 嵌入           |
| [Font Size](https://component-registry-4d4d86.gitlab.io/docs/editor/addons/font-size)                           | 字級                   |


# 自訂指南

## 自訂 extension

### 加 extension

用 `:extensions` 傳入任何 tiptap extension。要注意 editor 的 schema 在建立當下就固定了、之後沒辦法再加，所以 node / mark 這類 extension 一定要一開始就放進去：

```vue
<script setup lang="ts">
import CharacterCount from '@tiptap/extension-character-count'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor } from '@/registry/admin/ui/rich-editor'
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers }"
    v-model="value"
    :extensions="[CharacterCount.configure({ limit: 500 })]"
  >
    <admin-editor-toolbar :editor :handlers="handlers" :items="defaultEditorItems" />
  </admin-rich-editor>
</template>
```

### 擴充套件

`admin-rich-editor` 預設只帶 StarterKit，Image、TextAlign、Placeholder 這些要另外裝。自行安裝對應的官方 `@tiptap/extension-*` 套件，`.configure({})` 設定好再傳進 `:extensions`：

```vue
<script setup lang="ts">
import { Image } from '@tiptap/extension-image'
import TextAlign from '@tiptap/extension-text-align'
</script>

<template>
  <admin-rich-editor
    :extensions="[TextAlign.configure({ types: ['heading', 'paragraph'] }), Image.configure({})]"
  />
</template>
```

### StarterKit

#### 配置內建行為

```vue
<admin-rich-editor :starter-kit="{ heading: { levels: [1, 2] }, codeBlock: false }" />
```

#### 替換內建 extension

StarterKit 內建了 Link 等 extension。想換成自己的版本，得先用 `:starter-kit` 把內建的那個關掉，再從 `:extensions` 傳入，否則兩個同名 extension 會同時生效。完整可替換清單與限制見 [tiptap StarterKit 官方文件](https://tiptap.dev/docs/editor/extensions/functionality/starterkit#using-the-starterkit-extension){rel="&#x22;nofollow&#x22;"}。

```vue
<admin-rich-editor :starter-kit="{ link: false }" :extensions="[MyLink]" />
```

## 工具列

`AdminEditorToolbar` 靠 `items` 這個陣列決定要畫哪些按鈕，型別是 `EditorToolbarItem[][]`，外層陣列用來分組。每個 item 可以是：

- `{ kind: '...' }`：走內建或 `:handlers` 註冊的 handler
- `{ items: [...] }`：dropdown（巢狀）
- `{ type: 'label' | 'separator' }`：純標示
- `{ onClick }`：無 kind 的純自訂按鈕
- `{ slot: 'name' }`：改由具名 slot 渲染

### 有狀態的按鈕（用 `:handlers`）

如果按鈕的反白（active）、禁用（disabled）要跟著編輯狀態即時變化（按下會 toggle、游標移到粗體文字上時按鈕要亮起來），就得用 `:handlers` 註冊一個 kind。handler 裡給 `canExecute`、`execute`、`isActive` 三個 function，toolbar 會拿它們自動算出當下要不要反白、要不要禁用：

```vue
<script setup lang="ts">
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'

const handlers = {
  highlightLine: {
    canExecute: (editor) => editor.can().toggleNode?.('paragraph', 'paragraph') ?? true,
    execute: (editor) => editor.chain().focus().toggleMark('bold'),
    isActive: (editor) => editor.isActive('bold'),
  },
}
// satisfies 掛在自訂這組，自訂 kind 才有型別檢查：
// 打錯或用了沒註冊的 kind 會在編譯期就報錯
const items = [
  ...defaultEditorItems,
  [{ kind: 'highlightLine', label: '強調', tooltip: { text: '強調' } }] satisfies EditorToolbarItem<
    typeof handlers
  >[],
]
</script>

<template>
  <admin-rich-editor v-slot="{ editor, handlers: mergedHandlers }" v-model="value" :handlers="handlers">
    <admin-editor-toolbar :editor :handlers="mergedHandlers" :items="items" />
  </admin-rich-editor>
</template>
```

toolbar 收的是外層 v-slot 吐出的 `mergedHandlers`（你的自訂 kind + StarterKit 內建 kind 已合併），這樣預設按鈕和自訂按鈕才會同時有 handler 可用。

### 無狀態的按鈕（用 `onClick`）

純觸發、不需要 active 同步的按鈕（插入內容、開外部視窗…）直接用 `onClick`，免註冊 kind。`onClick` 只收得到 `MouseEvent`、拿不到 editor，要操作 editor 就從 rich-editor 的 exposed ref 取：

```vue
<script setup lang="ts">
import { IconSeparator } from '@tabler/icons-vue'
import { useTemplateRef } from 'vue'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor } from '@/registry/admin/ui/rich-editor'

const richEditor = useTemplateRef<InstanceType<typeof AdminRichEditor>>('richEditor')
const items = [
  ...defaultEditorItems,
  [{
    label: '插入分隔',
    icon: IconSeparator,
    onClick: () => richEditor.value?.editor?.commands.setHorizontalRule(),
  }],
]
</script>

<template>
  <admin-rich-editor ref="richEditor" v-slot="{ editor, handlers }" v-model="value">
    <admin-editor-toolbar :editor :handlers="handlers" :items="items" />
  </admin-rich-editor>
</template>
```

::alert{title="handler vs onClick 怎麼選" type="info"}
- 要按鈕**反白 / disabled 跟著編輯狀態變** → `:handlers` 註冊 kind（`onClick` **沒有**狀態同步）。
- 只是按一下做件事、長相固定 → `onClick` 即可。
- item 同時有 `kind` 與 `onClick` 時，**kind 優先、onClick 忽略**。
::

### 完全自訂渲染（用 slot）

toolbar 開了兩種 slot，不用改 toolbar 內部即可塞 button / dropdown / 元件：

- 通用 `#item`：攔下每一顆 item，全部自己畫
- 具名 slot：在 item 上寫 `slot: 'xxx'`，對應的 `<template #xxx>` 就會用你的元件取代那顆標準按鈕

兩種 slot 拿到的 props 都是 `{ item, index, isActive, isDisabled, onClick }`（對齊 Nuxt UI）。這裡的 `item` 是原始資料，狀態要自己用 `isActive(item)`、`isDisabled(item)` 算，點擊呼叫 `onClick(e, item)`。props 裡沒有 `editor`，需要時從外層 `<AdminRichEditor v-slot="{ editor }">` 拿。

```vue
<template>
  <admin-rich-editor v-slot="{ editor, handlers }" v-model="value">
    <admin-editor-toolbar :editor :handlers="handlers" :items="items">
      <!-- slot props 無 editor；從外層 v-slot 的 editor 取 -->
      <template #myPicker>
        <my-custom-button :editor="editor" />
      </template>
    </admin-editor-toolbar>
  </admin-rich-editor>
</template>
```

::alert{title="slot 內容取不到 provide 的 context" type="warning"}
slot 內容定義在 consumer 作用域，**取不到** `<AdminRichEditor>` provide 的 context。需要 editor 時用外層 `<AdminRichEditor v-slot="{ editor }">` 的 `editor`，不要靠 inject。
::

## 範例：接一排對齊按鈕

文字對齊要三步：裝上官方 `TextAlign` extension、用 `:handlers` 註冊左/中/右三個 kind、再把對應按鈕加進 toolbar。按鈕的反白由 handler 的 `isActive` 自動同步：

```vue
<script setup lang="ts">
import type { Editor, JSONContent } from '@tiptap/core'
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'
import { IconAlignCenter, IconAlignLeft, IconAlignRight } from '@tabler/icons-vue'
import TextAlign from '@tiptap/extension-text-align'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>(
  '<h2 style="text-align: center">置中標題</h2><p style="text-align: right">這段靠右對齊。</p><p>這段預設靠左。</p>'
)

// 1. 裝上官方 TextAlign extension
const extensions = [TextAlign.configure({ types: ['heading', 'paragraph'] })]

// 2. 每個對齊方向註冊一個 kind:handler 提供 canExecute / execute / isActive
function alignHandler(align: 'left' | 'center' | 'right') {
  return {
    canExecute: (editor: Editor) => editor.can().setTextAlign(align),
    execute: (editor: Editor) => editor.chain().focus().setTextAlign(align),
    isActive: (editor: Editor) => editor.isActive({ textAlign: align })
  }
}
const handlers = {
  alignLeft: alignHandler('left'),
  alignCenter: alignHandler('center'),
  alignRight: alignHandler('right')
}

// 3. 用 kind 掛上按鈕，toolbar 會據 handler 自動算 active / disabled
// satisfies 掛在自訂這組：打錯或用了沒註冊的 kind 會在編譯期就報錯
const items = [
  ...defaultEditorItems,
  [
    { kind: 'alignLeft', icon: IconAlignLeft, tooltip: { text: '靠左' } },
    { kind: 'alignCenter', icon: IconAlignCenter, tooltip: { text: '置中' } },
    { kind: 'alignRight', icon: IconAlignRight, tooltip: { text: '靠右' } }
  ] satisfies EditorToolbarItem<typeof handlers>[]
]
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers: mergedHandlers }"
    v-model="value"
    :extensions="extensions"
    :handlers="handlers"
    :ui="{ base: cn(baseProseClass, starterKitProseClass) }"
  >
    <admin-editor-toolbar :editor :handlers="mergedHandlers" :items="items" />
  </admin-rich-editor>
</template>
```

不想自己接的話，文字顏色、螢光筆、對齊這類功能本系統都有封裝好的擴充元件可直接用，見 [Text Color](https://component-registry-4d4d86.gitlab.io/docs/editor/addons/text-color)、[Highlight](https://component-registry-4d4d86.gitlab.io/docs/editor/addons/highlight)、[Text Align](https://component-registry-4d4d86.gitlab.io/docs/editor/addons/text-align)。


# Editor

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/editor
```

```ts
import { AdminEditor } from '@/registry/admin/ui/editor'
```

## 用法

傳入最小 ProseMirror schema（Document / Paragraph / Text）就是一個純文字輸入框，連粗體都沒有：

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import { Document } from '@tiptap/extension-document'
import { Paragraph } from '@tiptap/extension-paragraph'
import { Text } from '@tiptap/extension-text'
import { ref } from 'vue'
import { AdminEditor } from '@/registry/admin/ui/editor'

const value = ref<JSONContent | string>(
  '<p>只有 Document / Paragraph / Text，無任何格式 extension。</p>'
)
</script>

<template>
  <admin-editor v-model="value" :extensions="[Document, Paragraph, Text]" />
</template>
```

## 搭配 StarterKit

要粗體、標題、清單這些基本格式，把 StarterKit 傳進來：

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { AdminEditor, baseProseClass } from '@/registry/admin/ui/editor'
import { starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>(
  '<p>輕量 editor：無 toolbar，無附加 extension，StarterKit 由呼叫方提供。</p>'
)
</script>

<template>
  <admin-editor
    v-model="value"
    :extensions="[StarterKit]"
    :ui="{ base: cn(baseProseClass, starterKitProseClass) }"
  />
</template>
```

## 自訂 toolbar（slot）

透過 default slot 取得 `editor` instance，渲染自訂 toolbar：

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { AdminEditor, baseProseClass } from '@/registry/admin/ui/editor'
import { starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>('<p>透過 slot 取得 editor instance，掛上自訂 toolbar。</p>')
</script>

<template>
  <admin-editor
    v-model="value"
    :extensions="[StarterKit]"
    :ui="{ base: cn(baseProseClass, starterKitProseClass) }"
  >
    <template #default="{ editor }">
      <div class="flex gap-1 border-b border-text-30 px-2 py-1">
        <button
          class="rounded-sm px-2 py-0.5 text-sm"
          type="button"
          :class="
            editor.isActive('bold')
              ? 'bg-primary-10 font-semibold text-primary-60'
              : `
                text-text-70
                hover:bg-bg-80
              `
          "
          @click="editor.chain().focus().toggleBold().run()"
        >
          B
        </button>
        <button
          class="rounded-sm px-2 py-0.5 text-sm italic"
          type="button"
          :class="
            editor.isActive('italic')
              ? 'bg-primary-10 font-semibold text-primary-60'
              : `
                text-text-70
                hover:bg-bg-80
              `
          "
          @click="editor.chain().focus().toggleItalic().run()"
        >
          I
        </button>
      </div>
    </template>
  </admin-editor>
</template>
```

## API 參考

### admin-editor

::div{data-admin-api-table=""}
#### Props

| 名稱            | 型別                                 | 預設值     | 說明 |
| ------------- | ---------------------------------- | ------- | -- |
| `modelValue`  | `string | JSONContent | undefined` | —       | —  |
| `contentType` | `EditorContentType | undefined`    | —       | —  |
| `editable`    | `boolean | undefined`              | `true`  | —  |
| `extensions`  | `AnyExtension[] | undefined`       | —       | —  |
| `editorProps` | `EditorProps<any> | undefined`     | —       | —  |
| `autofocus`   | `FocusPosition | undefined`        | —       | —  |
| `ariaLabel`   | `string | undefined`               | —       | —  |
| `class`       | `ClassValue`                       | —       | —  |
| `ui`          | `AdminEditorUI | undefined`        | —       | —  |
| `as`          | `string | undefined`               | `"div"` | —  |

#### Events

| 名稱                  | Payload                | 說明 |
| ------------------- | ---------------------- | -- |
| `update:modelValue` | `string | JSONContent` | —  |

#### Slots

| 名稱        | Bindings              | 說明 |
| --------- | --------------------- | -- |
| `default` | `{ editor: Editor; }` | —  |

#### Expose

| 名稱       | 簽名                   | 說明 |
| -------- | -------------------- | -- |
| `editor` | `Editor | undefined` | —  |
::

## 更新紀錄

:admin-changelog{component="AdminEditor"}


# Rich Editor

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/rich-editor
```

```ts
import { AdminRichEditor } from '@/registry/admin/ui/rich-editor'
```

## 用法

掛上 `v-model` 即可編輯。StarterKit 快捷鍵與輸入規則：`Ctrl+B` 粗體、行首 `#` 加空格變標題、`-` 加空格變清單：

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>(
  '<h2>歡迎使用 admin-rich-editor</h2><p>沒有 toolbar 也能編輯:選取文字按 <strong>Ctrl+B</strong> 加粗,行首打 <code>#</code> 加空格變標題,打 <code>-</code> 加空格變清單。</p><ul><li>項目一</li><li>項目二</li></ul>'
)
</script>

<template>
  <admin-rich-editor v-model="value" :ui="{ base: cn(baseProseClass, starterKitProseClass) }" />
</template>
```

> 要按鈕式的工具列，裝 opt-in 的 [`@admin/editor-toolbar`](https://component-registry-4d4d86.gitlab.io/docs/editor/core/toolbar)，下一章介紹。

## 內容樣式

`<AdminRichEditor>` / `<AdminEditor>` 本身不套用任何內容外觀。要讓標題、清單這些內容長出樣子，把樣式常數用 `cn(...)` 組好、經 `:ui="{ base: ... }"` 注入內容節點：

- `baseProseClass`（`@/registry/admin/ui/editor`）— block 間距、段落行高
- `starterKitProseClass`（`@/registry/admin/ui/rich-editor`）— 標題 / 清單 / 程式碼 / 引言 / hr / link

```vue
<script setup lang="ts">
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'
</script>

<template>
  <admin-rich-editor v-model="value" :ui="{ base: cn(baseProseClass, starterKitProseClass) }" />
</template>
```

擴充包各自帶自己的樣式常數（如 `editorTableClass`），裝了就一起放進 `cn`，細節見各包文件。

### 前台唯讀 viewer

後台存的 HTML 要在前台展示時，不需要再掛一顆 editor。樣式常數就是一般的 package export，前台 import 同一份、套在 `v-html` 容器上，兩邊外觀就一致，之後改樣式也只改一處。

前台容器的直接子元素就是 `p` / `h1` 這些內容節點，和後台 `:ui.base` 注入的是同一層，直接用 `:class` 套即可。`v-html` 輸出前記得先過一層 sanitizer（例如 [DOMPurify](https://github.com/cure53/DOMPurify){rel="&#x22;nofollow&#x22;"}），內容出自多人後台或舊資料匯入時尤其重要：

```vue
<script setup lang="ts">
import DOMPurify from 'dompurify'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const html = ref('') // 後台存下的 HTML
const safeHtml = computed(() => DOMPurify.sanitize(html.value))
</script>

<template>
  <div :class="cn(baseProseClass, starterKitProseClass)" v-html="safeHtml"></div>
</template>
```

內容若存的是 JSON（ProseMirror doc）而不是 HTML，先用 tiptap 的 `generateHTML(json, extensions)` 轉成 HTML，再照上面套樣式。

## 場景

### 客製 starterKit（精簡版）

透過 `:starter-kit="{ heading: false, codeBlock: false, ... }"` 關閉 sub-extension，自寫 `items` 收緊功能。適合留言情境：

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { AdminEditorToolbar } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>(
  '<p>只啟用 <strong>bold</strong> / <em>italic</em> / link 的精簡版,適合留言情境。</p>'
)

// 客製 items：只保留留言情境會用到的功能
const leanItems: EditorToolbarItem[][] = [
  [
    { kind: 'mark', mark: 'bold', tooltip: { text: '粗體' } },
    { kind: 'mark', mark: 'italic', tooltip: { text: '斜體' } }
  ],
  [{ kind: 'link', tooltip: { text: '連結' } }]
]
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers }"
    v-model="value"
    :starter-kit="{
      heading: false,
      codeBlock: false,
      blockquote: false,
      horizontalRule: false
    }"
    :ui="{ base: cn(baseProseClass, starterKitProseClass) }"
  >
    <admin-editor-toolbar :editor :handlers="handlers" :items="leanItems" />
  </admin-rich-editor>
</template>
```

### 唯讀 / 預覽模式

`:editable="false"` 切到唯讀：

- 無編輯游標、無 focus ring、`cursor: default`
- 文字仍可選取（允許 Ctrl+C 複製）
- `<AdminEditorToolbar>` 可以選擇不渲染（純展示）

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

// 模擬 DB 來的 HTML 內容
const value = ref<JSONContent | string>(
  `
<h2>純展示模式(editable=false)</h2>
<p>這份內容是<strong>唯讀</strong>展示,沒有編輯游標、沒有 focus ring,但<em>文字可以選取</em>用來複製。</p>
<ul>
  <li>適用情境:列表預覽、文章詳情頁、hover 預覽。</li>
  <li>因為 toolbar 不渲染,UI 完全乾淨。</li>
</ul>
<blockquote>
  唯讀模式只渲染 StarterKit 內建節點;若 DB 內容含 <code>&lt;img&gt;</code>,需另行注入官方 Image extension。
</blockquote>
`.trim()
)
</script>

<template>
  <admin-rich-editor
    v-model="value"
    :editable="false"
    :ui="{ base: cn(baseProseClass, starterKitProseClass) }"
  />
</template>
```

### 表單整合（vee-validate）

`<AdminRichEditor>` 的 `v-model` 可直接接 vee-validate 的 `useField` value。用 `useField('content', rules)` 取得 `value` / `errorMessage`，把 `value` 綁到 editor、`errorMessage` 顯示錯誤即可：

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import { useField, useForm } from 'vee-validate'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const { handleSubmit, resetForm } = useForm<{ content: string | JSONContent }>({
  initialValues: { content: '' }
})

function validateContent(value: unknown) {
  if (typeof value !== 'string' || value.length === 0) {
    return '請輸入內容'
  }
  // 去掉 HTML tags 之後實際內容長度
  const text = value.replace(/<[^>]+>/g, '').trim()
  if (text.length < 10) {
    return '內容至少 10 字'
  }
  return true
}

const { value: content, errorMessage } = useField<string | JSONContent>('content', validateContent)

const onSubmit = handleSubmit((values) => {
  // eslint-disable-next-line no-console
  console.log('submit:', values)
  resetForm()
})
</script>

<template>
  <form class="flex flex-col gap-3" @submit="onSubmit">
    <div class="flex flex-col gap-1">
      <label class="text-sm font-medium text-text-80" for="editor-form-content">文章內容</label>
      <admin-rich-editor
        v-model="content"
        :class="errorMessage ? 'border-error-50' : ''"
        :ui="{ base: cn(baseProseClass, starterKitProseClass) }"
      >
        <template #default="{ editor, handlers }">
          <admin-editor-toolbar :editor :handlers="handlers" :items="defaultEditorItems" />
        </template>
      </admin-rich-editor>
      <span v-if="errorMessage" class="text-sm text-error-50">{{ errorMessage }}</span>
    </div>
    <div>
      <button
        type="submit"
        :class="cn('rounded-[8px] bg-primary-50 px-4 py-2 text-text-10', 'hover:bg-primary-60')"
      >
        送出
      </button>
    </div>
  </form>
</template>
```

要在 error 狀態顯示錯誤邊框，自行透過 `:class="{ 'border-error-50': errorMessage }"` 處理。

## 進階使用

### 加自訂 extension

```vue
<script setup lang="ts">
import { Underline } from '@tiptap/extension-underline'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor } from '@/registry/admin/ui/rich-editor'

const value = ref('<p>支援 underline 的內容</p>')
const items = [
  ...defaultEditorItems,
  [{ kind: 'mark', mark: 'underline', tooltip: { text: '底線' } }],
]
</script>

<template>
  <admin-rich-editor v-slot="{ editor }" v-model="value" :extensions="[Underline]">
    <admin-editor-toolbar :editor :items />
  </admin-rich-editor>
</template>
```

### 加自訂 kind handler

透過 `handlers` prop 新增任意 kind，toolbar items 直接寫 `{ kind: 'myCustom' }`：

```vue
<script setup lang="ts">
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor } from '@/registry/admin/ui/rich-editor'

const handlers = {
  insertVariable: {
    canExecute: () => true,
    execute: (editor: any, cmd: any) => editor.chain().focus().insertContent(`{{ ${cmd.name} }}`),
    isActive: () => false,
  },
}

const items = [
  ...defaultEditorItems,
  [
    { kind: 'insertVariable', name: 'username', label: '使用者名稱' },
    { kind: 'insertVariable', name: 'orderId', label: '訂單編號' },
  ],
]
</script>

<template>
  <admin-rich-editor v-slot="{ editor }" v-model="value" :handlers>
    <admin-editor-toolbar :editor :items />
  </admin-rich-editor>
</template>
```

## Type-safe 封裝

`AdminRichEditor` 的 `modelValue` 為 `string | JSONContent`，不會依 `contentType` 在 compile-time 與 `v-model` 型別對齊。這與 tiptap 的 `Content` 型別一致：序列化格式在執行期才決定，型別層維持寬 union。

開啟 `strictVModel` 或 `strictTemplates` 時，若以更嚴的型別（例如 `ref<JSONContent>`）綁定，容易出現型別錯誤。這屬刻意設計，而非元件缺漏——收窄會讓以 `ref<string>` 綁 HTML／markdown 的常見用法直接 type error。

若需要讓 `contentType` 與 `v-model` 型別對齊，可自行封裝：以 `contentType` 為 discriminant，`'json'` 對應 `JSONContent`、其餘對應 `string`。

範例：

```vue
<script setup lang="ts" generic="TContentType extends EditorContentType = 'html'">
import type { JSONContent } from '@tiptap/core'
import type { EditorContentType } from '@/registry/admin/ui/editor-core/composables/types'
import type {
  AdminRichEditorProps,
  AdminRichEditorSlots
} from '@/registry/admin/ui/rich-editor/types'
import { reactiveOmit } from '@vueuse/core'
import { useForwardPropsEmits } from 'reka-ui'
import { AdminRichEditor } from '@/registry/admin/ui/rich-editor'

// contentType 收斂 v-model 型別：json 存 ProseMirror doc，其餘存字串
type TModelValue = [TContentType] extends ['json'] ? JSONContent : string

defineOptions({
  name: 'typed-admin-rich-editor'
})

const props = defineProps<
  Omit<AdminRichEditorProps, 'modelValue' | 'contentType'> & {
    contentType?: TContentType
    modelValue?: TModelValue
  }
>()

const emits = defineEmits<{
  'update:modelValue': [value: TModelValue]
}>()

const slots = defineSlots<AdminRichEditorSlots>()

const delegatedProps = reactiveOmit(props, 'modelValue')

const forwardedAll = useForwardPropsEmits(delegatedProps, emits)

const forwarded = computed(() => {
  const { 'onUpdate:modelValue': _, ...rest } = forwardedAll.value
  return rest
})

const innerValue = computed<JSONContent | string>({
  get() {
    return props.modelValue ?? ''
  },
  set(value) {
    emits('update:modelValue', value as TModelValue)
  }
})
</script>

<template>
  <admin-rich-editor v-bind="forwarded" v-model="innerValue">
    <template v-if="slots.default" #default="slotProps">
      <slot v-bind="slotProps"></slot>
    </template>
  </admin-rich-editor>
</template>
```

::alert{title="需開啟 strictVModel" type="info"}
型別檢查需開啟 `strictVModel`（若已開啟 `strictTemplates` 則已包含）。設定見 [Type-safe](https://component-registry-4d4d86.gitlab.io/docs/get-started/type-safe)。下列同時含合法綁定與刻意錯誤綁定；錯誤處以 `@vue-expect-error` 標示。
::

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import { ref } from 'vue'
import TypedAdminRichEditor from './typed-admin-rich-editor-demo.vue'

const htmlValue = ref('<p>HTML 內容</p>')
const jsonValue = ref<JSONContent>({ type: 'doc', content: [] })
</script>

<template>
  <div class="flex w-full max-w-md flex-col gap-6">
    <typed-admin-rich-editor v-model="jsonValue" content-type="json" />
    <!-- @vue-expect-error content-type=json 需 JSONContent，給 string 報錯 -->
    <typed-admin-rich-editor v-model="htmlValue" content-type="json" />

    <!-- html -> string -->
    <typed-admin-rich-editor v-model="htmlValue" content-type="html" />
    <!-- @vue-expect-error content-type=html 需 string，給 JSONContent 報錯 -->
    <typed-admin-rich-editor v-model="jsonValue" content-type="html" />
  </div>
</template>
```

## 字數限制

core 不內建 character count extension，要的話透過 `:extensions` 自帶：

```vue
<script setup lang="ts">
import CharacterCount from '@tiptap/extension-character-count'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor } from '@/registry/admin/ui/rich-editor'

const value = ref('')
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor }"
    v-model="value"
    :extensions="[CharacterCount.configure({ limit: 500 })]"
  >
    <admin-editor-toolbar :editor :items="defaultEditorItems" />
    <div class="mt-2 text-xs text-text-50">
      {{ editor.storage.characterCount.characters() }} / 500
    </div>
  </admin-rich-editor>
</template>
```

## 複製貼上行為

tiptap StarterKit 內建 paste rules，行為：

- **保留**支援的 mark / node（粗體、斜體、標題、清單、引言、code、link、`<img>`）
- **丟棄**不在 schema 內的標籤（未安裝對應擴充包時，Mention / Emoji / TextAlign / TaskList 這類內容貼上會被吃掉）
- 從 Word 來源的 HTML（`<o:p>`、`<span style="...">` 等垃圾）會被清掉
- 外部圖片 URL 直接顯示，但要注意 **CORS / hot-link** 問題（建議自行接上 upload Dialog 把圖上傳到自家 CDN）

## SSR 行為

`useEditor()` 在 SSR 階段回 `undefined`，template 內 `<EditorContent v-if="editor">` 守護：

- Server-rendered HTML 不含 editor content
- Client hydration 後實例化，內容才出現（可能短暫跳動）
- 後台場景無 SEO / LCP 嚴格需求，可接受
- **不適合 SEO 場景**（若需要，該情境也不該用 editor）

**不支援 SSR**：tiptap `useEditor()` 為 browser-only；元件殼不含 `<ClientOnly>`。Nuxt 請自行以 `<ClientOnly>` 包覆，其他 SSR 框架用等價機制；純 CSR 不需處理。見 [安裝 · SSR](https://component-registry-4d4d86.gitlab.io/docs/get-started/installation#ssr-nuxt)。headed／vendor 命名與是否需包覆無關。

## API 參考

### 組成

```vue
<template>
  <admin-rich-editor v-slot="{ editor }" v-model="value">
    <admin-editor-toolbar :editor :items="defaultEditorItems" />
  </admin-rich-editor>
</template>
```

### admin-rich-editor

::div{data-admin-api-table=""}
#### Props

| 名稱            | 型別                                       | 預設值     | 說明 |
| ------------- | ---------------------------------------- | ------- | -- |
| `modelValue`  | `string | JSONContent | undefined`       | —       | —  |
| `contentType` | `EditorContentType | undefined`          | —       | —  |
| `editable`    | `boolean | undefined`                    | `true`  | —  |
| `extensions`  | `AnyExtension[] | undefined`             | —       | —  |
| `handlers`    | `EditorCustomHandlers | undefined`       | —       | —  |
| `editorProps` | `EditorProps<any> | undefined`           | —       | —  |
| `autofocus`   | `FocusPosition | undefined`              | —       | —  |
| `class`       | `ClassValue`                             | —       | —  |
| `ui`          | `AdminEditorUI | undefined`              | —       | —  |
| `as`          | `string | undefined`                     | `"div"` | —  |
| `starterKit`  | `Partial<StarterKitOptions> | undefined` | —       | —  |

#### Events

| 名稱                  | Payload                | 說明 |
| ------------------- | ---------------------- | -- |
| `update:modelValue` | `string | JSONContent` | —  |

#### Slots

| 名稱        | Bindings                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | 說明 |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -- |
| `default` | `{ editor: Editor; handlers: { [x: string]: EditorHandler<unknown> | EditorHandler<unknown>; mark: EditorHandler<unknown>; heading: EditorHandler<unknown>; link: EditorHandler<unknown>; unlink: EditorHandler<unknown>; blockquote: EditorHandler<unknown>; bulletList: EditorHandler<unknown>; orderedList: EditorHandler<unknown>; codeBlock: EditorHandler<unknown>; horizontalRule: EditorHandler<unknown>; paragraph: EditorHandler<unknown>; undo: EditorHandler<unknown>; redo: EditorHandler<unknown>; unsetAllMarks: EditorHandler<unknown>; clearNodes: EditorHandler<unknown>; hardBreak: EditorHandler<unknown>; }; }` | —  |

#### Expose

| 名稱       | 簽名                   | 說明 |
| -------- | -------------------- | -- |
| `editor` | `Editor | undefined` | —  |
::

## 更新紀錄

:admin-changelog{component="AdminRichEditor"}


# Editor Toolbar

## 安裝

```bash [Terminal] icon=i-lucide-terminal
# 只依賴 @admin/editor-core;可搭 rich-editor 或 base editor 使用
pnpm dlx shadcn-vue add @admin/editor-toolbar
```

```ts
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
```

## 用法

最小可用組合：`<AdminRichEditor>` 容器內擺 `<AdminEditorToolbar>`（預設 layout `'fixed'`），items 給 `defaultEditorItems`：

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>(
  '<h2>歡迎使用 admin-rich-editor</h2><p>這是一個 <strong>富文本編輯器</strong>，基於 <a href="https://tiptap.dev">tiptap</a> 並對齊 admin design tokens。</p><ul><li>項目一</li><li>項目二</li></ul>'
)

// 預設只 bundle StarterKit；預設 toolbar 僅含 StarterKit 範圍能力，所有按鈕開箱即用
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers }"
    v-model="value"
    :ui="{ base: cn(baseProseClass, starterKitProseClass) }"
  >
    <admin-editor-toolbar :editor :handlers :items="defaultEditorItems" />
  </admin-rich-editor>
</template>
```

## 場景

### Bubble layout

選取文字後浮現 toolbar（Notion / Medium 風）。設定 `layout="bubble"`：

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>(
  '<p>選取一段文字試試看 — toolbar 會浮現在選取範圍上方(bubble 模式)。</p>'
)
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers }"
    v-model="value"
    :ui="{ base: cn(baseProseClass, starterKitProseClass) }"
  >
    <admin-editor-toolbar
      layout="bubble"
      :editor
      :handlers="handlers"
      :items="defaultEditorItems"
    />
  </admin-rich-editor>
</template>
```

### Floating layout

游標停在空行時浮現（Notion 的 block 插入選單風格）。設定 `layout="floating"`，items 只放區塊操作：

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'
import { IconBlockquote, IconList, IconListNumbers, IconSourceCode } from '@tabler/icons-vue'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { AdminEditorToolbar } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>(
  '<p>在段尾按 Enter 產生空行,block menu 會浮現在該行(floating 模式)。</p>'
)

// floating 的語意是「在空行插入區塊」，items 只放 block 操作
const blockItems: EditorToolbarItem[][] = [
  [
    {
      label: '段落樣式',
      dropdownVariant: 'select',
      items: [
        { kind: 'paragraph', label: '內文' },
        { kind: 'heading', level: 1, label: '標題 1' },
        { kind: 'heading', level: 2, label: '標題 2' }
      ]
    }
  ],
  [
    { kind: 'blockquote', icon: IconBlockquote, label: '引言', tooltip: { text: '引言' } },
    { kind: 'bulletList', icon: IconList, label: '項目清單', tooltip: { text: '項目清單' } },
    {
      kind: 'orderedList',
      icon: IconListNumbers,
      label: '數字清單',
      tooltip: { text: '數字清單' }
    },
    {
      kind: 'codeBlock',
      icon: IconSourceCode,
      label: '程式碼區塊',
      tooltip: { text: '程式碼區塊' }
    }
  ]
]
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers }"
    v-model="value"
    :ui="{ base: cn(baseProseClass, starterKitProseClass) }"
  >
    <admin-editor-toolbar layout="floating" :editor :handlers="handlers" :items="blockItems" />
  </admin-rich-editor>
</template>
```

### 客製 items（精簡版）

`:items` 接受 `EditorToolbarItem[]`（單列）或 `EditorToolbarItem[][]`（分組，每組之間自動加 separator）。自寫 `items` 收緊功能：

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { AdminEditorToolbar } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>(
  '<p>只啟用 <strong>bold</strong> / <em>italic</em> / link 的精簡版,適合留言情境。</p>'
)

// 客製 items：只保留留言情境會用到的功能
const leanItems: EditorToolbarItem[][] = [
  [
    { kind: 'mark', mark: 'bold', tooltip: { text: '粗體' } },
    { kind: 'mark', mark: 'italic', tooltip: { text: '斜體' } }
  ],
  [{ kind: 'link', tooltip: { text: '連結' } }]
]
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers }"
    v-model="value"
    :starter-kit="{
      heading: false,
      codeBlock: false,
      blockquote: false,
      horizontalRule: false
    }"
    :ui="{ base: cn(baseProseClass, starterKitProseClass) }"
  >
    <admin-editor-toolbar :editor :handlers="handlers" :items="leanItems" />
  </admin-rich-editor>
</template>
```

### 具名 slot 與 #item slot

item 可以整顆換成自訂元件：指定 `slot: '<name>'` 就交給同名具名 slot 渲染，沒指定的落到通用 `#item` slot。slot props 為 `{ item, index, isActive, isDisabled, onClick }`；不含 `editor`，需要就從外層 `<AdminRichEditor v-slot="{ editor, handlers }">` 取。`@admin/editor-text-color` / `@admin/editor-highlight` 就是這樣接入的：

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'
import { IconLetterA } from '@tabler/icons-vue'
import { Color } from '@tiptap/extension-color'
import { TextStyle } from '@tiptap/extension-text-style'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import {
  AdminEditorTextColorButton,
  defaultColorSwatches
} from '@/registry/admin/ui/editor-text-color'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>('<p>選取文字後,用 toolbar 最右側的 A 鈕設定文字顏色。</p>')

// 文字顏色需自行注入官方 extension:Color 依賴 TextStyle，兩者都要
const extensions = [TextStyle, Color]

// color picker 為 kindless slot item：靠具名 slot 自畫，不綁 handler
const items: EditorToolbarItem[][] = [
  ...defaultEditorItems,
  [{ slot: 'color', icon: IconLetterA, label: '文字顏色', tooltip: { text: '文字顏色' } }]
]
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers }"
    v-model="value"
    :extensions="extensions"
    :ui="{ base: cn(baseProseClass, starterKitProseClass) }"
  >
    <admin-editor-toolbar :editor :handlers="handlers" :items="items">
      <!-- slot props 不含 editor;picker 從外層 v-slot 的 editor 取 -->
      <template #color>
        <admin-editor-text-color-button :editor="editor" :swatches="defaultColorSwatches" />
      </template>
    </admin-editor-toolbar>
  </admin-rich-editor>
</template>
```

## defaultEditorItems

`defaultEditorItems: EditorToolbarItem[][]` 是預設工具列分組，只涵蓋 StarterKit 能力（復原、文字裝飾、段落樣式、區塊、Link），每個 item 都帶好 icon、繁中 label 與 tooltip。textAlign / image / indent 等非 StarterKit 能力由對應的 opt-in 包提供，spread 後追加即可：

```ts
const items = [
  ...defaultEditorItems,
  [{ kind: 'insertVariable', name: 'username', label: '使用者名稱' }],
]
```

## API 參考

### 組成

```vue
<template>
  <admin-rich-editor v-slot="{ editor, handlers }" v-model="value">
    <admin-editor-toolbar :editor :handlers :items="defaultEditorItems" />
  </admin-rich-editor>
</template>
```

### admin-editor-toolbar

::div{data-admin-api-table=""}
#### Props

| 名稱           | 型別                                | 預設值       | 說明                                                                |
| ------------ | --------------------------------- | --------- | ----------------------------------------------------------------- |
| `class`      | `ClassValue`                      | —         | —                                                                 |
| `editor`\*   | `Editor`                          | —         | 一律由外部顯式傳入的 tiptap editor 實例                                       |
| `handlers`\* | `EditorHandlers`                  | —         | merged handler map（必填）：由呼叫端顯式傳入，決定各 kind 的 active / disabled / 執行 |
| `items`\*    | `A`                               | —         | —                                                                 |
| `layout`     | `EditorToolbarLayout | undefined` | `"fixed"` | —                                                                 |

*\\\* 代表必填*

#### Slots

| 名稱     | Bindings                                    | 說明 |
| ------ | ------------------------------------------- | -- |
| `item` | `{ item: NestedItem<A>; } & SlotExtraProps` | —  |
::

## 注意事項

- **不支援 SSR**：bubble / floating layout 依賴瀏覽器 DOM 定位；元件殼不含 `<ClientOnly>`。Nuxt 請自行以 `<ClientOnly>` 包覆，其他 SSR 框架用等價機制；純 CSR 不需處理。見 [安裝 · SSR](https://component-registry-4d4d86.gitlab.io/docs/get-started/installation#ssr-nuxt)。

## 更新紀錄

:admin-changelog{component="AdminEditorToolbar"}


# Editor Image

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/editor-image
pnpm add @tiptap/extension-image
```

```ts
import { Image } from '@tiptap/extension-image'
import { createImageHandler } from '@/registry/admin/ui/editor-image'
```

含 `createImageHandler`；圖片能力來自 tiptap `Image`，需自行注入。把 `Image.configure({})` 傳入 `:extensions`、`createImageHandler` 經 `:handlers` 注入後，toolbar 可放 `{ kind: 'image' }` 按鈕（見下方用法）。

## 用法

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'
import { IconPhoto } from '@tabler/icons-vue'
import { Image } from '@tiptap/extension-image'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { createImageHandler, editorImageClass } from '@/registry/admin/ui/editor-image'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>(
  '<p>下方為 &lt;img&gt; 圖片，toolbar 的插入圖片按鈕會以 prompt 取網址後 setImage。</p><img src="https://picsum.photos/seed/admin-image/800/360" alt="範例圖片">'
)

// opt-in：注入官方 Image extension 與 image handler
const extensions = [Image.configure({})]
const handlers = { image: createImageHandler() }

// 預設 toolbar（純 StarterKit）後面 append image 按鈕
const items: EditorToolbarItem[][] = [
  ...defaultEditorItems,
  [{ kind: 'image', icon: IconPhoto, label: '插入圖片', tooltip: { text: '插入圖片' } }]
]
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers: mergedHandlers }"
    v-model="value"
    :extensions="extensions"
    :handlers="handlers"
    :ui="{ base: cn(baseProseClass, starterKitProseClass, editorImageClass) }"
  >
    <admin-editor-toolbar :editor :handlers="mergedHandlers" :items="items" />
  </admin-rich-editor>
</template>
```

```vue
<script setup lang="ts">
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'
import { IconPhoto } from '@tabler/icons-vue'
import { Image } from '@tiptap/extension-image'
import { ref } from 'vue'
import { createImageHandler } from '@/registry/admin/ui/editor-image'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor } from '@/registry/admin/ui/rich-editor'

const value = ref('<p>圖:<img src="https://picsum.photos/seed/admin-image/800/360" alt="x"></p>')

const extensions = [Image.configure({})]
const handlers = { image: createImageHandler() }
const items: EditorToolbarItem[][] = [
  ...defaultEditorItems,
  [{ kind: 'image', icon: IconPhoto, label: '插入圖片', tooltip: { text: '插入圖片' } }]
]
</script>

<template>
  <admin-rich-editor v-model="value" :extensions="extensions" :handlers="handlers">
    <admin-editor-toolbar :items="items" />
  </admin-rich-editor>
</template>
```

啟用後：

- `<img>` 顯示不會被 tiptap parser 丟掉
- `editor.commands.setImage({ src, alt })` 可程式式插入圖片
- 序列化輸出為原始 `<img src="...">`（HTML）或 image node attrs（JSON）

## 進階 configure

需要 inline 圖片、允許 base64 等，自行用 `Image.configure({...})` 建立 instance：

```vue
<script setup lang="ts">
import { Image } from '@tiptap/extension-image'

const customImage = Image.configure({ inline: true, allowBase64: true })
</script>

<template>
  <admin-rich-editor v-model="value" :extensions="[customImage]" />
</template>
```

## API 參考

`@tiptap/extension-image` 套件 API 詳見 [tiptap image 官方文件](https://tiptap.dev/docs/editor/extensions/nodes/image){rel="&#x22;nofollow&#x22;"}。

## 注意事項

- **extension 必須在建立編輯器時注入**：`Image` 無法於編輯器建立後補上，未注入時 `<img>` 內容會被 parser 丟掉。


# Editor Emoji Menu

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/editor-emoji-menu
```

```ts
import type { EmojiMenuItem } from '@/registry/admin/ui/editor-emoji-menu'
import { AdminEditorEmojiMenu } from '@/registry/admin/ui/editor-emoji-menu'
```

`admin-editor-emoji-menu` 依賴 `@admin/rich-editor` 與 `@tiptap/extension-emoji`。

::alert{title="裝完必須在 :extensions 注入 Emoji" type="warning"}
`@tiptap/extension-emoji` 跟 mention 一樣是 Node extension，會動到 schema，而 schema 在編輯器建立時就固定、無法後補。`<AdminEditorEmojiMenu>` mount 時會註冊 Suggestion plugin，popup 照常浮現，但 schema 沒有 emoji node 時，選定後只能退回插入純 Unicode 字元，失去 emoji node 的三個好處：

- **多 codepoint 安全**：`👨‍👩‍👧` 這類 ZWJ 組合 emoji，純 Unicode 模式下游標和 backspace 會跳到字元中間
- **attrs 持久化**：node 模式存的是 `data-name="smile"`，之後可以用 shortcode 反查、切換 emoji set
- **不吃 mark**：atomic node 不會被 bold / italic / color 等 mark 套到
::

```ts
import Emoji from '@tiptap/extension-emoji'
const extensions = [Emoji.configure({ enableEmoticons: false })]

// <AdminRichEditor :extensions="extensions">
```

## 用法

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import type { EmojiMenuItem } from '@/registry/admin/ui/editor-emoji-menu'
import Emoji, { gitHubEmojis } from '@tiptap/extension-emoji'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { AdminEditorEmojiMenu } from '@/registry/admin/ui/editor-emoji-menu'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>('<p>輸入 : 觸發 emoji menu(例如 :smile)</p>')

// 用 @tiptap/extension-emoji 內附的 gitHubEmojis 資料集（免自帶 JSON）。
// 過濾掉 regional_indicator（國旗用字母）與顯而易見不適合 demo 的群，取前 60 個常用。
const emojis: EmojiMenuItem[] = gitHubEmojis
  .filter(
    (e) =>
      !e.name.startsWith('regional_indicator_') &&
      !e.name.endsWith('_button') &&
      !e.name.endsWith('_sign')
  )
  .slice(0, 60)

// 把 Emoji extension 傳給 admin-rich-editor，讓 schema 有 emoji node
// 選定後插入的是 atomic node（多 codepoint 安全 / attrs 持久化 / 不吃 mark）
// 不傳的話 SFC 會 fallback 為純 Unicode 插入（有缺點）
const extensions = [Emoji.configure({ enableEmoticons: false })]
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers }"
    v-model="value"
    :extensions="extensions"
    :ui="{ base: cn(baseProseClass, starterKitProseClass) }"
  >
    <admin-editor-toolbar :editor :handlers="handlers" :items="defaultEditorItems" />
    <admin-editor-emoji-menu :editor :items="emojis" />
  </admin-rich-editor>
</template>
```

```vue
<script setup lang="ts">
import Emoji, { gitHubEmojis } from '@tiptap/extension-emoji'
import { ref } from 'vue'
import { AdminEditorEmojiMenu } from '@/registry/admin/ui/editor-emoji-menu'
import { AdminRichEditor } from '@/registry/admin/ui/rich-editor'

const value = ref('')
// @tiptap/extension-emoji 內附 gitHubEmojis 資料集（約 1500 個），免自帶 JSON
const emojis = gitHubEmojis.slice(0, 50)

// schema 需要 emoji node，顯式傳入 Emoji extension
const extensions = [Emoji.configure({ enableEmoticons: false })]
</script>

<template>
  <admin-rich-editor v-slot="{ editor }" v-model="value" :extensions="extensions">
    <admin-editor-emoji-menu :editor :items="emojis" />
  </admin-rich-editor>
</template>
```

## EmojiMenuItem 介面

本 block 的 `EmojiMenuItem` 跟 `@tiptap/extension-emoji` 的 `EmojiItem` shape 一致：

```ts
interface EmojiMenuItem {
  name: string // 唯一名稱，當作 emoji node attr 存
  emoji?: string // Unicode 字元（fallback 模式時用）
  shortcodes: string[] // 簡碼 filter 欄位（:smile / :+1）
  tags: string[] // 標籤 filter 欄位（happy / love）
  group?: string // 分組（供 UI 分類）
  fallbackImage?: string // emoji 為 undefined 時的圖片 fallback（自訂貼圖）
  emoticons?: string[] // 顏文字（`:)` 對應 :smile），配 enableEmoticons 使用
  [key: string]: unknown
}
```

### filter 多欄位行為

預設 `filterFields = ['name', 'shortcodes', 'tags']`，輸入的字串會同時比對這三個欄位。例如輸入 `:happy` 時，`{ name: 'grinning', shortcodes: ['grin'], tags: ['happy', 'joy'] }` 會因 `tags` 命中而列入結果。

## emoji 資料集

`@tiptap/extension-emoji` 內附三個資料集，免自帶 JSON：

```ts
import { emojis, gitHubCustomEmojis, gitHubEmojis } from '@tiptap/extension-emoji'

// emojis：通用 Unicode emoji 全集
// gitHubEmojis：GitHub 風格（約 1500 個，含 shortcode）
// gitHubCustomEmojis：GitHub 自訂（如 :octocat:）
```

要自訂資料集，直接傳 `EmojiMenuItem[]` 給 `:items` 即可。後台情境通常 50 到 100 個常用就夠：

```ts
const emojis = gitHubEmojis.slice(0, 50)
```

資料量上千時，改用 `v-model:search-term` 加 `ignore-filter` 接外部 fuzzy library（如 `fuse.js`），避免內建 fuzzy filter 卡頓。

## 鍵盤導航

同 [Editor Suggestion Menu](https://component-registry-4d4d86.gitlab.io/docs/editor/addons/suggestion#%E9%8D%B5%E7%9B%A4%E5%B0%8E%E8%88%AA)。

## API 參考

### admin-editor-emoji-menu

::div{data-admin-api-table=""}
#### Props

| 名稱             | 型別                                    | 預設值                              | 說明                                                 |
| -------------- | ------------------------------------- | -------------------------------- | -------------------------------------------------- |
| `editor`\*     | `Editor`                              | —                                | —                                                  |
| `items`\*      | `EmojiMenuItem[] | EmojiMenuItem[][]` | —                                | —                                                  |
| `char`         | `string | undefined`                  | `":"`                            | 觸發字元，預設 \`:\`                                      |
| `pluginKey`    | `string | undefined`                  | `"editorEmojiMenu"`              | PM plugin key，預設 \`editorEmojiMenu\`               |
| `limit`        | `number | undefined`                  | `10`                             | 顯示筆數上限，預設 10                                       |
| `filterFields` | `string[] | undefined`                | `["name", "shortcodes", "tags"]` | filter 比對欄位，預設 \`\['name', 'shortcodes', 'tags']\` |
| `ignoreFilter` | `boolean | undefined`                 | `false`                          | true 時跳過內建 fuzzy filter                            |
| `class`        | `ClassValue`                          | —                                | —                                                  |

*\\\* 代表必填*
::

## 更新紀錄

:admin-changelog{component="AdminEditorEmojiMenu"}


# Editor Suggestion Menu

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/editor-suggestion-menu
```

```ts
import type { EditorSuggestionMenuItem } from '@/registry/admin/ui/editor-suggestion-menu'
import { AdminEditorSuggestionMenu } from '@/registry/admin/ui/editor-suggestion-menu'
```

`admin-editor-suggestion-menu` 只依賴 `@admin/editor-core`（menu popup engine 與共用型別）；`handlers` 由呼叫端顯式傳入，可搭 `<AdminRichEditor>` 或 base `<AdminEditor>` 使用。

## 用法

在 `<admin-rich-editor v-slot="{ editor, handlers }">` slot 內加 `<admin-editor-suggestion-menu :editor :handlers :items="...">`。輸入 `/` 觸發 popup。

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import type { EditorSuggestionMenuItem } from '@/registry/admin/ui/editor-suggestion-menu'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { AdminEditorSuggestionMenu } from '@/registry/admin/ui/editor-suggestion-menu'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>('<p>輸入 / 觸發 slash command menu</p>')

const slashItems: EditorSuggestionMenuItem[] = [
  { kind: 'heading', level: 1, label: '標題 1', description: '大標題' },
  { kind: 'heading', level: 2, label: '標題 2', description: '中標題' },
  { kind: 'heading', level: 3, label: '標題 3', description: '小標題' },
  { kind: 'paragraph', label: '內文', description: '一般段落' },
  { kind: 'bulletList', label: '項目清單' },
  { kind: 'orderedList', label: '數字清單' },
  { kind: 'blockquote', label: '引言' }
]
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers }"
    v-model="value"
    :ui="{ base: cn(baseProseClass, starterKitProseClass) }"
  >
    <admin-editor-toolbar :editor :handlers="handlers" :items="defaultEditorItems" />
    <admin-editor-suggestion-menu :editor :handlers="handlers" :items="slashItems" />
  </admin-rich-editor>
</template>
```

## EditorSuggestionMenuItem 介面

```ts
type EditorSuggestionMenuItem = EditorItem & {
  label: string
  description?: string
  icon?: Component | string
}
```

`EditorItem` 是 `admin-editor-core` 定義的 discriminated union（`admin-rich-editor` 也有 re-export），涵蓋 `mark` / `heading` / `link`、12 個無參數 kind 與自訂 handler kind。它直接重用 toolbar items 的結構，寫過 toolbar 就會寫：

```ts
const slashItems: EditorSuggestionMenuItem[] = [
  { kind: 'heading', level: 1, label: '標題 1' },
  { kind: 'bulletList', label: '項目清單' },
  { kind: 'blockquote', label: '引言' }
]
```

選定 item 後 SFC 內部會：

1. 用 `editor.chain().focus().deleteRange(range)` 刪掉 `/xxx` 觸發範圍
2. 透過 `props.handlers` 取出 `handler[item.kind]`（`handlers` 由呼叫端顯式傳入，可取自 `<AdminRichEditor v-slot="{ editor, handlers }">` 或 base editor 情境的 `createDefaultHandlers()`）
3. 呼叫 `handler.execute(editor, item).run()`

由於與 toolbar items 共用 kind dispatch，對應 extension 未啟用時，選取後不會有動作（不會報錯）。

## 鍵盤導航

由 `useEditorMenu` composable 提供，不需額外設定：

| 按鍵                  | 行為       |
| ------------------- | -------- |
| ArrowUp / ArrowDown | 上下移動選取   |
| Enter / Tab         | 確認選取     |
| Escape              | 關閉 popup |

選取 label / separator type 的 item 會自動跳過。

## 與 toolbar items 共用結構

suggestion menu 的 `:items` 接受扁平或分組陣列。`defaultEditorItems` 是分組陣列，攤平後即可直接沿用：

```ts
const slashItems = defaultEditorItems
  .flat()
  .filter((item): item is EditorSuggestionMenuItem =>
    'kind' in item && typeof item.label === 'string'
  )
```

## API 參考

### admin-editor-suggestion-menu

::div{data-admin-api-table=""}
#### Props

| 名稱             | 型別                                                          | 預設值                      | 說明                                                                       |
| -------------- | ----------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------ |
| `editor`\*     | `Editor`                                                    | —                        | tiptap Editor instance（必填）                                               |
| `handlers`\*   | `EditorHandlers`                                            | —                        | handler map（必填）：決定各 kind 選定後執行的行為，由呼叫端顯式傳入                               |
| `items`\*      | `EditorSuggestionMenuItem[] | EditorSuggestionMenuItem[][]` | —                        | 候選清單（可為扁平或分組陣列）                                                          |
| `char`         | `string | undefined`                                        | `"/"`                    | 觸發字元，預設 \`/\`                                                            |
| `pluginKey`    | `string | undefined`                                        | `"editorSuggestionMenu"` | PM plugin key，預設 \`editorSuggestionMenu\`（同 editor 內多 menu 並存時 override） |
| `limit`        | `number | undefined`                                        | `10`                     | 顯示筆數上限，預設 10                                                             |
| `filterFields` | `string[] | undefined`                                      | `["label"]`              | filter 比對欄位，預設 \`\['label']\`                                            |
| `ignoreFilter` | `boolean | undefined`                                       | `false`                  | true 時跳過內建 fuzzy filter（外部已 filter 時使用）                                  |
| `class`        | `ClassValue`                                                | —                        | —                                                                        |

*\\\* 代表必填*
::

## 更新紀錄

:admin-changelog{component="AdminEditorSuggestionMenu"}


# Editor Link Bubble

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/editor-link-bubble
```

```ts
import { AdminEditorLinkBubble } from '@/registry/admin/ui/editor-link-bubble'
```

`admin-editor-link-bubble` 依賴 `@admin/rich-editor`。Link mark 由 `@admin/rich-editor` 的 StarterKit 提供，本包只負責浮層 UI。

## 用法

把 `<AdminEditorLinkBubble>` 放進 `<AdminRichEditor>` 的 default slot，並傳入 slot 暴露的 `editor`。游標移到既有連結上即浮出泡泡。

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { AdminEditorLinkBubble } from '@/registry/admin/ui/editor-link-bubble'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>(
  `<p>第 1 段：捲動測試用內容,讓 editor 超過固定高度而出現內部捲軸。</p>
   <p>第 2 段：捲動測試用內容。</p>
   <p>第 3 段：捲動測試用內容。</p>
   <p>第 4 段：點此含<a href="https://example.com">連結</a>的文字，會浮出檢視 / 編輯 / 移除的泡泡。捲動時泡泡應跟隨此連結移動。</p>
   <p>第 5 段：捲動測試用內容。</p>
   <p>第 6 段：捲動測試用內容。</p>
   <p>第 7 段：捲動測試用內容。</p>
   <p>第 8 段：捲動測試用內容。</p>
   <p>第 9 段：捲動測試用內容。</p>
   <p>第 10 段：捲動測試用內容。</p>`
)
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor }"
    v-model="value"
    class="max-h-[180px] overflow-y-auto"
    :ui="{ base: cn(baseProseClass, starterKitProseClass) }"
  >
    <admin-editor-link-bubble :editor />
  </admin-rich-editor>
</template>
```

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminEditorLinkBubble } from '@/registry/admin/ui/editor-link-bubble'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor } from '@/registry/admin/ui/rich-editor'

const value = ref('<p>含<a href="https://example.com">連結</a>的內容。</p>')
</script>

<template>
  <admin-rich-editor v-slot="{ editor }" v-model="value">
    <admin-editor-toolbar :editor :items="defaultEditorItems" />
    <admin-editor-link-bubble :editor />
  </admin-rich-editor>
</template>
```

## API 參考

### admin-editor-link-bubble

::div{data-admin-api-table=""}
#### Props

| 名稱         | 型別           | 預設值 | 說明 |
| ---------- | ------------ | --- | -- |
| `editor`\* | `Editor`     | —   | —  |
| `class`    | `ClassValue` | —   | —  |

*\\\* 代表必填*
::

## 注意事項

- **與預設 prompt 並存**：未安裝本包時，toolbar 的 link 按鈕走 `window.prompt`；裝上本包後，選到連結會多一層浮層編輯體驗，兩者不衝突。
- **需要 Link mark**：依賴 StarterKit 內建的 Link mark；若以 `:starter-kit="{ link: false }"` 關閉 link，則本浮層不會出現。

## 更新紀錄

:admin-changelog{component="AdminEditorLinkBubble"}


# Editor List Trash

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/editor-list-trash
```

```ts
import { AdminEditorListTrash } from '@/registry/admin/ui/editor-list-trash'
```

`admin-editor-list-trash` 依賴 `@admin/rich-editor`，自帶刪除邏輯（不需 core 的 `delete` handler）。

## 用法

把 `<AdminEditorListTrash>` 放進 `<AdminRichEditor>` 的 default slot，游標移到清單項時即於右側浮出刪除鈕。

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { AdminEditorListTrash } from '@/registry/admin/ui/editor-list-trash'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>(
  '<ul><li>把游標移到清單項,右側會浮出刪除鈕</li><li>第二項</li><li>第三項</li></ul>'
)
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers }"
    v-model="value"
    :ui="{ base: cn(baseProseClass, starterKitProseClass) }"
  >
    <admin-editor-toolbar :editor :handlers="handlers" :items="defaultEditorItems" />
    <admin-editor-list-trash :editor />
  </admin-rich-editor>
</template>
```

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminEditorListTrash } from '@/registry/admin/ui/editor-list-trash'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor } from '@/registry/admin/ui/rich-editor'

const value = ref('<ul><li>清單項</li></ul>')
</script>

<template>
  <admin-rich-editor v-slot="{ editor }" v-model="value">
    <admin-editor-toolbar :editor :items="defaultEditorItems" />
    <admin-editor-list-trash :editor />
  </admin-rich-editor>
</template>
```

## API 參考

### admin-editor-list-trash

::div{data-admin-api-table=""}
#### Props

| 名稱         | 型別           | 預設值 | 說明 |
| ---------- | ------------ | --- | -- |
| `editor`\* | `Editor`     | —   | —  |
| `class`    | `ClassValue` | —   | —  |

*\\\* 代表必填*
::

## 注意事項

- **僅作用於清單項**：只在游標位於 `listItem` / `taskItem` 時顯示；一般段落不出現。
- **刪除整個節點**：點擊會刪掉整個清單項（含內容），非僅清空文字。
- **不支援 SSR**：旁側刪除鈕依賴瀏覽器 DOM 定位；元件殼不含 `<ClientOnly>`。Nuxt 請自行以 `<ClientOnly>` 包覆，其他 SSR 框架用等價機制；純 CSR 不需處理。見 [安裝 · SSR](https://component-registry-4d4d86.gitlab.io/docs/get-started/installation#ssr-nuxt)。

## 更新紀錄

:admin-changelog{component="AdminEditorListTrash"}


# Editor Drag Handle

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/editor-drag-handle
```

```ts
import { AdminEditorDragHandle } from '@/registry/admin/ui/editor-drag-handle'
```

`admin-editor-drag-handle` 依賴 `@admin/rich-editor` 與 `@tiptap/extension-drag-handle-vue-3`。`@admin/rich-editor` 本身不會渲染任何 drag handle，需安裝本包並放進 default slot。

## 用法

把 `<AdminEditorDragHandle>` 放進 `<AdminRichEditor>` 的 default slot，游標 hover 區塊時於左側浮出 grip。

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { AdminEditorDragHandle } from '@/registry/admin/ui/editor-drag-handle'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>(
  '<h2>Drag Handle 範例</h2><p>滑鼠 hover 任一段落,左側會出現拖曳區塊。</p><p>第二個段落。</p><ul><li>列表 1</li><li>列表 2</li></ul><p>第三個段落。</p>'
)
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers }"
    v-model="value"
    :ui="{ base: cn(baseProseClass, starterKitProseClass) }"
  >
    <admin-editor-toolbar :editor :handlers="handlers" :items="defaultEditorItems" />
    <admin-editor-drag-handle :editor />
  </admin-rich-editor>
</template>
```

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { AdminEditorDragHandle } from '@/registry/admin/ui/editor-drag-handle'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor } from '@/registry/admin/ui/rich-editor'

const value = ref('<p>hover 我，左側會出現拖曳把手。</p>')
</script>

<template>
  <admin-rich-editor v-slot="{ editor }" v-model="value">
    <admin-editor-toolbar :editor :items="defaultEditorItems" />
    <admin-editor-drag-handle :editor />
  </admin-rich-editor>
</template>
```

## API 參考

### admin-editor-drag-handle

::div{data-admin-api-table=""}
#### Props

| 名稱         | 型別           | 預設值 | 說明 |
| ---------- | ------------ | --- | -- |
| `editor`\* | `Editor`     | —   | —  |
| `class`    | `ClassValue` | —   | —  |

*\\\* 代表必填*

#### Slots

| 名稱        | Bindings | 說明 |
| --------- | -------- | -- |
| `default` | `{}`     | —  |
::

## 注意事項

- **預設不啟用**：`@admin/rich-editor` 本身不顯示 drag handle；未安裝本包則無拖曳把手。
- **最小官方包裝**：本元件僅轉發 `editor`、提供預設 grip，定位採官方 `@tiptap/extension-drag-handle-vue-3` 預設（`left-start`）。需自訂 icon 改用 default slot；需 node 變更 callback 或點擊選取等行為，請直接使用官方 `DragHandle` 的 `onNodeChange` / `computePositionConfig`。
- **裁切限制**：把手 append 於編輯器內容層，若超出編輯器 `overflow-hidden` 邊界會被裁切（官方 `DragHandle` 無 `appendTo`，無法 portal）。

## 更新紀錄

:admin-changelog{component="AdminEditorDragHandle"}


# Editor Table

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm add @tiptap/extension-table
pnpm dlx shadcn-vue add @admin/editor-table
```

```ts
import { TableKit } from '@tiptap/extension-table'
import {
  AdminEditorTableControls,
  createTableHandler,
  editorTableClass
} from '@/registry/admin/ui/editor-table'
```

含 Notion 式 grip 控制層（`AdminEditorTableControls`）、toolbar handler（`createTableHandler`）與表格樣式（`editorTableClass`）；表格能力來自 tiptap `TableKit`，需自行注入（見下方用法）。

## 用法

把 `TableKit.configure(...)` 注入 `:extensions`、`createTableHandler()` 注入 `:handlers`，並將 `<AdminEditorTableControls>` 放進 default slot。游標移入表格即浮出欄 / 列 grip。

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'
import { IconTable } from '@tabler/icons-vue'
import { TableKit } from '@tiptap/extension-table'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { AdminEditorDragHandle } from '@/registry/admin/ui/editor-drag-handle'
import {
  AdminEditorTableControls,
  createTableHandler,
  editorTableClass
} from '@/registry/admin/ui/editor-table'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>(
  `<p>下方為表格,游標移入後欄頂 / 列左會浮出 grip,點擊選取整欄 / 列並開啟選單,可插入 / 刪除欄列、切換首欄列標題或刪除表格;右緣 / 底緣的「+」可在末端加欄 / 列。</p>
   <table>
     <tbody>
       <tr><th>項目</th><th>數量</th><th>備註</th></tr>
       <tr><td>蘋果</td><td>3</td><td>紅富士</td></tr>
       <tr><td>香蕉</td><td>5</td><td>進口</td></tr>
     </tbody>
   </table>
   <p>toolbar 的插入表格按鈕會插入一個 3×3 含標題列的表格。</p>`
)

// opt-in：自行注入官方 TableKit 與 table handler
const extensions = [TableKit.configure({ table: { resizable: true } })]
const handlers = { table: createTableHandler() }

// 預設 toolbar（純 StarterKit）後面 append 插入表格按鈕
const items: EditorToolbarItem[][] = [
  ...defaultEditorItems,
  [{ kind: 'table', icon: IconTable, label: '插入表格', tooltip: { text: '插入表格' } }]
]
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers: mergedHandlers }"
    v-model="value"
    :extensions="extensions"
    :handlers="handlers"
    :ui="{ base: cn(baseProseClass, starterKitProseClass, editorTableClass) }"
  >
    <admin-editor-toolbar :editor :handlers="mergedHandlers" :items="items" />
    <admin-editor-drag-handle :editor />
    <admin-editor-table-controls :editor />
  </admin-rich-editor>
</template>
```

```vue
<script setup lang="ts">
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'
import { IconTable } from '@tabler/icons-vue'
import { TableKit } from '@tiptap/extension-table'
import { ref } from 'vue'
import {
  AdminEditorTableControls,
  createTableHandler,
  editorTableClass
} from '@/registry/admin/ui/editor-table'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor } from '@/registry/admin/ui/rich-editor'

const value = ref('<p>表格內容。</p>')

const extensions = [TableKit.configure({ table: { resizable: true } })]
const handlers = { table: createTableHandler() }
const items: EditorToolbarItem[][] = [
  ...defaultEditorItems,
  [{ kind: 'table', icon: IconTable, label: '插入表格', tooltip: { text: '插入表格' } }]
]
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor }"
    v-model="value"
    :class="editorTableClass"
    :extensions="extensions"
    :handlers="handlers"
  >
    <admin-editor-toolbar :editor :items="items" />
    <admin-editor-table-controls :editor />
  </admin-rich-editor>
</template>
```

啟用後：

- toolbar 的插入表格按鈕插入 3×3 含標題列的表格
- 游標移入表格時，欄頂 / 列左浮出 grip；點 grip 選取整欄 / 列並開啟選單，可在前後 / 上下插入欄列、刪除欄列、刪除表格
- 第 1 欄 grip 選單含「設為標題欄」、第 1 列 grip 選單含「設為標題列」（切換首欄 / 首列的 `th`）
- 表格右緣 / 底緣 hover 浮出「+」條，點擊在末端追加一欄 / 一列
- 預設開啟欄寬拖曳（`resizable`），拖曳欄邊界調整寬度
- read-only（`:editable="false"`）時不顯示任何 grip 與「+」控制層

## 進階 configure

需要關閉欄寬拖曳或調整其他設定，自行 `TableKit.configure(...)`：

```ts
const tableKit = TableKit.configure({ table: { resizable: false } })
```

## API 參考

### admin-editor-table-controls

::div{data-admin-api-table=""}
#### Props

| 名稱         | 型別           | 預設值 | 說明                                                           |
| ---------- | ------------ | --- | ------------------------------------------------------------ |
| `editor`\* | `Editor`     | —   | tiptap editor 實例，由 \`\<AdminRichEditor>\` default slot 暴露後傳入 |
| `class`    | `ClassValue` | —   | 併入控制層容器的 class                                               |

*\\\* 代表必填*
::

### `createTableHandler()`

回傳 toolbar handler，以 `{ kind: 'table' }` 觸發插入 3×3 含標題列的表格。

### `editorTableClass`

表格外觀的 Tailwind class 字串，append 到 editor 的 `:class`。

## 注意事項

- **需要 TableKit**：`<AdminEditorTableControls>` 依賴 editor 註冊 table extension；未以 `TableKit.configure(...)` 經 `:extensions` 注入時，dev 會 `console.warn` 且控制層不作用。
- **欄寬拖曳需要 `editorTableClass`**：其中 column resize handle 的樣式由 `editorTableClass` 提供，未 append 時拖曳功能仍在但無視覺提示。
- **標題切換僅限首欄 / 首列**：對齊 Notion，只有第 1 欄 / 第 1 列可切換為標題；grip 選單僅於首欄 / 首列顯示對應切換項。
- **互動為 pointer 導向**：以滑鼠 hover / 點擊操作 grip 與「+」，不提供鍵盤焦點導航；鍵盤使用者仍可用 toolbar 插入、方向鍵移動與官方表格快捷鍵。
- **不支援 SSR**：表格 grip 與欄寬拖曳依賴瀏覽器 DOM；元件殼不含 `<ClientOnly>`。Nuxt 請自行以 `<ClientOnly>` 包覆，其他 SSR 框架用等價機制；純 CSR 不需處理。見 [安裝 · SSR](https://component-registry-4d4d86.gitlab.io/docs/get-started/installation#ssr-nuxt)。

## 更新紀錄

:admin-changelog{component="AdminEditorTableControls"}


# Editor Superscript / Subscript

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm add @tiptap/extension-superscript @tiptap/extension-subscript
```

上標／下標來自 tiptap `Superscript`／`Subscript`。與 highlight／text-align 不同，它們是單純 toggle mark，不需額外元件：注入官方 extension、用 `:handlers` 註冊 toggle handler，再於 toolbar 加上 `{ kind: 'superscript' }`／`{ kind: 'subscript' }` item 即可；本頁無對應 registry 包。

## 用法

```vue
<script setup lang="ts">
import type { Editor, JSONContent } from '@tiptap/core'
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'
import { IconSubscript, IconSuperscript } from '@tabler/icons-vue'
import Subscript from '@tiptap/extension-subscript'
import Superscript from '@tiptap/extension-superscript'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>(
  '<p>E = mc<sup>2</sup>,H<sub>2</sub>O。選取文字後點 toolbar 的上標 / 下標。</p>'
)

const extensions = [Superscript, Subscript]

const scriptHandlers = {
  superscript: {
    canExecute: (e: Editor) => e.can().toggleSuperscript(),
    execute: (e: Editor) => e.chain().focus().toggleSuperscript(),
    isActive: (e: Editor) => e.isActive('superscript')
  },
  subscript: {
    canExecute: (e: Editor) => e.can().toggleSubscript(),
    execute: (e: Editor) => e.chain().focus().toggleSubscript(),
    isActive: (e: Editor) => e.isActive('subscript')
  }
}

const items: EditorToolbarItem[][] = [
  ...defaultEditorItems,
  [
    { kind: 'superscript', icon: IconSuperscript, tooltip: '上標' },
    { kind: 'subscript', icon: IconSubscript, tooltip: '下標' }
  ]
]
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers }"
    v-model="value"
    :extensions="extensions"
    :handlers="scriptHandlers"
    :ui="{ base: cn(baseProseClass, starterKitProseClass) }"
  >
    <admin-editor-toolbar :editor :handlers="handlers" :items="items" />
  </admin-rich-editor>
</template>
```

handler 直接以 inline 物件註冊，無任何內部依賴，可原樣複製：

```ts
import type { Editor } from '@tiptap/core'
import Subscript from '@tiptap/extension-subscript'
import Superscript from '@tiptap/extension-superscript'

const extensions = [Superscript, Subscript]

const scriptHandlers = {
  superscript: {
    canExecute: (e: Editor) => e.can().toggleSuperscript(),
    execute: (e: Editor) => e.chain().focus().toggleSuperscript(),
    isActive: (e: Editor) => e.isActive('superscript')
  },
  subscript: {
    canExecute: (e: Editor) => e.can().toggleSubscript(),
    execute: (e: Editor) => e.chain().focus().toggleSubscript(),
    isActive: (e: Editor) => e.isActive('subscript')
  }
}
```

```vue
<admin-rich-editor v-slot="{ editor }" v-model="value" :extensions="extensions" :handlers="scriptHandlers">
  <admin-editor-toolbar :editor :items="items" />
</admin-rich-editor>
```

toolbar item 以 `kind` 對應 handler，經 rich-editor context 派發：

```ts
const items = [
  ...defaultEditorItems,
  [
    { kind: 'superscript', icon: IconSuperscript, tooltip: '上標' },
    { kind: 'subscript', icon: IconSubscript, tooltip: '下標' }
  ]
]
```

注入後 `toggleSuperscript()` / `toggleSubscript()` command 可用（官方 extension 另附 `Mod-.` / `Mod-,` 快捷鍵）；toolbar 按鈕依當前 mark 高亮。

## API 參考

`@tiptap/extension-superscript` / `@tiptap/extension-subscript` 套件 API 詳見 [tiptap superscript 官方文件](https://tiptap.dev/docs/editor/extensions/marks/superscript){rel="&#x22;nofollow&#x22;"}與 [subscript 官方文件](https://tiptap.dev/docs/editor/extensions/marks/subscript){rel="&#x22;nofollow&#x22;"}。

## 注意事項

- **不互斥**：上標與下標可同時套用於同一段文字。若需互斥，自行以 `Superscript.extend({ excludes: 'subscript' })`（及對稱設定）於 schema 層處理。
- **不支援 markdown 模式**：官方 extension 不含 markdown tokenizer / serializer，`content-type="markdown"` 下 sup / sub 不會被序列化，來回轉換會遺失。此情境需自寫帶 `markdownTokenizer` 的 custom mark。


# Editor Video

## 安裝

`editor-video` 自帶 `Video` node（以 `@tiptap/core` 自製，無需額外安裝 tiptap extension 套件）。

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/editor-video
```

```ts
import { createVideoHandler, Video } from '@/registry/admin/ui/editor-video'
```

把本包的 `Video` node 傳入 `:extensions`、`createVideoHandler` 經 `:handlers` 注入後，toolbar 可放 `{ kind: 'video' }` 按鈕（見下方用法）。

## 用法

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'
import { IconMovie } from '@tabler/icons-vue'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { createVideoHandler, editorVideoClass, Video } from '@/registry/admin/ui/editor-video'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>(
  '<p>下方為 &lt;video&gt; 影片,toolbar 的插入影片按鈕會以 prompt 取網址後 setVideo。</p><video src="https://www.w3schools.com/html/mov_bbb.mp4" controls></video>'
)

// opt-in：注入本包自帶的 Video node 與 video handler
const extensions = [Video]
const handlers = { video: createVideoHandler() }

// 預設 toolbar（純 StarterKit）後面 append video 按鈕
const items: EditorToolbarItem[][] = [
  ...defaultEditorItems,
  [{ kind: 'video', icon: IconMovie, label: '插入影片', tooltip: { text: '插入影片' } }]
]
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers: mergedHandlers }"
    v-model="value"
    :extensions="extensions"
    :handlers="handlers"
    :ui="{ base: cn(baseProseClass, starterKitProseClass, editorVideoClass) }"
  >
    <admin-editor-toolbar :editor :handlers="mergedHandlers" :items="items" />
  </admin-rich-editor>
</template>
```

```vue
<script setup lang="ts">
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'
import { IconMovie } from '@tabler/icons-vue'
import { ref } from 'vue'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { createVideoHandler, Video } from '@/registry/admin/ui/editor-video'
import { AdminRichEditor } from '@/registry/admin/ui/rich-editor'

const value = ref('<p>影片：<video src="https://www.w3schools.com/html/mov_bbb.mp4" controls></video></p>')

const extensions = [Video]
const handlers = { video: createVideoHandler() }
const items: EditorToolbarItem[][] = [
  ...defaultEditorItems,
  [{ kind: 'video', icon: IconMovie, label: '插入影片', tooltip: { text: '插入影片' } }]
]
</script>

<template>
  <admin-rich-editor v-model="value" :extensions="extensions" :handlers="handlers">
    <admin-editor-toolbar :items="items" />
  </admin-rich-editor>
</template>
```

啟用後：

- `<video>` 顯示不會被 tiptap parser 丟掉
- `editor.commands.setVideo({ src })` 可程式式插入影片
- 序列化輸出為原始 `<video src="..." controls>`（HTML）或 video node attrs（JSON）

## src 來源與上傳

`createVideoHandler` 只處理網址：缺 `src` 時以 `window.prompt` 要一個 URL。檔案上傳流程不內建於本包，請自行以 `:handlers` 覆寫 `video` handler 接上上傳端點。

::alert{title="src 不做白名單" type="warning"}
`src` 直接寫入 `<video src>`，本包不驗證網址；若 `src` 來源不可信，請於 consumer 端自行 sanitize。
::

## 屬性

`Video` node 屬性刻意最小化：

- `src`（必備）：影片來源網址
- `controls`（預設 `true`）：是否顯示原生播放控制列

poster / width / height / autoplay / loop / muted 等進階屬性未內建。

## API 參考

| 匯出                     | 說明                                                                |
| ---------------------- | ----------------------------------------------------------------- |
| `Video`                | 自製 tiptap block atom node，傳入 `<AdminRichEditor :extensions>`      |
| `createVideoHandler()` | 回傳 `EditorHandler`，傳入 `<AdminRichEditor :handlers>` 的 `video` key |


# Editor YouTube

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/editor-youtube
pnpm add @tiptap/extension-youtube
```

```ts
import { Youtube } from '@tiptap/extension-youtube'
import { createYoutubeHandler } from '@/registry/admin/ui/editor-youtube'
```

含 `createYoutubeHandler`；嵌入能力來自 tiptap `Youtube`，需自行注入。把 `Youtube.configure({})` 傳入 `:extensions`、`createYoutubeHandler` 經 `:handlers` 注入後，toolbar 可放 `{ kind: 'youtube' }` 按鈕（見下方用法）。

## 用法

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'
import { IconBrandYoutube } from '@tabler/icons-vue'
import { Youtube } from '@tiptap/extension-youtube'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { createYoutubeHandler, editorYoutubeClass } from '@/registry/admin/ui/editor-youtube'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>(
  '<p>下方為 YouTube 影片,toolbar 的插入 YouTube 按鈕會以 prompt 取網址後 setYoutubeVideo。</p><div data-youtube-video><iframe src="https://www.youtube.com/embed/dQw4w9WgXcQ"></iframe></div>'
)

// opt-in：注入官方 Youtube extension 與 youtube handler
const extensions = [Youtube.configure({ nocookie: true, width: 640, height: 360 })]
const handlers = { youtube: createYoutubeHandler() }

// 預設 toolbar（純 StarterKit）後面 append youtube 按鈕
const items: EditorToolbarItem[][] = [
  ...defaultEditorItems,
  [
    {
      kind: 'youtube',
      icon: IconBrandYoutube,
      label: '插入 YouTube',
      tooltip: { text: '插入 YouTube' }
    }
  ]
]
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers: mergedHandlers }"
    v-model="value"
    :extensions="extensions"
    :handlers="handlers"
    :ui="{ base: cn(baseProseClass, starterKitProseClass, editorYoutubeClass) }"
  >
    <admin-editor-toolbar :editor :handlers="mergedHandlers" :items="items" />
  </admin-rich-editor>
</template>
```

```vue
<script setup lang="ts">
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'
import { IconBrandYoutube } from '@tabler/icons-vue'
import { Youtube } from '@tiptap/extension-youtube'
import { ref } from 'vue'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { createYoutubeHandler } from '@/registry/admin/ui/editor-youtube'
import { AdminRichEditor } from '@/registry/admin/ui/rich-editor'

const value = ref('<p>影片：</p><div data-youtube-video><iframe src="https://www.youtube.com/embed/dQw4w9WgXcQ"></iframe></div>')

const extensions = [Youtube.configure({ nocookie: true, width: 640, height: 360 })]
const handlers = { youtube: createYoutubeHandler() }
const items: EditorToolbarItem[][] = [
  ...defaultEditorItems,
  [{ kind: 'youtube', icon: IconBrandYoutube, label: '插入 YouTube', tooltip: { text: '插入 YouTube' } }]
]
</script>

<template>
  <admin-rich-editor v-model="value" :extensions="extensions" :handlers="handlers">
    <admin-editor-toolbar :items="items" />
  </admin-rich-editor>
</template>
```

啟用後：

- YouTube iframe 顯示不會被 tiptap parser 丟掉
- `editor.commands.setYoutubeVideo({ src })` 可程式式嵌入影片（`src` 需為合法 YouTube 網址，否則官方 command 回 `false` 不插入）
- 序列化輸出為 `<div data-youtube-video><iframe ...></iframe></div>`

::alert{title="選取外框與節點拖曳" type="info"}
`data-youtube-video` wrapper 是 block 元素，預設佔滿整行，選取時的 `.ProseMirror-selectednode` 外框會比 iframe 寬。要讓外框貼齊 iframe，給 wrapper 套 `width: fit-content`（如 `[&_[data-youtube-video]]:w-fit`）。

不過 YouTube iframe 會攔截滑鼠事件（點擊會進到 YouTube 而不是選取節點），縮成 `w-fit` 後 iframe 旁已無可點區域，無法用點擊選取或拖曳。要選取、拖曳影片節點，請一併啟用 [Drag Handle](https://component-registry-4d4d86.gitlab.io/docs/editor/addons/drag-handle)，以把手拖曳（tiptap 官方對互動式 node 的建議做法）。
::

## 進階 configure

寬高、隱私模式（`nocookie`）等由 consumer 自行 `Youtube.configure({...})`：

```vue
<script setup lang="ts">
import { Youtube } from '@tiptap/extension-youtube'

const customYoutube = Youtube.configure({ nocookie: true, width: 640, height: 360, controls: true })
</script>

<template>
  <admin-rich-editor v-model="value" :extensions="[customYoutube]" />
</template>
```

## src 來源

`createYoutubeHandler` 只處理網址：缺 `src` 時以 `window.prompt` 要一個 URL。進階選片 UI 請自行以 `:handlers` 覆寫 `youtube` handler。

## API 參考

| 匯出                       | 說明                                                                  |
| ------------------------ | ------------------------------------------------------------------- |
| `createYoutubeHandler()` | 回傳 `EditorHandler`，傳入 `<AdminRichEditor :handlers>` 的 `youtube` key |

`@tiptap/extension-youtube` 套件 API 詳見 [tiptap youtube 官方文件](https://tiptap.dev/docs/editor/extensions/nodes/youtube){rel="&#x22;nofollow&#x22;"}。


# Editor Font Size

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/editor-font-size
pnpm add @tiptap/extension-text-style
```

```ts
import { FontSize, TextStyle } from '@tiptap/extension-text-style'
import { AdminEditorFontSize } from '@/registry/admin/ui/editor-font-size'
```

含 toolbar 字級控制（`−` stepper、數值下拉、`+` stepper，共用同一狀態）；字級能力來自 tiptap `TextStyle`／`FontSize`（`@tiptap/extension-text-style`），需自行注入（見下方用法）。

## 用法

加入字級需三個步驟：在 `:extensions` 注入 `[TextStyle, FontSize]`、在 toolbar items 加入一個指定 `slot: 'fontSize'` 的項目、在 toolbar 的 `#fontSize` slot 放入 `<AdminEditorFontSize>`。

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'
import { IconTextResize } from '@tabler/icons-vue'
import { FontSize, TextStyle } from '@tiptap/extension-text-style'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { AdminEditorFontSize } from '@/registry/admin/ui/editor-font-size'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>('<p>選取文字後,用 toolbar 的 −／下拉／+ 調整字級。</p>')

// 字級需自行注入官方 extension:FontSize 依賴 TextStyle，兩者都要
const extensions = [TextStyle, FontSize]

// 字級為 kindless slot item：靠具名 slot 自畫，不綁 handler
const items: EditorToolbarItem[][] = [
  ...defaultEditorItems,
  [{ slot: 'fontSize', icon: IconTextResize, label: '字級', tooltip: { text: '字級' } }]
]
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers }"
    v-model="value"
    :extensions="extensions"
    :ui="{ base: cn(baseProseClass, starterKitProseClass) }"
  >
    <admin-editor-toolbar :editor :handlers="handlers" :items="items">
      <template #fontSize>
        <admin-editor-font-size :editor="editor" />
      </template>
    </admin-editor-toolbar>
  </admin-rich-editor>
</template>
```

```vue
<script setup lang="ts">
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'
import { IconTextResize } from '@tabler/icons-vue'
import { FontSize, TextStyle } from '@tiptap/extension-text-style'
import { ref } from 'vue'
import { AdminEditorFontSize } from '@/registry/admin/ui/editor-font-size'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor } from '@/registry/admin/ui/rich-editor'

const value = ref('<p>內容</p>')
// 自行注入官方 extension（FontSize 依賴 TextStyle）
const extensions = [TextStyle, FontSize]
// 字級是 kindless slot item：由具名 slot 渲染，不綁 handler
const items: EditorToolbarItem[][] = [
  ...defaultEditorItems,
  [{ slot: 'fontSize', icon: IconTextResize, label: '字級', tooltip: { text: '字級' } }]
]
</script>

<template>
  <admin-rich-editor v-slot="{ editor }" v-model="value" :extensions="extensions">
    <admin-editor-toolbar :items="items">
      <template #fontSize>
        <admin-editor-font-size :editor="editor" />
      </template>
    </admin-editor-toolbar>
  </admin-rich-editor>
</template>
```

### 無障礙：改用 rem 級距

預設級距以 `px` 寫入 inline `font-size`，不會隨使用者瀏覽器的根字級設定縮放。要符合無障礙需求，改透過 `:sizes` 傳入以 `rem` 為值的級距：`label` 仍是給人看的數字、`value` 寫 `rem`，套用後即隨根字級縮放。同時以 `base-value` 指定未設定字級時的起算基準（預設 `'16px'`，rem 級距要改傳如 `'1rem'`，否則基準查不到會 fallback 至級距中點）。

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import type { FontSizeOption } from '@/registry/admin/ui/editor-font-size'
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'
import { IconTextResize } from '@tabler/icons-vue'
import { FontSize, TextStyle } from '@tiptap/extension-text-style'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { AdminEditorFontSize } from '@/registry/admin/ui/editor-font-size'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>('<p>a11y 版:字級以 rem 寫入,隨使用者瀏覽器根字級縮放。</p>')

const extensions = [TextStyle, FontSize]

// a11y:label 仍給人看的數字（以 16px 根字級換算），value 寫 rem
const remSizes: FontSizeOption[] = [
  { label: '12', value: '0.75rem' },
  { label: '14', value: '0.875rem' },
  { label: '16', value: '1rem' },
  { label: '18', value: '1.125rem' },
  { label: '20', value: '1.25rem' },
  { label: '24', value: '1.5rem' },
  { label: '30', value: '1.875rem' },
  { label: '36', value: '2.25rem' }
]

const items: EditorToolbarItem[][] = [
  ...defaultEditorItems,
  [{ slot: 'fontSize', icon: IconTextResize, label: '字級', tooltip: { text: '字級(rem)' } }]
]
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers }"
    v-model="value"
    :extensions="extensions"
    :ui="{ base: cn(baseProseClass, starterKitProseClass) }"
  >
    <admin-editor-toolbar :editor :handlers="handlers" :items="items">
      <template #fontSize>
        <admin-editor-font-size base-value="1rem" :editor="editor" :sizes="remSizes" />
      </template>
    </admin-editor-toolbar>
  </admin-rich-editor>
</template>
```

```ts
import type { FontSizeOption } from '@/registry/admin/ui/editor-font-size'

// label 是給人看的數字（以 16px 根字級換算），value 寫 rem
const remSizes: FontSizeOption[] = [
  { label: '14', value: '0.875rem' },
  { label: '16', value: '1rem' },
  { label: '18', value: '1.125rem' },
  { label: '20', value: '1.25rem' }
]
```

```vue
<admin-editor-font-size base-value="1rem" :editor="editor" :sizes="remSizes" />
```

## API 參考

### admin-editor-font-size

::div{data-admin-api-table=""}
#### Props

| 名稱          | 型別                             | 預設值                  | 說明                                                                                        |
| ----------- | ------------------------------ | -------------------- | ----------------------------------------------------------------------------------------- |
| `editor`\*  | `Editor`                       | —                    | —                                                                                         |
| `sizes`     | `FontSizeOption[] | undefined` | `defaultFontSizes`   | 級距清單與順序（需由小到大）；預設 \`defaultFontSizes\`(12\~36 px)                                         |
| `baseValue` | `string | undefined`           | `DEFAULT_BASE_VALUE` | unset 時 stepper 的起算基準，需與 \`sizes\` 內某個 \`value\` 嚴格相等；預設 \`'16px'\`,rem 級距請改傳如 \`'1rem'\` |
| `disabled`  | `boolean | undefined`          | `false`              | —                                                                                         |
| `class`     | `unknown`                      | —                    | —                                                                                         |

*\\\* 代表必填*
::

## 注意事項

- **extension 必須在建立編輯器時注入**：`TextStyle` 與 `FontSize` 無法於編輯器建立後補上，未注入時字級控制不會生效。
- **級距需由小到大**：`sizes` 陣列需依值遞增排列，stepper 的上／下一級與到頂到底停用皆依此順序判定。
- **未設定字級時顯示「預設」**：游標所在文字未套字級時，下拉 trigger 顯示「預設」；選單頂端的「預設」項會移除 inline `font-size`，回退 CSS 繼承。
- **px vs rem**：預設 px 不隨瀏覽器字級縮放；需 a11y 請改用 rem 級距並搭配 `base-value`（見上方）。

## 更新紀錄

:admin-changelog{component="AdminEditorFontSize"}


# Editor Markdown

## 安裝

markdown 模式來自 tiptap `@tiptap/markdown`；`admin-rich-editor`／`admin-editor` 不自動注入，需自行安裝並經 `:extensions` 傳入：

```bash [Terminal] icon=i-lucide-terminal
pnpm add @tiptap/markdown
```

```ts
import { Markdown } from '@tiptap/markdown'
```

## 用法

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import { Markdown } from '@tiptap/markdown'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>(`# 歡迎使用 admin-rich-editor

這是 **markdown 模式**,v-model 出向 / 入向皆為 markdown 字串。

- 項目一
- 項目二

> 引言區塊
`)
</script>

<template>
  <div class="flex flex-col gap-4">
    <admin-rich-editor
      v-slot="{ editor, handlers }"
      v-model="value"
      content-type="markdown"
      :extensions="[Markdown.configure({})]"
      :ui="{ base: cn(baseProseClass, starterKitProseClass) }"
    >
      <admin-editor-toolbar :editor :handlers="handlers" :items="defaultEditorItems" />
    </admin-rich-editor>
    <div>
      <p class="mb-2 text-xs text-text-50">v-model 同步的 markdown 字串:</p>
      <pre
        class="overflow-x-auto rounded-sm border border-text-20 bg-bg-90 p-3 text-xs text-text-90"
        >{{ value }}</pre>
    </div>
  </div>
</template>
```

在 `<AdminRichEditor>`（或 `<AdminEditor>`）加上 `content-type="markdown"`、用 markdown 字串綁 v-model，並把 `Markdown.configure({})` 傳進 `:extensions`：

```vue
<script setup lang="ts">
import { Markdown } from '@tiptap/markdown'

const md = ref('# 標題\n\n內文')
</script>

<template>
  <admin-rich-editor v-model="md" content-type="markdown" :extensions="[Markdown.configure({})]" />
</template>
```

注入後：

- v-model 輸出走 `editor.getMarkdown()`
- v-model 寫入走 `setContent(value, { contentType: 'markdown' })`

## 進階 configure

關掉 markdown shortcuts（`# `自動轉 heading）或改 indentation，在 `configure` 帶選項即可：

```vue
<script setup lang="ts">
import { Markdown } from '@tiptap/markdown'

const customMarkdown = Markdown.configure({
  // markdownShortcuts: false, // 關掉自動 shortcut
  // indentation: { style: 'tab' },
})
</script>

<template>
  <admin-rich-editor
    v-model="md"
    content-type="markdown"
    :extensions="[customMarkdown]"
  />
</template>
```

## API 參考

`@tiptap/markdown` 套件 API 詳見 [tiptap markdown 官方文件](https://tiptap.dev/docs/editor/extensions/functionality/markdown){rel="&#x22;nofollow&#x22;"}。

## 注意事項

- **extension 必須在建立編輯器時注入**：未注入 `Markdown` 時，markdown 序列化會失效並退回純文字。
- **來回轉換不保證字元級一致**：HTML 與 markdown 互轉時，多餘空白與換行可能被正規化、`<br>` 讀回可能變單一換行、inline mark 的嵌套順序（粗體與斜體）可能調整。段落、標題、列表、連結、強調等核心元素轉換後外觀一致；若內容需要逐字元穩定（例如要進版控 diff），改用 `contentType="html"` 或 `contentType="json"`。


# Editor Code Block

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/editor-code-block
```

```ts
import { createCodeBlockExtension, editorCodeBlockClass } from '@/registry/admin/ui/editor-code-block'
```

本包以 `@tiptap/extension-code-block-lowlight`（highlight.js）取代 StarterKit 內建的 `codeBlock`，註冊 `lowlight/common` 的常用語言，並在每個區塊右上角掛上可搜尋的語言下拉。`lowlight` 隨安裝一併帶入，不用另裝。

## 用法

啟用要兩步：先 `:starter-kit="{ codeBlock: false }"` 關掉內建 `codeBlock`，再把 `createCodeBlockExtension()` 加進 `:extensions`。上色配色由 `editorCodeBlockClass` 提供，append 到 `:ui` 的 `base`。

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import {
  createCodeBlockExtension,
  editorCodeBlockClass
} from '@/registry/admin/ui/editor-code-block'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>(
  "<p>點程式碼區塊右上角的下拉可切換語言，選好即時上色：</p><pre><code class=\"language-typescript\">function greet(name: string): string {\n  return 'Hello, ' + name\n}\nconsole.log(greet('TPI'))</code></pre>"
)

// opt-in：關掉 starter-kit 內建 codeBlock，改用本擴展（含語言下拉 + lowlight 上色）
const extensions = [createCodeBlockExtension()]
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers }"
    v-model="value"
    :extensions="extensions"
    :starter-kit="{ codeBlock: false }"
    :ui="{ base: cn(baseProseClass, starterKitProseClass, editorCodeBlockClass) }"
  >
    <admin-editor-toolbar :editor :handlers="handlers" :items="defaultEditorItems" />
  </admin-rich-editor>
</template>
```

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { createCodeBlockExtension, editorCodeBlockClass } from '@/registry/admin/ui/editor-code-block'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref('<pre><code class="language-typescript">const x = 1</code></pre>')

const extensions = [createCodeBlockExtension()]
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers }"
    v-model="value"
    :extensions="extensions"
    :starter-kit="{ codeBlock: false }"
    :ui="{ base: cn(baseProseClass, starterKitProseClass, editorCodeBlockClass) }"
  >
    <admin-editor-toolbar :editor :handlers="handlers" :items="defaultEditorItems" />
  </admin-rich-editor>
</template>
```

啟用後：

- toolbar 的程式碼區塊按鈕照舊建立／取消區塊
- 區塊右上角的下拉切換語言，選好就上色；預設「純文字」不上色
- 存檔輸出標準的 `<pre><code class="language-<lang>">`，純文字則是 `language-plaintext`
- 唯讀（`:editable="false"`）時下拉收起，程式碼仍照原語言上色

## 預設語言

新建區塊預設為純文字，要換個預設語言就傳 `defaultLanguage`：

```ts
const extensions = [createCodeBlockExtension({ defaultLanguage: 'typescript' })]
```

## 注意事項

- **一定要先關掉內建 `codeBlock`**：本擴展跟 StarterKit 的 `codeBlock` 同名，同時存在會讓 TipTap 拋 `duplicate node: codeBlock`。
- **顏色不寫進內容**：語法色是顯示層的 decoration，存檔只留純碼與 `language` class，前台各自於 render 時再上色。
- **前台要一致上色**：把 `editorCodeBlockClass` 一起 append 到前台唯讀 viewer 容器的 `:class`，顏色才會跟編輯器一致。

## API 參考

| 匯出                                   | 說明                                                                             |
| ------------------------------------ | ------------------------------------------------------------------------------ |
| `createCodeBlockExtension(options?)` | 回傳配置好 lowlight 與語言下拉的 code block extension，傳入 `<AdminRichEditor :extensions>`  |
| `editorCodeBlockClass`               | 語法上色的 class 字串（`hljs-*` 對應 admin tokens），append 到 `:ui` 的 `base` 或前台 viewer 容器 |

| 選項                | 型別       | 預設            | 說明        |
| ----------------- | -------- | ------------- | --------- |
| `defaultLanguage` | `string` | `'plaintext'` | 新建區塊的預設語言 |


# Editor Text Color

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/editor-text-color
pnpm add @tiptap/extension-text-style @tiptap/extension-color
```

```ts
import { Color } from '@tiptap/extension-color'
import { TextStyle } from '@tiptap/extension-text-style'
import {
  AdminEditorTextColorButton,
  defaultColorSwatches
} from '@/registry/admin/ui/editor-text-color'
```

含 toolbar 按鈕與色板；顏色能力來自 tiptap `TextStyle`／`Color`，需自行注入（見下方用法）。

## 用法

加入文字顏色需三個步驟：在 `:extensions` 注入 `[TextStyle, Color]`、在 toolbar items 加入一個指定 `slot: 'color'` 的項目、在 toolbar 的 `#color` slot 放入 `<AdminEditorTextColorButton>`。

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'
import { IconLetterA } from '@tabler/icons-vue'
import { Color } from '@tiptap/extension-color'
import { TextStyle } from '@tiptap/extension-text-style'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import {
  AdminEditorTextColorButton,
  defaultColorSwatches
} from '@/registry/admin/ui/editor-text-color'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>('<p>選取文字後,用 toolbar 最右側的 A 鈕設定文字顏色。</p>')

// 文字顏色需自行注入官方 extension:Color 依賴 TextStyle，兩者都要
const extensions = [TextStyle, Color]

// color picker 為 kindless slot item：靠具名 slot 自畫，不綁 handler
const items: EditorToolbarItem[][] = [
  ...defaultEditorItems,
  [{ slot: 'color', icon: IconLetterA, label: '文字顏色', tooltip: { text: '文字顏色' } }]
]
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers }"
    v-model="value"
    :extensions="extensions"
    :ui="{ base: cn(baseProseClass, starterKitProseClass) }"
  >
    <admin-editor-toolbar :editor :handlers="handlers" :items="items">
      <!-- slot props 不含 editor;picker 從外層 v-slot 的 editor 取 -->
      <template #color>
        <admin-editor-text-color-button :editor="editor" :swatches="defaultColorSwatches" />
      </template>
    </admin-editor-toolbar>
  </admin-rich-editor>
</template>
```

```vue
<script setup lang="ts">
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'
import { IconLetterA } from '@tabler/icons-vue'
import { Color } from '@tiptap/extension-color'
import { TextStyle } from '@tiptap/extension-text-style'
import { ref } from 'vue'
import {
  AdminEditorTextColorButton,
  defaultColorSwatches
} from '@/registry/admin/ui/editor-text-color'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor } from '@/registry/admin/ui/rich-editor'

const value = ref('<p>內容</p>')
// 自行注入官方 extension（Color 依賴 TextStyle）
const extensions = [TextStyle, Color]
// color picker 是 kindless slot item：由具名 slot 渲染，不綁 handler
const items: EditorToolbarItem[][] = [
  ...defaultEditorItems,
  [{ slot: 'color', icon: IconLetterA, label: '文字顏色', tooltip: { text: '文字顏色' } }]
]
</script>

<template>
  <admin-rich-editor v-slot="{ editor }" v-model="value" :extensions="extensions">
    <admin-editor-toolbar :items="items">
      <template #color>
        <admin-editor-text-color-button :editor="editor" :swatches="defaultColorSwatches" />
      </template>
    </admin-editor-toolbar>
  </admin-rich-editor>
</template>
```

## API 參考

### admin-editor-text-color-button

::div{data-admin-api-table=""}
#### Props

| 名稱         | 型別                                        | 預設值     | 說明                             |
| ---------- | ----------------------------------------- | ------- | ------------------------------ |
| `editor`\* | `Editor`                                  | —       | —                              |
| `swatches` | `ColorPickerSwatch<string>[] | undefined` | —       | 色板；預設 \`defaultColorSwatches\` |
| `disabled` | `boolean | undefined`                     | `false` | —                              |
| `class`    | `unknown`                                 | —       | —                              |

*\\\* 代表必填*
::

## 注意事項

- **extension 必須在建立編輯器時注入**：`TextStyle` 與 `Color` 無法於編輯器建立後補上，未注入時顏色按鈕不會生效。
- **色板需自行提供**：使用本元件的 `defaultColorSwatches`，或透過 props 傳入自訂色板。

## 更新紀錄

:admin-changelog{component="AdminEditorTextColorButton"}


# Editor Highlight

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/editor-highlight
pnpm add @tiptap/extension-highlight
```

```ts
import Highlight from '@tiptap/extension-highlight'
import {
  AdminEditorHighlightButton,
  defaultHighlightSwatches
} from '@/registry/admin/ui/editor-highlight'
```

含 toolbar 按鈕與色板；底色能力來自 tiptap `Highlight`，需自行注入（見下方用法）。

## 用法

加入文字底色需三個步驟：在 `:extensions` 注入 `Highlight.configure({ multicolor: true })`、在 toolbar items 加入一個指定 `slot: 'highlight'` 的項目、在 toolbar 的 `#highlight` slot 放入 `<AdminEditorHighlightButton>`。

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'
import { IconHighlight } from '@tabler/icons-vue'
import Highlight from '@tiptap/extension-highlight'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import {
  AdminEditorHighlightButton,
  defaultHighlightSwatches
} from '@/registry/admin/ui/editor-highlight'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>(
  '<p>選取文字後,用 toolbar 最右側的螢光筆鈕設定文字底色。</p>'
)

// 文字底色需自行注入官方 Highlight extension（multicolor 允許自訂色碼）
const extensions = [Highlight.configure({ multicolor: true })]

// highlight picker 為 kindless slot item：靠具名 slot 自畫，不綁 handler
const items: EditorToolbarItem[][] = [
  ...defaultEditorItems,
  [{ slot: 'highlight', icon: IconHighlight, label: '文字底色', tooltip: { text: '文字底色' } }]
]
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers }"
    v-model="value"
    :extensions="extensions"
    :ui="{ base: cn(baseProseClass, starterKitProseClass) }"
  >
    <admin-editor-toolbar :editor :handlers="handlers" :items="items">
      <!-- slot props 不含 editor;picker 從外層 v-slot 的 editor 取 -->
      <template #highlight>
        <admin-editor-highlight-button :editor="editor" :swatches="defaultHighlightSwatches" />
      </template>
    </admin-editor-toolbar>
  </admin-rich-editor>
</template>
```

```vue
<script setup lang="ts">
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'
import { IconHighlight } from '@tabler/icons-vue'
import Highlight from '@tiptap/extension-highlight'
import { ref } from 'vue'
import {
  AdminEditorHighlightButton,
  defaultHighlightSwatches
} from '@/registry/admin/ui/editor-highlight'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor } from '@/registry/admin/ui/rich-editor'

const value = ref('<p>內容</p>')
// 自行注入官方 Highlight extension（multicolor 屬於 schema，建立後不可改）
const extensions = [Highlight.configure({ multicolor: true })]
// highlight picker 是 kindless slot item：由具名 slot 渲染，不綁 handler
const items: EditorToolbarItem[][] = [
  ...defaultEditorItems,
  [{ slot: 'highlight', icon: IconHighlight, label: '文字底色', tooltip: { text: '文字底色' } }]
]
</script>

<template>
  <admin-rich-editor v-slot="{ editor }" v-model="value" :extensions="extensions">
    <admin-editor-toolbar :items="items">
      <template #highlight>
        <admin-editor-highlight-button :editor="editor" :swatches="defaultHighlightSwatches" />
      </template>
    </admin-editor-toolbar>
  </admin-rich-editor>
</template>
```

## API 參考

### admin-editor-highlight-button

::div{data-admin-api-table=""}
#### Props

| 名稱         | 型別                                        | 預設值     | 說明                                 |
| ---------- | ----------------------------------------- | ------- | ---------------------------------- |
| `editor`\* | `Editor`                                  | —       | —                                  |
| `swatches` | `ColorPickerSwatch<string>[] | undefined` | —       | 色板；預設 \`defaultHighlightSwatches\` |
| `disabled` | `boolean | undefined`                     | `false` | —                                  |
| `class`    | `unknown`                                 | —       | —                                  |

*\\\* 代表必填*
::

## 注意事項

- **extension 必須在建立編輯器時注入**：`Highlight` 無法於編輯器建立後補上，未注入時底色按鈕會呈 disabled、無法套用。
- **色板需自行提供**：使用本元件的 `defaultHighlightSwatches`，或透過 props 傳入自訂色板。

## 更新紀錄

:admin-changelog{component="AdminEditorHighlightButton"}


# Editor TextAlign

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/editor-text-align
pnpm add @tiptap/extension-text-align
```

```ts
import TextAlign from '@tiptap/extension-text-align'
import { AdminEditorTextAlignButton } from '@/registry/admin/ui/editor-text-align'
```

含並排左／中／右三顆對齊按鈕；對齊能力來自 tiptap `TextAlign`，需自行注入（見下方用法）。

## 用法

加入對齊按鈕需三個步驟：在 `:extensions` 注入 `TextAlign.configure({ types: ['heading', 'paragraph'] })`、在 toolbar items 加入一個指定 `slot: 'textAlign'` 的項目、在 toolbar 的 `#textAlign` slot 放入 `<AdminEditorTextAlignButton>`。

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'
import { IconAlignLeft } from '@tabler/icons-vue'
import TextAlign from '@tiptap/extension-text-align'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { AdminEditorTextAlignButton } from '@/registry/admin/ui/editor-text-align'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>(
  '<h2 style="text-align: center">置中標題</h2><p style="text-align: right">這段靠右對齊。</p><p>這段為預設靠左。</p>'
)

// 對齊需自行注入官方 TextAlign extension
const extensions = [TextAlign.configure({ types: ['heading', 'paragraph'] })]

// 對齊按鈕為 kindless slot item：靠具名 slot 放入並排三顆對齊鈕元件，不綁 handler
const items: EditorToolbarItem[][] = [
  ...defaultEditorItems,
  [{ slot: 'textAlign', icon: IconAlignLeft, label: '對齊' }]
]
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers }"
    v-model="value"
    :extensions="extensions"
    :ui="{ base: cn(baseProseClass, starterKitProseClass) }"
  >
    <admin-editor-toolbar :editor :handlers="handlers" :items="items">
      <!-- slot props 不含 editor；對齊元件從外層 v-slot 的 editor 取 -->
      <template #textAlign>
        <admin-editor-text-align-button :editor="editor" />
      </template>
    </admin-editor-toolbar>
  </admin-rich-editor>
</template>
```

```vue
<script setup lang="ts">
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'
import { IconAlignLeft } from '@tabler/icons-vue'
import TextAlign from '@tiptap/extension-text-align'
import { ref } from 'vue'
import { AdminEditorTextAlignButton } from '@/registry/admin/ui/editor-text-align'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor } from '@/registry/admin/ui/rich-editor'

const value = ref('<p>內容</p>')

const extensions = [TextAlign.configure({ types: ['heading', 'paragraph'] })]
const items: EditorToolbarItem[][] = [
  ...defaultEditorItems,
  [{ slot: 'textAlign', icon: IconAlignLeft, label: '對齊' }]
]
</script>

<template>
  <admin-rich-editor v-slot="{ editor }" v-model="value" :extensions="extensions">
    <admin-editor-toolbar :items="items">
      <template #textAlign>
        <admin-editor-text-align-button :editor="editor" />
      </template>
    </admin-editor-toolbar>
  </admin-rich-editor>
</template>
```

注入後 `setTextAlign('left' | 'center' | 'right')` command 即可用，`AdminEditorTextAlignButton` 每顆按鈕會依游標所在段落的對齊狀態高亮。

## 進階 configure

需要新增可對齊的 node type 或改預設對齊，自行用 `TextAlign.configure({...})`：

```vue
<script setup lang="ts">
import TextAlign from '@tiptap/extension-text-align'

const customTextAlign = TextAlign.configure({
  types: ['heading', 'paragraph'],
  defaultAlignment: 'left'
})
</script>
```

## API 參考

### admin-editor-text-align-button

::div{data-admin-api-table=""}
#### Props

| 名稱         | 型別                            | 預設值                           | 說明                                              |
| ---------- | ----------------------------- | ----------------------------- | ----------------------------------------------- |
| `editor`\* | `Editor`                      | —                             | —                                               |
| `aligns`   | `TextAlignKind[] | undefined` | `["left", "center", "right"]` | 要顯示的對齊選項與順序；預設 \`\['left', 'center', 'right']\` |
| `disabled` | `boolean | undefined`         | `false`                       | —                                               |
| `class`    | `unknown`                     | —                             | —                                               |

*\\\* 代表必填*
::

`@tiptap/extension-text-align` 套件 API 詳見 [tiptap text-align 官方文件](https://tiptap.dev/docs/editor/extensions/functionality/textalign){rel="&#x22;nofollow&#x22;"}。

## 注意事項

- **extension 必須在建立編輯器時注入**：`TextAlign` 無法於編輯器建立後補上，未注入時對齊按鈕不會生效。
- **僅支援左/中/右三值**：不含 justify；需要 justify 請自行擴充按鈕與 `TextAlign.configure`。

## 更新紀錄

:admin-changelog{component="AdminEditorTextAlignButton"}


# Editor Placeholder

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm add @tiptap/extension-placeholder
```

```ts
import Placeholder from '@tiptap/extension-placeholder'
```

placeholder 來自 tiptap `Placeholder`；`admin-rich-editor`／`admin-editor` 不內建，需自行安裝並注入 `:extensions`。空狀態視覺 CSS 依下方片段自行套用。

## 用法

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import Placeholder from '@tiptap/extension-placeholder'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>('')

// placeholderExtension 為零配置預設；自訂文字用 Placeholder.configure({ placeholder })
const extensions = [Placeholder.configure({ placeholder: '開始輸入內容…' })]

// empty-state 視覺 CSS 不內含於包，透過 class 落 root,descendant selector 命中內容
const placeholderClass = `
  [&_p.is-editor-empty:first-child]:before:pointer-events-none
  [&_p.is-editor-empty:first-child]:before:float-left
  [&_p.is-editor-empty:first-child]:before:h-0
  [&_p.is-editor-empty:first-child]:before:text-text-40
  [&_p.is-editor-empty:first-child]:before:content-[attr(data-placeholder)]
`
</script>

<template>
  <admin-rich-editor
    v-model="value"
    :extensions="extensions"
    :ui="{ base: cn(baseProseClass, starterKitProseClass, placeholderClass) }"
  />
</template>
```

```vue
<script setup lang="ts">
import Placeholder from '@tiptap/extension-placeholder'
import { ref } from 'vue'
import { AdminRichEditor } from '@/registry/admin/ui/rich-editor'

const value = ref('')

// 空狀態 CSS 經 :ui.base 套到 editor content 元素
const placeholderClass = `
  [&_p.is-editor-empty:first-child]:before:pointer-events-none
  [&_p.is-editor-empty:first-child]:before:float-left
  [&_p.is-editor-empty:first-child]:before:h-0
  [&_p.is-editor-empty:first-child]:before:text-text-40
  [&_p.is-editor-empty:first-child]:before:content-[attr(data-placeholder)]
`
</script>

<template>
  <admin-rich-editor
    v-model="value"
    :extensions="[Placeholder.configure({ placeholder: '開始輸入內容…' })]"
    :ui="{ base: placeholderClass }"
  />
</template>
```

## 空狀態 CSS 說明

Placeholder extension 會在空節點加上 `is-editor-empty` class，並把 placeholder 文字放在 `data-placeholder` attr。上方片段以 `::before` 偽元素把該 attr 渲染出來。

- **僅首行**：用 `p.is-editor-empty:first-child`（如範例）
- **每一空行**：改用 `.is-empty`，並改注入 `Placeholder.configure({ showOnlyCurrent: false })`

顏色使用 admin design token `text-40`，可依需要調整。

## API 參考

`@tiptap/extension-placeholder` 套件 API 詳見 [tiptap placeholder 官方文件](https://tiptap.dev/docs/editor/extensions/functionality/placeholder){rel="&#x22;nofollow&#x22;"}。


# Editor TaskList

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/editor-task-list
pnpm add @tiptap/extension-task-list @tiptap/extension-task-item
```

```ts
import { TaskItem } from '@tiptap/extension-task-item'
import { TaskList } from '@tiptap/extension-task-list'
import { createTaskListHandler } from '@/registry/admin/ui/editor-task-list'
```

含 `createTaskListHandler`；待辦清單能力來自 tiptap `TaskList`／`TaskItem`，需自行注入。把 `TaskList` 與 `TaskItem.configure({ nested: true })` 傳入 `:extensions`、`createTaskListHandler` 經 `:handlers` 注入後，toolbar 可放 `{ kind: 'taskList' }` 按鈕（見下方用法）。

## 用法

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'
import { IconListCheck } from '@tabler/icons-vue'
import { TaskItem } from '@tiptap/extension-task-item'
import { TaskList } from '@tiptap/extension-task-list'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { createTaskListHandler, editorTaskListClass } from '@/registry/admin/ui/editor-task-list'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>(
  '<ul data-type="taskList"><li data-type="taskItem" data-checked="true">已完成的項目</li><li data-type="taskItem" data-checked="false">待辦項目</li></ul><p>選取段落後點 toolbar 的待辦清單鈕切換。</p>'
)

// opt-in：注入官方 TaskList / TaskItem extension 與 taskList handler
const extensions = [TaskList, TaskItem.configure({ nested: true })]
const handlers = { taskList: createTaskListHandler() }

const items: EditorToolbarItem[][] = [
  ...defaultEditorItems,
  [{ kind: 'taskList', icon: IconListCheck, label: '待辦清單', tooltip: { text: '待辦清單' } }]
]
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers: mergedHandlers }"
    v-model="value"
    :extensions="extensions"
    :handlers="handlers"
    :ui="{ base: cn(baseProseClass, starterKitProseClass, editorTaskListClass) }"
  >
    <admin-editor-toolbar :editor :handlers="mergedHandlers" :items="items" />
  </admin-rich-editor>
</template>
```

```vue
<script setup lang="ts">
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'
import { IconListCheck } from '@tabler/icons-vue'
import { TaskItem } from '@tiptap/extension-task-item'
import { TaskList } from '@tiptap/extension-task-list'
import { ref } from 'vue'
import { createTaskListHandler } from '@/registry/admin/ui/editor-task-list'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor } from '@/registry/admin/ui/rich-editor'

const value = ref('<ul data-type="taskList"><li data-type="taskItem" data-checked="true">已完成</li><li data-type="taskItem" data-checked="false">待辦</li></ul>')

const extensions = [TaskList, TaskItem.configure({ nested: true })]
const handlers = { taskList: createTaskListHandler() }
const items: EditorToolbarItem[][] = [
  ...defaultEditorItems,
  [{ kind: 'taskList', icon: IconListCheck, label: '待辦清單', tooltip: { text: '待辦清單' } }]
]
</script>

<template>
  <admin-rich-editor v-model="value" :extensions="extensions" :handlers="handlers">
    <admin-editor-toolbar :items="items" />
  </admin-rich-editor>
</template>
```

啟用後：

- `toggleTaskList` command 可用，toolbar 按鈕在其他 list type 上會自動互轉
- `indent` / `outdent` 對 task item 的縮排由 core 提供（`pickIndentTarget` 涵蓋 `taskItem`）
- 待辦清單的勾選框與排版樣式不內含於 registry，由使用者依需求自套（見 demo 的 `taskListContentClass`）

## API 參考

`@tiptap/extension-task-list` / `@tiptap/extension-task-item` 套件 API 詳見 [tiptap task-list 官方文件](https://tiptap.dev/docs/editor/extensions/nodes/task-list){rel="&#x22;nofollow&#x22;"}。

## 注意事項

- **extension 必須在建立編輯器時注入**：`TaskList` / `TaskItem` 無法於編輯器建立後補上，未注入時待辦清單內容會被 parser 丟掉。


# Editor Indent

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/editor-indent
```

```ts
import { createIndentHandlers, Indent } from '@/registry/admin/ui/editor-indent'
```

list 縮排可用 `Tab` / `Shift-Tab`（StarterKit）。本包補段落縮排：`Indent` extension 為 `paragraph` / `heading` 加上 `data-indent`；`createIndentHandlers` 含 indent／outdent handler，list 內走 `sinkListItem`／`liftListItem`，段落走 `data-indent`。

## 用法

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'
import { IconIndentDecrease, IconIndentIncrease } from '@tabler/icons-vue'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { createIndentHandlers, editorIndentClass, Indent } from '@/registry/admin/ui/editor-indent'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>(
  '<h2>段落縮排</h2><p>選取這段,點 toolbar 的增加縮排鈕。</p><p>list 縮排仍可直接用 Tab / Shift-Tab。</p><ul><li>清單項目(Tab 縮排)</li></ul>'
)

// opt-in：注入 Indent extension + 注入成對的 indent/outdent handler(dual-mode)
const extensions = [Indent]
const handlers = createIndentHandlers()

// 預設 toolbar（無縮排鈕）後面 append indent/outdent
const items: EditorToolbarItem[][] = [
  ...defaultEditorItems,
  [
    { kind: 'outdent', icon: IconIndentDecrease, label: '減少縮排', tooltip: { text: '減少縮排' } },
    { kind: 'indent', icon: IconIndentIncrease, label: '增加縮排', tooltip: { text: '增加縮排' } }
  ]
]
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers: mergedHandlers }"
    v-model="value"
    :extensions="extensions"
    :handlers="handlers"
    :ui="{ base: cn(baseProseClass, starterKitProseClass, editorIndentClass) }"
  >
    <admin-editor-toolbar :editor :handlers="mergedHandlers" :items="items" />
  </admin-rich-editor>
</template>
```

```vue
<script setup lang="ts">
import type { EditorToolbarItem } from '@/registry/admin/ui/editor-toolbar'
import { IconIndentDecrease, IconIndentIncrease } from '@tabler/icons-vue'
import { ref } from 'vue'
import { createIndentHandlers, Indent } from '@/registry/admin/ui/editor-indent'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor } from '@/registry/admin/ui/rich-editor'

const value = ref('<p>段落內容</p>')

const extensions = [Indent]
const handlers = createIndentHandlers()
const items: EditorToolbarItem[][] = [
  ...defaultEditorItems,
  [
    { kind: 'outdent', icon: IconIndentDecrease, label: '減少縮排', tooltip: { text: '減少縮排' } },
    { kind: 'indent', icon: IconIndentIncrease, label: '增加縮排', tooltip: { text: '增加縮排' } }
  ]
]
</script>

<template>
  <admin-rich-editor v-model="value" :extensions="extensions" :handlers="handlers">
    <admin-editor-toolbar :items="items" />
  </admin-rich-editor>
</template>
```

啟用後：

- `paragraph` / `heading` 縮排寫成 `data-indent="<n>"`（0–7，0 時省略 attribute）
- 同一顆 indent / outdent 按鈕，在 list 內縮排 list item、在段落調整 `data-indent`
- 縮到頂（7）或底（0）時按鈕自動 disabled
- 段落縮排不綁 `Tab`（避免劫持鍵盤焦點切換）；list 的 `Tab` / `Shift-Tab` 仍由 StarterKit 處理

## 樣式自套

`data-indent` 的視覺（左邊距）不內含於 registry，由使用者依需求自套 content class：

```ts
const indentContentClass = `
  [&_[data-indent='1']]:ml-[2rem] [&_[data-indent='2']]:ml-[4rem]
  /* …依級距 3–7 類推 */
`
```

## API 參考

- `Indent`：tiptap extension，為 `paragraph` / `heading` 補 `indent`（0–7）attribute（序列化為 `data-indent`），並提供段落的 `indent` / `outdent` command
- `createIndentHandlers(): { indent, outdent }`：成對的 indent / outdent handler，經 `<AdminRichEditor :handlers>` 注入


# Editor Mention Menu

## 安裝

```bash [Terminal] icon=i-lucide-terminal
pnpm dlx shadcn-vue add @admin/editor-mention-menu
```

```ts
import type { MentionMenuItem } from '@/registry/admin/ui/editor-mention-menu'
import { AdminEditorMentionMenu } from '@/registry/admin/ui/editor-mention-menu'
```

`admin-editor-mention-menu` 依賴 `@admin/rich-editor` + `@tiptap/extension-mention`。

::alert{title="裝完必須在 :extensions 注入 Mention" type="warning"}
`@tiptap/extension-mention` 是 Node extension，跟 suggestion / emoji 這類純 plugin 不同，它會動到 schema，而 schema 在編輯器建立時就固定、無法後補。`<AdminEditorMentionMenu>` mount 時會註冊 Suggestion plugin，popup 照常浮現，但 schema 沒有 mention node 時，選定後只能退回插入純文字 `@John`，`data-id` / `data-label` 等 attrs 不會持久化。
::

```ts
import Mention from '@tiptap/extension-mention'
const extensions = [
  Mention.configure({
    HTMLAttributes: { class: 'mention' },
    renderText: ({ node }) => `${node.attrs.mentionSuggestionChar ?? '@'}${node.attrs.label ?? node.attrs.id}`,
  }),
]

// <AdminRichEditor :extensions="extensions">
```

兩個設定都是建議值，不是必填。`renderText` 決定序列化與複製貼上的文字輸出，未設定時沿用 tiptap 預設的 `@label`，設定後可改成以觸發字元開頭；`class: 'mention'` 讓慣用的 `.mention` CSS 有地方掛（本文件 demo 的 chip 樣式改以 `data-type` 屬性選取，不依賴它）。

## 用法

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import type { MentionMenuItem } from '@/registry/admin/ui/editor-mention-menu'
import Mention from '@tiptap/extension-mention'
import { ref } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { AdminEditorMentionMenu } from '@/registry/admin/ui/editor-mention-menu'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>('<p>輸入 @ 觸發 mention menu(例如 @john)</p>')

const users: MentionMenuItem[] = [
  { id: 'u1', label: 'John', avatar: 'https://i.pravatar.cc/24?u=u1' },
  { id: 'u2', label: 'Jane', avatar: 'https://i.pravatar.cc/24?u=u2' },
  { id: 'u3', label: 'Alex', avatar: 'https://i.pravatar.cc/24?u=u3' },
  { id: 'u4', label: 'Sam', avatar: 'https://i.pravatar.cc/24?u=u4' }
]

// 必須自行注入配置好的 Mention extension 讓 schema 認識 mention node（完整持久化）。
// `renderText` 與 `HTMLAttributes.class` 為建議配置：
//   - renderText 讓序列化 / 複製貼上沿用觸發字元（未設定時 Tiptap 預設輸出 `@label`）
//   - class: 'mention' 供慣用 .mention CSS 掛載（chip 樣式本 demo 以 data-type 屬性選取，不依賴它）
const extensions = [
  Mention.configure({
    HTMLAttributes: { class: 'mention' },
    renderText: ({ node }) =>
      `${node.attrs.mentionSuggestionChar ?? '@'}${node.attrs.label ?? node.attrs.id}`
  })
]

// mention chip 樣式不內含於 registry，由使用者依需求自套
const mentionChipClass = `
  **:data-[type=mention]:inline-block **:data-[type=mention]:cursor-default
  **:data-[type=mention]:rounded-[4px] **:data-[type=mention]:bg-info-10
  **:data-[type=mention]:px-1.5 **:data-[type=mention]:py-0.5 **:data-[type=mention]:text-sm
  **:data-[type=mention]:font-medium **:data-[type=mention]:text-info-70
  **:data-[type=mention]:select-none
`
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers }"
    v-model="value"
    :extensions="extensions"
    :ui="{ base: cn(baseProseClass, starterKitProseClass, mentionChipClass) }"
  >
    <admin-editor-toolbar :editor :handlers="handlers" :items="defaultEditorItems" />
    <admin-editor-mention-menu :editor :items="users" />
  </admin-rich-editor>
</template>
```

```vue
<script setup lang="ts">
import Mention from '@tiptap/extension-mention'
import { ref } from 'vue'
import { AdminEditorMentionMenu } from '@/registry/admin/ui/editor-mention-menu'
import { AdminRichEditor } from '@/registry/admin/ui/rich-editor'

const value = ref('')
const users = [
  { id: 'u1', label: 'John' },
  { id: 'u2', label: 'Jane' }
]

// mention node 要能持久化，務必在 :extensions 加配置好的 Mention
const extensions = [
  Mention.configure({
    HTMLAttributes: { class: 'mention' },
    renderText: ({ node }) => `${node.attrs.mentionSuggestionChar ?? '@'}${node.attrs.label ?? node.attrs.id}`,
  }),
]
</script>

<template>
  <admin-rich-editor v-slot="{ editor }" v-model="value" :extensions="extensions">
    <admin-editor-mention-menu :editor :items="users" />
  </admin-rich-editor>
</template>
```

## MentionMenuItem 介面

```ts
interface MentionMenuItem {
  id: string | number
  label: string
  avatar?: string
  [key: string]: unknown // 任意 metadata
}
```

選定後，mention node 的 `attrs` 會展開整個 item 物件（外加 `mentionSuggestionChar: '@'`），讓 `renderText` / `renderHTML` 讀得到任意欄位。

### attrs 持久化注意

存進 DB 的 HTML 形如：

```html
<span data-type="mention" data-id="u1" data-label="John">@John</span>
```

item 建議只放 id、label 和很小的 metadata（部門代號、role 等）；avatar URL、長描述這類欄位改用 `id` 在顯示時二次查詢補上，避免內容膨脹、拖慢序列化。

## 非同步搜尋

```vue
<script setup lang="ts">
import type { JSONContent } from '@tiptap/core'
import type { MentionMenuItem } from '@/registry/admin/ui/editor-mention-menu'
import Mention from '@tiptap/extension-mention'
import { ref, watch } from 'vue'
import { cn } from '@/lib/utils'
import { baseProseClass } from '@/registry/admin/ui/editor'
import { AdminEditorMentionMenu } from '@/registry/admin/ui/editor-mention-menu'
import { AdminEditorToolbar, defaultEditorItems } from '@/registry/admin/ui/editor-toolbar'
import { AdminRichEditor, starterKitProseClass } from '@/registry/admin/ui/rich-editor'

const value = ref<JSONContent | string>('<p>輸入 @ 觸發 mention menu(非同步搜尋 — 模擬 API)</p>')
const searchTerm = ref('')

const ALL_USERS: MentionMenuItem[] = [
  { id: 'u1', label: 'John' },
  { id: 'u2', label: 'Jane' },
  { id: 'u3', label: 'Alex' },
  { id: 'u4', label: 'Sam' },
  { id: 'u5', label: 'Emily' },
  { id: 'u6', label: 'Michael' }
]

// 初始給全部 users（模擬 API 預載清單），讓 `@` 一觸發 popup 就有東西
const results = ref<MentionMenuItem[]>(ALL_USERS)

// 模擬非同步 API（延遲 200ms）
let fetchTimer: ReturnType<typeof setTimeout> | null = null
watch(searchTerm, (q) => {
  if (fetchTimer) {
    clearTimeout(fetchTimer)
  }
  fetchTimer = setTimeout(() => {
    const ql = q.toLowerCase()
    results.value = ql ? ALL_USERS.filter((u) => u.label.toLowerCase().includes(ql)) : ALL_USERS
  }, 200)
})

const extensions = [Mention]

// mention chip 樣式不內含於 registry，由使用者依需求自套
const mentionChipClass = `
  **:data-[type=mention]:inline-block **:data-[type=mention]:cursor-default
  **:data-[type=mention]:rounded-[4px] **:data-[type=mention]:bg-info-10
  **:data-[type=mention]:px-1.5 **:data-[type=mention]:py-0.5 **:data-[type=mention]:text-sm
  **:data-[type=mention]:font-medium **:data-[type=mention]:text-info-70
  **:data-[type=mention]:select-none
`
</script>

<template>
  <admin-rich-editor
    v-slot="{ editor, handlers }"
    v-model="value"
    :extensions="extensions"
    :ui="{ base: cn(baseProseClass, starterKitProseClass, mentionChipClass) }"
  >
    <admin-editor-toolbar :editor :handlers="handlers" :items="defaultEditorItems" />
    <admin-editor-mention-menu
      v-model:search-term="searchTerm"
      ignore-filter
      :editor
      :items="results"
    />
  </admin-rich-editor>
</template>
```

users 來自後端 API、前端不適合全載時，用 `v-model:search-term` 雙向綁定搜尋字串，並加 `ignore-filter` 跳過內建的 fuzzy filter：

```vue
<script setup lang="ts">
import Mention from '@tiptap/extension-mention'
import { ref } from 'vue'

const search = ref('')
const { data: users } = await useFetch('/api/users', {
  query: { q: search }
})
const extensions = [
  Mention.configure({
    HTMLAttributes: { class: 'mention' },
    renderText: ({ node }) => `${node.attrs.mentionSuggestionChar ?? '@'}${node.attrs.label ?? node.attrs.id}`,
  }),
]
</script>

<template>
  <admin-rich-editor v-slot="{ editor }" v-model="value" :extensions="extensions">
    <admin-editor-mention-menu
      v-model:search-term="search"
      ignore-filter
      :editor
      :items="users ?? []"
    />
  </admin-rich-editor>
</template>
```

`search` 變動時 `useFetch` 會自動重打 API。

## 鍵盤導航

同 [Editor Suggestion Menu](https://component-registry-4d4d86.gitlab.io/docs/editor/addons/suggestion#%E9%8D%B5%E7%9B%A4%E5%B0%8E%E8%88%AA)。

## 樣式

mention chip 樣式不內含於 registry，由使用者依需求自套。demo 以 `**:data-[type=mention]:*` utility class 注入編輯器容器（見「用法」demo 原始碼的 `mentionChipClass` 常數，色票對齊 admin design tokens），也可以改用 CSS 選取 `[data-type='mention']` 自寫：

```css
:deep([data-type='mention']) {
  /* 自訂樣式 */
}
```

## API 參考

### admin-editor-mention-menu

::div{data-admin-api-table=""}
#### Props

| 名稱             | 型別                                        | 預設值                   | 說明                                                                            |
| -------------- | ----------------------------------------- | --------------------- | ----------------------------------------------------------------------------- |
| `editor`\*     | `Editor`                                  | —                     | tiptap Editor instance（必填）                                                    |
| `items`\*      | `MentionMenuItem[] | MentionMenuItem[][]` | —                     | 候選清單（可為扁平或分組陣列）                                                               |
| `char`         | `string | undefined`                      | `"@"`                 | 觸發字元，預設 \`@\`                                                                 |
| `pluginKey`    | `string | undefined`                      | `"editorMentionMenu"` | PM plugin key，預設 \`editorMentionMenu\`                                        |
| `limit`        | `number | undefined`                      | `10`                  | 顯示筆數上限，預設 10                                                                  |
| `filterFields` | `string[] | undefined`                    | `["label"]`           | filter 比對欄位，預設 \`\['label']\`                                                 |
| `ignoreFilter` | `boolean | undefined`                     | `false`               | true 時跳過內建 fuzzy filter（外部已 filter — 典型搭配 \`v-model\:searchTerm\` + useFetch） |
| `class`        | `ClassValue`                              | —                     | —                                                                             |
| `searchTerm`   | `string | undefined`                      | `""`                  | —                                                                             |

*\\\* 代表必填*

#### Events

| 名稱                  | Payload  | 說明 |
| ------------------- | -------- | -- |
| `update:searchTerm` | `string` | —  |
::

## 更新紀錄

:admin-changelog{component="AdminEditorMentionMenu"}


# 介紹

Admin Registry 是 shadcn-vue registry：用 CLI 把元件原始碼複製進專案，不是安裝成 npm 套件。

與 shadcn-vue 官方集合的差異：

- 元件以 `admin-` 為字首，樣式用 `tailwind-variants`
- 使用設計系統 color tokens（`primary-*`、`secondary-*`、`text-*`、`bg-*`、`success-*`、`info-*`、`warning-*`、`error-*`）與 typography utilities（`typo-*`）
- 尺寸以 `rem` 為主

## 下一步

- [安裝](https://component-registry-4d4d86.gitlab.io/docs/get-started/installation)
- [主題](https://component-registry-4d4d86.gitlab.io/docs/get-started/theming) — color palette 與 typography utilities
- [元件](https://component-registry-4d4d86.gitlab.io/docs/components)


# 安裝

## 先決條件

Node.js 22 以上。shadcn-vue 2.8.2 需 Node ≥ 22；Node 20 執行 CLI 會出現 `undici` 錯誤。

專案需已完成 shadcn-vue 設定，且 `components.json` 的 `iconLibrary` 為 `tabler`：

- [Vite](https://shadcn-vue.com/docs/installation/vite){rel="&#x22;nofollow&#x22;"}
- [Nuxt](https://shadcn-vue.com/docs/installation/nuxt){rel="&#x22;nofollow&#x22;"}

`@admin` 元件直接 import `@tabler/icons-vue`。shadcn-vue CLI 會依 `iconLibrary`，把 registry `dependencies` 裡已知的 icon 套件換成該設定對應的套件。未指定時預設是 `lucide`，此時不會改寫這些 import，因此 `add @admin/dialog` 等元件後 build 會找不到 `@tabler/icons-vue`。

尚未初始化時：

```bash
pnpm dlx shadcn-vue init --icon-library tabler
```

完成後確認 `components.json` 含：

```json
{
  "iconLibrary": "tabler"
}
```

### 已是 lucide 或已有 components.json

把 `iconLibrary` 改成 `"tabler"`，再執行 `pnpm dlx shadcn-vue add`。CLI 才會安裝 `@tabler/icons-vue`。

元件已經寫入、build 仍找不到套件時：

```bash
pnpm add @tabler/icons-vue
```

## 設定 Registry

在根目錄 `components.json` 加入 `@admin`，並保留 `iconLibrary`：

```json
{
  "iconLibrary": "tabler",
  "registries": {
    "@admin": {
      "url": "https://component-registry-4d4d86.gitlab.io/r/styles/admin/{name}.json"
    }
  }
}
```

### Registry 授權

目前 `@admin` 網址免授權即可讀取。若之後改為需授權，在 `@admin` 加 `headers`，並在環境變數設定 `REGISTRY_TOKEN`：

```json
{
  "registries": {
    "@admin": {
      "url": "https://component-registry-4d4d86.gitlab.io/r/styles/admin/{name}.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}
```

## 安裝設計系統樣式

```bash
pnpm dlx shadcn-vue add @admin/style
```

::alert{title="會覆寫 utils 檔" type="warning"}
`@admin/style` 含 `cn` 的 utils 檔，路徑依 `components.json` 的 `aliases.utils`（Nuxt 常見為 `app/lib/utils.ts`）。該檔已存在時，CLI 會詢問是否覆寫，預設為否（略過）；回答是或加 `-o` 會覆寫。專案的 utils 有自訂內容時，請先備份或確認差異，要覆寫再加 `-o`（`pnpm dlx shadcn-vue add @admin/style -o`）。
::

驗證：專案應能解析 admin color tokens 與 `typo-*`；細節見 [主題](https://component-registry-4d4d86.gitlab.io/docs/get-started/theming)。

## Agent skill（可選）

要以 AI agent 依 Setup／Install／Compose 操作 `@admin` 時，見 [Agent skill](https://component-registry-4d4d86.gitlab.io/docs/ai/skills)。

## 安裝元件

```bash
pnpm dlx shadcn-vue add @admin/button
```

一次多個：

```bash
pnpm dlx shadcn-vue add @admin/button @admin/input @admin/dialog
```

驗證：對應元件出現在 `components.json` 設定的 components 目錄（常見為 `@/components/admin/`）。

## SSR（Nuxt）

元件本身不包 `<ClientOnly>`，純 Vue 3 專案可直接用。

不支援 SSR 的元件（依賴 DOM、canvas、WASM）在 Nuxt 自行包：

```vue
<template>
  <client-only>
    <admin-vxe-table :columns="columns" :data="data" />
    <template #fallback>
      <!-- 可選：骨架或 loading -->
    </template>
  </client-only>
</template>
```

### 元件同名警告 NUXT\_B3011

安裝 `@admin/button`、`@admin/dialog` 等元件後，Nuxt build 可能出現：

```text
[NUXT_B3011] Two component files resolving to the same name AdminButton
```

原因：Nuxt 預設會把 `.ts` 也當成元件掃描，元件資料夾裡的 `index.ts`（barrel 匯出檔）會被解析成與 `admin-button.vue` 同名的元件。這只是警告，不影響 build 與執行。在 `nuxt.config.ts` 設定只掃描 `.vue` 檔即可避開：

```ts
export default defineNuxtConfig({
  components: {
    dirs: [{ path: '~/components', extensions: ['.vue'] }]
  }
})
```

已使用 `shadcn-nuxt` 的專案，也可以把兩個目錄都列進 `componentDir`（兩個都要列，只列 `@/components/admin` 會讓 `ui` 目錄出現同樣的警告）：

```ts
export default defineNuxtConfig({
  shadcn: {
    prefix: '',
    componentDir: ['@/components/ui', '@/components/admin']
  }
})
```


# 主題

## 色彩 (Semantic Colors)

:semantic-colors-preview

- `primary-{10-90}`：主要操作、強調、互動焦點
- `secondary-{10-90}`：次要品牌色、輔助區塊
- `text-{10-90}`：標題、段落、輔助文字
- `bg-{10-90}`：畫布、卡片、巢狀 surface
- `success`／`info`／`warning`／`error`：回饋、狀態、驗證

用法例：`text-primary-50`、`bg-success-10`、`border-error-60`（會隨上方 preview 切換）。

## Typography Utilities

:typography-utilities-preview


# Type-safe

部分 admin 元件的 `modelValue` 在 compile-time 不會與呼叫端期望的較嚴型別對齊。元件文件的「Type-safe 封裝」章節提供可複製的封裝範例與驗證 demo。

**文件站不會顯示這些型別錯誤。** 錯誤只會出現在呼叫端專案：安裝元件、複製程式碼，並開啟下方檢查之後，由編輯器或 `vue-tsc` 標出。

## 要看到錯誤須具備

1. **安裝對應 `@admin` 元件**到呼叫端專案（見各元件文件的「安裝」）。
2. **複製**該頁「Type-safe 封裝」的封裝範例與驗證 demo 到專案（或等價自行撰寫）。
3. **開啟** `strictVModel`（或已包含此檢查的 `strictTemplates`）。

## 開啟檢查

於呼叫端專案的 `tsconfig`（或 `jsconfig`）設：

```json
{
  "vueCompilerOptions": {
    "strictVModel": true
  }
}
```

若已開啟 `strictTemplates`，則已包含 `strictVModel`，不必再設。

未開啟時，驗證 demo 仍可閱讀；刻意錯誤的綁定不會被標為型別錯誤。


# Headed UI

文件頁、sidebar 或元件總覽出現 `Headed UI` badge，代表該元件包裝的第三方套件**自帶 DOM 結構與互動**。內部結構與行為由上游決定，admin 改不動。

多數 admin 元件包的是只給邏輯、不畫 UI 的套件（reka-ui、vidstack engine、embedpdf、cropperjs 等），DOM 由 admin 自寫，沒有此標記。

| 維度                     | 一般 admin 元件 | Headed UI      |
| ---------------------- | ----------- | -------------- |
| DOM 結構與內部互動            | admin 自寫    | 上游決定、admin 改不動 |
| props / events / slots | admin 介面為主  | 大量透傳上游介面       |
| Bug 與行為差異              | admin 端可修   | 多數需追上游版本       |

## 使用注意

### API 多在上游

該頁 API 參考表**只列 admin 額外擴充或覆寫的欄位**，不列上游透傳的 props / events / slots。

完整介面：點頁面右上角 **參考** 跳上游文件。例：[Vxe Table](https://component-registry-4d4d86.gitlab.io/docs/admin/vxe-table) → [vxe-table API](https://vxetable.cn/v4/table/api){rel="&#x22;nofollow&#x22;"}。

### Bug 先分清來源

- admin 自加 prop / event / slot → 開 issue 到本 repo
- 上游套件本身 → 先查上游 issue tracker；已知問題可能需等上游修