@djangocfg/ui-nextjs 2.1.66 → 2.1.67

package/src/tools/ImageViewer/index.ts

@@ -8,9 +8,53 @@
  * - Flip horizontal/vertical
  * - Fullscreen dialog mode
  * - Keyboard shortcuts (+/-, 0 for reset, r for rotate)
+ * - Progressive loading with LQIP for large images
  * - Checkerboard background for transparency
- * - Image dimensions display
+ * - Image dimensions display with caching
  */
 
-export { ImageViewer } from './ImageViewer';
-export type { ImageViewerProps, ImageFile } from './ImageViewer';
+// =============================================================================
+// COMPONENTS
+// =============================================================================
+
+export { ImageViewer, ImageToolbar, ImageInfo } from './components';
+
+// =============================================================================
+// HOOKS
+// =============================================================================
+
+export { useImageTransform, useImageLoading } from './hooks';
+export type {
+  UseImageTransformOptions,
+  UseImageTransformReturn,
+  UseImageLoadingOptions,
+  UseImageLoadingReturn,
+} from './hooks';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export type {
+  ImageFile,
+  ImageViewerProps,
+  ImageToolbarProps,
+  ImageInfoProps,
+  ImageTransform,
+  ZoomPreset,
+} from './types';
+
+// =============================================================================
+// UTILS
+// =============================================================================
+
+export {
+  createLQIP,
+  MAX_IMAGE_SIZE,
+  WARNING_IMAGE_SIZE,
+  PROGRESSIVE_LOADING_THRESHOLD,
+  MIN_ZOOM,
+  MAX_ZOOM,
+  ZOOM_PRESETS,
+  DEFAULT_TRANSFORM,
+} from './utils';

package/src/tools/ImageViewer/types.ts

@@ -0,0 +1,75 @@
+/**
+ * ImageViewer type definitions
+ */
+
+// =============================================================================
+// FILE TYPES
+// =============================================================================
+
+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;
+}
+
+// =============================================================================
+// COMPONENT PROPS
+// =============================================================================
+
+export interface ImageViewerProps {
+  /** File info (name, path, mimeType) */
+  file: ImageFile;
+  /** Image content as string (data URL or base64) or ArrayBuffer */
+  content: string | ArrayBuffer;
+  /** Hide expand button when already in dialog */
+  inDialog?: boolean;
+}
+
+export interface ImageToolbarProps {
+  /** Current zoom scale */
+  scale: number;
+  /** Current transform state */
+  transform: ImageTransform;
+  /** Rotate image callback */
+  onRotate: () => void;
+  /** Flip horizontal callback */
+  onFlipH: () => void;
+  /** Flip vertical callback */
+  onFlipV: () => void;
+  /** Zoom preset selection callback */
+  onZoomPreset: (value: number | 'fit') => void;
+  /** Expand to fullscreen callback (undefined hides button) */
+  onExpand?: () => void;
+}
+
+export interface ImageInfoProps {
+  /** Image source URL */
+  src: string;
+}
+
+// =============================================================================
+// STATE TYPES
+// =============================================================================
+
+export interface ImageTransform {
+  /** Rotation angle: 0, 90, 180, or 270 degrees */
+  rotation: number;
+  /** Horizontal flip state */
+  flipH: boolean;
+  /** Vertical flip state */
+  flipV: boolean;
+}
+
+// =============================================================================
+// UI TYPES
+// =============================================================================
+
+export interface ZoomPreset {
+  /** Display label (e.g., "100%", "Fit") */
+  label: string;
+  /** Zoom value or 'fit' for fit-to-view */
+  value: number | 'fit';
+}

package/src/tools/ImageViewer/utils/constants.ts

@@ -0,0 +1,59 @@
+/**
+ * ImageViewer constants
+ */
+
+import type { ZoomPreset, ImageTransform } 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 WARNING_IMAGE_SIZE = 10 * 1024 * 1024;
+
+/** Progressive loading threshold - use LQIP for images > 500KB */
+export const PROGRESSIVE_LOADING_THRESHOLD = 500 * 1024;
+
+// =============================================================================
+// LQIP CONFIGURATION
+// =============================================================================
+
+/** Low-quality placeholder size (32x32) */
+export const LQIP_SIZE = 32;
+
+/** LQIP JPEG quality */
+export const LQIP_QUALITY = 0.5;
+
+// =============================================================================
+// ZOOM CONFIGURATION
+// =============================================================================
+
+/** Minimum zoom level */
+export const MIN_ZOOM = 0.1;
+
+/** Maximum zoom level */
+export const MAX_ZOOM = 8;
+
+/** Available zoom presets */
+export const ZOOM_PRESETS: readonly ZoomPreset[] = [
+  { label: 'Fit', value: 'fit' },
+  { label: '25%', value: 0.25 },
+  { label: '50%', value: 0.5 },
+  { label: '100%', value: 1 },
+  { label: '200%', value: 2 },
+  { label: '400%', value: 4 },
+] as const;
+
+// =============================================================================
+// DEFAULT VALUES
+// =============================================================================
+
+/** Default transform state */
+export const DEFAULT_TRANSFORM: ImageTransform = {
+  rotation: 0,
+  flipH: false,
+  flipV: false,
+};

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

