desktop-team-doc 0.1.0

package/content/docs/knowledge/component-library/ControlComponent/quick-start.md

@@ -0,0 +1,345 @@
+# 快速入門指南
+
+本指南幫助開發者在 5 分鐘內了解 Audio Plugin 控制元件的整體架構與使用方式。
+
+---
+
+## 概念總覽
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        使用者互動層                              │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
+│  │   滑鼠拖曳   │  │   滾輪操作   │  │   鍵盤 (精確模式)       │ │
+│  └──────┬──────┘  └──────┬──────┘  └───────────┬─────────────┘ │
+└─────────┼────────────────┼─────────────────────┼───────────────┘
+          │                │                     │
+          ▼                ▼                     ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                       手勢處理層                                 │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │  Pointer Events / useAudioControl Hook                      ││
+│  │  - 平台適應 (Mac/Windows)                                   ││
+│  │  - 精確模式偵測 (Ctrl/Cmd)                                  ││
+│  │  - 節流與防抖                                               ││
+│  └─────────────────────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────────────────────┘
+          │
+          ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                       數值處理層                                 │
+│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────┐│
+│  │   正規化      │  │   約束/步進   │  │   曲線映射 (對數等)   ││
+│  │   (0-1)      │  │   clamp/snap │  │   頻率/增益           ││
+│  └──────────────┘  └──────────────┘  └────────────────────────┘│
+└─────────────────────────────────────────────────────────────────┘
+          │
+          ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Native Interface 層                          │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │  useParameter Hook → Native Interface → Audio Plugin Host  ││
+│  │  - getValue / setValue (0-1 正規化值)                       ││
+│  │  - beginGesture / endGesture (DAW 自動化)                   ││
+│  └─────────────────────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────────────────────┘
+          │
+          ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                       視覺更新層                                 │
+│  ┌──────────────────────┐  ┌───────────────────────────────────┐│
+│  │  CSS 變數更新         │  │  圖片幀切換 / CSS Transform      ││
+│  │  (繞過 React 渲染)    │  │  (requestAnimationFrame)         ││
+│  └──────────────────────┘  └───────────────────────────────────┘│
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 核心概念
+
+### 1. Native Interface Contract
+
+控制元件透過 **Native Interface** 與 Audio Plugin Host 溝通：
+
+```typescript
+// 使用元件只需要提供 pid (Parameter ID)
+<Knob pid={0} label="Gain" />
+<Slider pid={1} label="Mix" />
+
+// Native Interface 由 Host 實作
+const nativeAPI: NativeInterface = {
+  parameter: {
+    getValue: (pid) => /* 從 Host 取值 */,
+    setValue: (pid, value) => /* 設定到 Host */,
+    getDisplayValue: (pid) => /* 取得格式化顯示 */,
+    beginGesture: (pid) => /* 通知 DAW 開始 */,
+    endGesture: (pid) => /* 通知 DAW 結束 */,
+  },
+  subscribe: (pid, callback) => /* 訂閱變化 */,
+};
+```
+
+詳細說明：[Native Interface Contract](./core/native-interface.md)
+
+### 2. 兩種主要元件系列
+
+| 系列 | 元件 | 適用場景 |
+| ---- | ---- | -------- |
+| **Knob** | 旋鈕控制 | 音量、增益、頻率、Pan 等 |
+| **Slider** | 滑桿控制 | 音量條、數值輸入、模式切換 |
+
+### 3. 數值範圍標準
+
+所有控制元件內部使用 **0-1 正規化值**：
+
+```typescript
+// 內部值永遠是 0-1
+const normalizedValue = 0.5;
+
+// 顯示值由 Native Interface 提供
+const displayValue = nativeAPI.parameter.getDisplayValue(pid);
+// → "−6.0 dB" 或 "440 Hz" 或 "50%"
+```
+
+### 4. 精確模式
+
+按住 **Ctrl (Windows)** 或 **Cmd (Mac)** 可啟用精確模式：
+- 拖曳靈敏度降低 (通常為 0.1-0.2 倍)
+- 滾輪步進更細緻
+- 適合微調參數
+
+---
+
+## 最簡單的使用範例
+
+### 步驟 1：設置 Native Interface
+
+```typescript
+// main.tsx
+import { NativeInterfaceProvider } from './contexts/NativeInterfaceContext';
+import { createNativeInterface } from './your-host-adapter';
+
+// 從你的 Audio Plugin Host 創建介面
+const nativeAPI = createNativeInterface(yourAudioHost);
+
+function App() {
+  return (
+    <NativeInterfaceProvider value={nativeAPI}>
+      <PluginUI />
+    </NativeInterfaceProvider>
+  );
+}
+```
+
+### 步驟 2：使用 Knob 旋鈕
+
+```typescript
+import { Knob } from './components/Knob';
+
+function PluginUI() {
+  return (
+    <div className="plugin-panel">
+      {/* 只需提供 pid，其餘由 Native Interface 處理 */}
+      <Knob pid={0} label="Gain" />
+      <Knob pid={1} label="Tone" />
+      <Knob pid={2} label="Mix" />
+    </div>
+  );
+}
+```
+
+### 步驟 3：使用 Slider 滑桿
+
+```typescript
+import { Slider } from './components/Slider';
+
+function PluginUI() {
+  return (
+    <div className="plugin-panel">
+      <Slider pid={3} label="Volume" orientation="vertical" />
+      <Slider pid={4} label="Pan" orientation="horizontal" />
+    </div>
+  );
+}
+```
+
+---
+
+## 進階配置範例
+
+### 自訂 Knob 外觀
+
+```typescript
+<Knob
+  pid={0}
+  label="Gain"
+  size="large"           // 'small' | 'medium' | 'large'
+  showValue={true}       // 顯示數值
+  showLabel={true}       // 顯示標籤
+  indicatorStyle="dot"   // 指示器樣式
+/>
+```
+
+### 步進 Knob（模式切換）
+
+```typescript
+<Knob
+  pid={5}
+  label="Mode"
+  stepped={true}
+  steps={['Clean', 'Crunch', 'Lead', 'High Gain']}
+/>
+```
+
+### 精確數值 Slider
+
+```typescript
+<Slider
+  pid={6}
+  label="Frequency"
+  orientation="horizontal"
+  showNumericInput={true}  // 允許直接輸入數值
+/>
+```
+
+---
+
+## 核心 Hook 使用
+
+### useParameter Hook
+
+```typescript
+import { useParameter } from './hooks/useParameter';
+
+function CustomControl({ pid }: { pid: number }) {
+  const {
+    value,           // 當前正規化值 (0-1)
+    displayValue,    // 格式化顯示值
+    setValue,        // 設定新值
+    beginGesture,    // 開始互動
+    endGesture,      // 結束互動
+    resetToDefault,  // 重置為預設值
+  } = useParameter({ pid });
+
+  return (
+    <div
+      onPointerDown={beginGesture}
+      onPointerUp={endGesture}
+    >
+      <span>{displayValue}</span>
+    </div>
+  );
+}
+```
+
+### useAudioControl Hook
+
+```typescript
+import { useAudioControl } from './hooks/useAudioControl';
+
+function MyKnob({ pid }: { pid: number }) {
+  const { containerRef, isDragging } = useAudioControl({
+    pid,
+    orientation: 'vertical',
+    sensitivity: 0.005,
+    preciseSensitivity: 0.001,
+  });
+
+  return (
+    <div
+      ref={containerRef}
+      className={`knob ${isDragging ? 'dragging' : ''}`}
+    />
+  );
+}
+```
+
+---
+
+## 效能最佳實踐
+
+### 使用 CSS 變數更新視覺
+
+```typescript
+// ✅ 好：使用 CSS 變數
+element.style.setProperty('--value-normalized', String(value));
+
+// ❌ 避免：觸發 React 重新渲染
+setVisualValue(value); // 每次拖動都會重新渲染
+```
+
+### 節流更新到 Native
+
+```typescript
+// 視覺更新：每幀 (60fps)
+// Native 更新：節流到 ~30-60fps
+const throttledSetValue = useThrottle(setValue, 16);
+```
+
+---
+
+## 常見任務速查
+
+### 調整靈敏度
+
+```typescript
+// 在元件層級設定
+<Knob
+  pid={0}
+  sensitivity={0.005}          // 預設拖曳靈敏度
+  preciseSensitivity={0.001}   // 精確模式靈敏度
+  wheelSensitivity={0.01}      // 滾輪靈敏度
+/>
+```
+
+### 處理 Mac/Windows 滾輪差異
+
+```typescript
+// 已內建在 useAudioControl 中
+// 自動處理 Mac 的 webkitDirectionInvertedFromDevice
+if (isMac) {
+  const isDirectionInverted = e.webkitDirectionInvertedFromDevice;
+  delta = isDirectionInverted ? delta : -delta;
+}
+```
+
+### 雙擊重置
+
+```typescript
+<Knob
+  pid={0}
+  onDoubleClick={() => resetToDefault()}
+  // 或使用內建行為
+  enableDoubleClickReset={true}
+/>
+```
+
+---
+
+## 下一步
+
+1. **理解核心介面**: [Native Interface Contract](./core/native-interface.md)
+2. **深入了解架構**: [Knob 架構分析](./knob/architecture.md)
+3. **學習建立新元件**: [建立新元件指南](./creating-new-controls.md)
+4. **了解效能優化**: [效能最佳化策略](./optimization/performance-optimization.md)
+5. **API 設計標準**: [API 設計參考](./design/api-design-reference.md)
+
+---
+
+## 常見問題
+
+**Q: 為什麼用 0-1 正規化值？**
+A: 統一內部計算，便於跨元件傳遞。實際值和顯示格式由 Host 負責轉換。
+
+**Q: 為什麼用 CSS 變數而不是 React 狀態？**
+A: 避免高頻拖曳時的 React 重新渲染，提升效能。
+
+**Q: 什麼是手勢開始/結束 (beginGesture/endGesture)？**
+A: 通知 DAW 使用者開始/結束調整參數，讓 DAW 正確記錄自動化曲線。
+
+**Q: 如何測試元件？**
+A: 使用 [Mock Native Interface](./core/native-interface.md#測試支援) 進行單元測試。
+
+**Q: 如何除錯元件問題？**
+A: 查看 [故障排除指南](./troubleshooting.md)。