npm package: @kk2229/custom-button
Description: A customizable button web component built with TypeScript
Author: kk2229
Latest version: 1.0.1

# Custom Button Component

一個功能豐富、可自定義的現代化 Web Component 按鈕組件。

## 特色功能

- 🎨 **豐富的樣式變體** - 5 種按鈕變體 (primary, secondary, danger, ghost, outline)
- 📏 **多種尺寸** - 3 種尺寸選擇 (small, medium, large)
- 🎯 **靈活的圖標支持** - 內建圖標系統，支持左右位置
- ⚡ **狀態管理** - 禁用和載入狀態
- 🌙 **深色模式** - 自動適應系統主題
- ♿ **無障礙設計** - 支持鍵盤導航和螢幕閱讀器
- 📱 **響應式設計** - 適配各種裝置
- 🔧 **TypeScript 支持** - 完整的類型定義

## 基本使用

```html
<!-- 基本按鈕 -->
<custom-button>點擊我</custom-button>

<!-- 主要按鈕 -->
<custom-button variant="primary">主要操作</custom-button>

<!-- 大尺寸按鈕 -->
<custom-button variant="primary" size="large">大按鈕</custom-button>
```

## 屬性 (Attributes)

| 屬性            | 類型                                                           | 默認值      | 說明     |
| --------------- | -------------------------------------------------------------- | ----------- | -------- |
| `variant`       | `'primary' \| 'secondary' \| 'danger' \| 'ghost' \| 'outline'` | `'primary'` | 按鈕變體 |
| `size`          | `'small' \| 'medium' \| 'large'`                               | `'medium'`  | 按鈕尺寸 |
| `disabled`      | `boolean`                                                      | `false`     | 禁用狀態 |
| `loading`       | `boolean`                                                      | `false`     | 載入狀態 |
| `full-width`    | `boolean`                                                      | `false`     | 全寬顯示 |
| `icon`          | `string`                                                       | -           | 圖標名稱 |
| `icon-position` | `'left' \| 'right'`                                            | `'left'`    | 圖標位置 |

## 變體說明

### Primary

主要操作按鈕，具有高對比度的藍色漸變背景。

```html
<custom-button variant="primary">主要操作</custom-button>
```

### Secondary

次要操作按鈕，具有灰色漸變背景。

```html
<custom-button variant="secondary">次要操作</custom-button>
```

### Danger

危險操作按鈕，具有紅色漸變背景，用於刪除等操作。

```html
<custom-button variant="danger">刪除</custom-button>
```

### Ghost

透明背景按鈕，適用於較不突出的操作。

```html
<custom-button variant="ghost">取消</custom-button>
```

### Outline

邊框按鈕，具有透明背景和邊框。

```html
<custom-button variant="outline">了解更多</custom-button>
```

## 尺寸

```html
<custom-button size="small">小按鈕</custom-button>
<custom-button size="medium">中等按鈕</custom-button>
<custom-button size="large">大按鈕</custom-button>
```

## 圖標使用

### 內建圖標

組件內建了常用的圖標：

- `arrow-right` - 右箭頭
- `check` - 勾選
- `plus` - 加號
- `download` - 下載
- `heart` - 愛心
- `star` - 星星

```html
<!-- 左側圖標 -->
<custom-button icon="plus">新增</custom-button>

<!-- 右側圖標 -->
<custom-button icon="arrow-right" icon-position="right">繼續</custom-button>
```

## 狀態

### 禁用狀態

```html
<custom-button disabled>禁用按鈕</custom-button>
```

### 載入狀態

```html
<custom-button loading>載入中...</custom-button>
```

### 全寬顯示

```html
<custom-button full-width>全寬按鈕</custom-button>
```

## 事件處理

按鈕支持標準的 DOM 事件：

```javascript
const button = document.querySelector("custom-button");
button.addEventListener("click", (event) => {
  console.log("按鈕被點擊了！");
});
```

## 方法

### focus()

聚焦到按鈕

```javascript
button.focus();
```

### blur()

移除按鈕焦點

```javascript
button.blur();
```

## CSS 自定義

組件使用 Shadow DOM，你可以通過 CSS 自定義屬性進行樣式調整：

```css
custom-button::part(button) {
  /* 自定義按鈕樣式 */
}
```

## 瀏覽器支持

- Chrome 54+
- Firefox 63+
- Safari 10.1+
- Edge 79+

## TypeScript 支持

組件已經包含完整的 TypeScript 類型定義：

```typescript
// 類型自動推斷
const button = document.querySelector("custom-button"); // 類型：CustomButton | null

// 使用組件類型
import type { ButtonProps } from "./src/components/button/types.js";
```

## 範例

完整的使用範例可以在 [main.ts](./main.ts) 中找到，包含各種變體和互動效果的演示。