無障礙設計（a11y）：
讓每個人都能使用你的網站

<!-- ❌ 不語義化：全是 div，螢幕閱讀器無法理解任何結構 -->
<div class="header">
  <div class="nav">
    <div class="nav-item" onclick="navigate()">首頁</div>
    <div class="nav-item" onclick="navigate('/about')">關於</div>
  </div>
</div>
<div class="main">
  <div class="article">
    <div class="title">文章標題</div>
    <div class="content">內容...</div>
  </div>
</div>
<div class="footer">版權所有</div>

<!-- ✅ 語義化：結構清晰，螢幕閱讀器能自動理解頁面架構 -->
<header>
  <nav>
    <a href="/">首頁</a>
    <a href="/about">關於</a>
  </nav>
</header>
<main>
  <article>
    <h1>文章標題</h1>
    <p>內容...</p>
  </article>
</main>
<footer>版權所有</footer>

// ❌ 自訂按鈕：無法用 Tab 聚焦，無法用 Enter 觸發
function BadButton({ onClick, children }: { onClick: () => void; children: React.ReactNode }) {
  return (
    <div
      className="cursor-pointer bg-blue-500 text-white px-4 py-2 rounded"
      onClick={onClick}
    >
      {children}
    </div>
    // 問題：
    // 1. Tab 無法聚焦（div 預設不在 Tab 順序中）
    // 2. Enter / Space 無法觸發 onClick
    // 3. 螢幕閱讀器不知道這是「按鈕」
  );
}

// ✅ 正確做法：直接使用 <button>
// button 自動支援 Tab 聚焦、Enter 觸發、螢幕閱讀器識別
function GoodButton({ onClick, children }: { onClick: () => void; children: React.ReactNode }) {
  return (
    <button
      onClick={onClick}
      className="bg-blue-500 text-white px-4 py-2 rounded
                 hover:bg-blue-600
                 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2"
                 // ↑ focus ring 非常重要！讓鍵盤用戶知道焦點在哪
    >
      {children}
    </button>
  );
}

// ✅ 如果真的必須讓非互動元素可鍵盤操作（例如自訂 Card 點擊）
function ClickableCard({ onClick, children }) {
  return (
    <div
      role="button"          // 告訴螢幕閱讀器這是按鈕
      tabIndex={0}           // 加入 Tab 順序
      onClick={onClick}
      onKeyDown={(e) => {
        // 鍵盤 Enter 和 Space 都應該觸發操作
        if (e.key === 'Enter' || e.key === ' ') {
          e.preventDefault();
          onClick();
        }
      }}
      className="cursor-pointer focus:outline-none focus:ring-2 focus:ring-blue-500 rounded"
    >
      {children}
    </div>
  );
}

import { useRef, useEffect } from 'react';

function Modal({
  isOpen,
  onClose,
  children,
}: {
  isOpen: boolean;
  onClose: () => void;
  children: React.ReactNode;
}) {
  const closeButtonRef = useRef<HTMLButtonElement>(null);

  useEffect(() => {
    if (isOpen) {
      // Modal 開啟時：將焦點移到 Modal 內的第一個可互動元素
      closeButtonRef.current?.focus();
    }
  }, [isOpen]);

  // Escape 鍵關閉 Modal（這是標準無障礙行為）
  const handleKeyDown = (e: React.KeyboardEvent) => {
    if (e.key === 'Escape') {
      onClose();
    }
  };

  if (!isOpen) return null;

  return (
    <>
      {/* 遮罩：aria-hidden 讓螢幕閱讀器忽略，避免干擾 */}
      <div
        className="fixed inset-0 bg-black/50"
        onClick={onClose}
        aria-hidden="true"
      />

      <div
        role="dialog"
        aria-modal="true"
        aria-labelledby="modal-title"
        onKeyDown={handleKeyDown}
        className="fixed inset-0 flex items-center justify-center z-50"
      >
        <div className="bg-white rounded-xl p-8 max-w-md w-full shadow-2xl">
          <div className="flex items-center justify-between mb-4">
            <h2 id="modal-title" className="text-xl font-bold">對話框標題</h2>
            {/* 關閉按鈕放第一個，方便鍵盤用戶快速退出 */}
            <button
              ref={closeButtonRef}
              onClick={onClose}
              aria-label="關閉對話框"
              className="text-gray-500 hover:text-gray-700 focus:outline-none focus:ring-2 focus:ring-gray-400 rounded"
            >
              ✕
            </button>
          </div>
          {children}
        </div>
      </div>
    </>
  );
}