@@ -0,0 +1,16 @@
+/**
+ * ImageViewer utilities - Public API
+ */
+
+export { createLQIP } from './lqip';
+export {
+  MAX_IMAGE_SIZE,
+  WARNING_IMAGE_SIZE,
+  PROGRESSIVE_LOADING_THRESHOLD,
+  LQIP_SIZE,
+  LQIP_QUALITY,
+  MIN_ZOOM,
+  MAX_ZOOM,
+  ZOOM_PRESETS,
+  DEFAULT_TRANSFORM,
+} from './constants';

package/src/tools/ImageViewer/utils/lqip.ts

@@ -0,0 +1,47 @@
+/**
+ * LQIP (Low-Quality Image Placeholder) generator
+ *
+ * Creates a tiny blurred preview image for progressive loading.
+ */
+
+import { LQIP_SIZE, LQIP_QUALITY } from './constants';
+
+/**
+ * Create a low-quality image placeholder from source URL
+ *
+ * @param imageSrc - Full quality image URL
+ * @returns Data URL of tiny preview, or null on error
+ */
+export async function createLQIP(imageSrc: string): Promise<string | null> {
+  try {
+    // Load the full image
+    const img = new Image();
+    img.crossOrigin = 'anonymous';
+
+    await new Promise<void>((resolve, reject) => {
+      img.onload = () => resolve();
+      img.onerror = () => reject(new Error('Failed to load image for LQIP'));
+      img.src = imageSrc;
+    });
+
+    // Calculate aspect ratio preserving dimensions
+    const aspect = img.naturalWidth / img.naturalHeight;
+    const width = aspect >= 1 ? LQIP_SIZE : Math.round(LQIP_SIZE * aspect);
+    const height = aspect >= 1 ? Math.round(LQIP_SIZE / aspect) : LQIP_SIZE;
+
+    // Create canvas for downscaling
+    const canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return null;
+
+    // Draw scaled down image
+    ctx.drawImage(img, 0, 0, width, height);
+
+    // Return as data URL (very small, ~1-2KB)
+    return canvas.toDataURL('image/jpeg', LQIP_QUALITY);
+  } catch {
+    return null;
+  }
+}

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

@@ -0,0 +1,91 @@
+# VideoPlayer Refactoring Plan
+
+## Overview
+
+The VideoPlayer is already reasonably well-organized with a `providers/` subfolder. This refactoring focuses on incremental improvements rather than major restructuring.
+
+**Total: 2,024 lines across 10 files**
+
+## Current Structure (Before)
+
+```
+VideoPlayer/
+├── index.ts (68 lines)                 # Public exports
+├── types.ts (369 lines)                # All types + helper functions ⚠️
+├── VideoPlayer.tsx (202 lines)         # Main orchestrator
+├── VideoPlayerContext.tsx (125 lines)  # Streaming context
+├── VideoControls.tsx (139 lines)       # Vidstack controls
+├── VideoErrorFallback.tsx (174 lines)  # Error UI
+├── README.md
+└── providers/
+    ├── index.ts (8 lines)
+    ├── VidstackProvider.tsx (332 lines) # YouTube/Vimeo/HLS/DASH
+    ├── NativeProvider.tsx (206 lines)   # HTML5 <video>
+    └── StreamProvider.tsx (401 lines)   # HTTP Range + Blob ⚠️
+```
+
+**Issues Identified:**
+1. `types.ts` (369 lines) - Contains types AND helper functions
+2. `StreamProvider.tsx` (401 lines) - Largest file, multiple concerns
+3. Position caching logic duplicated in VidstackProvider & StreamProvider
+4. No dedicated hooks/ folder
+
+## Target Structure (After)
+
+```
+VideoPlayer/
+├── index.ts                    # Public API
+├── README.md
+├── types/
+│   ├── index.ts                # Re-exports all types
+│   ├── sources.ts              # Source type definitions
+│   ├── player.ts               # Player props and config types
+│   └── provider.ts             # Provider-specific types
+├── hooks/
+│   ├── index.ts
+│   └── useVideoPositionCache.ts  # Extracted caching logic
+├── utils/
+│   ├── index.ts
+│   ├── resolvers.ts            # resolvePlayerMode, resolveFileSource
+│   └── stream.ts               # Stream URL generation helpers
+├── components/
+│   ├── index.ts
+│   ├── VideoPlayer.tsx         # Main component
+│   ├── VideoControls.tsx       # Vidstack controls
+│   └── VideoErrorFallback.tsx  # Error UI
+├── context/
+│   ├── index.ts
+│   └── VideoPlayerContext.tsx
+└── providers/
+    ├── index.ts
+    ├── VidstackProvider.tsx
+    ├── NativeProvider.tsx
+    └── StreamProvider.tsx
+```
+
+## Benefits
+
+1. **DRY Principle** - Extract duplicated position caching logic
+2. **Separation of Concerns** - Types split by domain
+3. **Consistent Structure** - Matches AudioPlayer/ImageViewer patterns
+4. **Maintainability** - Easier to find and modify specific functionality
+5. **Testability** - Hooks and utils can be unit tested
+
+## Execution Phases
+
+| Phase | Description | Files |
+|-------|-------------|-------|
+| 1 | Create folder structure | types/, hooks/, utils/, components/, context/ |
+| 2 | Split types | sources.ts, player.ts, provider.ts |
+| 3 | Extract utils | resolvers.ts, stream.ts |
+| 4 | Extract hooks | useVideoPositionCache.ts |
+| 5 | Move components | VideoPlayer.tsx, VideoControls.tsx, VideoErrorFallback.tsx |
+| 6 | Move context | VideoPlayerContext.tsx |
+| 7 | Update exports | index.ts |
+| 8 | Cleanup and verify | Delete old files, run pnpm check |
+
+## Risk Assessment
+
+- **Low Risk**: Incremental changes, no logic modifications
+- **Testing**: Run `pnpm check` after each phase
+- **Providers**: Already well-organized, minimal changes needed

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

