@djangocfg/ui-nextjs 2.1.65 → 2.1.66

package/src/tools/AudioPlayer/useAudioHotkeys.ts

@@ -0,0 +1,142 @@
+'use client';
+
+/**
+ * Audio Player Hotkeys Hook
+ *
+ * Provides keyboard shortcuts for audio playback control.
+ * Uses useHotkey from @djangocfg/ui-nextjs.
+ */
+
+import { useHotkey, useDeviceDetect } from '@djangocfg/ui-nextjs';
+import { useAudioControls, useAudioState } from './context';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface AudioHotkeyOptions {
+  /** Enable hotkeys (default: true) */
+  enabled?: boolean;
+  /** Skip duration in seconds (default: 10) */
+  skipDuration?: number;
+  /** Volume step (default: 0.1) */
+  volumeStep?: number;
+}
+
+// =============================================================================
+// HOOK
+// =============================================================================
+
+export function useAudioHotkeys(options: AudioHotkeyOptions = {}) {
+  const { enabled = true, skipDuration = 10, volumeStep = 0.1 } = options;
+
+  const { togglePlay, skip, setVolume, toggleMute, isReady } = useAudioControls();
+  const { volume, duration } = useAudioState();
+  const device = useDeviceDetect();
+
+  // Play/Pause - Space
+  useHotkey(
+    'space',
+    (e) => {
+      e.preventDefault();
+      togglePlay();
+    },
+    { enabled: enabled && isReady, description: 'Play/Pause' }
+  );
+
+  // Skip backward - ArrowLeft or J
+  useHotkey(
+    ['ArrowLeft', 'j'],
+    () => skip(-skipDuration),
+    { enabled: enabled && isReady, description: `Skip ${skipDuration}s backward` }
+  );
+
+  // Skip forward - ArrowRight or L
+  useHotkey(
+    ['ArrowRight', 'l'],
+    () => skip(skipDuration),
+    { enabled: enabled && isReady, description: `Skip ${skipDuration}s forward` }
+  );
+
+  // Volume up - ArrowUp
+  useHotkey(
+    'ArrowUp',
+    (e) => {
+      e.preventDefault();
+      setVolume(Math.min(1, volume + volumeStep));
+    },
+    { enabled: enabled && isReady, description: 'Volume up' }
+  );
+
+  // Volume down - ArrowDown
+  useHotkey(
+    'ArrowDown',
+    (e) => {
+      e.preventDefault();
+      setVolume(Math.max(0, volume - volumeStep));
+    },
+    { enabled: enabled && isReady, description: 'Volume down' }
+  );
+
+  // Mute/Unmute - M
+  useHotkey(
+    'm',
+    () => toggleMute(),
+    { enabled: enabled && isReady, description: 'Mute/Unmute' }
+  );
+
+  // Number keys 0-9 to seek to percentage
+  useHotkey(
+    ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9'],
+    (e) => {
+      if (!duration) return;
+      const percent = parseInt(e.key, 10) / 10;
+      skip(duration * percent - duration * (volume || 0));
+    },
+    { enabled: enabled && isReady, description: 'Seek to percentage' }
+  );
+
+  return {
+    isMac: device.isMacOs,
+    isEnabled: enabled && isReady,
+  };
+}
+
+// =============================================================================
+// SHORTCUTS CONFIG (for display)
+// =============================================================================
+
+export interface ShortcutItem {
+  keys: string[];
+  label: string;
+}
+
+export interface ShortcutGroup {
+  title: string;
+  shortcuts: ShortcutItem[];
+}
+
+export const AUDIO_SHORTCUTS: ShortcutGroup[] = [
+  {
+    title: 'Playback',
+    shortcuts: [
+      { keys: ['Space'], label: 'Play/Pause' },
+      { keys: ['←'], label: 'Skip 10s back' },
+      { keys: ['→'], label: 'Skip 10s forward' },
+    ],
+  },
+  {
+    title: 'Volume',
+    shortcuts: [
+      { keys: ['↑'], label: 'Volume up' },
+      { keys: ['↓'], label: 'Volume down' },
+      { keys: ['M'], label: 'Mute/Unmute' },
+    ],
+  },
+  {
+    title: 'Seek',
+    shortcuts: [
+      { keys: ['0-9'], label: 'Jump to 0-90%' },
+    ],
+  },
+];

package/src/tools/AudioPlayer/useAudioVisualization.tsx

