@djangocfg/ui-nextjs 2.1.65 → 2.1.67

package/src/tools/AudioPlayer/types/effects.ts

@@ -0,0 +1,73 @@
+/**
+ * Effect-related types for audio-reactive visualizations
+ */
+
+// =============================================================================
+// EFFECT TYPES
+// =============================================================================
+
+export type EffectVariant = 'glow' | 'orbs' | 'spotlight' | 'mesh';
+export type EffectIntensity = 'subtle' | 'medium' | 'strong';
+export type EffectColorScheme = 'primary' | 'vibrant' | 'cool' | 'warm';
+
+export interface AudioLevels {
+  bass: number;
+  mid: number;
+  high: number;
+  overall: number;
+}
+
+export interface EffectConfig {
+  opacity: number;
+  scale: number;
+  blur: string;
+}
+
+export interface EffectColors {
+  colors: string[];
+  hueShift: number;
+}
+
+export interface EffectLayer {
+  inset: number;
+  opacity: number;
+  scale: number;
+  background: string;
+  blur: string;
+  animation?: string;
+}
+
+export interface Orb {
+  x: number;
+  y: number;
+  size: number;
+  color: string;
+  opacity: number;
+  scale: number;
+}
+
+export interface MeshGradient {
+  width: string;
+  height: string;
+  top?: string;
+  bottom?: string;
+  left?: string;
+  right?: string;
+  color: string;
+  opacity: number;
+  scale: number;
+  rotation: number;
+  blur: string;
+  isCenter?: boolean;
+}
+
+export interface SpotlightData {
+  rotation: number;
+  inset: number;
+  colors: Array<{ color: string; opacity: number }>;
+  pulseInset: number;
+  pulseOpacity: number;
+  pulseScale: number;
+  ringOpacity: number;
+  ringScale: number;
+}

package/src/tools/AudioPlayer/types/index.ts

@@ -0,0 +1,35 @@
+/**
+ * AudioPlayer types - re-exports all types
+ */
+
+// Audio types
+export type {
+  AudioSource,
+  PlaybackStatus,
+  WaveformOptions,
+  EqualizerOptions,
+  SharedWebAudioContext,
+  AudioContextState,
+} from './audio';
+
+// Component props
+export type {
+  AudioPlayerProps,
+  AudioEqualizerProps,
+  AudioReactiveCoverProps,
+  AudioViewerProps,
+} from './components';
+
+// Effect types
+export type {
+  EffectVariant,
+  EffectIntensity,
+  EffectColorScheme,
+  AudioLevels,
+  EffectConfig,
+  EffectColors,
+  EffectLayer,
+  Orb,
+  MeshGradient,
+  SpotlightData,
+} from './effects';

package/src/tools/AudioPlayer/utils/formatTime.ts

@@ -0,0 +1,10 @@
+/**
+ * formatTime - Format seconds to mm:ss string
+ */
+
+export function formatTime(seconds: number): string {
+  if (!seconds || !isFinite(seconds) || seconds < 0) return '0:00';
+  const mins = Math.floor(seconds / 60);
+  const secs = Math.floor(seconds % 60);
+  return `${mins}:${secs.toString().padStart(2, '0')}`;
+}

package/src/tools/AudioPlayer/utils/index.ts

@@ -0,0 +1,5 @@
+/**
+ * AudioPlayer utilities - Public API
+ */
+
+export { formatTime } from './formatTime';

package/src/tools/ImageViewer/@refactoring/00-PLAN.md

