desktop-team-doc 0.1.0

package/content/docs/knowledge/component-library/ControlComponent/interaction/gesture-algorithms.md

@@ -0,0 +1,705 @@
+# 手勢處理演算法
+
+本文檔詳細說明音訊控制項中的手勢處理演算法，包括事件捕獲、座標轉換、精確模式控制等核心實作。
+
+---
+
+## 1. 基礎拖曳手勢模式
+
+### Pointer Events API
+
+現代瀏覽器推薦使用 Pointer Events API，它統一處理滑鼠、觸控和觸控筆輸入：
+
+```typescript
+interface PointerEventHandlers {
+  onPointerDown: (event: React.PointerEvent) => void;
+  onPointerMove: (event: React.PointerEvent) => void;
+  onPointerUp: (event: React.PointerEvent) => void;
+  onPointerCancel: (event: React.PointerEvent) => void;
+}
+```
+
+### 事件捕獲模式
+
+關鍵是使用 `setPointerCapture` 確保拖曳時游標離開元件也能持續追蹤：
+
+```typescript
+/**
+ * 拖曳事件管理器
+ * 確保拖曳過程中游標離開元件也能持續追蹤
+ */
+class DragEventManager {
+  private isDragging = false;
+  private startPosition: Point = { x: 0, y: 0 };
+  private currentPosition: Point = { x: 0, y: 0 };
+
+  handlePointerDown(event: PointerEvent, element: HTMLElement): void {
+    this.isDragging = true;
+    this.startPosition = { x: event.clientX, y: event.clientY };
+    this.currentPosition = { ...this.startPosition };
+
+    // 關鍵：捕獲指標，確保事件持續傳遞到此元素
+    element.setPointerCapture(event.pointerId);
+
+    // 防止文字選取和預設行為
+    event.preventDefault();
+  }
+
+  handlePointerMove(event: PointerEvent): Point | null {
+    if (!this.isDragging) return null;
+
+    const previousPosition = { ...this.currentPosition };
+    this.currentPosition = { x: event.clientX, y: event.clientY };
+
+    // 返回相對移動量
+    return {
+      x: this.currentPosition.x - previousPosition.x,
+      y: this.currentPosition.y - previousPosition.y,
+    };
+  }
+
+  handlePointerUp(event: PointerEvent, element: HTMLElement): void {
+    if (!this.isDragging) return;
+
+    this.isDragging = false;
+    element.releasePointerCapture(event.pointerId);
+  }
+
+  getTotalMovement(): Point {
+    return {
+      x: this.currentPosition.x - this.startPosition.x,
+      y: this.currentPosition.y - this.startPosition.y,
+    };
+  }
+}
+```
+
+---
+
+## 2. movementX/movementY 與跨平台問題
+
+### MDN 警告
+
+`MouseEvent.movementX` 和 `MouseEvent.movementY` 是瀏覽器提供的相對移動量，但存在跨平台不一致問題：
+
+> "瀏覽器對 movementX 和 screenX 使用的單位與規範定義的不同。根據瀏覽器和作業系統的差異，movementX 的單位可能是物理像素、邏輯像素或 CSS 像素。"
+
+### 解決方案：sensitivity 參數
+
+```typescript
+/**
+ * 跨平台的移動量標準化
+ */
+function normalizeMovement(
+  event: PointerEvent,
+  sensitivity: number,
+  platformAdapter: PlatformAdapter
+): Point {
+  // 方法 1: 使用 movementX/Y (簡單但有跨平台問題)
+  const rawMovement = {
+    x: event.movementX ?? 0,
+    y: event.movementY ?? 0,
+  };
+
+  // 方法 2: 手動計算差值 (更可靠)
+  // const rawMovement = calculateDelta(event, lastPosition);
+
+  // 應用平台校正因子
+  const platformFactor = platformAdapter.getMovementFactor();
+
+  return {
+    x: rawMovement.x * sensitivity * platformFactor,
+    y: rawMovement.y * sensitivity * platformFactor,
+  };
+}
+
+/**
+ * 平台適配器
+ */
+class PlatformAdapter {
+  private readonly isMac: boolean;
+  private readonly isHighDPI: boolean;
+
+  constructor() {
+    this.isMac = navigator.platform.toLowerCase().includes('mac');
+    this.isHighDPI = window.devicePixelRatio > 1;
+  }
+
+  getMovementFactor(): number {
+    // macOS 的觸控板通常需要較低的靈敏度
+    if (this.isMac) {
+      return 0.8;
+    }
+
+    // 高 DPI 螢幕可能需要調整
+    if (this.isHighDPI) {
+      return 1 / window.devicePixelRatio;
+    }
+
+    return 1.0;
+  }
+
+  getPreciseModifierKey(): 'metaKey' | 'ctrlKey' {
+    return this.isMac ? 'metaKey' : 'ctrlKey';
+  }
+}
+```
+
+---
+
+## 3. GestureToValueConverter 完整實作
+
+### 統一的手勢轉數值轉換器
+
+```typescript
+/**
+ * 手勢配置
+ */
+interface GestureConfig {
+  mode: AudioControlMode;
+  sensitivity: number;
+  damping?: DampingConfig;
+  velocity?: VelocityConfig;
+  rotaryMethod?: 'simple' | 'weighted' | 'angular';
+}
+
+/**
+ * 手勢數據
+ */
+interface GestureData {
+  movement: [number, number];  // [mx, my]
+  event: PointerEvent;
+  startPosition?: Point;
+  currentPosition?: Point;
+  centerPosition?: Point;  // 用於圓形模式
+}
+
+/**
+ * 轉換上下文
+ */
+interface ConversionContext {
+  velocityTracker: VelocityTracker;
+  preciseState: PreciseState;
+  min: number;
+  max: number;
+}
+
+/**
+ * 統一的手勢轉數值轉換器
+ */
+class GestureToValueConverter {
+  private config: GestureConfig;
+
+  constructor(config: GestureConfig) {
+    this.config = config;
+  }
+
+  /**
+   * 主要轉換函式
+   */
+  convert(gesture: GestureData, context: ConversionContext): number {
+    // 1. 計算基礎移動增量
+    let delta = this.calculateBaseDelta(gesture);
+
+    // 2. 應用靈敏度
+    delta *= this.config.sensitivity;
+
+    // 3. 應用修飾鍵效果 (Damping)
+    delta = this.applyModifiers(delta, gesture.event, context);
+
+    // 4. 應用速度感應
+    if (this.config.velocity?.enabled) {
+      delta = this.applyVelocityScaling(delta, context.velocityTracker);
+    }
+
+    // 5. 轉換為數值變化量 (基於 200px = 全範圍的假設)
+    const range = context.max - context.min;
+    return (delta / 200) * range;
+  }
+
+  /**
+   * 計算基礎移動增量
+   */
+  private calculateBaseDelta(gesture: GestureData): number {
+    const [mx, my] = gesture.movement;
+
+    switch (this.config.mode) {
+      case 'linear-horizontal':
+        return mx;
+
+      case 'linear-vertical':
+        return -my;
+
+      case 'rotary':
+        return this.calculateRotaryDelta(mx, my);
+
+      case 'rotary-circular':
+        return this.calculateCircularDelta(gesture);
+
+      default:
+        return 0;
+    }
+  }
+
+  /**
+   * 旋鈕拖曳增量計算 - 三種方法
+   */
+  private calculateRotaryDelta(mx: number, my: number): number {
+    switch (this.config.rotaryMethod ?? 'simple') {
+      case 'simple':
+        // 方法1：簡單加權組合 (react-knob-headless 風格)
+        // 上或右為正，下或左為負
+        return mx - my;
+
+      case 'weighted':
+        // 方法2：向量長度考慮 (更精確)
+        const magnitude = Math.sqrt(mx * mx + my * my);
+        const direction = Math.sign(mx - my);
+        return magnitude * direction * 0.7;
+
+      case 'angular':
+        // 方法3：角度感知組合 (45度方向最敏感)
+        const angle = Math.atan2(my, mx);
+        const angleFactor = Math.cos(angle - Math.PI / 4);
+        return (mx - my) * Math.abs(angleFactor);
+
+      default:
+        return mx - my;
+    }
+  }
+
+  /**
+   * 圓形路徑拖曳增量計算
+   */
+  private calculateCircularDelta(gesture: GestureData): number {
+    const { startPosition, currentPosition, centerPosition } = gesture;
+
+    if (!startPosition || !currentPosition || !centerPosition) {
+      return 0;
+    }
+
+    // 計算角度變化
+    const startAngle = Math.atan2(
+      startPosition.y - centerPosition.y,
+      startPosition.x - centerPosition.x
+    );
+
+    const currentAngle = Math.atan2(
+      currentPosition.y - centerPosition.y,
+      currentPosition.x - centerPosition.x
+    );
+
+    // 處理角度跨越 (-π 到 π)
+    let angleDelta = currentAngle - startAngle;
+
+    if (angleDelta > Math.PI) {
+      angleDelta -= 2 * Math.PI;
+    } else if (angleDelta < -Math.PI) {
+      angleDelta += 2 * Math.PI;
+    }
+
+    // 轉換為數值變化 (270° = 全範圍)
+    const fullRotation = (270 * Math.PI) / 180;
+    return (angleDelta / fullRotation) * 200; // 乘以 200 統一到像素單位
+  }
+
+  /**
+   * 應用修飾鍵效果
+   */
+  private applyModifiers(
+    delta: number,
+    event: PointerEvent,
+    context: ConversionContext
+  ): number {
+    const { damping } = this.config;
+
+    if (!damping?.enabled || !damping?.key) {
+      return delta;
+    }
+
+    const keyMap: Record<string, keyof PointerEvent> = {
+      shift: 'shiftKey',
+      ctrl: 'ctrlKey',
+      alt: 'altKey',
+      meta: 'metaKey',
+    };
+
+    const isDamped = Boolean(event[keyMap[damping.key]]);
+
+    if (isDamped) {
+      return delta * (damping.factor ?? 0.1);
+    }
+
+    return delta;
+  }
+
+  /**
+   * 應用速度感應縮放
+   */
+  private applyVelocityScaling(
+    delta: number,
+    velocityTracker: VelocityTracker
+  ): number {
+    const velocity = velocityTracker.getSmoothedVelocity();
+    const config = this.config.velocity!;
+
+    const threshold = config.threshold ?? 0.5;
+    if (velocity < threshold) {
+      return delta;
+    }
+
+    const normalizedVelocity = velocity - threshold;
+    const sensitivity = config.sensitivity ?? 1;
+
+    let multiplier: number;
+
+    switch (config.curve) {
+      case 'exponential':
+        multiplier = 1 + Math.pow(normalizedVelocity * sensitivity, 2);
+        break;
+      case 'logarithmic':
+        multiplier = 1 + Math.log(1 + normalizedVelocity * sensitivity);
+        break;
+      case 'linear':
+      default:
+        multiplier = 1 + normalizedVelocity * sensitivity;
+    }
+
+    const maxMultiplier = config.maxMultiplier ?? 10;
+    return delta * Math.min(multiplier, maxMultiplier);
+  }
+}
+```
+
+---
+
+## 4. PreciseModeController 完整實作
+
+### 距離解鎖的精確模式
+
+基於 react-rotary-knob 的設計，防止意外跳躍並提供漸進式精確度：
+
+```typescript
+/**
+ * 精確模式配置
+ */
+interface PreciseModeConfig {
+  enabled?: boolean;
+  unlockDistance?: number;   // 解鎖距離 (px)，預設 50
+  basePrecision?: number;    // 基礎精確度，預設 1.0
+  precisionGain?: number;    // 精確度增益，預設 0.01
+  minPrecision?: number;     // 最小精確度，預設 0.1
+}
+
+/**
+ * 精確模式狀態
+ */
+interface PreciseState {
+  isUnlocked: boolean;
+  startPosition: Point | null;
+  accumulatedDistance: number;
+  precisionLevel: number;
+}
+
+/**
+ * 精確度計算結果
+ */
+interface PrecisionResult {
+  isActive: boolean;
+  multiplier: number;
+}
+
+/**
+ * 精確模式控制器
+ * 防止意外跳躍，提供漸進式精確度
+ */
+class PreciseModeController {
+  private config: PreciseModeConfig;
+  private state: PreciseState;
+
+  constructor(config: PreciseModeConfig = {}) {
+    this.config = {
+      enabled: true,
+      unlockDistance: 50,
+      basePrecision: 1.0,
+      precisionGain: 0.01,
+      minPrecision: 0.1,
+      ...config,
+    };
+
+    this.state = this.createInitialState();
+  }
+
+  private createInitialState(): PreciseState {
+    return {
+      isUnlocked: false,
+      startPosition: null,
+      accumulatedDistance: 0,
+      precisionLevel: 1.0,
+    };
+  }
+
+  /**
+   * 重置狀態 (拖曳結束時調用)
+   */
+  reset(): void {
+    this.state = this.createInitialState();
+  }
+
+  /**
+   * 處理指標移動
+   * @param currentPosition 當前指標位置
+   * @param isFirst 是否為拖曳開始
+   */
+  process(currentPosition: Point, isFirst: boolean): PrecisionResult {
+    if (!this.config.enabled) {
+      return { isActive: false, multiplier: 1.0 };
+    }
+
+    if (isFirst) {
+      this.state.startPosition = currentPosition;
+      this.state.isUnlocked = false;
+      this.state.accumulatedDistance = 0;
+    }
+
+    if (!this.state.startPosition) {
+      return { isActive: false, multiplier: 1.0 };
+    }
+
+    // 計算累積距離
+    this.state.accumulatedDistance = this.calculateDistance(
+      this.state.startPosition,
+      currentPosition
+    );
+
+    // 檢查解鎖條件
+    if (!this.state.isUnlocked) {
+      if (this.state.accumulatedDistance >= this.config.unlockDistance!) {
+        this.state.isUnlocked = true;
+      } else {
+        // 尚未解鎖，返回零變化 (防止意外跳躍)
+        return { isActive: false, multiplier: 0 };
+      }
+    }
+
+    // 計算精確度乘數
+    this.state.precisionLevel = this.calculatePrecisionLevel(
+      this.state.accumulatedDistance
+    );
+
+    return {
+      isActive: true,
+      multiplier: this.state.precisionLevel,
+    };
+  }
+
+  /**
+   * 計算精確度等級
+   * 距離越大，精確度越高 (乘數越小)
+   */
+  private calculatePrecisionLevel(distance: number): number {
+    const { basePrecision, precisionGain, minPrecision } = this.config;
+
+    // 對數曲線：初期快速提升精確度，後期趨緩
+    const precision = basePrecision! / (1 + distance * precisionGain!);
+
+    return Math.max(minPrecision!, precision);
+  }
+
+  /**
+   * 計算兩點間距離
+   */
+  private calculateDistance(p1: Point, p2: Point): number {
+    const dx = p2.x - p1.x;
+    const dy = p2.y - p1.y;
+    return Math.sqrt(dx * dx + dy * dy);
+  }
+
+  /**
+   * 獲取當前狀態 (用於調試或 UI 顯示)
+   */
+  getState(): Readonly<PreciseState> {
+    return { ...this.state };
+  }
+}
+```
+
+---
+
+## 5. Pointer Lock API (無界拖曳)
+
+### 問題背景
+
+當滑鼠拖曳到螢幕邊緣時，無法再提供進一步的運動增量，互動被迫中斷。
+
+### 解決方案
+
+```typescript
+/**
+ * 指標鎖定管理器
+ * 實現無界拖曳體驗
+ */
+class PointerLockManager {
+  private isLocked = false;
+  private element: HTMLElement | null = null;
+  private onMovement: ((mx: number, my: number) => void) | null = null;
+
+  /**
+   * 請求指標鎖定
+   */
+  async requestLock(
+    element: HTMLElement,
+    onMovement: (mx: number, my: number) => void
+  ): Promise<boolean> {
+    this.element = element;
+    this.onMovement = onMovement;
+
+    try {
+      await element.requestPointerLock();
+      this.isLocked = true;
+      this.attachListeners();
+      return true;
+    } catch (error) {
+      console.warn('Pointer Lock not supported or denied:', error);
+      return false;
+    }
+  }
+
+  /**
+   * 釋放指標鎖定
+   */
+  exitLock(): void {
+    if (this.isLocked) {
+      document.exitPointerLock();
+      this.isLocked = false;
+      this.removeListeners();
+    }
+  }
+
+  private attachListeners(): void {
+    document.addEventListener('mousemove', this.handleMouseMove);
+    document.addEventListener('pointerlockchange', this.handleLockChange);
+    document.addEventListener('pointerlockerror', this.handleLockError);
+  }
+
+  private removeListeners(): void {
+    document.removeEventListener('mousemove', this.handleMouseMove);
+    document.removeEventListener('pointerlockchange', this.handleLockChange);
+    document.removeEventListener('pointerlockerror', this.handleLockError);
+  }
+
+  private handleMouseMove = (event: MouseEvent): void => {
+    if (this.isLocked && this.onMovement) {
+      // 在鎖定模式下，movementX/Y 持續提供相對運動
+      this.onMovement(event.movementX, event.movementY);
+    }
+  };
+
+  private handleLockChange = (): void => {
+    if (document.pointerLockElement !== this.element) {
+      this.isLocked = false;
+      this.removeListeners();
+    }
+  };
+
+  private handleLockError = (): void => {
+    console.error('Pointer Lock error');
+    this.isLocked = false;
+  };
+}
+
+/**
+ * 整合到 Hook 中的使用方式
+ */
+function useAudioControlWithPointerLock(options: UseAudioControlOptions) {
+  const { usePointerLock = false } = options;
+  const pointerLockManager = useRef(new PointerLockManager());
+
+  const handlePointerDown = useCallback((e: React.PointerEvent) => {
+    // 標準處理...
+
+    if (usePointerLock) {
+      pointerLockManager.current.requestLock(
+        e.currentTarget as HTMLElement,
+        (mx, my) => {
+          // 在鎖定模式下處理移動
+          handleMovement(mx, my);
+        }
+      );
+    }
+  }, [usePointerLock]);
+
+  const handlePointerUp = useCallback((e: React.PointerEvent) => {
+    // 標準處理...
+
+    if (usePointerLock) {
+      pointerLockManager.current.exitLock();
+    }
+  }, [usePointerLock]);
+
+  // ...
+}
+```
+
+---
+
+## 6. RxJS 拖曳處理 (替代方案)
+
+如果專案使用 RxJS，以下是一個使用 RxJS 處理滑鼠事件的替代方案：
+
+```typescript
+// RxJS 拖曳處理模式
+const useMouseMoveRx = (
+  onMove: (delta: number) => void,
+  sensitivity: number
+) => {
+  useEffect(() => {
+    const mouseMove$ = fromEvent<MouseEvent>(document, 'mousemove');
+    const mouseUp$ = fromEvent<MouseEvent>(document, 'mouseup');
+
+    const subscription = mouseMove$.pipe(
+      takeUntil(mouseUp$),
+      map(event => -event.movementY * sensitivity),
+      throttleTime(16) // 60fps
+    ).subscribe(onMove);
+
+    return () => subscription.unsubscribe();
+  }, [onMove, sensitivity]);
+};
+```
+
+### 實作選項對照
+
+| 面向 | 原生實作 | RxJS 實作 |
+|------|---------|---------|
+| 事件 API | Pointer Events | fromEvent + mousemove |
+| 串流處理 | useCallback + RAF | pipe + throttleTime |
+| 取消訂閱 | removeEventListener | subscription.unsubscribe |
+| 學習曲線 | 較低 | 需要 RxJS 知識 |
+
+---
+
+## 總結
+
+### 演算法選擇指南
+
+| 場景 | 推薦演算法 | 原因 |
+|------|-----------|------|
+| 一般旋鈕 | `rotary (simple)` | 最大容錯性，mx - my |
+| 專業混音台 | `rotary (weighted)` | 更精確的向量計算 |
+| 圓形控制項 | `rotary-circular` | 真實的角度追蹤 |
+| 大範圍參數 | `+ Pointer Lock` | 無界拖曳體驗 |
+| 精細調整 | `+ PreciseModeController` | 防跳躍 + 漸進精確度 |
+
+### 核心公式速查
+
+```typescript
+// 基礎轉換
+delta = calculateBaseDelta(movement, mode);
+
+// 完整轉換 (含所有修飾)
+valueChange = delta * sensitivity * dampingMultiplier * velocityMultiplier * precisionMultiplier;
+
+// 範圍映射 (200px = 全範圍)
+finalChange = (valueChange / 200) * (max - min);
+```