# Number Stepper／數值步進器

自 UI Components 0.4.0 起提供原生 JavaScript 數值步進器。使用者於 2026-10-27 依「欄位 focus 移除深色外框、數字欄位聚焦全選、長按預設開啟」三項條件確認正式收錄；完整試作歷史見 [Lab 紀錄](number-stepper-lab.md)。正式展示為 `demo/number-stepper.html`，回歸為 `ui-lab/number-stepper.html`，共用同一核心與頁面來源。

## 安裝與標記

已使用 `ui-components/source.css` 或 standalone 時包含元件 CSS 與共用 [Field Focus](field-focus.md)。按需載入則使用 `ui-components/components/number-stepper.css`，需要共用 focus 樣式時另匯入 `ui-components/components/field-focus.css`；消費端須有 daisyUI input／button／join。

```html
<div class="number-stepper" id="quantity-stepper">
   <label for="quantity">數量</label>
   <div class="join">
      <button type="button" class="btn join-item" data-step="-1" aria-label="減少數量">−</button>
      <input type="number" inputmode="numeric" class="input join-item"
         id="quantity" name="quantity" value="0" min="0" max="100" step="1"
         aria-describedby="quantity-error">
      <button type="button" class="btn join-item" data-step="1" aria-label="增加數量">＋</button>
   </div>
   <p id="quantity-error" data-stepper-error aria-live="polite"></p>
</div>
<script src="./dist/number-stepper.js"></script>
<script>
   const oQuantity = window.UicNumberStepper.create(document.getElementById('quantity-stepper'));
</script>
```

ESM 用法：

```js
import UicNumberStepper from 'ui-components/number-stepper';
const oQuantity = UicNumberStepper.create(document.getElementById('quantity-stepper'), {
   hold: true,
   wheel: false
});
```

ESM wrapper 使用瀏覽器 `window`，與既有元件相同，不提供 SSR 初始化。傳統 bundle 重複載入不覆寫已存在全域；同一容器重複 create 回傳同實例，不增加事件。先 destroy 才能以新 min／max／step 重新初始化。

## 尺寸（0.6.0）

使用 daisyUI 原生尺寸 class，中央 input 與兩側 button 須採相同尺寸；不需要新增 JavaScript 選項。切換為純數值顯示時，output 沿用 input 的 class，因此尺寸一致。

| 尺寸 | 中央欄位 | 兩側按鈕 | 預設主題高度 |
| --- | --- | --- | --- |
| xs | input-xs | btn-xs | 24px |
| sm | input-sm | btn-sm | 32px |
| md（預設） | input-md | btn-md | 40px |
| lg | input-lg | btn-lg | 48px |
| xl | input-xl | btn-xl | 56px |

以上高度以專案預設主題及 16px 根字級量測，會隨主題的 size-field 或根字級調整。未指定尺寸時採原生 md；0.6.0 移除舊有 44px 最小高度及按鈕 48px 最小寬度，因此既有預設外觀在預設主題下回歸 40px。整組寬度仍沿用既有 20rem 上限與可縮小布局，不隨尺寸另行放大。

例如小尺寸：

```html
<div class="join">
   <button type="button" class="btn btn-sm join-item" data-step="-1" aria-label="減少數量">−</button>
   <input type="number" class="input input-sm join-item" aria-label="數量" value="30" min="0" max="100" step="1">
   <button type="button" class="btn btn-sm join-item" data-step="1" aria-label="增加數量">＋</button>
</div>
```

以上 join 放在既有 number-stepper 容器內，初始化方式不變。五種尺寸的共用展示位於 `number-stepper.html#sizes`；確認範圍見 [尺寸試作紀錄](number-stepper-size-lab.md)。

## 手動輸入切換（0.5.2 修訂）