@@ -0,0 +1,195 @@
+'use client';
+
+/**
+ * useAudioVisualization - Hook for managing audio visualization settings
+ *
+ * Persists settings in localStorage for user preferences
+ * Uses React Context for shared state between components
+ */
+
+import { createContext, useContext, useCallback, useMemo, type ReactNode } from 'react';
+import { useLocalStorage } from '@djangocfg/ui-nextjs';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export type VisualizationVariant = 'glow' | 'orbs' | 'spotlight' | 'mesh' | 'none';
+export type VisualizationIntensity = 'subtle' | 'medium' | 'strong';
+export type VisualizationColorScheme = 'primary' | 'vibrant' | 'cool' | 'warm';
+
+export interface VisualizationSettings {
+  /** Enable reactive cover animation */
+  enabled: boolean;
+  /** Visual effect variant */
+  variant: VisualizationVariant;
+  /** Effect intensity */
+  intensity: VisualizationIntensity;
+  /** Color scheme */
+  colorScheme: VisualizationColorScheme;
+}
+
+export interface UseAudioVisualizationReturn {
+  /** Current settings */
+  settings: VisualizationSettings;
+  /** Toggle visualization on/off */
+  toggle: () => void;
+  /** Set specific setting */
+  setSetting: <K extends keyof VisualizationSettings>(
+    key: K,
+    value: VisualizationSettings[K]
+  ) => void;
+  /** Cycle to next variant */
+  nextVariant: () => void;
+  /** Cycle to next intensity */
+  nextIntensity: () => void;
+  /** Cycle to next color scheme */
+  nextColorScheme: () => void;
+  /** Reset to defaults */
+  reset: () => void;
+}
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const STORAGE_KEY = 'audio-visualization-settings';
+
+const DEFAULT_SETTINGS: VisualizationSettings = {
+  enabled: true,
+  variant: 'spotlight',
+  intensity: 'medium',
+  colorScheme: 'primary',
+};
+
+const VARIANTS: VisualizationVariant[] = ['spotlight', 'glow', 'orbs', 'mesh', 'none'];
+const INTENSITIES: VisualizationIntensity[] = ['subtle', 'medium', 'strong'];
+const COLOR_SCHEMES: VisualizationColorScheme[] = ['primary', 'vibrant', 'cool', 'warm'];
+
+// =============================================================================
+// CONTEXT
+// =============================================================================
+
+const VisualizationContext = createContext<UseAudioVisualizationReturn | null>(null);
+
+// =============================================================================
+// PROVIDER
+// =============================================================================
+
+export interface VisualizationProviderProps {
+  children: ReactNode;
+}
+
+export function VisualizationProvider({ children }: VisualizationProviderProps) {
+  const value = useVisualizationState();
+  return (
+    <VisualizationContext.Provider value={value}>
+      {children}
+    </VisualizationContext.Provider>
+  );
+}
+
+// =============================================================================
+// INTERNAL HOOK (creates the actual state)
+// =============================================================================
+
+function useVisualizationState(): UseAudioVisualizationReturn {
+  const [settings, setSettings] = useLocalStorage<VisualizationSettings>(
+    STORAGE_KEY,
+    DEFAULT_SETTINGS
+  );
+
+  const toggle = useCallback(() => {
+    setSettings((prev) => ({ ...prev, enabled: !prev.enabled }));
+  }, [setSettings]);
+
+  const setSetting = useCallback(
+    <K extends keyof VisualizationSettings>(
+      key: K,
+      value: VisualizationSettings[K]
+    ) => {
+      setSettings((prev) => ({ ...prev, [key]: value }));
+    },
+    [setSettings]
+  );
+
+  const nextVariant = useCallback(() => {
+    setSettings((prev) => {
+      const currentIndex = VARIANTS.indexOf(prev.variant);
+      const nextIndex = (currentIndex + 1) % VARIANTS.length;
+      return { ...prev, variant: VARIANTS[nextIndex] };
+    });
+  }, [setSettings]);
+
+  const nextIntensity = useCallback(() => {
+    setSettings((prev) => {
+      const currentIndex = INTENSITIES.indexOf(prev.intensity);
+      const nextIndex = (currentIndex + 1) % INTENSITIES.length;
+      return { ...prev, intensity: INTENSITIES[nextIndex] };
+    });
+  }, [setSettings]);
+
+  const nextColorScheme = useCallback(() => {
+    setSettings((prev) => {
+      const currentIndex = COLOR_SCHEMES.indexOf(prev.colorScheme);
+      const nextIndex = (currentIndex + 1) % COLOR_SCHEMES.length;
+      return { ...prev, colorScheme: COLOR_SCHEMES[nextIndex] };
+    });
+  }, [setSettings]);
+
+  const reset = useCallback(() => {
+    setSettings(DEFAULT_SETTINGS);
+  }, [setSettings]);
+
+  return useMemo(
+    () => ({
+      settings,
+      toggle,
+      setSetting,
+      nextVariant,
+      nextIntensity,
+      nextColorScheme,
+      reset,
+    }),
+    [settings, toggle, setSetting, nextVariant, nextIntensity, nextColorScheme, reset]
+  );
+}
+
+// =============================================================================
+// HOOK (uses context when available)
+// =============================================================================
+
+export function useAudioVisualization(): UseAudioVisualizationReturn {
+  const context = useContext(VisualizationContext);
+
+  // Always call the fallback hooks (React hooks rules require consistent calls)
+  const fallbackState = useVisualizationState();
+
+  // If inside a provider, use shared context; otherwise use fallback
+  return context ?? fallbackState;
+}
+
+// =============================================================================
+// VARIANT INFO
+// =============================================================================
+
+export const VARIANT_INFO: Record<VisualizationVariant, { label: string; icon: string }> = {
+  spotlight: { label: 'Spotlight', icon: '💫' },
+  glow: { label: 'Glow', icon: '✨' },
+  orbs: { label: 'Orbs', icon: '🔮' },
+  mesh: { label: 'Mesh', icon: '🌈' },
+  none: { label: 'Off', icon: '⭕' },
+};
+
+export const INTENSITY_INFO: Record<VisualizationIntensity, { label: string }> = {
+  subtle: { label: 'Subtle' },
+  medium: { label: 'Medium' },
+  strong: { label: 'Strong' },
+};
+
+export const COLOR_SCHEME_INFO: Record<VisualizationColorScheme, { label: string; preview: string }> = {
+  primary: { label: 'Primary', preview: '🔵' },
+  vibrant: { label: 'Vibrant', preview: '🌈' },
+  cool: { label: 'Cool', preview: '💙' },
+  warm: { label: 'Warm', preview: '🔥' },
+};