@@ -0,0 +1,71 @@
+# ImageViewer Refactoring Plan
+
+## Overview
+
+Decompose the monolithic 589-line `ImageViewer.tsx` into a well-organized module structure similar to AudioPlayer.
+
+## Current Structure (Before)
+
+```
+ImageViewer/
+├── ImageViewer.tsx (589 lines) - Everything in one file
+├── index.ts (16 lines)
+└── README.md
+```
+
+**Issues:**
+- Single 589-line file with mixed concerns
+- 2 sub-components inline (ImageToolbar, ImageInfo)
+- 1 utility function inline (createLQIP)
+- 8 separate useState calls
+- Types defined inline
+- Constants hardcoded
+
+## Target Structure (After)
+
+```
+ImageViewer/
+├── index.ts                    # Public API
+├── README.md                   # Documentation
+├── components/
+│   ├── index.ts
+│   ├── ImageViewer.tsx         # Main component (~150 lines)
+│   ├── ImageToolbar.tsx        # Toolbar with zoom/rotate/flip (~130 lines)
+│   └── ImageInfo.tsx           # Dimensions display (~35 lines)
+├── hooks/
+│   ├── index.ts
+│   ├── useImageTransform.ts    # Rotation/flip state management
+│   └── useImageLoading.ts      # LQIP and loading state
+├── utils/
+│   ├── index.ts
+│   ├── lqip.ts                 # LQIP generator utility
+│   └── constants.ts            # Zoom presets, size limits
+└── types.ts                    # All type definitions
+```
+
+## Benefits
+
+1. **Separation of Concerns** - Each file has single responsibility
+2. **Testability** - Hooks and utils can be unit tested independently
+3. **Reusability** - Components can be used standalone
+4. **Maintainability** - Easier to find and modify specific functionality
+5. **Code Organization** - Consistent with AudioPlayer structure
+
+## Execution Phases
+
+| Phase | Description | Files |
+|-------|-------------|-------|
+| 1 | Create folder structure | components/, hooks/, utils/ |
+| 2 | Extract types | types.ts |
+| 3 | Extract constants and utilities | utils/constants.ts, utils/lqip.ts |
+| 4 | Extract hooks | hooks/useImageTransform.ts, hooks/useImageLoading.ts |
+| 5 | Split components | ImageToolbar.tsx, ImageInfo.tsx |
+| 6 | Refactor main component | ImageViewer.tsx (simplified) |
+| 7 | Update exports | index.ts, components/index.ts, hooks/index.ts |
+| 8 | Cleanup and verify | Delete old file, run pnpm check |
+
+## Risk Assessment
+
+- **Low Risk**: Pure extraction with no logic changes
+- **Testing**: Run `pnpm check` after each phase
+- **Rollback**: Keep old file until verification complete

package/src/tools/ImageViewer/@refactoring/01-TYPES.md

@@ -0,0 +1,121 @@
+# Phase 1: Types Extraction
+
+## Goal
+
+Extract all type definitions from ImageViewer.tsx into a dedicated types.ts file.
+
+## Types to Extract
+
+### ImageFile (Props)
+```typescript
+export interface ImageFile {
+  /** Display name for the image */
+  name: string;
+  /** File path used for change detection and caching */
+  path: string;
+  /** Optional MIME type */
+  mimeType?: string;
+}
+```
+
+### ImageViewerProps (Props)
+```typescript
+export interface ImageViewerProps {
+  /** Image file metadata */
+  file: ImageFile;
+  /** Image content as string or ArrayBuffer */
+  content: string | ArrayBuffer;
+  /** Whether viewer is inside a dialog (hides expand button) */
+  inDialog?: boolean;
+}
+```
+
+### ImageTransform (State)
+```typescript
+export interface ImageTransform {
+  /** Rotation angle: 0, 90, 180, or 270 degrees */
+  rotation: number;
+  /** Horizontal flip state */
+  flipH: boolean;
+  /** Vertical flip state */
+  flipV: boolean;
+}
+```
+
+### ZoomPreset (UI)
+```typescript
+export interface ZoomPreset {
+  /** Zoom level (1 = 100%) */
+  value: number;
+  /** Display label (e.g., "100%") */
+  label: string;
+}
+```
+
+### ImageToolbarProps (Internal)
+```typescript
+export interface ImageToolbarProps {
+  /** Current zoom scale */
+  scale: number;
+  /** Expand to fullscreen callback */
+  onExpand: () => void;
+  /** Rotate image callback */
+  onRotate: () => void;
+  /** Flip horizontal callback */
+  onFlipH: () => void;
+  /** Flip vertical callback */
+  onFlipV: () => void;
+  /** Whether horizontal flip is active */
+  flipH: boolean;
+  /** Whether vertical flip is active */
+  flipV: boolean;
+  /** Whether inside dialog (hides expand) */
+  inDialog?: boolean;
+}
+```
+
+### ImageInfoProps (Internal)
+```typescript
+export interface ImageInfoProps {
+  /** Blob URL source of the image */
+  src: string;
+  /** Content key for cache lookup */
+  contentKey: string;
+}
+```
+
+## File Structure
+
+```typescript
+// types.ts
+
+/**
+ * ImageViewer type definitions
+ */
+
+// =============================================================================
+// FILE TYPES
+// =============================================================================
+
+export interface ImageFile { ... }
+
+// =============================================================================
+// COMPONENT PROPS
+// =============================================================================
+
+export interface ImageViewerProps { ... }
+export interface ImageToolbarProps { ... }
+export interface ImageInfoProps { ... }
+
+// =============================================================================
+// STATE TYPES
+// =============================================================================
+
+export interface ImageTransform { ... }
+
+// =============================================================================
+// UI TYPES
+// =============================================================================
+
+export interface ZoomPreset { ... }
+```

