create-pardx-scaffold 0.1.0

package/template/apps/web/hooks/useAspectRatioSize.ts

@@ -0,0 +1,187 @@
+import { useState, useCallback, useEffect } from 'react';
+
+// 解析宽高比字符串为数字
+const parseAspectRatio = (ratio: string): [number, number] => {
+  const [w, h] = ratio.split(':').map(Number);
+  return [w ?? 0, h ?? 0];
+};
+
+// 根据分辨率获取基准尺寸
+const getBaseSize = (resolution: string): number => {
+  switch (resolution) {
+    case '1K':
+      return 1024;
+    case '2K':
+      return 2048;
+    case '4K':
+      return 4096;
+    default:
+      return 2048;
+  }
+};
+
+// 根据比例计算最大尺寸限制
+const getMaxDimensions = (aspectRatio: string): [number, number] => {
+  const [w, h] = parseAspectRatio(aspectRatio);
+  const maxDimension = 6240;
+
+  if (w > h) {
+    // 横向比例：以高度为基准计算宽度
+    const maxHeight = maxDimension;
+    const maxWidth = Math.round(maxDimension * (w / h));
+    // 如果计算出的宽度超过最大限制，则以宽度为基准重新计算
+    return maxWidth > maxDimension
+      ? [maxDimension, Math.round(maxDimension * (h / w))]
+      : [maxWidth, maxHeight];
+  } else {
+    // 纵向比例：以宽度为基准计算高度
+    const maxWidth = maxDimension;
+    const maxHeight = Math.round(maxDimension * (h / w));
+    // 如果计算出的高度超过最大限制，则以高度为基准重新计算
+    return maxHeight > maxDimension
+      ? [Math.round(maxDimension * (w / h)), maxDimension]
+      : [maxWidth, maxHeight];
+  }
+};
+
+// 根据宽高比和分辨率计算尺寸
+const calculateSize = (
+  aspectRatio: string,
+  resolution: string,
+): [number, number] => {
+  const [w, h] = parseAspectRatio(aspectRatio);
+  const baseSize = getBaseSize(resolution);
+  const [maxWidth, maxHeight] = getMaxDimensions(aspectRatio);
+
+  // 计算最适合的尺寸，保持比例
+  if (w > h) {
+    // 横向比例：宽度为主导
+    const width = Math.min(baseSize, maxWidth, Math.round(baseSize * (w / h)));
+    const height = Math.round(width * (h / w));
+    return [width, height];
+  } else {
+    // 纵向比例：高度为主导
+    const height = Math.min(
+      baseSize,
+      maxHeight,
+      Math.round(baseSize * (h / w)),
+    );
+    const width = Math.round(height * (w / h));
+    return [width, height];
+  }
+};
+
+interface UseAspectRatioSizeOptions {
+  initialAspectRatio?: string;
+  initialResolution?: string;
+  initialRatioLocked?: boolean;
+  onSizeChange?: (width: number, height: number) => void;
+}
+
+interface UseAspectRatioSizeReturn {
+  width: number;
+  height: number;
+  ratioLocked: boolean;
+  setRatioLocked: (locked: boolean) => void;
+  handleWidthChange: (value: string, aspectRatio: string) => void;
+  handleHeightChange: (value: string, aspectRatio: string) => void;
+  updateSizeFromRatio: (aspectRatio: string, resolution: string) => void;
+}
+
+export function useAspectRatioSize({
+  initialAspectRatio = '3:4',
+  initialResolution = '2K',
+  initialRatioLocked = true,
+  onSizeChange,
+}: UseAspectRatioSizeOptions): UseAspectRatioSizeReturn {
+  const [width, setWidth] = useState<number>(() => {
+    const [w] = calculateSize(initialAspectRatio, initialResolution);
+    return w;
+  });
+  const [height, setHeight] = useState<number>(() => {
+    const [, h] = calculateSize(initialAspectRatio, initialResolution);
+    return h;
+  });
+  const [ratioLocked, setRatioLocked] = useState<boolean>(initialRatioLocked);
+
+  // 更新尺寸的方法
+  const updateSizeFromRatio = useCallback(
+    (aspectRatio: string, resolution: string) => {
+      const [newWidth, newHeight] = calculateSize(aspectRatio, resolution);
+      setWidth(newWidth);
+      setHeight(newHeight);
+    },
+    [],
+  );
+
+  // 处理宽度输入 - 需要外部传入当前aspectRatio
+  const handleWidthChange = useCallback(
+    (value: string, currentAspectRatio: string) => {
+      const numValue = parseInt(value);
+
+      // 如果输入不是有效数字，忽略
+      if (isNaN(numValue) || value === '') return;
+
+      // 根据比例获取最大尺寸限制
+      const [maxWidth] = getMaxDimensions(currentAspectRatio);
+
+      // 限制在有效范围内，如果超出范围则修正
+      const clampedValue = Math.max(1, Math.min(maxWidth, numValue));
+      setWidth(clampedValue);
+
+      if (ratioLocked) {
+        const [w, h] = parseAspectRatio(currentAspectRatio);
+        const newHeight = Math.round(clampedValue * (h / w));
+        // 根据比例获取最大高度限制
+        const [, maxHeight] = getMaxDimensions(currentAspectRatio);
+        const clampedHeight = Math.max(1, Math.min(maxHeight, newHeight));
+        setHeight(clampedHeight);
+      }
+    },
+    [ratioLocked],
+  );
+
+  // 处理高度输入 - 需要外部传入当前aspectRatio
+  const handleHeightChange = useCallback(
+    (value: string, currentAspectRatio: string) => {
+      const numValue = parseInt(value);
+
+      // 如果输入不是有效数字，忽略
+      if (isNaN(numValue) || value === '') return;
+
+      // 根据比例获取最大尺寸限制
+      const [, maxHeight] = getMaxDimensions(currentAspectRatio);
+
+      // 限制在有效范围内，如果超出范围则修正
+      const clampedValue = Math.max(1, Math.min(maxHeight, numValue));
+      setHeight(clampedValue);
+
+      if (ratioLocked) {
+        const [w, h] = parseAspectRatio(currentAspectRatio);
+        const newWidth = Math.round(clampedValue * (w / h));
+        // 根据比例获取最大宽度限制
+        const [maxWidth] = getMaxDimensions(currentAspectRatio);
+        const clampedWidth = Math.max(1, Math.min(maxWidth, newWidth));
+        setWidth(clampedWidth);
+      }
+    },
+    [ratioLocked],
+  );
+
+  // 同步尺寸变化到外部（如 form）
+  useEffect(() => {
+    if (onSizeChange) {
+      onSizeChange(width, height);
+    }
+  }, [width, height, onSizeChange]);
+
+  return {
+    width,
+    height,
+    ratioLocked,
+    setRatioLocked,
+    handleWidthChange,
+    handleHeightChange,
+    updateSizeFromRatio,
+  };
+}

