desktop-team-doc 0.1.0

package/content/docs/knowledge/component-library/ControlComponent/design/design-principles.md

@@ -0,0 +1,336 @@
+# Audio Control 設計原則
+
+本文件定義 Audio Plugin 控制元件的核心設計原則，從專業音訊軟體（如 JUCE、DAW）中提取的最佳實踐。
+
+---
+
+## 1. 統一元件模型 (Unified Component Model)
+
+### 設計理念
+
+使用單一 API 介面支援多種控制行為，降低學習曲線：
+
+```typescript
+// 統一的 Hook 支援多種互動模式
+type AudioControlMode =
+  | 'linear-horizontal'   // 水平滑桿
+  | 'linear-vertical'     // 垂直滑桿
+  | 'rotary'              // 旋鈕（垂直拖曳）
+  | 'rotary-circular';    // 旋鈕（圓形拖曳）
+
+// 相同的 API，不同的行為
+const slider = useAudioControl({ mode: 'linear-horizontal', pid: 0 });
+const knob = useAudioControl({ mode: 'rotary', pid: 1 });
+```
+
+### 實作要點
+
+- **統一的數值介面**：`setValue()`, `getValue()`, `beginGesture()`, `endGesture()`
+- **一致的正規化值**：所有控制元件使用 0-1 範圍
+- **共享的行為邏輯**：精確模式、雙擊重置、鍵盤操作
+
+---
+
+## 2. 關注點分離 (Separation of Concerns)
+
+### 設計理念
+
+將邏輯與視覺徹底分離，提高可維護性和可測試性：
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                       應用層                                     │
+│  ┌───────────────────────────────────────────────────────────┐  │
+│  │  使用控制元件的業務代碼                                     │  │
+│  └───────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+          │
+          ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                       邏輯層 (Headless)                          │
+│  ┌───────────────────────────────────────────────────────────┐  │
+│  │  useAudioControl Hook                                      │  │
+│  │  - 數值計算、手勢處理、狀態管理                            │  │
+│  │  - 與 Native Interface 溝通                                │  │
+│  └───────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+          │
+          ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                       視覺層 (Presentational)                    │
+│  ┌───────────────────────────────────────────────────────────┐  │
+│  │  Knob / Slider 展示元件                                    │  │
+│  │  - CSS 樣式、動畫                                          │  │
+│  │  - DOM 結構、ARIA 屬性                                     │  │
+│  └───────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 實作範例
+
+```typescript
+// ============================================
+// 邏輯層：Headless Hook
+// ============================================
+function useAudioControl(options: AudioControlOptions) {
+  const { pid, mode, sensitivity } = options;
+
+  // Native Interface 整合
+  const nativeAPI = useNativeInterface();
+  const [value, setValueState] = useState(() =>
+    nativeAPI.parameter.getValue(pid)
+  );
+
+  // 手勢處理邏輯
+  const handleDrag = useCallback((delta: number) => {
+    const newValue = calculateNewValue(value, delta, sensitivity);
+    setValueState(newValue);
+    nativeAPI.parameter.setValue(pid, newValue);
+  }, [value, pid, sensitivity, nativeAPI]);
+
+  return {
+    value,
+    setValue: handleDrag,
+    bind: () => ({ /* 事件綁定 */ }),
+  };
+}
+
+// ============================================
+// 視覺層：展示元件
+// ============================================
+const Knob: React.FC<KnobProps> = ({ pid, className }) => {
+  const { value, bind } = useAudioControl({ pid, mode: 'rotary' });
+
+  return (
+    <div
+      {...bind()}
+      className={className}
+      style={{ '--value-normalized': value } as React.CSSProperties}
+    >
+      <div className="knob__indicator" />
+    </div>
+  );
+};
+```
+
+---
+
+## 3. 可組合性 (Composability)
+
+### 設計理念
+
+功能正交設計，可獨立使用或自由組合：
+
+```typescript
+interface AudioControlOptions {
+  // 基礎功能
+  pid: number;
+  mode: AudioControlMode;
+
+  // 可組合的進階功能 - 每個獨立
+  damping?: DampingConfig;       // 精確模式
+  velocity?: VelocityConfig;     // 速度感應
+  keyboard?: KeyboardConfig;     // 鍵盤控制
+  valueMapping?: MappingConfig;  // 數值映射
+}
+
+// 各功能獨立配置
+interface DampingConfig {
+  enabled?: boolean;
+  key?: 'shift' | 'ctrl' | 'meta';
+  factor?: number;  // 0.1 = 1/10 靈敏度
+}
+
+interface VelocityConfig {
+  enabled?: boolean;
+  sensitivity?: number;
+  curve?: 'linear' | 'exponential' | 'logarithmic';
+}
+```
+
+### 使用範例
+
+```typescript
+// 最簡單使用
+<Knob pid={0} />
+
+// 添加精確模式
+<Knob pid={0} damping={{ key: 'shift', factor: 0.1 }} />
+
+// 完整專業配置
+<Knob
+  pid={0}
+  damping={{ key: 'shift', factor: 0.1 }}
+  velocity={{ enabled: true, curve: 'logarithmic' }}
+  valueMapping={{ type: 'logarithmic' }}  // 頻率適合對數映射
+/>
+```
+
+---
+
+## 4. 漸進式增強 (Progressive Enhancement)
+
+### 設計理念
+
+開箱即用，進階功能按需啟用：
+
+```typescript
+// 合理的預設值
+const defaultOptions = {
+  sensitivity: 0.005,
+  preciseSensitivity: 0.001,
+  wheelSensitivity: 0.01,
+  enableDoubleClickReset: true,
+  enableKeyboard: true,
+};
+
+// 最簡使用 - 只需提供 pid
+<Knob pid={0} />
+
+// 漸進增強 - 覆蓋特定設定
+<Knob pid={0} sensitivity={0.01} />
+
+// 完整配置 - 專業級控制
+<Knob
+  pid={0}
+  sensitivity={0.005}
+  preciseSensitivity={0.0005}
+  wheelSensitivity={0.002}
+  enableVelocity={true}
+  velocityCurve="logarithmic"
+/>
+```
+
+---
+
+## 5. 專業音訊控制特性
+
+### 精確模式 (Fine Control)
+
+音訊參數需要精確調整，提供修飾鍵支援：
+
+```typescript
+// 偵測精確模式
+const isPreciseMode = e.ctrlKey || e.metaKey || e.shiftKey;
+
+// 應用不同靈敏度
+const sensitivity = isPreciseMode
+  ? PRECISE_SENSITIVITY  // 0.001
+  : DEFAULT_SENSITIVITY; // 0.005
+
+// 計算數值變化
+const delta = movementY * sensitivity;
+```
+
+### 手勢開始/結束 (DAW Automation)
+
+支援 DAW 自動化錄製的手勢通知：
+
+```typescript
+const handlePointerDown = () => {
+  // 通知 DAW 開始錄製自動化
+  nativeAPI.parameter.beginGesture(pid);
+};
+
+const handlePointerUp = () => {
+  // 通知 DAW 結束錄製自動化
+  nativeAPI.parameter.endGesture(pid);
+};
+```
+
+### 雙擊重置 (Double-Click Reset)
+
+快速恢復預設值的標準操作：
+
+```typescript
+const handleDoubleClick = () => {
+  const defaultValue = nativeAPI.parameterInfo?.getDefaultValue(pid) ?? 0.5;
+  nativeAPI.parameter.beginGesture(pid);
+  nativeAPI.parameter.setValue(pid, defaultValue);
+  nativeAPI.parameter.endGesture(pid);
+};
+```
+
+### 數值映射 (Value Mapping)
+
+不同參數類型需要不同的數值映射：
+
+```typescript
+// 線性映射 (音量、Pan)
+const linearMap = (normalized: number, min: number, max: number) =>
+  min + normalized * (max - min);
+
+// 對數映射 (頻率)
+const logarithmicMap = (normalized: number, min: number, max: number) =>
+  min * Math.pow(max / min, normalized);
+
+// 指數映射 (時間常數)
+const exponentialMap = (normalized: number, min: number, max: number, skew: number) =>
+  min + (max - min) * Math.pow(normalized, skew);
+```
+
+---
+
+## 6. 效能設計原則
+
+### CSS 變數驅動視覺更新
+
+```typescript
+// ✅ 好：使用 CSS 變數，繞過 React 渲染
+const updateVisual = (value: number) => {
+  element.style.setProperty('--value-normalized', String(value));
+};
+
+// ❌ 避免：每次拖動觸發 React 重新渲染
+const [visualValue, setVisualValue] = useState(0);
+```
+
+### 視覺與狀態分離更新
+
+```typescript
+const handleDrag = (delta: number) => {
+  const newValue = calculateValue(delta);
+
+  // 1. 立即更新視覺 (60fps)
+  updateCSS(newValue);
+
+  // 2. 節流更新 Native (30-60fps)
+  throttledSetValue(newValue);
+};
+```
+
+### 使用 Ref 存儲高頻狀態
+
+```typescript
+// ✅ 使用 ref 存儲拖曳狀態
+const stateRef = useRef({
+  isDragging: false,
+  startValue: 0,
+  startY: 0,
+});
+
+// ❌ 避免使用 useState 存儲高頻變更的狀態
+const [isDragging, setIsDragging] = useState(false);
+```
+
+---
+
+## 7. 設計原則檢查清單
+
+| 原則 | 實作要點 | 檢查項 |
+| ---- | -------- | ------ |
+| **統一元件模型** | 單一 Hook 支援多模式 | mode 參數切換行為 |
+| **關注點分離** | Headless Hook + 展示元件 | 邏輯與視覺分離 |
+| **可組合性** | 功能獨立配置 | damping/velocity 獨立 |
+| **漸進式增強** | 合理預設值 | 開箱即用 + 可選進階 |
+| **專業特性** | 精確模式、手勢通知 | Ctrl/Cmd 支援 |
+| **效能優先** | CSS 變數、節流更新 | 60fps 視覺更新 |
+
+---
+
+## 相關文件
+
+- [API 設計參考](./api-design-reference.md) - 完整 Props 介面
+- [視覺回饋指南](./visual-feedback.md) - 狀態視覺化設計
+- [手勢處理演算法](../interaction/gesture-algorithms.md) - 互動邏輯詳解
+- [效能最佳化策略](../optimization/performance-optimization.md) - 效能技巧