package/src/tools/ImageViewer/@refactoring/02-UTILS.md

@@ -0,0 +1,143 @@
+# Phase 2: Utils Extraction
+
+## Goal
+
+Extract constants and utility functions into dedicated files.
+
+## Files to Create
+
+### utils/constants.ts
+
+```typescript
+/**
+ * ImageViewer constants
+ */
+
+import type { ZoomPreset } from '../types';
+
+// =============================================================================
+// SIZE LIMITS
+// =============================================================================
+
+/** Maximum image size before blocking (50MB) */
+export const MAX_IMAGE_SIZE = 50 * 1024 * 1024;
+
+/** Image size threshold for warning (10MB) */
+export const WARN_IMAGE_SIZE = 10 * 1024 * 1024;
+
+// =============================================================================
+// ZOOM CONFIGURATION
+// =============================================================================
+
+/** Minimum zoom level */
+export const MIN_ZOOM = 0.25;
+
+/** Maximum zoom level */
+export const MAX_ZOOM = 4;
+
+/** Available zoom presets */
+export const ZOOM_PRESETS: ZoomPreset[] = [
+  { value: 0.25, label: '25%' },
+  { value: 0.5, label: '50%' },
+  { value: 1, label: '100%' },
+  { value: 2, label: '200%' },
+  { value: 4, label: '400%' },
+  { value: -1, label: 'Fit' }, // Special value for fit-to-view
+];
+
+// =============================================================================
+// DEFAULT VALUES
+// =============================================================================
+
+/** Default transform state */
+export const DEFAULT_TRANSFORM: ImageTransform = {
+  rotation: 0,
+  flipH: false,
+  flipV: false,
+};
+```
+
+### utils/lqip.ts
+
+```typescript
+/**
+ * LQIP (Low-Quality Image Placeholder) generator
+ *
+ * Creates a tiny blurred preview image for progressive loading.
+ */
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const LQIP_SIZE = 32;
+const LQIP_QUALITY = 0.5;
+
+// =============================================================================
+// GENERATOR
+// =============================================================================
+
+/**
+ * Create a low-quality image placeholder from source URL
+ *
+ * @param src - Full quality image URL
+ * @returns Data URL of tiny preview, or null on error
+ */
+export async function createLQIP(src: string): Promise<string | null> {
+  return new Promise((resolve) => {
+    const img = new Image();
+
+    img.onload = () => {
+      try {
+        // Calculate aspect-preserving dimensions
+        const aspectRatio = img.width / img.height;
+        const width = aspectRatio >= 1 ? LQIP_SIZE : Math.round(LQIP_SIZE * aspectRatio);
+        const height = aspectRatio >= 1 ? Math.round(LQIP_SIZE / aspectRatio) : LQIP_SIZE;
+
+        // Create tiny canvas
+        const canvas = document.createElement('canvas');
+        canvas.width = width;
+        canvas.height = height;
+
+        // Draw and export as JPEG
+        const ctx = canvas.getContext('2d');
+        if (ctx) {
+          ctx.drawImage(img, 0, 0, width, height);
+          resolve(canvas.toDataURL('image/jpeg', LQIP_QUALITY));
+        } else {
+          resolve(null);
+        }
+      } catch {
+        resolve(null);
+      }
+    };
+
+    img.onerror = () => resolve(null);
+    img.src = src;
+  });
+}
+```
+
+### utils/index.ts
+
+```typescript
+/**
+ * ImageViewer utilities - Public API
+ */
+
+export { createLQIP } from './lqip';
+export {
+  MAX_IMAGE_SIZE,
+  WARN_IMAGE_SIZE,
+  MIN_ZOOM,
+  MAX_ZOOM,
+  ZOOM_PRESETS,
+  DEFAULT_TRANSFORM,
+} from './constants';
+```
+
+## Notes
+
+- Constants are separated for easy modification
+- LQIP is async and handles errors gracefully
+- No dependencies on React in utils