package/template/apps/web/hooks/useDebouncedValue.ts

@@ -0,0 +1,25 @@
+'use client';
+
+import { useState, useEffect } from 'react';
+
+/**
+ * 防抖 hook，延迟更新值
+ * @param value 需要防抖的值
+ * @param delay 延迟时间（毫秒），默认 500ms
+ * @returns 防抖后的值
+ */
+export function useDebouncedValue<T>(value: T, delay = 500): T {
+  const [debouncedValue, setDebouncedValue] = useState<T>(value);
+
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      setDebouncedValue(value);
+    }, delay);
+
+    return () => {
+      clearTimeout(timer);
+    };
+  }, [value, delay]);
+
+  return debouncedValue;
+}

package/template/apps/web/hooks/useErrorHandler.ts

@@ -0,0 +1,113 @@
+/**
+ * useErrorHandler - 统一的错误处理 Hook
+ * 提供友好的错误提示和错误分类处理
+ */
+
+import { useCallback } from 'react';
+import { useOperationFeedback } from './useOperationFeedback';
+import { useTranslations } from 'next-intl';
+
+/**
+ * 错误类型定义
+ */
+export class NetworkError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'NetworkError';
+  }
+}
+
+export class ValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ValidationError';
+  }
+}
+
+export class AuthenticationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'AuthenticationError';
+  }
+}
+
+export class PermissionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'PermissionError';
+  }
+}
+
+/**
+ * 统一错误处理 Hook
+ *
+ * @example
+ * ```tsx
+ * const handleError = useErrorHandler();
+ *
+ * try {
+ *   await someOperation();
+ * } catch (error) {
+ *   handleError(error);
+ * }
+ * ```
+ */
+export function useErrorHandler() {
+  const { error } = useOperationFeedback();
+  const t = useTranslations('errors');
+
+  const handleError = useCallback(
+    (err: unknown, customMessage?: string) => {
+      // 如果有自定义消息，直接使用
+      if (customMessage) {
+        error(customMessage);
+        return;
+      }
+
+      // 根据错误类型显示不同的提示
+      if (err instanceof NetworkError) {
+        error(
+          t('network', {
+            defaultValue: '网络连接失败，请检查网络后重试',
+          }),
+        );
+      } else if (err instanceof ValidationError) {
+        error(
+          t('validation', {
+            defaultValue: '输入数据格式不正确，请检查后重试',
+          }),
+        );
+      } else if (err instanceof AuthenticationError) {
+        error(
+          t('authentication', {
+            defaultValue: '登录已过期，请重新登录',
+          }),
+        );
+      } else if (err instanceof PermissionError) {
+        error(
+          t('permission', {
+            defaultValue: '您没有权限执行此操作',
+          }),
+        );
+      } else if (err instanceof Error) {
+        // 普通 Error 对象，显示错误消息
+        error(
+          err.message ||
+            t('unknown', {
+              defaultValue: '操作失败，请稍后重试',
+            }),
+        );
+      } else {
+        // 未知错误类型
+        error(
+          t('unknown', {
+            defaultValue: '操作失败，请稍后重试',
+          }),
+        );
+      }
+    },
+    [error, t],
+  );
+
+  return handleError;
+}

