@djangocfg/ui-nextjs 2.1.66 → 2.1.68

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-nextjs",
-  "version": "2.1.66",
+  "version": "2.1.68",
   "description": "Next.js UI component library with Radix UI primitives, Tailwind CSS styling, charts, and form components",
   "keywords": [
     "ui-components",
@@ -58,8 +58,8 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.66",
-    "@djangocfg/ui-core": "^2.1.66",
+    "@djangocfg/api": "^2.1.68",
+    "@djangocfg/ui-core": "^2.1.68",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",
     "consola": "^3.4.2",
@@ -70,7 +70,8 @@
     "react-dom": "^19.1.0",
     "react-hook-form": "7.65.0",
     "tailwindcss": "^4.1.14",
-    "zod": "^4.1.13"
+    "zod": "^4.1.13",
+    "zustand": "^5.0.9"
   },
   "dependencies": {
     "@radix-ui/react-dropdown-menu": "^2.1.16",
@@ -109,11 +110,12 @@
     "wavesurfer.js": "^7.12.1"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.66",
+    "@djangocfg/typescript-config": "^2.1.68",
     "@types/node": "^24.7.2",
     "eslint": "^9.37.0",
     "tailwindcss-animate": "1.0.7",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "zustand": "^5.0.9"
   },
   "publishConfig": {
     "access": "public"

package/src/stores/index.ts

@@ -0,0 +1,8 @@
+export {
+  useMediaCacheStore,
+  useImageCache,
+  useAudioCache,
+  useVideoCache,
+  useBlobUrlCleanup,
+  generateContentKey,
+} from './mediaCache';

package/src/stores/mediaCache.ts

@@ -0,0 +1,474 @@
+'use client';
+
+import { create } from 'zustand';
+import { persist, devtools } from 'zustand/middleware';
+import { useShallow } from 'zustand/react/shallow';
+
+// Types
+interface BlobUrlEntry {
+  url: string;
+  refCount: number;
+  createdAt: number;
+}
+
+interface ImageDimensions {
+  width: number;
+  height: number;
+}
+
+interface VideoMetadata {
+  duration: number;
+  width: number;
+  height: number;
+  codec?: string;
+}
+
+interface EffectConfig {
+  opacity: number;
+  scale: number;
+  blur: string;
+}
+
+// Stream URL TTL (5 minutes)
+const STREAM_URL_TTL = 5 * 60 * 1000;
+
+interface MediaCacheState {
+  // Blob URL cache (shared by Image, Audio, Video)
+  blobUrls: Map<string, BlobUrlEntry>;
+
+  // Image-specific
+  imageDimensions: Map<string, ImageDimensions>;
+
+  // Audio-specific
+  audioPlaybackPositions: Map<string, number>;
+  audioEffectConfigs: Map<string, EffectConfig>;
+
+  // Video-specific
+  videoStreamUrls: Map<string, { url: string; timestamp: number }>;
+  videoPosterUrls: Map<string, string>;
+  videoPlaybackPositions: Map<string, number>;
+  videoMetadata: Map<string, VideoMetadata>;
+}
+
+interface MediaCacheActions {
+  // Blob URL management (shared)
+  getOrCreateBlobUrl: (
+    key: string,
+    content: ArrayBuffer,
+    mimeType: string
+  ) => string;
+  releaseBlobUrl: (key: string) => void;
+  hasBlobUrl: (key: string) => boolean;
+
+  // Image actions
+  cacheDimensions: (src: string, dims: ImageDimensions) => void;
+  getDimensions: (src: string) => ImageDimensions | null;
+
+  // Audio actions
+  saveAudioPosition: (uri: string, time: number) => void;
+  getAudioPosition: (uri: string) => number | null;
+  getEffectConfig: (key: string) => EffectConfig | null;
+  cacheEffectConfig: (key: string, config: EffectConfig) => void;
+
+  // Video actions
+  getOrCreateStreamUrl: (
+    sessionId: string,
+    path: string,
+    generator: (sessionId: string, path: string) => string
+  ) => string;
+  getPosterUrl: (title: string) => string | null;
+  cachePosterUrl: (title: string, url: string) => void;
+  saveVideoPosition: (key: string, time: number) => void;
+  getVideoPosition: (key: string) => number | null;
+  cacheVideoMetadata: (url: string, meta: VideoMetadata) => void;
+  getVideoMetadata: (url: string) => VideoMetadata | null;
+  invalidateSession: (sessionId: string) => void;
+
+  // Global
+  clearCache: () => void;
+  getCacheStats: () => {
+    blobUrls: number;
+    dimensions: number;
+    audioPositions: number;
+    videoPositions: number;
+  };
+}
+
+type MediaCacheStore = MediaCacheState & MediaCacheActions;
+
+// Initial state
+const initialState: MediaCacheState = {
+  blobUrls: new Map(),
+  imageDimensions: new Map(),
+  audioPlaybackPositions: new Map(),
+  audioEffectConfigs: new Map(),
+  videoStreamUrls: new Map(),
+  videoPosterUrls: new Map(),
+  videoPlaybackPositions: new Map(),
+  videoMetadata: new Map(),
+};
+
+export const useMediaCacheStore = create<MediaCacheStore>()(
+  devtools(
+    persist(
+      (set, get) => ({
+        ...initialState,
+
+        // ========== Blob URL Management ==========
+
+        getOrCreateBlobUrl: (key, content, mimeType) => {
+          const existing = get().blobUrls.get(key);
+          if (existing) {
+            // Increment ref count
+            set(
+              (state) => ({
+                blobUrls: new Map(state.blobUrls).set(key, {
+                  ...existing,
+                  refCount: existing.refCount + 1,
+                }),
+              }),
+              false,
+              'blobUrl/incrementRef'
+            );
+            return existing.url;
+          }
+
+          // Create new blob URL
+          const blob = new Blob([content], { type: mimeType });
+          const url = URL.createObjectURL(blob);
+          set(
+            (state) => ({
+              blobUrls: new Map(state.blobUrls).set(key, {
+                url,
+                refCount: 1,
+                createdAt: Date.now(),
+              }),
+            }),
+            false,
+            'blobUrl/create'
+          );
+          return url;
+        },
+
+        releaseBlobUrl: (key) => {
+          const entry = get().blobUrls.get(key);
+          if (!entry) return;
+
+          if (entry.refCount <= 1) {
+            // Last reference - revoke and remove
+            URL.revokeObjectURL(entry.url);
+            set(
+              (state) => {
+                const newMap = new Map(state.blobUrls);
+                newMap.delete(key);
+                return { blobUrls: newMap };
+              },
+              false,
+              'blobUrl/revoke'
+            );
+          } else {
+            // Decrement ref count
+            set(
+              (state) => ({
+                blobUrls: new Map(state.blobUrls).set(key, {
+                  ...entry,
+                  refCount: entry.refCount - 1,
+                }),
+              }),
+              false,
+              'blobUrl/decrementRef'
+            );
+          }
+        },
+
+        hasBlobUrl: (key) => get().blobUrls.has(key),
+
+        // ========== Image Cache ==========
+
+        cacheDimensions: (src, dims) => {
+          set(
+            (state) => ({
+              imageDimensions: new Map(state.imageDimensions).set(src, dims),
+            }),
+            false,
+            'image/cacheDimensions'
+          );
+        },
+
+        getDimensions: (src) => get().imageDimensions.get(src) ?? null,
+
+        // ========== Audio Cache ==========
+
+        saveAudioPosition: (uri, time) => {
+          set(
+            (state) => ({
+              audioPlaybackPositions: new Map(state.audioPlaybackPositions).set(
+                uri,
+                time
+              ),
+            }),
+            false,
+            'audio/savePosition'
+          );
+        },
+
+        getAudioPosition: (uri) =>
+          get().audioPlaybackPositions.get(uri) ?? null,
+
+        getEffectConfig: (key) => get().audioEffectConfigs.get(key) ?? null,
+
+        cacheEffectConfig: (key, config) => {
+          set(
+            (state) => ({
+              audioEffectConfigs: new Map(state.audioEffectConfigs).set(
+                key,
+                config
+              ),
+            }),
+            false,
+            'audio/cacheEffectConfig'
+          );
+        },
+
+        // ========== Video Cache ==========
+
+        getOrCreateStreamUrl: (sessionId, path, generator) => {
+          const key = `${sessionId}:${path}`;
+          const cached = get().videoStreamUrls.get(key);
+
+          // Return if fresh
+          if (cached && Date.now() - cached.timestamp < STREAM_URL_TTL) {
+            return cached.url;
+          }
+
+          // Generate and cache
+          const url = generator(sessionId, path);
+          set(
+            (state) => ({
+              videoStreamUrls: new Map(state.videoStreamUrls).set(key, {
+                url,
+                timestamp: Date.now(),
+              }),
+            }),
+            false,
+            'video/cacheStreamUrl'
+          );
+          return url;
+        },
+
+        getPosterUrl: (title) => get().videoPosterUrls.get(title) ?? null,
+
+        cachePosterUrl: (title, url) => {
+          set(
+            (state) => ({
+              videoPosterUrls: new Map(state.videoPosterUrls).set(title, url),
+            }),
+            false,
+            'video/cachePosterUrl'
+          );
+        },
+
+        saveVideoPosition: (key, time) => {
+          set(
+            (state) => ({
+              videoPlaybackPositions: new Map(state.videoPlaybackPositions).set(
+                key,
+                time
+              ),
+            }),
+            false,
+            'video/savePosition'
+          );
+        },
+
+        getVideoPosition: (key) =>
+          get().videoPlaybackPositions.get(key) ?? null,
+
+        cacheVideoMetadata: (url, meta) => {
+          set(
+            (state) => ({
+              videoMetadata: new Map(state.videoMetadata).set(url, meta),
+            }),
+            false,
+            'video/cacheMetadata'
+          );
+        },
+
+        getVideoMetadata: (url) => get().videoMetadata.get(url) ?? null,
+
+        invalidateSession: (sessionId) => {
+          set(
+            (state) => {
+              const newUrls = new Map(state.videoStreamUrls);
+              for (const [key] of newUrls) {
+                if (key.startsWith(`${sessionId}:`)) {
+                  newUrls.delete(key);
+                }
+              }
+              return { videoStreamUrls: newUrls };
+            },
+            false,
+            'video/invalidateSession'
+          );
+        },
+
+        // ========== Global ==========
+
+        clearCache: () => {
+          // Revoke all blob URLs before clearing
+          get().blobUrls.forEach(({ url }) => URL.revokeObjectURL(url));
+          set(initialState, false, 'clearCache');
+        },
+
+        getCacheStats: () => ({
+          blobUrls: get().blobUrls.size,
+          dimensions: get().imageDimensions.size,
+          audioPositions: get().audioPlaybackPositions.size,
+          videoPositions: get().videoPlaybackPositions.size,
+        }),
+      }),
+      {
+        name: 'media-cache-storage',
+        // Only persist playback positions and poster URLs
+        partialize: (state) => ({
+          audioPlaybackPositions: Array.from(
+            state.audioPlaybackPositions.entries()
+          ),
+          videoPlaybackPositions: Array.from(
+            state.videoPlaybackPositions.entries()
+          ),
+          videoPosterUrls: Array.from(state.videoPosterUrls.entries()),
+        }),
+        // Rehydrate Maps from arrays
+        onRehydrateStorage: () => (state) => {
+          if (state) {
+            // Type assertion for persisted data
+            const persistedAudio = state.audioPlaybackPositions as unknown;
+            const persistedVideo = state.videoPlaybackPositions as unknown;
+            const persistedPosters = state.videoPosterUrls as unknown;
+
+            state.audioPlaybackPositions = new Map(
+              Array.isArray(persistedAudio)
+                ? (persistedAudio as [string, number][])
+                : []
+            );
+            state.videoPlaybackPositions = new Map(
+              Array.isArray(persistedVideo)
+                ? (persistedVideo as [string, number][])
+                : []
+            );
+            state.videoPosterUrls = new Map(
+              Array.isArray(persistedPosters)
+                ? (persistedPosters as [string, string][])
+                : []
+            );
+          }
+        },
+      }
+    ),
+    { name: 'MediaCacheStore' }
+  )
+);
+
+// ========== Selective Hooks ==========
+
+/**
+ * Hook for image-related cache operations
+ * Uses useShallow to prevent infinite re-renders
+ */
+export const useImageCache = () =>
+  useMediaCacheStore(
+    useShallow((state) => ({
+      getOrCreateBlobUrl: state.getOrCreateBlobUrl,
+      releaseBlobUrl: state.releaseBlobUrl,
+      hasBlobUrl: state.hasBlobUrl,
+      cacheDimensions: state.cacheDimensions,
+      getDimensions: state.getDimensions,
+    }))
+  );
+
+/**
+ * Hook for audio-related cache operations
+ * Uses useShallow to prevent infinite re-renders
+ */
+export const useAudioCache = () =>
+  useMediaCacheStore(
+    useShallow((state) => ({
+      getOrCreateBlobUrl: state.getOrCreateBlobUrl,
+      releaseBlobUrl: state.releaseBlobUrl,
+      hasBlobUrl: state.hasBlobUrl,
+      saveAudioPosition: state.saveAudioPosition,
+      getAudioPosition: state.getAudioPosition,
+      getEffectConfig: state.getEffectConfig,
+      cacheEffectConfig: state.cacheEffectConfig,
+    }))
+  );
+
+/**
+ * Hook for video-related cache operations
+ * Uses useShallow to prevent infinite re-renders
+ */
+export const useVideoCache = () =>
+  useMediaCacheStore(
+    useShallow((state) => ({
+      getOrCreateBlobUrl: state.getOrCreateBlobUrl,
+      releaseBlobUrl: state.releaseBlobUrl,
+      hasBlobUrl: state.hasBlobUrl,
+      getOrCreateStreamUrl: state.getOrCreateStreamUrl,
+      getPosterUrl: state.getPosterUrl,
+      cachePosterUrl: state.cachePosterUrl,
+      saveVideoPosition: state.saveVideoPosition,
+      getVideoPosition: state.getVideoPosition,
+      cacheVideoMetadata: state.cacheVideoMetadata,
+      getVideoMetadata: state.getVideoMetadata,
+      invalidateSession: state.invalidateSession,
+    }))
+  );
+
+/**
+ * Hook for blob URL cleanup on unmount
+ */
+export function useBlobUrlCleanup(key: string | null) {
+  const releaseBlobUrl = useMediaCacheStore((s) => s.releaseBlobUrl);
+
+  // Using inline effect to avoid importing useEffect in store
+  if (typeof window !== 'undefined') {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const { useEffect } = require('react');
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    useEffect(() => {
+      return () => {
+        if (key) {
+          releaseBlobUrl(key);
+        }
+      };
+    }, [key, releaseBlobUrl]);
+  }
+}
+
+// ========== Utilities ==========
+
+/**
+ * Generate a cache key from ArrayBuffer content
+ * Uses first and last 1KB + length for fast hashing
+ */
+export function generateContentKey(content: ArrayBuffer): string {
+  const arr = new Uint8Array(content);
+  const len = arr.length;
+
+  // Take first 1KB
+  const start = arr.slice(0, Math.min(1024, len));
+  // Take last 1KB
+  const end = arr.slice(Math.max(0, len - 1024));
+
+  // Simple hash from bytes
+  let hash = len;
+  for (let i = 0; i < start.length; i++) {
+    hash = ((hash << 5) - hash + start[i]) | 0;
+  }
+  for (let i = 0; i < end.length; i++) {
+    hash = ((hash << 5) - hash + end[i]) | 0;
+  }
+
+  return `blob-${len}-${hash.toString(16)}`;
+}

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

@@ -0,0 +1,148 @@
+# AudioPlayer Refactoring Plan
+
+## Goal
+
+Decompose the AudioPlayer module into a clean, maintainable folder structure with proper separation of concerns.
+
+## Current Issues
+
+1. **`context.tsx` is too large (574 lines)** - contains 4 different hooks and provider
+2. **`types.ts` is monolithic (185 lines)** - mixes audio, component, and effect types
+3. **`effects/index.ts` is overloaded (413 lines)** - types, constants, and calculations together
+4. **`AudioReactiveCover.tsx` has inline effect components** - harder to maintain
+
+## Target Structure
+
+```
+AudioPlayer/
+├── index.ts                      # Public API (re-exports)
+│
+├── types/
+│   ├── index.ts                  # Re-exports all types
+│   ├── audio.ts                  # Core audio types
+│   ├── components.ts             # Component props
+│   └── effects.ts                # Effect-related types
+│
+├── hooks/
+│   ├── index.ts                  # Re-exports all hooks
+│   ├── useSharedWebAudio.ts      # Web Audio API management
+│   ├── useAudioAnalysis.ts       # Frequency analysis
+│   ├── useAudioHotkeys.ts        # Keyboard shortcuts (existing)
+│   └── useVisualization.tsx      # Settings + Provider (renamed)
+│
+├── context/
+│   ├── index.ts                  # Re-exports
+│   ├── AudioProvider.tsx         # Provider component only
+│   └── selectors.ts              # useAudio, useAudioControls, useAudioState, useAudioElement
+│
+├── components/
+│   ├── index.ts                  # Re-exports
+│   ├── AudioPlayer.tsx           # Main player UI
+│   ├── AudioEqualizer.tsx        # Equalizer visualization
+│   ├── SimpleAudioPlayer.tsx     # Easy-to-use wrapper
+│   ├── ShortcutsPopover.tsx      # Keyboard shortcuts popover
+│   ├── VisualizationToggle.tsx   # Effect toggle button
+│   └── ReactiveCover/            # Cover with effects
+│       ├── index.tsx             # Main component
+│       ├── GlowEffect.tsx        # Glow effect
+│       ├── OrbsEffect.tsx        # Orbs effect
+│       ├── SpotlightEffect.tsx   # Spotlight effect
+│       └── MeshEffect.tsx        # Mesh gradient effect
+│
+├── effects/
+│   ├── index.ts                  # Re-exports
+│   ├── constants.ts              # INTENSITY_CONFIG, COLOR_SCHEMES
+│   ├── calculations.ts           # calculateGlowLayers, calculateOrbs, etc.
+│   └── animations.ts             # EFFECT_ANIMATIONS CSS string
+│
+└── utils/
+    ├── index.ts                  # Re-exports
+    └── formatTime.ts             # Time formatting helper
+```
+
+## Migration Steps
+
+### Phase 1: Create folder structure
+- [ ] Create `types/`, `hooks/`, `context/`, `components/`, `effects/`, `utils/` folders
+
+### Phase 2: Split types
+- [ ] Create `types/audio.ts` - AudioSource, PlaybackStatus, SharedWebAudioContext, AudioContextState
+- [ ] Create `types/components.ts` - AudioPlayerProps, AudioEqualizerProps, etc.
+- [ ] Create `types/effects.ts` - EffectVariant, AudioLevels, EffectConfig, etc.
+- [ ] Create `types/index.ts` - re-export all
+
+### Phase 3: Extract hooks from context.tsx
+- [ ] Create `hooks/useSharedWebAudio.ts` - extract from context.tsx
+- [ ] Create `hooks/useAudioAnalysis.ts` - extract from context.tsx
+- [ ] Move `useAudioHotkeys.ts` to `hooks/`
+- [ ] Move `useAudioVisualization.tsx` to `hooks/useVisualization.tsx`
+- [ ] Create `hooks/index.ts`
+
+### Phase 4: Refactor context
+- [ ] Create `context/AudioProvider.tsx` - provider only
+- [ ] Create `context/selectors.ts` - useAudio, useAudioControls, useAudioState, useAudioElement
+- [ ] Create `context/index.ts`
+
+### Phase 5: Reorganize components
+- [ ] Move `AudioPlayer.tsx` to `components/`
+- [ ] Move `AudioEqualizer.tsx` to `components/`
+- [ ] Move `SimpleAudioPlayer.tsx` to `components/`
+- [ ] Rename and move `AudioShortcutsPopover.tsx` to `components/ShortcutsPopover.tsx`
+- [ ] Move `VisualizationToggle.tsx` to `components/`
+- [ ] Split `AudioReactiveCover.tsx` into `components/ReactiveCover/`
+
+### Phase 6: Refactor effects
+- [ ] Create `effects/constants.ts` - INTENSITY_CONFIG, COLOR_SCHEMES
+- [ ] Create `effects/calculations.ts` - all calculate* functions
+- [ ] Create `effects/animations.ts` - EFFECT_ANIMATIONS
+- [ ] Update `effects/index.ts`
+
+### Phase 7: Create utils
+- [ ] Create `utils/formatTime.ts` - extract from AudioPlayer.tsx
+- [ ] Create `utils/index.ts`
+
+### Phase 8: Update main index.ts
+- [ ] Update `index.ts` to re-export from new locations
+- [ ] Ensure backward compatibility of public API
+
+### Phase 9: Cleanup
+- [ ] Delete old files
+- [ ] Run type check
+- [ ] Test imports
+
+## File Size Targets
+
+| File | Current | Target |
+|------|---------|--------|
+| context.tsx | 574 lines | Split into 4 files (~100-150 each) |
+| types.ts | 185 lines | Split into 3 files (~60 each) |
+| effects/index.ts | 413 lines | Split into 3 files (~100-150 each) |
+| AudioReactiveCover.tsx | 390 lines | Split into 5 files (~80 each) |
+
+## Public API (must remain unchanged)
+
+```typescript
+// Components
+export { SimpleAudioPlayer } from './components';
+export { AudioPlayer } from './components';
+export { AudioEqualizer } from './components';
+export { AudioReactiveCover } from './components';
+export { AudioShortcutsPopover } from './components'; // alias for backward compat
+
+// Context & Hooks
+export { AudioProvider, useAudio, useAudioControls, useAudioState, useAudioElement } from './context';
+export { useAudioHotkeys, AUDIO_SHORTCUTS } from './hooks';
+export { useAudioVisualization, VisualizationProvider } from './hooks'; // alias
+
+// Effects utilities
+export { INTENSITY_CONFIG, COLOR_SCHEMES, ... } from './effects';
+
+// Types (all existing types)
+export type { AudioSource, PlaybackStatus, ... } from './types';
+```
+
+## Notes
+
+- Keep backward compatibility for all public exports
+- Internal imports will change but external API stays the same
+- Run `pnpm check` after each phase to catch issues early