超商取貨選店

台灣電商結帳最常見的「超商取貨」流程，做成一個自足的步驟式面板：第一步用色塊 chips 選通路，第二步從門市資料自動推導出縣市與鄉鎮市區下拉，第三步在可搜尋的清單裡挑門市——每筆顯示地址、營業時間、24 小時徽章與（可選的）距離文字。點選門市後面板收合成摘要卡（通路色塊＋門市名＋地址＋「更換」按鈕）並回呼 onSelect(store)。步驟切換用水平滑動過場、清單項目依序進場、選中項打勾；支援受控 value 與非受控 defaultValue、isLoading 載入骨架與全部可覆寫的文案。元件不含任何真實品牌 logo 或名稱，通路與門市資料一律由 props 傳入。

Playground

即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。

<ConvenienceStorePickup />

安裝

使用

import {
  ConvenienceStorePickup,
  type PickupChain,
  type PickupStore,
} from "@/components/ui/convenience-store-pickup";

// 通路與門市皆由你的 API 提供；此處為虛構示意
const chains: PickupChain[] = [
  { id: "sudah", name: "速達超商", color: "#e8541e" },
  { id: "neighbor", name: "好鄰居便利店", color: "#2e7d32" },
];

const stores: PickupStore[] = [
  {
    id: "sd-001",
    chainId: "sudah",
    name: "大安樂活門市",
    address: "臺北市大安區樂活路 12 號",
    city: "臺北市",
    district: "大安區",
    open24h: true,
    distanceText: "350 公尺",
  },
  {
    id: "nb-001",
    chainId: "neighbor",
    name: "大安木棉店",
    address: "臺北市大安區木棉巷 6 號",
    city: "臺北市",
    district: "大安區",
    hours: "07:00–22:30",
  },
];

// 受控：把門市 id 存進結帳表單狀態
<ConvenienceStorePickup
  chains={chains}
  stores={stores}
  value={form.pickupStoreId}
  onChange={(id) => setForm({ ...form, pickupStoreId: id })}
  onSelect={(store) => console.log("取貨門市", store.name, store.address)}
/>

// 非受控：只想知道最後選了誰
<ConvenienceStorePickup
  chains={chains}
  stores={stores}
  defaultValue="sd-001"
  onSelect={(store) => console.log(store.id)}
  compact
/>

Props

PickupChain

PickupStore

ConvenienceStorePickupLabels

另外具名匯出 filterPickupStores(stores, { chainId, city, district, query })，與元件內部相同的篩選邏輯（關鍵字同時比對門市名稱與地址、忽略大小寫），方便在表單層計算門市數量或做伺服器端預篩。

細節

• 三步導覽：步驟列可點回已完成的步驟；尚未達成前置條件的步驟（例如還沒選通路就想選門市）為停用。換通路會清掉已選縣市／區，同一通路則保留。選好區後自動前進到門市清單，回到第二步時另有「查看門市」按鈕。
• 選項由資料推導：縣市與鄉鎮市區皆從該通路的 stores 去重取得，並保留你傳入的排序（例如由北到南）；不需要另外維護行政區表。
• 收合成摘要卡：點選門市後步驟面板收合、只留摘要卡，按「更換」重新展開並直接回到該門市所在的清單、預先把它設為 active。受控模式下 value 從外部變成 null 也會自動展開面板。
• 距離文字由你決定：元件不做定位或距離計算，只顯示 distanceText；showDistance={false} 可整體隱藏。
• 動畫：步驟切換為方向感知的水平滑動（前進向左、後退向右）、清單前 8 筆依序進場、選中打勾用彈簧縮放、摘要卡以高度展開。

可及性

• 步驟列為 ol 清單，目前步驟以 aria-current="step" 標示，未達前置條件的步驟以 disabled 停用
• 通路 chips 為 role="group" 內的 aria-pressed 按鈕；縣市／區使用原生 select（含 label），行動裝置直接呼叫系統選單
• 門市清單為 role="listbox"（可 Tab 聚焦）搭配 role="option" 與 aria-selected，以 aria-activedescendant 指向目前項目；支援 ↑／↓／Home／End 移動、Enter／Space 選取，搜尋框按 ↓ 可直接跳進清單，Enter 選取目前項目（中文輸入法組字中不會誤觸）
• 選定門市後焦點自動移到摘要卡的「更換」按鈕；按「更換」後焦點回到搜尋框，鍵盤流程不斷裂；門市數量以 aria-live="polite" 朗讀
• isLoading 骨架以 role="status"、aria-busy 與 sr-only 文字告知載入中
• 使用者系統開啟「減少動態效果」時，步驟切換改為淡入淡出、清單不再依序進場、打勾與摘要卡取消縮放／高度動畫，只保留即時切換