package/template/apps/web/hooks/useHotkeys.ts

@@ -0,0 +1,251 @@
+'use client';
+
+import { useEffect, useCallback, useRef } from 'react';
+
+/**
+ * Hotkey definition
+ */
+export interface HotkeyConfig {
+  /** Key combination (e.g., 'Space', 'Ctrl+S', 'Meta+Shift+P') */
+  key: string;
+  /** Callback when hotkey is pressed */
+  handler: (event: KeyboardEvent) => void;
+  /** Whether to prevent default behavior (default: true) */
+  preventDefault?: boolean;
+  /** Whether to stop propagation (default: false) */
+  stopPropagation?: boolean;
+  /** Only trigger when these elements are NOT focused */
+  ignoreInputs?: boolean;
+  /** Description for accessibility */
+  description?: string;
+  /** Whether the hotkey is enabled (default: true) */
+  enabled?: boolean;
+}
+
+/**
+ * Parse key combination string into parts
+ */
+function parseKey(key: string): {
+  key: string;
+  ctrl: boolean;
+  alt: boolean;
+  shift: boolean;
+  meta: boolean;
+} {
+  const parts = key
+    .toLowerCase()
+    .split('+')
+    .map((p) => p.trim());
+  const mainKey = parts[parts.length - 1] ?? '';
+
+  return {
+    key: mainKey === 'space' ? ' ' : mainKey,
+    ctrl: parts.includes('ctrl') || parts.includes('control'),
+    alt: parts.includes('alt') || parts.includes('option'),
+    shift: parts.includes('shift'),
+    meta:
+      parts.includes('meta') ||
+      parts.includes('cmd') ||
+      parts.includes('command'),
+  };
+}
+
+/**
+ * Check if an element is an input element
+ */
+function isInputElement(element: Element | null): boolean {
+  if (!element) return false;
+
+  const tagName = element.tagName.toLowerCase();
+  if (tagName === 'input' || tagName === 'textarea' || tagName === 'select') {
+    return true;
+  }
+
+  if (element.getAttribute('contenteditable') === 'true') {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Custom hook for keyboard shortcuts
+ *
+ * Features:
+ * - Support for key combinations (Ctrl, Alt, Shift, Meta)
+ * - Option to ignore when input elements are focused
+ * - Enable/disable hotkeys dynamically
+ * - Prevent default and stop propagation options
+ *
+ * @example
+ * ```tsx
+ * useHotkeys([
+ *   { key: 'Space', handler: toggleRecording, description: 'Toggle recording' },
+ *   { key: 'Escape', handler: cancelRecording, description: 'Cancel recording' },
+ *   { key: 'Ctrl+S', handler: saveRecording, description: 'Save recording' },
+ * ]);
+ * ```
+ */
+export function useHotkeys(
+  hotkeys: HotkeyConfig[],
+  deps: React.DependencyList = [],
+) {
+  const hotkeysRef = useRef(hotkeys);
+
+  // Update ref when hotkeys change
+  useEffect(() => {
+    hotkeysRef.current = hotkeys;
+  }, [hotkeys]);
+
+  const handleKeyDown = useCallback((event: KeyboardEvent) => {
+    const activeElement = document.activeElement;
+
+    for (const hotkey of hotkeysRef.current) {
+      // Skip if disabled
+      if (hotkey.enabled === false) continue;
+
+      // Skip if focused on input and ignoreInputs is true
+      if (hotkey.ignoreInputs !== false && isInputElement(activeElement)) {
+        continue;
+      }
+
+      const parsed = parseKey(hotkey.key);
+
+      // Check if key matches
+      const keyMatches =
+        event.key.toLowerCase() === parsed.key ||
+        event.code.toLowerCase() === parsed.key ||
+        event.code.toLowerCase() === `key${parsed.key}`;
+
+      // Check modifiers
+      const modifiersMatch =
+        event.ctrlKey === parsed.ctrl &&
+        event.altKey === parsed.alt &&
+        event.shiftKey === parsed.shift &&
+        event.metaKey === parsed.meta;
+
+      if (keyMatches && modifiersMatch) {
+        if (hotkey.preventDefault !== false) {
+          event.preventDefault();
+        }
+
+        if (hotkey.stopPropagation) {
+          event.stopPropagation();
+        }
+
+        hotkey.handler(event);
+        return;
+      }
+    }
+  }, []);
+
+  useEffect(() => {
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
+  }, [handleKeyDown, ...deps]);
+}
+
+/**
+ * Hook for a single hotkey
+ */
+export function useHotkey(
+  key: string,
+  handler: (event: KeyboardEvent) => void,
+  options: Omit<HotkeyConfig, 'key' | 'handler'> = {},
+  deps: React.DependencyList = [],
+) {
+  useHotkeys([{ key, handler, ...options }], deps);
+}
+
+/**
+ * Recording-specific hotkeys preset
+ */
+export interface RecordingHotkeysConfig {
+  onToggleRecording?: () => void;
+  onPauseResume?: () => void;
+  onStop?: () => void;
+  onCancel?: () => void;
+  enabled?: boolean;
+}
+
+/**
+ * Hook for recording-specific keyboard shortcuts
+ *
+ * Default shortcuts:
+ * - Space: Pause/Resume
+ * - Enter: Stop recording
+ * - Escape: Cancel recording
+ * - R: Start recording (when idle)
+ *
+ * @example
+ * ```tsx
+ * useRecordingHotkeys({
+ *   onToggleRecording: handleToggle,
+ *   onPauseResume: handlePauseResume,
+ *   onStop: handleStop,
+ *   onCancel: handleCancel,
+ *   enabled: isRecordingActive,
+ * });
+ * ```
+ */
+export function useRecordingHotkeys(config: RecordingHotkeysConfig) {
+  const {
+    onToggleRecording,
+    onPauseResume,
+    onStop,
+    onCancel,
+    enabled = true,
+  } = config;
+
+  const hotkeys: HotkeyConfig[] = [];
+
+  if (onPauseResume) {
+    hotkeys.push({
+      key: 'Space',
+      handler: onPauseResume,
+      description: 'Pause/Resume recording',
+      enabled,
+      ignoreInputs: true,
+    });
+  }
+
+  if (onStop) {
+    hotkeys.push({
+      key: 'Enter',
+      handler: onStop,
+      description: 'Stop recording',
+      enabled,
+      ignoreInputs: true,
+    });
+  }
+
+  if (onCancel) {
+    hotkeys.push({
+      key: 'Escape',
+      handler: onCancel,
+      description: 'Cancel recording',
+      enabled,
+      ignoreInputs: true,
+    });
+  }
+
+  if (onToggleRecording) {
+    hotkeys.push({
+      key: 'r',
+      handler: onToggleRecording,
+      description: 'Toggle recording',
+      enabled,
+      ignoreInputs: true,
+    });
+  }
+
+  useHotkeys(hotkeys, [
+    enabled,
+    onToggleRecording,
+    onPauseResume,
+    onStop,
+    onCancel,
+  ]);
+}
+
+export default useHotkeys;