desktop-team-doc 0.1.0

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

@@ -0,0 +1,456 @@
+# 視覺回饋指南
+
+本文件說明 Audio Plugin 控制元件的視覺回饋設計原則與實作方法。
+
+---
+
+## 設計原則
+
+### 1. 即時性
+
+視覺回饋必須在使用者操作後立即呈現，延遲不應超過 16ms (60fps)。
+
+### 2. 一致性
+
+所有控制元件應使用統一的視覺語言表達相同的狀態。
+
+### 3. 專業性
+
+模擬實體音訊設備的視覺回饋，提供專業的操作感。
+
+---
+
+## 狀態視覺化
+
+### 互動狀態
+
+| 狀態 | 視覺表現 | CSS 實作 |
+|------|---------|---------|
+| **Idle** | 預設樣式 | 無特殊處理 |
+| **Hover** | 輕微高亮 | `filter: brightness(1.1)` |
+| **Active/Dragging** | 明顯高亮 + 游標變更 | `filter: brightness(1.2)`, `cursor: grabbing` |
+| **Focus** | 焦點環 | `outline: 2px solid var(--focus-color)` |
+| **Disabled** | 降低透明度 | `opacity: 0.5`, `pointer-events: none` |
+
+### CSS 變數系統
+
+```css
+/* 定義狀態變數 */
+.audio-control {
+  --is-hovering: 0;
+  --is-dragging: 0;
+  --is-focused: 0;
+  --is-disabled: 0;
+
+  /* 視覺屬性 */
+  --brightness: calc(1 + var(--is-hovering) * 0.1 + var(--is-dragging) * 0.2);
+  --cursor: grab;
+
+  filter: brightness(var(--brightness));
+  cursor: var(--cursor);
+}
+
+.audio-control[data-hovering="true"] {
+  --is-hovering: 1;
+}
+
+.audio-control[data-dragging="true"] {
+  --is-dragging: 1;
+  --cursor: grabbing;
+}
+
+.audio-control:focus-visible {
+  --is-focused: 1;
+  outline: 2px solid var(--focus-color, #d3cd36);
+  outline-offset: 2px;
+}
+
+.audio-control[data-disabled="true"] {
+  --is-disabled: 1;
+  opacity: 0.5;
+  pointer-events: none;
+}
+```
+
+---
+
+## Knob 視覺回饋
+
+### 旋轉動畫
+
+```css
+/* 旋鈕指示器 */
+.knob__indicator {
+  transform: rotate(var(--rotation, 0deg));
+  transform-origin: var(--rotate-center, 50% 50%);
+
+  /* 拖曳時無過渡 */
+  transition: transform 0ms;
+}
+
+/* 非拖曳時的平滑過渡 */
+.knob:not([data-dragging="true"]) .knob__indicator {
+  transition: transform 100ms ease-out;
+}
+```
+
+### 圖片幀動畫
+
+```typescript
+// 根據值切換圖片幀
+const updateKnobFrame = (value: number, frames: number, basePath: string) => {
+  const frameIndex = Math.round(value * (frames - 1));
+  const paddedIndex = String(frameIndex).padStart(4, '0');
+  return `${basePath}/${paddedIndex}.png`;
+};
+
+// 使用
+const imageSrc = updateKnobFrame(normalizedValue, 64, '/images/knobs/vintage');
+knobImage.src = imageSrc;
+```
+
+### 層疊效果
+
+對於 `FrameMode: 'Layer'` 的旋鈕：
+
+```css
+/* 三層結構 */
+.knob--layered {
+  position: relative;
+}
+
+/* 底層：背景 */
+.knob__layer-bg {
+  position: absolute;
+  z-index: 0;
+}
+
+/* 中層：指示器 (會旋轉) */
+.knob__layer-indicator {
+  position: absolute;
+  z-index: 1;
+  transform: rotate(var(--rotation));
+}
+
+/* 頂層：高光/陰影 */
+.knob__layer-overlay {
+  position: absolute;
+  z-index: 2;
+  pointer-events: none;
+}
+```
+
+---
+
+## Slider 視覺回饋
+
+### 填充動畫
+
+```css
+/* 滑桿填充 */
+.slider__fill {
+  /* 水平滑桿 */
+  width: calc(var(--value-normalized, 0) * 100%);
+
+  /* 或垂直滑桿 */
+  height: calc(var(--value-normalized, 0) * 100%);
+
+  background: linear-gradient(
+    90deg,
+    var(--fill-color-start, #4a4a4a),
+    var(--fill-color-end, #f2f2f2)
+  );
+
+  transition: none;
+}
+
+/* 非拖曳時平滑過渡 */
+.slider:not([data-dragging="true"]) .slider__fill {
+  transition: width 100ms ease-out, height 100ms ease-out;
+}
+```
+
+### 音量條漸層
+
+```css
+/* 專業音量表漸層 */
+.volume-bar__fill {
+  background: linear-gradient(
+    to top,
+    #22c55e 0%,      /* 綠色：安全區 */
+    #22c55e 60%,
+    #eab308 60%,     /* 黃色：警告區 */
+    #eab308 85%,
+    #ef4444 85%,     /* 紅色：過載區 */
+    #ef4444 100%
+  );
+}
+
+/* 過載指示燈 */
+.volume-bar__peak-indicator {
+  background: #ef4444;
+  opacity: var(--is-clipping, 0);
+  transition: opacity 50ms;
+}
+
+.volume-bar__peak-indicator.active {
+  --is-clipping: 1;
+}
+```
+
+### 把手效果
+
+```css
+/* 滑桿把手 */
+.slider__thumb {
+  position: absolute;
+  width: 16px;
+  height: 16px;
+  background: var(--thumb-color, #fff);
+  border-radius: 50%;
+  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.2);
+
+  /* 位置由 CSS 變數控制 */
+  left: calc(var(--value-normalized) * 100% - 8px);
+
+  /* 懸停效果 */
+  transition: transform 100ms, box-shadow 100ms;
+}
+
+.slider__thumb:hover,
+.slider[data-dragging="true"] .slider__thumb {
+  transform: scale(1.2);
+  box-shadow: 0 4px 8px rgba(0, 0, 0, 0.3);
+}
+```
+
+---
+
+## 數值顯示
+
+### 即時數值提示
+
+```typescript
+// 拖曳時顯示數值標籤
+const ValueTooltip: React.FC<{
+  value: number;
+  isVisible: boolean;
+  format: (v: number) => string;
+}> = ({ value, isVisible, format }) => {
+  return (
+    <div
+      className="value-tooltip"
+      style={{
+        opacity: isVisible ? 1 : 0,
+        transform: `translateY(${isVisible ? 0 : 10}px)`,
+        transition: 'opacity 150ms, transform 150ms',
+      }}
+    >
+      {format(value)}
+    </div>
+  );
+};
+```
+
+### Native Label 整合
+
+```typescript
+// 使用原生標籤系統
+const { setNativeLabel } = useNativeLabel();
+
+// 拖曳開始時顯示
+const handleDragStart = () => {
+  setNativeLabel(true);
+};
+
+// 拖曳結束後延遲隱藏
+const handleDragEnd = () => {
+  setTimeout(() => {
+    setNativeLabel(false);
+  }, 1000); // 1 秒後隱藏
+};
+```
+
+---
+
+## 精確模式視覺
+
+### 模式指示
+
+```css
+/* 精確模式指示 */
+.audio-control[data-precise-mode="true"]::after {
+  content: 'FINE';
+  position: absolute;
+  top: -20px;
+  left: 50%;
+  transform: translateX(-50%);
+  font-size: 10px;
+  color: var(--precise-indicator-color, #d3cd36);
+  opacity: 1;
+  transition: opacity 150ms;
+}
+```
+
+### 靈敏度視覺回饋
+
+```typescript
+// 精確模式下的視覺提示
+const PreciseModeIndicator: React.FC<{ isActive: boolean }> = ({ isActive }) => {
+  return (
+    <div
+      className={`precise-indicator ${isActive ? 'active' : ''}`}
+      aria-hidden="true"
+    >
+      <span className="precise-indicator__icon">🎯</span>
+      <span className="precise-indicator__text">Fine Adjust</span>
+    </div>
+  );
+};
+```
+
+---
+
+## 錯誤與警告視覺
+
+### 邊界錯誤動畫
+
+```css
+/* 錯誤閃爍動畫 */
+@keyframes errorSplash {
+  0%, 100% {
+    border-color: transparent;
+    background-color: transparent;
+  }
+  50% {
+    border-color: #ef4444;
+    background-color: rgba(239, 68, 68, 0.1);
+  }
+}
+
+.input-error {
+  animation: errorSplash 300ms linear 3;
+}
+```
+
+### 超出範圍提示
+
+```css
+/* 超出範圍視覺提示 */
+.value-display.out-of-range {
+  color: #ef4444;
+}
+
+.value-display.out-of-range::before {
+  content: '⚠️ ';
+}
+```
+
+---
+
+## 過渡動畫
+
+### 值變更過渡
+
+```css
+/* 外部值變更時的平滑過渡 */
+.audio-control:not([data-dragging="true"]) {
+  --value-transition: 100ms ease-out;
+}
+
+.knob__indicator {
+  transition: transform var(--value-transition, 0ms);
+}
+
+.slider__fill {
+  transition: width var(--value-transition, 0ms),
+              height var(--value-transition, 0ms);
+}
+```
+
+### 預設載入動畫
+
+```css
+/* 預設載入時的動畫 */
+@keyframes valueSet {
+  0% {
+    filter: brightness(1.5);
+  }
+  100% {
+    filter: brightness(1);
+  }
+}
+
+.audio-control.preset-loading {
+  animation: valueSet 300ms ease-out;
+}
+```
+
+---
+
+## 效能考量
+
+### 使用 GPU 加速
+
+```css
+/* 使用 transform 而非直接改變位置 */
+.knob__indicator {
+  /* ✅ 好：使用 transform */
+  transform: rotate(var(--rotation));
+
+  /* ❌ 避免：直接旋轉可能觸發重排 */
+  /* rotate: var(--rotation); */
+}
+
+/* 啟用 GPU 加速 */
+.slider__fill {
+  will-change: transform;
+  transform: scaleX(var(--value-normalized));
+  transform-origin: left center;
+}
+```
+
+### 避免 Layout Thrashing
+
+```typescript
+// ✅ 好：批次讀取後批次寫入
+const updateMultipleControls = (updates: ControlUpdate[]) => {
+  // 先批次讀取
+  const measurements = updates.map(u => ({
+    rect: u.element.getBoundingClientRect(),
+    ...u,
+  }));
+
+  // 再批次寫入
+  requestAnimationFrame(() => {
+    measurements.forEach(m => {
+      m.element.style.setProperty('--value', String(m.value));
+    });
+  });
+};
+
+// ❌ 避免：交錯讀寫
+updates.forEach(u => {
+  const rect = u.element.getBoundingClientRect(); // 讀
+  u.element.style.setProperty('--value', String(u.value)); // 寫
+  // 每次循環都會觸發重排
+});
+```
+
+---
+
+## 最佳實踐
+
+1. **使用 CSS 變數** - 透過 CSS 變數更新視覺，避免 React 重新渲染
+2. **區分拖曳與非拖曳** - 拖曳時無過渡，外部更新時有過渡
+3. **使用 transform** - 優先使用 transform 進行視覺變化
+4. **批次更新** - 將多個 DOM 更新合併到同一 RAF 回調
+5. **適當的過渡時長** - 過渡動畫不超過 150ms，保持即時感
+
+---
+
+## 相關文件
+
+- [樣式系統架構](./styling-architecture.md) - CSS 架構設計
+- [效能最佳化策略](../optimization/performance-optimization.md) - 視覺更新效能
+- [API 設計參考](./api-design-reference.md) - 視覺相關 Props