預設 `manualInput: true`，維持既有直接輸入與聚焦全選；建立時傳入 `{ manualInput: false }`，或呼叫 `setManualInput(false)`，可限制使用者僅透過＋／－按鈕調整。按鈕 Enter／空白鍵與長按仍可用；欄位上的打字、貼上、方向鍵及滾輪均不能改值。

自 0.5.2 起，此模式在原位置顯示非編輯的 `<output>`，沿用正常字色、底色、尺寸與一般箭頭；滑鼠、Tab 或程式 focus() 均不會進入數值區。原 number input 以 hidden 隱藏，保留 name、form、數值及驗證規則，仍是唯一表單值來源；不建立第二個同名欄位，也不為限制輸入而設定 readonly／disabled。＋／－按鈕維持可用。原先 disabled、父 fieldset disabled 或整組 readonly 的限制仍優先；真正停用的欄位不參與 FormData。外部程式可用 setDisabled() 管理整體停用，以 isDisabled() 判斷包含父 fieldset 的停用狀態。此模式不是權限機制，程式 setValue()、reset() 仍可更新數值。

關閉時停止目前長按並放棄未提交草稿，回到上一有效值、清除草稿錯誤，不因切換派發數值事件；已在欄位中的焦點會移出。畫面點選 checkbox 前，合法輸入仍依原生 blur 先結算。切回允許或 destroy 時移除 output，恢復原 input 的 hidden 狀態；切回允許後恢復既有輸入操作，不自動搶回焦點。元件不接管 readonly／disabled，保留 setDisabled() 最新設定。

「重設表單」及 API reset 只重設數值，保留模式；「重設全部試作」將模式恢復開啟。試作與確認歷史見 [手動輸入切換紀錄](number-stepper-manual-input-lab.md)及 [數值顯示模式紀錄](number-stepper-display-lab.md)。

## 數值契約（0.7.0 小數與負數）

- 使用原生 min／max／step 設定，預設 min=0、step=1 保持非負整數行為。min<0 才允許負值，step 必須大於 0；不支援 step=any。
- 以 min 為步距起點，包含負數與小數；例如 min=0.05、step=0.1，可用值為 0.05、0.15、0.25。max=0.34 時，加號停在 0.25；手填 0.3 會被拒絕，不自動四捨五入。
- 依 min／max／step 的小數位數決定精度，尾端的 0 不增加精度。最多 15 位小數；使用 BigInt 整數單位計算，輸出普通十進位字串，避免連續加 0.1 累積尾數誤差。
- 保留 Number 型別的 getValue／事件值。為維持十進位值與 Number API 的往返一致，小數模式的整數單位絕對值上限為 999999999999999；例如精度 2 時，最大絕對值為 9999999999999.99。未設定 max 時採該精度上限；純整數模式仍以 Number.MAX_SAFE_INTEGER 為上限。超過可用精度／範圍的設定會在初始化拒絕，不偷偷捨入。
- 字串接受完整十進位，例如 0.5、-0.5、001.50；不接受正號、空白、千分位、科學記號、只有負號、`.5` 或 `1.`。數值型 API 參數可用 1e-7（已是 Number），但字串 "1e-7" 不接受。負零顯示為 0，去除無意義尾零。
- 原生 number 輸入可能把未完成文字讀成空字串；保持現有驗證與 Escape 回復，不轉成別的數值。0.1+0.2 的 API 結果 0.30000000000000004 會被拒絕，不以寬鬆容差接受。
- 不新增 allowNegative 開關，由 min 統一控制；輸入、貼上、API、按鈕、方向鍵、長按、滾輪共用同一驗證。全選、純顯示、真正停用／唯讀、重設與 destroy 沿用原行為。


例如半單位數值使用 `min="0" max="10" step="0.5" value="0.5"`；允許負半單位使用 `min="-2" max="2" step="0.5" value="-0.5"`。其他 HTML 結構及初始化方式不變。正小數可用 `inputmode="decimal"`；負數範例採 `inputmode="text"` 以保留負號輸入機會，實體手機鍵盤仍須設備驗證。

