Setup Checklist Rail
固定於應用側邊的安裝引導清單：完成項目打勾摺疊、頂端進度環計數推進，全部完成後縮成可展開的浮動徽章。
載入預覽⋯
Playground
即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。
<SetupChecklistRail />
安裝
npx shadcn@latest add https://webberui.com/r/setup-checklist-rail.json或在 components.json 設定 registries 後，改用 @webberui/setup-checklist-rail 安裝。
安裝依賴後，從 registry JSON（/r/setup-checklist-rail.json 的 files[0].content）複製 setup-checklist-rail.tsx 原始碼到你的 components/ui/ 目錄：
npm install motion clsx tailwind-merge lucide-react使用
以資料驅動：傳入 items 陣列，元件內部管理已完成狀態（非受控）。
import { SetupChecklistRail } from "@/components/ui/setup-checklist-rail";
const items = [
{ id: "profile", title: "完善個人檔案", description: "加上頭像與名稱。", actionLabel: "前往檔案" },
{ id: "workspace", title: "建立工作區", description: "把專案集中管理。" },
{ id: "invite", title: "邀請團隊成員" },
];
<SetupChecklistRail items={items} defaultCompleted={["profile"]} />需要與後端進度同步時，改用受控模式：
const [done, setDone] = React.useState<string[]>([]);
<SetupChecklistRail
items={items}
completed={done}
onCompletedChange={setDone}
onAllComplete={() => track("onboarding_complete")}
/>Props
| Prop | 型別 | 預設值 | 說明 |
|---|---|---|---|
items | SetupChecklistItem[] | — | 檢查清單項目（見下方型別） |
completed | string[] | — | 受控的已完成 id 陣列，不傳則內部管理 |
defaultCompleted | string[] | [] | 非受控模式的初始已完成 id |
onCompletedChange | (ids: string[]) => void | — | 完成集合變更時觸發（受控與非受控皆會） |
onAllComplete | () => void | — | 全部完成時觸發一次 |
title | string | "開始使用" | 面板標題 |
side | "left" | "right" | "right" | 面板貼齊的邊角 |
position | "fixed" | "absolute" | "fixed" | fixed 貼齊視口；absolute 由具 relative 的父層容納 |
collapseOnComplete | boolean | true | 全部完成後是否自動縮成浮動徽章 |
doneLabel | string | "設定完成" | 完成後徽章顯示的文字 |
className | string | — | 追加到最外層容器的 className |
SetupChecklistItem
| 欄位 | 型別 | 說明 |
|---|---|---|
id | string | 唯一識別碼，作為完成狀態的鍵 |
title | string | 步驟標題 |
description | React.ReactNode | 步驟說明，完成後隨該列摺疊隱藏 |
actionLabel | string | 選填的行動按鈕文字 |
onAction | () => void | 點擊行動按鈕時的回呼 |
細節
- 未完成的步驟自動排在前面，下一個要做的步驟會浮到頂端。
- 勾選後該列的說明摺疊、標題轉為刪除線，頂端進度環的弧長與中央數字一路「數」到新值。
- 進度環以單一
MotionValue（已完成比例）同時驅動弧長與中央數字，避免兩者不同步。 - 標題列的收合鈕可隨時把整條欄位縮成浮動徽章；徽章點擊即可展開。全部完成後會自動收合成徽章。
可及性
- 每一列為
role="checkbox"並帶aria-checked，可用Tab聚焦、Space/Enter勾選。 - 進度環容器為
role="progressbar"，帶aria-valuemin/aria-valuemax/aria-valuenow，aria-valuenow取實際完成數而非動畫中的過渡值。 - 面板為帶
aria-label的section；徽章按鈕的aria-label含目前進度與展開提示。 - 使用者系統開啟「減少動態效果」時，停用縮放、重排與描邊動畫，僅保留即時的淡入淡出。