package/content/docs/knowledge/component-library/ControlComponent/development-environment.md

@@ -0,0 +1,213 @@
+# 開發環境與專案結構指南
+
+本文件說明如何建立一個高效的 Audio Plugin 控制元件開發環境，包含推薦的專案結構以及互動式遊樂場 (Playground) 的設置。
+
+---
+
+## 推薦專案結構
+
+為了確保元件的獨立性與可維護性，建議採用以下目錄結構：
+
+```
+src/
+├── components/              # UI 元件庫
+│   ├── Knob/               # Knob 元件
+│   │   ├── index.tsx       # 元件入口
+│   │   ├── Knob.tsx        # 實作邏輯
+│   │   ├── types.ts        # 類型定義
+│   │   ├── constants.ts    # 常數配置
+│   │   └── styles.module.css
+│   ├── Slider/             # Slider 元件
+│   │   └── ...
+│   └── shared/             # 共用子元件 (如 Label, ValueDisplay)
+│
+├── hooks/                   # 共用 Hooks
+│   ├── useAudioControl.ts  # 核心互動邏輯
+│   ├── useParameter.ts     # Native Interface 綁定
+│   ├── usePreciseMode.ts   # 精確模式處理
+│   └── usePlatform.ts      # 平台檢測
+│
+├── core/                    # 核心定義
+│   ├── NativeInterface.ts  # 介面契約定義
+│   └── MockHost.ts         # 開發用 Mock 實作
+│
+├── contexts/                # React Contexts
+│   └── NativeInterfaceContext.tsx
+│
+├── utils/                   # 工具函數
+│   ├── math.ts             # 數值運算 (clamp, normalize)
+│   ├── platform.ts         # 平台檢測工具
+│   └── css.ts              # CSS 變數操作
+│
+├── styles/                  # 全域樣式
+│   ├── variables.css       # CSS 變數定義
+│   └── reset.css           # 樣式重置
+│
+└── playground/              # 開發遊樂場 (App Entry)
+    ├── App.tsx             # 遊樂場主程式
+    └── main.tsx            # 入口點
+```
+
+---
+
+## 互動式遊樂場 (Playground)
+
+在開發 Audio Plugin UI 時，我們通常無法隨時連接真實的 DSP 後端。因此，建立一個「互動式遊樂場」至關重要。
+
+### 1. 建立 Mock Host
+
+首先，我們需要一個模擬的 Host 來實作 `NativeInterface`。這個 Mock Host 應該將狀態儲存在記憶體中，並模擬 DAW 的行為。
+
+```typescript
+// core/MockHost.ts
+import { NativeInterface } from './NativeInterface';
+
+class MockHost implements NativeInterface {
+  private values = new Map<number, number>();
+  private listeners = new Map<number, Set<(v: number) => void>>();
+
+  constructor() {
+    // 初始化一些預設值
+    this.values.set(0, 0.5); // Gain
+    this.values.set(1, 0.0); // Volume
+  }
+
+  parameter = {
+    getValue: (pid: number) => this.values.get(pid) ?? 0,
+
+    setValue: (pid: number, value: number) => {
+      this.values.set(pid, value);
+      this.notifyListeners(pid, value);
+      console.log(`[MockHost] Set Param ${pid} = ${value.toFixed(3)}`);
+    },
+
+    getDisplayValue: (pid: number) => {
+      const val = this.values.get(pid) ?? 0;
+      return `${(val * 100).toFixed(1)} %`;
+    },
+
+    beginGesture: (pid: number) => console.log(`[MockHost] Begin Gesture ${pid}`),
+    endGesture: (pid: number) => console.log(`[MockHost] End Gesture ${pid}`),
+  };
+
+  subscribe(pid: number, callback: (value: number) => void) {
+    if (!this.listeners.has(pid)) {
+      this.listeners.set(pid, new Set());
+    }
+    this.listeners.get(pid)!.add(callback);
+
+    // 立即回調當前值
+    callback(this.parameter.getValue(pid));
+
+    return () => {
+      this.listeners.get(pid)?.delete(callback);
+    };
+  }
+
+  private notifyListeners(pid: number, value: number) {
+    this.listeners.get(pid)?.forEach((cb) => cb(value));
+  }
+}
+
+export const mockHost = new MockHost();
+```
+
+### 2. 設定 Storybook (推薦)
+
+Storybook 是最適合 UI 元件開發的環境。它允許你獨立開發每個元件，並提供控制項來測試不同狀態。
+
+**安裝 Storybook:**
+
+```bash
+npx storybook@latest init
+```
+
+**編寫 Story (Knob.stories.tsx):**
+
+```typescript
+import type { Meta, StoryObj } from '@storybook/react';
+import { Knob } from './Knob';
+import { NativeInterfaceProvider } from '../contexts/NativeInterfaceContext';
+import { mockHost } from '../core/MockHost';
+
+const meta: Meta<typeof Knob> = {
+  component: Knob,
+  decorators: [
+    (Story) => (
+      <NativeInterfaceProvider value={mockHost}>
+        <div style={{ padding: '2rem', background: '#222' }}>
+          <Story />
+        </div>
+      </NativeInterfaceProvider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof Knob>;
+
+export const Default: Story = {
+  args: {
+    pid: 0,
+    label: 'Gain',
+  },
+};
+
+export const Large: Story = {
+  args: {
+    pid: 0,
+    label: 'Master',
+    size: 'large',
+  },
+};
+```
+
+### 3. 簡易開發頁面 (Alternative)
+
+如果你不想使用 Storybook，也可以建立一個簡單的 `App.tsx` 作為開發頁面。
+
+```typescript
+// playground/App.tsx
+import React from 'react';
+import { NativeInterfaceProvider } from '../contexts/NativeInterfaceContext';
+import { mockHost } from '../core/MockHost';
+import { Knob } from '../components/Knob';
+import { Slider } from '../components/Slider';
+
+export const App = () => {
+  return (
+    <NativeInterfaceProvider value={mockHost}>
+      <div className="playground">
+        <h1>Audio Control Playground</h1>
+
+        <section className="control-group">
+          <h2>Knobs</h2>
+          <div className="row">
+            <Knob pid={0} label="Gain" />
+            <Knob pid={1} label="Drive" size="large" />
+            <Knob pid={2} label="Tone" size="small" />
+          </div>
+        </section>
+
+        <section className="control-group">
+          <h2>Sliders</h2>
+          <div className="row">
+            <Slider pid={3} label="Volume" orientation="vertical" />
+            <Slider pid={4} label="Mix" orientation="horizontal" />
+          </div>
+        </section>
+      </div>
+    </NativeInterfaceProvider>
+  );
+};
+```
+
+---
+
+## 開發流程建議
+
+1.  **定義 API**: 先在 `types.ts` 定義好元件的 Props。
+2.  **建立 Mock**: 在 `MockHost` 中準備好測試用的參數 ID 和預設值。
+3.  **Storybook 開發**: 使用 Storybook 建立元件的各種狀態 (Normal, Disabled, Large, etc.)。
+4.  **互動測試**: 在 Storybook 或 Playground 中測試拖曳、滾輪、精確模式等互動。
+5.  **整合測試**: 最後再整合到真實的 Plugin Host 環境中。