正式與 Lab 展示的 `#decimals` 提供六組範例、模擬 FormData／Number API 與可重設的本機資料。確認歷史見 [小數與負數紀錄](number-stepper-decimal-lab.md)。

## 焦點、鍵盤與長按

可編輯數字欄位每次取得焦點呼叫原生 `select()` 全選；第一次滑鼠 mouseup 保留全選，已聚焦後再次點選不強迫全選，方便移動游標。Tab 取得焦點同樣全選，readonly／disabled 不強制選取。

長按加速預設開啟，`hold: false` 可關閉；滾輪仍預設關閉。按鈕短按使用原生 click，Enter／空白鍵各一步；↑／↓ 一步，PageUp／PageDown 或 Shift＋方向鍵十步。長按延遲 400ms，後續間隔逐步縮短至 60ms，第 13／26 次起倍率為 5／10。關閉長按時忽略鍵盤 repeat。

keyup、pointerup／cancel／離開按鈕、輸入或按鈕失焦、視窗失焦、分頁隱藏、API 停用／重設／destroy 都停止 timer。長按按鈕的尾端 click 不雙增。

`wheel: true` 只在輸入聚焦時生效；每個非零 wheel 事件一步，Shift 十步。聚焦時即使 wheel 關閉也攔截預設滾輪，以阻止原生 number 自行改值；輸入上不會捲頁，移出後可正常捲頁。

## API 與事件

| 方法 | 行為 |
| --- | --- |
| `getValue()` | 目前有效值，非法／空白／destroy 後為 null。 |
| `setValue(value, notify = false)` | 合法則 true，非法或 destroy 後 false；拒絕時原輸入與訊息不變。可程式化更新 disabled／readonly，與原生賦值一致。 |
| `reset(notify = false)` | 回初始化值，包含 0；不修改 disabled／readonly。原生 form reset 也同步；取消 reset 時保留原狀。 |
| `setDisabled(boolean)`／`isDisabled()` | 切換 input／按鈕並停止 timer；isDisabled 也辨識父 fieldset。 |
| `setManualInput(boolean)` | 切換手動輸入；有效實例回 true，destroy 後 false。 |
| `isManualInputAllowed()` | 回報目前是否實際允許直接輸入；disabled／原生 readonly／destroy 後也為 false。 |
| `setOptions({ hold, wheel, manualInput })` | 停止 timer；hold 未提供時 true，wheel 未提供時 false；manualInput 未提供時保留目前模式。 |
| `validate()` | 驗證草稿、更新錯誤與有效值，回傳 boolean。 |
| `destroy()` | 冪等移除事件及 timer、清除實例快取與候選錯誤、還原按鈕原 disabled；保留 input 目前值／disabled，可重新初始化。 |

每次有效值實際變更，派發 bubbling `uic:number-stepper:change`，detail 為 `{ name, value, previousValue, source }`；source 包含 `button`、`keyboard`、`wheel`、`paste`、`input`、`api`。長按可連續發事件，不等放開；靜默 API 與值未變時不發。它不代替原生 input/change，也不自動送出表單。

表單提交時先對未停用欄位呼叫 validate，再使用 FormData／fetch；後端仍要驗證範圍、權限與業務規則。展示頁的 submit 已 preventDefault，使用本機 Promise<Response> 模擬 JSON 200／422／離線，完全不呼叫真實網路。送出中停用重複送出；失敗保留輸入；重設全部可取消未完成模擬。

## 驗證與範圍

`npm run test:number-stepper` 涵蓋原 NS-01～08、聚焦全選／mouseup、預設 hold／顯式 false、非法數值、零值、disabled／readonly、原生 reset、冪等初始化及 destroy。DOM 替身不代替真實瀏覽器焦點、觸控或輔助工具；本次已進行本機 Chromium 自驗，未執行獨立代理審查；技術自驗與使用者驗收分開記錄。