// 實際專案中，推薦使用 focus-trap-react 套件處理複雜的焦點陷阱：
// npm install focus-trap-react
//
// import FocusTrap from 'focus-trap-react';
// <FocusTrap active={isOpen}>
//   <div role="dialog" aria-modal="true">...</div>
// </FocusTrap>

// ✅ 有意義的圖片：alt 描述圖片傳達的資訊
<img
  src="sales-chart.png"
  alt="2024 年第三季銷售成長 23%，較上季成長 5%"
  className="rounded-lg"
/>

// ✅ 裝飾性圖片：空 alt + role="presentation" 讓螢幕閱讀器跳過
<img
  src="decoration-wave.png"
  alt=""
  role="presentation"
  className="absolute bottom-0 left-0 w-full"
/>

// ✅ icon 按鈕：沒有文字時，用 aria-label 說明
<button
  onClick={handleSearch}
  aria-label="搜尋"
>
  <SearchIcon aria-hidden="true" />  {/* icon 本身用 aria-hidden 隱藏，避免重複播報 */}
</button>

// ✅ 有文字的 icon 按鈕：icon 用 aria-hidden，讓螢幕閱讀器只播報文字
<button onClick={handleDelete}>
  <TrashIcon aria-hidden="true" size={16} />
  <span>刪除</span>
</button>

// 完整的無障礙表單
function AccessibleForm() {
  const [emailError, setEmailError] = useState('');
  const [isLoading, setIsLoading] = useState(false);

  return (
    <form noValidate onSubmit={handleSubmit}>
      {/* label htmlFor 必須對應 input id，點擊 label 也會聚焦 input */}
      <div className="mb-4">
        <label htmlFor="email" className="block text-sm font-medium text-gray-700 mb-1">
          電子郵件
          {/* 星號告知視覺用戶必填，但 aria-hidden 讓螢幕閱讀器跳過 */}
          {/* 螢幕閱讀器改由 aria-required 得知必填資訊 */}
          <span aria-hidden="true" className="text-red-500 ml-1">*</span>
        </label>
        <input
          id="email"
          type="email"
          required
          aria-required="true"
          aria-describedby={emailError ? 'email-error' : undefined}
          aria-invalid={!!emailError}
          className={`w-full border rounded-lg p-3 focus:ring-2 focus:ring-blue-500
            ${emailError ? 'border-red-500' : 'border-gray-300'}`}
          onBlur={(e) => {
            if (!e.target.value.includes('@')) {
              setEmailError('請輸入有效的電子郵件格式，例如：name@example.com');
            } else {
              setEmailError('');
            }
          }}
        />
        {/* 錯誤訊息：id 對應 aria-describedby，role="alert" 觸發 aria-live */}
        {emailError && (
          <p id="email-error" role="alert" className="text-red-500 text-sm mt-1">
            {emailError}
          </p>
        )}
      </div>

      {/* 3. Loading 狀態的無障礙處理 */}
      <button
        type="submit"
        disabled={isLoading}
        aria-busy={isLoading}
        className="w-full bg-blue-600 text-white py-3 rounded-lg
                   disabled:opacity-60 focus:outline-none focus:ring-2 focus:ring-blue-500"
      >
        {isLoading ? (
          <>
            {/* loading icon 對螢幕閱讀器隱藏 */}
            <span aria-hidden="true" className="inline-block animate-spin mr-2">⏳</span>
            {/* 文字描述狀態 */}
            <span>處理中，請稍候...</span>
          </>
        ) : (
          <span>送出表單</span>
        )}
      </button>
    </form>
  );
}

// 放在 <body> 最頂部的第一個元素
// 平常用 sr-only 隱藏，Tab 鍵聚焦時才顯示
function SkipToContent() {
  return (
    <a
      href="#main-content"
      className="
        sr-only                           /* 平常對視覺隱藏（screen reader only）*/
        focus:not-sr-only                 /* 聚焦時取消隱藏 */
        focus:absolute focus:top-4 focus:left-4
        focus:z-50
        bg-blue-600 text-white
        px-4 py-2 rounded-lg
        focus:outline-none focus:ring-2 focus:ring-white
      "
    >
      跳到主要內容
    </a>
  );
}

// 在 Layout 中使用
function Layout({ children }) {
  return (
    <>
      <SkipToContent />
      <Header />
      <main id="main-content" tabIndex={-1}>
        {/* tabIndex={-1} 讓 main 可以接收程式化 focus */}
        {children}
      </main>
      <Footer />
    </>
  );
}

// 為什麼需要 Skip Navigation？
// 鍵盤用戶每次到達新頁面，都必須從導覽列的第一個連結開始按 Tab
// 如果導覽列有 20 個連結，需要按 20 次才能到達主要內容
// Skip Navigation 讓他們可以按一次 Tab 就跳過整個導覽