desktop-team-doc 0.1.0

package/content/docs/knowledge/component-library/ControlComponent/slider/architecture.md

@@ -0,0 +1,444 @@
+# Slider 元件架構分析
+
+本文件深入分析 Slider 控制元件的核心架構，包括狀態管理、視覺更新機制和互動處理流程。
+
+---
+
+## 核心架構
+
+### 1. 元件結構
+
+```typescript
+interface SliderProps {
+  pid: number;                        // 參數 ID
+  label?: string;                     // 標籤文字
+  orientation?: 'horizontal' | 'vertical';
+  showValue?: boolean;                // 顯示數值
+  showLabel?: boolean;                // 顯示標籤
+  showMeter?: boolean;                // 顯示音量表
+  meterValue?: number;                // 音量表值
+  sensitivity?: number;               // 拖曳靈敏度
+  preciseSensitivity?: number;        // 精確模式靈敏度
+  stepped?: boolean;                  // 步進模式
+  steps?: string[] | number[];        // 步進選項
+  disabled?: boolean;
+}
+
+const Slider: React.FC<SliderProps> = (props) => {
+  // 1. 從 Native Interface 取得參數狀態
+  const {
+    value,
+    displayValue,
+    setValue,
+    beginGesture,
+    endGesture,
+    resetToDefault,
+  } = useParameter({ pid: props.pid });
+
+  // 2. 本地視覺狀態
+  const containerRef = useRef<HTMLDivElement>(null);
+  const trackRef = useRef<HTMLDivElement>(null);
+  const isDraggingRef = useRef(false);
+
+  // 3. 計算填充百分比
+  const fillPercentage = props.orientation === 'vertical'
+    ? `${value * 100}%`
+    : `${value * 100}%`;
+};
+```
+
+### 2. 狀態層級
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     元件狀態層級                                 │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Native Interface 狀態 (透過 useParameter)                   │
+│     - value: 0-1 正規化參數值                                   │
+│     - displayValue: 格式化顯示值                                │
+│                                                                 │
+│  2. 本地 Ref 狀態 (不觸發渲染)                                   │
+│     - isDraggingRef: 拖曳狀態                                   │
+│     - startValueRef: 拖曳開始時的值                             │
+│     - startPositionRef: 拖曳開始位置                            │
+│                                                                 │
+│  3. CSS 變數狀態 (視覺更新)                                      │
+│     - --value-normalized: 正規化值                              │
+│     - --fill-percentage: 填充百分比                             │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 視覺結構
+
+### DOM 結構
+
+```html
+<div class="slider slider--horizontal" data-dragging="false">
+  <!-- 軌道 -->
+  <div class="slider__track">
+    <!-- 填充區域 -->
+    <div class="slider__fill"></div>
+    <!-- 把手 -->
+    <div class="slider__thumb"></div>
+  </div>
+
+  <!-- 音量表 (可選) -->
+  <div class="slider__meter">
+    <div class="slider__meter-fill"></div>
+  </div>
+
+  <!-- 標籤 (可選) -->
+  <div class="slider__label">Volume</div>
+
+  <!-- 數值顯示 (可選) -->
+  <div class="slider__value">-6.0 dB</div>
+</div>
+```
+
+### CSS 變數驅動
+
+```css
+.slider {
+  --slider-track-length: 200px;
+  --slider-track-thickness: 4px;
+  --slider-thumb-size: 16px;
+  --value-normalized: 0;
+}
+
+.slider__fill {
+  /* 根據方向設定填充 */
+  width: calc(var(--value-normalized) * 100%);
+}
+
+.slider--vertical .slider__fill {
+  width: 100%;
+  height: calc(var(--value-normalized) * 100%);
+}
+
+.slider__thumb {
+  /* 把手位置跟隨數值 */
+  left: calc(var(--value-normalized) * 100%);
+  transform: translateX(-50%);
+}
+
+.slider--vertical .slider__thumb {
+  left: 50%;
+  bottom: calc(var(--value-normalized) * 100%);
+  transform: translate(-50%, 50%);
+}
+```
+
+---
+
+## 互動機制
+
+### 1. 位置計算
+
+```typescript
+interface PositionCalculator {
+  (e: PointerEvent, track: HTMLElement): number;
+}
+
+// 水平滑桿：X 軸位置
+const calculateHorizontalPosition: PositionCalculator = (e, track) => {
+  const rect = track.getBoundingClientRect();
+  const relativeX = e.clientX - rect.left;
+  return Math.max(0, Math.min(1, relativeX / rect.width));
+};
+
+// 垂直滑桿：Y 軸位置（注意方向反轉）
+const calculateVerticalPosition: PositionCalculator = (e, track) => {
+  const rect = track.getBoundingClientRect();
+  const relativeY = rect.bottom - e.clientY;
+  return Math.max(0, Math.min(1, relativeY / rect.height));
+};
+
+// 統一的位置計算器
+const getPosition = (
+  e: PointerEvent,
+  track: HTMLElement,
+  orientation: 'horizontal' | 'vertical'
+): number => {
+  return orientation === 'horizontal'
+    ? calculateHorizontalPosition(e, track)
+    : calculateVerticalPosition(e, track);
+};
+```
+
+### 2. 拖曳操作
+
+```typescript
+const useSliderDrag = (
+  pid: number,
+  setValue: (value: number) => void,
+  options: SliderOptions
+) => {
+  const trackRef = useRef<HTMLDivElement>(null);
+  const stateRef = useRef({
+    isDragging: false,
+    startValue: 0,
+  });
+
+  const handlePointerDown = useCallback((e: PointerEvent) => {
+    const track = trackRef.current;
+    if (!track) return;
+
+    e.preventDefault();
+
+    // 1. 開始手勢
+    beginGesture();
+
+    // 2. 計算點擊位置的值
+    const clickValue = getPosition(e, track, options.orientation);
+
+    // 3. 根據模式決定行為
+    if (options.clickBehavior === 'jump') {
+      // 直接跳到點擊位置
+      setValue(clickValue);
+      stateRef.current.startValue = clickValue;
+    } else {
+      // 記錄當前值，等待拖曳
+      stateRef.current.startValue = value;
+    }
+
+    stateRef.current.isDragging = true;
+    (e.target as HTMLElement).setPointerCapture(e.pointerId);
+  }, [options, value, setValue, beginGesture]);
+
+  const handlePointerMove = useCallback((e: PointerEvent) => {
+    const track = trackRef.current;
+    if (!track || !stateRef.current.isDragging) return;
+
+    const newValue = getPosition(e, track, options.orientation);
+
+    // 精確模式處理
+    const isPrecise = e.ctrlKey || e.metaKey;
+    if (isPrecise) {
+      // 精確模式：相對於起始值的細微調整
+      const delta = (newValue - stateRef.current.startValue) * options.preciseFactor;
+      setValue(Math.max(0, Math.min(1, stateRef.current.startValue + delta)));
+    } else {
+      // 正常模式：直接使用位置
+      setValue(newValue);
+    }
+
+    updateVisual(newValue);
+  }, [options, setValue]);
+
+  const handlePointerUp = useCallback((e: PointerEvent) => {
+    if (!stateRef.current.isDragging) return;
+
+    stateRef.current.isDragging = false;
+    (e.target as HTMLElement).releasePointerCapture(e.pointerId);
+
+    endGesture();
+  }, [endGesture]);
+
+  return { trackRef };
+};
+```
+
+### 3. 滾輪操作
+
+```typescript
+const useSliderWheel = (
+  value: number,
+  setValue: (value: number) => void,
+  options: WheelOptions
+) => {
+  const handleWheel = useCallback((e: WheelEvent) => {
+    e.preventDefault();
+
+    // 1. 判斷精確模式
+    const isPrecise = e.ctrlKey || e.metaKey;
+    const sensitivity = isPrecise
+      ? options.preciseWheelSensitivity
+      : options.wheelSensitivity;
+
+    // 2. 計算差值
+    let delta = e.deltaY * sensitivity;
+
+    // 3. 處理平台差異
+    if (isMac) {
+      const isInverted = (e as any).webkitDirectionInvertedFromDevice;
+      if (!isInverted) delta = -delta;
+    }
+
+    // 4. 方向處理
+    if (options.orientation === 'vertical') {
+      delta = -delta; // 垂直滑桿向上應增加值
+    }
+
+    // 5. 計算新值
+    const newValue = Math.max(0, Math.min(1, value - delta));
+    setValue(newValue);
+  }, [value, setValue, options]);
+
+  return { onWheel: handleWheel };
+};
+```
+
+---
+
+## 音量表系統
+
+### 音量表結構
+
+```typescript
+interface MeterConfig {
+  enabled: boolean;
+  value: number;          // 0-1，音量電平
+  peakValue?: number;     // 峰值保持
+  peakHoldTime?: number;  // 峰值保持時間 (ms)
+  warningThreshold: number;  // 警告閾值 (如 0.8)
+  dangerThreshold: number;   // 危險閾值 (如 0.95)
+}
+```
+
+### 音量表渲染
+
+```typescript
+const SliderMeter: React.FC<MeterProps> = ({
+  value,
+  peakValue,
+  warningThreshold = 0.8,
+  dangerThreshold = 0.95,
+  orientation,
+}) => {
+  // 計算顏色區域
+  const getMeterColor = (level: number) => {
+    if (level >= dangerThreshold) return 'var(--meter-danger-color)';
+    if (level >= warningThreshold) return 'var(--meter-warning-color)';
+    return 'var(--meter-safe-color)';
+  };
+
+  return (
+    <div
+      className="slider__meter"
+      style={{
+        '--meter-value': value,
+        '--meter-peak': peakValue ?? value,
+        '--meter-color': getMeterColor(value),
+      } as React.CSSProperties}
+    >
+      <div className="slider__meter-fill" />
+      {peakValue && <div className="slider__meter-peak" />}
+    </div>
+  );
+};
+```
+
+### CSS 樣式
+
+```css
+.slider__meter {
+  position: absolute;
+  /* 根據方向定位 */
+}
+
+.slider__meter-fill {
+  background: linear-gradient(
+    to top,
+    var(--meter-safe-color) 0%,
+    var(--meter-safe-color) calc(var(--meter-warning-threshold) * 100%),
+    var(--meter-warning-color) calc(var(--meter-warning-threshold) * 100%),
+    var(--meter-warning-color) calc(var(--meter-danger-threshold) * 100%),
+    var(--meter-danger-color) calc(var(--meter-danger-threshold) * 100%),
+    var(--meter-danger-color) 100%
+  );
+  height: calc(var(--meter-value) * 100%);
+}
+
+.slider__meter-peak {
+  position: absolute;
+  width: 100%;
+  height: 2px;
+  bottom: calc(var(--meter-peak) * 100%);
+  background: var(--meter-danger-color);
+}
+```
+
+---
+
+## 效能最佳化
+
+### 1. CSS 變數更新
+
+```typescript
+const updateVisual = useCallback((value: number) => {
+  const container = containerRef.current;
+  if (!container) return;
+
+  // 直接更新 CSS 變數，繞過 React
+  container.style.setProperty('--value-normalized', String(value));
+}, []);
+```
+
+### 2. 節流更新
+
+```typescript
+// 視覺更新：每幀
+// Native 更新：節流
+const throttledSetValue = useThrottle(setValue, 16);
+
+const handleMove = (newValue: number) => {
+  updateVisual(newValue);        // 立即
+  throttledSetValue(newValue);   // 節流
+};
+```
+
+### 3. 拖曳狀態樣式
+
+```css
+/* 拖曳時禁用過渡動畫 */
+.slider[data-dragging="true"] .slider__fill,
+.slider[data-dragging="true"] .slider__thumb {
+  transition: none;
+}
+
+/* 非拖曳時啟用過渡 */
+.slider:not([data-dragging="true"]) .slider__fill,
+.slider:not([data-dragging="true"]) .slider__thumb {
+  transition: all 100ms ease-out;
+}
+```
+
+---
+
+## 常數配置
+
+```typescript
+export const SLIDER_CONSTANTS = {
+  // 靈敏度
+  DEFAULT_SENSITIVITY: 1,
+  PRECISE_FACTOR: 0.1,
+  WHEEL_SENSITIVITY: 0.001,
+  PRECISE_WHEEL_SENSITIVITY: 0.0002,
+
+  // 軌道尺寸
+  DEFAULT_TRACK_LENGTH: 200,
+  DEFAULT_TRACK_THICKNESS: 4,
+  DEFAULT_THUMB_SIZE: 16,
+
+  // 音量表
+  METER_WARNING_THRESHOLD: 0.8,
+  METER_DANGER_THRESHOLD: 0.95,
+  PEAK_HOLD_TIME: 1500,
+
+  // 節流
+  UPDATE_THROTTLE_MS: 16,
+};
+```
+
+---
+
+## 相關文件
+
+- [手勢處理演算法](../interaction/gesture-algorithms.md) - 詳細手勢演算法
+- [數值處理模式](../interaction/value-processing-patterns.md) - 數值轉換詳解
+- [效能最佳化策略](../optimization/performance-optimization.md) - 更多優化技巧
+- [API 設計參考](../design/api-design-reference.md) - 完整 Props 定義