# Floating Label Frame

`floating-label-frame` 是 daisyUI 5 `floating-label` 的選用擴充。它以分段裝飾層繪製標籤前後框線，標籤背景保持透明，因此不需要用 `base-100` 遮住欄位框線。

內框與 focus 外框都採分段繪製，因此兩層框線都會在標籤左右真正中斷。`floating-label-frame-outline` 是純裝飾層，必須保留 `aria-hidden="true"`。分段外框使用 CSS subgrid；不支援 subgrid 的舊瀏覽器會安全退回 daisyUI 原生完整 outline，仍保有可見的鍵盤 focus。

## 基本使用

```html
<label class="floating-label floating-label-frame">
   <input type="text" class="input w-full" placeholder="請輸入姓名">
   <span class="floating-label-frame-box">
      <span class="floating-label-frame-outline" aria-hidden="true"></span>
      <span class="floating-label-frame-text">姓名</span>
   </span>
</label>
```

請同時使用 `floating-label` 與 `floating-label-frame`。擴充樣式不會影響未加入 `floating-label-frame` 的 daisyUI 原生 Floating Label。

`input` 與 `textarea` 若要在空白時把標籤顯示於欄位內，必須提供 `placeholder`。可以填入真正的提示文字；欄位取得 focus 後才會顯示 placeholder。若省略 placeholder，標籤會維持浮起狀態。

## Fieldset

```html
<fieldset class="fieldset">
   <legend class="fieldset-legend">聯絡資料</legend>

   <label class="floating-label floating-label-frame">
      <input type="email" class="input w-full" placeholder="name@example.com">
      <span class="floating-label-frame-box">
         <span class="floating-label-frame-outline" aria-hidden="true"></span>
         <span class="floating-label-frame-text">電子郵件</span>
      </span>
   </label>

   <p class="fieldset-label">我們不會公開您的電子郵件。</p>
</fieldset>
```

`.fieldset`、`.fieldset-legend` 與 `.fieldset-label` 保持 daisyUI 原有用途；不要把 `fieldset-label` 加到浮動標籤框線層。

## 搭配 Field Soft

`field-soft` 可直接加入欄位，Floating Label Frame 會沿用其 35% 柔和框線與 12% focus 外框色彩。由於 CSS 原生 `outline` 無法分段，元件會把 input 的實際 outline 設為透明，再以 `floating-label-frame-outline` 按照 daisyUI 預設的 2px 寬度與 2px offset 繪製相同外框。

```html
<label class="floating-label floating-label-frame">
   <input type="text" class="input field-soft w-full" placeholder="請輸入姓名">
   <span class="floating-label-frame-box">
      <span class="floating-label-frame-outline" aria-hidden="true"></span>
      <span class="floating-label-frame-text">姓名</span>
   </span>
</label>
```

## 搭配右側按鈕（Join）

需要密碼顯示、撥打電話或開啟地圖等欄位操作時，可在 daisyUI `join` 上加入 `floating-label-frame-join`。input 與右側按鈕各自加入 `join-item`；按鈕必須放在 `label` 外，讓兩個控制項保有各自的語意與鍵盤 focus。

```html
<div class="floating-label-frame-join join w-full">
   <label class="floating-label floating-label-frame">
      <input type="password" class="input field-soft join-item w-full" placeholder="請輸入密碼">
      <span class="floating-label-frame-box">
         <span class="floating-label-frame-outline" aria-hidden="true"></span>
         <span class="floating-label-frame-text">密碼</span>
      </span>
   </label>
   <button type="button" class="btn join-item">顯示</button>
</div>
```

`floating-label-frame-join` 會讓按鈕只對齊實際欄位高度，並把 Frame 接近按鈕的一端改為方角。按鈕行為由應用程式的 JavaScript 負責；元件 CSS 不會改變 input 的值或類型。

## 支援範圍

- 直接子元素形式的 daisyUI `input`、`textarea`、`select`
- `input-xs` 至 `input-xl`，以及對應的 textarea/select 尺寸
- `neutral`、`primary`、`secondary`、`accent`、`info`、`success`、`warning`、`error` 語意色
- focus、已輸入、readonly、disabled、`aria-invalid="true"` 與瀏覽器自動填入
- daisyUI `join` 搭配右側按鈕或連結
- daisyUI themes、RTL、forced colors 與 reduced motion

checkbox、radio、toggle、range、file input 不適合使用 Floating Label。Select2 等會重建 DOM 的第三方選單套件需要獨立 adapter，不屬於核心 CSS。

## CSS 變數

### daisyUI 與 UI Components 的責任邊界

Floating Label Frame 會沿用 daisyUI theme 的 `--color-*`、`--radius-field` 與 `--border`。下表中以 `--uic-` 開頭的變數全是 UI Components 自有的擴充，不是 daisyUI 5 要求的 theme 參數，也不會影響未使用 `floating-label-frame` 的 daisyUI 元件。

其中 `--uic-floating-label-frame-border`、`--uic-floating-label-frame-focus-border`、`--uic-floating-label-frame-outline-border` 是 theme 層級的實色框線 token。套件 standalone 的 `light`、`dark` theme 已經提供；source-first 的自訂 theme 建議逐一設定。若未設定，元件仍會依目前 theme 的 `base-content` 與 `base-100` 使用相同公式 fallback，不會形成破壞性變更。

| 變數 | 預設值 | 用途 |
| --- | --- | --- |
| `--uic-floating-label-idle-color` | `base-content` 20% | 未取得 focus 的框線顏色 |
| `--uic-floating-label-focus-color` | `base-content` | focus 框線與標籤顏色 |
| `--uic-floating-label-frame-border` | `base-content` 7% 預混 `base-100` | Field Soft 未 focus 的實色框線 |
| `--uic-floating-label-frame-focus-border` | `base-content` 35% 預混 `base-100` | Field Soft focus 內框實色 |
| `--uic-floating-label-frame-outline-border` | `base-content` 12% 預混 `base-100` | Field Soft focus 外框實色 |
| `--uic-floating-label-idle-text-color` | `base-content` 60% | 已浮起但未 focus 的標籤顏色 |
| `--uic-floating-label-duration` | `180ms` | 標籤與框線過渡時間 |
| `--uic-floating-label-easing` | `ease-out` | 過渡曲線 |
| `--uic-floating-label-scale` | `0.94` | 標籤浮起後的縮放比例 |
| `--uic-floating-label-outline-width` | `2px` | 分段 focus 外框寬度，對應 daisyUI input outline |
| `--uic-floating-label-outline-offset` | `2px` | 分段 focus 外框與欄位的距離 |
| `--uic-floating-label-reserved-space` | `字級 × 1.25` | 為浮起標籤與 focus outline 預留的上方空間 |

三個 Field Soft 框線 token 必須是不透明色，建議直接使用文件列出的 `color-mix(..., var(--color-base-100))` 公式，或填入已預混完成的實色。左右半框負責上、側、下三條邊與圓角，共用底線則補齊標籤下方的中段；兩者在底部圓角處會重疊。實色能讓重疊處維持相同顏色，透明色則會因二次合成而變深。

focus 時，`floating-label-frame-outline` 本身繪製帶圓角的共用底線，`::before` 與 `::after` 分別繪製完整左右半框。內框採用相同架構，讓 `--radius-field` 隨 daisyUI theme 改變時，底線與左右圓角仍保持對齊。語意色欄位會自動以相同強度將對應 semantic color 預混至 `base-100`。標籤浮起後維持原本字級來源，字重改為 500；placeholder 在 focus 時保持原尺寸。