@@ -0,0 +1,284 @@
+# Phase 1: Types Split
+
+## Goal
+
+Split the 369-line `types.ts` into domain-specific files and move helper functions to utils.
+
+## Current Structure
+
+```typescript
+// types.ts (369 lines)
+// Contains:
+// 1. Source types (UrlSource, YouTubeSource, VimeoSource, HLSSource, etc.)
+// 2. Player types (PlayerMode, AspectRatioValue, VideoPlayerProps, etc.)
+// 3. Provider types (VidstackProviderProps, NativeProviderProps, etc.)
+// 4. Helper functions (resolvePlayerMode, resolveFileSource, isSimpleStreamSource)
+```
+
+## Target Files
+
+### types/sources.ts (~120 lines)
+
+All source type definitions:
+
+```typescript
+/**
+ * Video source type definitions
+ */
+
+// URL source (direct video URL)
+export interface UrlSource {
+  type: 'url';
+  url: string;
+  mimeType?: string;
+}
+
+// YouTube embed
+export interface YouTubeSource {
+  type: 'youtube';
+  videoId: string;
+  startTime?: number;
+}
+
+// Vimeo embed
+export interface VimeoSource {
+  type: 'vimeo';
+  videoId: string;
+  startTime?: number;
+}
+
+// HLS streaming
+export interface HLSSource {
+  type: 'hls';
+  url: string;
+}
+
+// DASH streaming
+export interface DASHSource {
+  type: 'dash';
+  url: string;
+}
+
+// HTTP Range streaming with auth
+export interface StreamSource {
+  type: 'stream';
+  streamKey: string;
+  fileName: string;
+  fileSize?: number;
+  mimeType?: string;
+  getStreamUrl: (streamKey: string) => Promise<string>;
+}
+
+// Simple stream (resolved via context)
+export interface SimpleStreamSource {
+  type: 'stream';
+  streamKey: string;
+  fileName: string;
+  fileSize?: number;
+  mimeType?: string;
+}
+
+// Blob (ArrayBuffer)
+export interface BlobSource {
+  type: 'blob';
+  data: ArrayBuffer;
+  mimeType?: string;
+  fileName?: string;
+}
+
+// Data URL (base64)
+export interface DataUrlSource {
+  type: 'data-url';
+  dataUrl: string;
+  mimeType?: string;
+}
+
+// Union of all sources
+export type VideoSourceUnion =
+  | UrlSource
+  | YouTubeSource
+  | VimeoSource
+  | HLSSource
+  | DASHSource
+  | StreamSource
+  | BlobSource
+  | DataUrlSource;
+```
+
+### types/player.ts (~100 lines)
+
+Player configuration and main component types:
+
+```typescript
+/**
+ * Player configuration types
+ */
+
+import type { ReactNode, CSSProperties } from 'react';
+import type { VideoSourceUnion } from './sources';
+
+// Player mode
+export type PlayerMode = 'auto' | 'vidstack' | 'native' | 'streaming';
+
+// Aspect ratio
+export type AspectRatioValue = number | 'auto' | 'fill';
+
+// Common settings
+export interface CommonPlayerSettings {
+  autoPlay?: boolean;
+  muted?: boolean;
+  loop?: boolean;
+  playsInline?: boolean;
+  controls?: boolean;
+  preload?: 'none' | 'metadata' | 'auto';
+}
+
+// Common events
+export interface CommonPlayerEvents {
+  onPlay?: () => void;
+  onPause?: () => void;
+  onEnded?: () => void;
+  onTimeUpdate?: (currentTime: number) => void;
+  onError?: (error: Error) => void;
+  onLoadStart?: () => void;
+  onCanPlay?: () => void;
+}
+
+// Error fallback props
+export interface ErrorFallbackProps {
+  error: Error | null;
+  source: VideoSourceUnion;
+  retry?: () => void;
+}
+
+// Main component props
+export interface VideoPlayerProps extends CommonPlayerSettings, CommonPlayerEvents {
+  source: VideoSourceUnion;
+  mode?: PlayerMode;
+  aspectRatio?: AspectRatioValue;
+  poster?: string;
+  className?: string;
+  style?: CSSProperties;
+  errorFallback?: (props: ErrorFallbackProps) => ReactNode;
+}
+
+// Ref API
+export interface VideoPlayerRef {
+  play: () => Promise<void>;
+  pause: () => void;
+  seek: (time: number) => void;
+  setVolume: (volume: number) => void;
+  setMuted: (muted: boolean) => void;
+  requestFullscreen: () => Promise<void>;
+  exitFullscreen: () => Promise<void>;
+  readonly currentTime: number;
+  readonly duration: number;
+  readonly paused: boolean;
+  readonly muted: boolean;
+  readonly volume: number;
+  readonly isFullscreen: boolean;
+}
+```
+
+### types/provider.ts (~80 lines)
+
+Provider-specific types:
+
+```typescript
+/**
+ * Provider-specific types
+ */
+
+import type { ReactNode } from 'react';
+import type { VideoSourceUnion, StreamSource, BlobSource, DataUrlSource } from './sources';
+import type { CommonPlayerSettings, CommonPlayerEvents, AspectRatioValue, ErrorFallbackProps } from './player';
+
+// Vidstack provider props
+export interface VidstackProviderProps extends CommonPlayerSettings, CommonPlayerEvents {
+  source: VideoSourceUnion;
+  aspectRatio?: AspectRatioValue;
+  poster?: string;
+  className?: string;
+  errorFallback?: (props: ErrorFallbackProps) => ReactNode;
+}
+
+// Native provider props
+export interface NativeProviderProps extends CommonPlayerSettings, CommonPlayerEvents {
+  source: VideoSourceUnion;
+  aspectRatio?: AspectRatioValue;
+  poster?: string;
+  className?: string;
+  disableContextMenu?: boolean;
+}
+
+// Stream provider props
+export interface StreamProviderProps extends CommonPlayerSettings, CommonPlayerEvents {
+  source: StreamSource | BlobSource | DataUrlSource;
+  aspectRatio?: AspectRatioValue;
+  poster?: string;
+  className?: string;
+  errorFallback?: (props: ErrorFallbackProps) => ReactNode;
+}
+
+// File source resolution options
+export interface ResolveFileSourceOptions {
+  fileName: string;
+  content: string | ArrayBuffer;
+  mimeType?: string;
+}
+
+// Context value
+export interface VideoPlayerContextValue {
+  getStreamUrl?: (streamKey: string) => Promise<string>;
+}
+
+export interface VideoPlayerProviderProps {
+  getStreamUrl: (streamKey: string) => Promise<string>;
+  children: ReactNode;
+}
+```
+
+### types/index.ts
+
+Re-export all types:
+
+```typescript
+/**
+ * VideoPlayer types - Public API
+ */
+
+// Source types
+export type {
+  UrlSource,
+  YouTubeSource,
+  VimeoSource,
+  HLSSource,
+  DASHSource,
+  StreamSource,
+  SimpleStreamSource,
+  BlobSource,
+  DataUrlSource,
+  VideoSourceUnion,
+} from './sources';
+
+// Player types
+export type {
+  PlayerMode,
+  AspectRatioValue,
+  CommonPlayerSettings,
+  CommonPlayerEvents,
+  ErrorFallbackProps,
+  VideoPlayerProps,
+  VideoPlayerRef,
+} from './player';
+
+// Provider types
+export type {
+  VidstackProviderProps,
+  NativeProviderProps,
+  StreamProviderProps,
+  ResolveFileSourceOptions,
+  VideoPlayerContextValue,
+  VideoPlayerProviderProps,
+} from './provider';
+```