@djangocfg/ui-tools 2.1.110 → 2.1.111

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.110",
+  "version": "2.1.111",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -10,7 +10,11 @@
     "audio-player",
     "json-form",
     "mermaid",
-    "code-highlight"
+    "code-highlight",
+    "gallery",
+    "lightbox",
+    "map",
+    "maplibre"
   ],
   "author": {
     "name": "DjangoCFG",
@@ -32,6 +36,16 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
+    },
+    "./gallery": {
+      "types": "./src/tools/Gallery/index.ts",
+      "import": "./src/tools/Gallery/index.ts",
+      "require": "./src/tools/Gallery/index.ts"
+    },
+    "./map": {
+      "types": "./src/tools/Map/index.ts",
+      "import": "./src/tools/Map/index.ts",
+      "require": "./src/tools/Map/index.ts"
     }
   },
   "files": [
@@ -47,7 +61,8 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/ui-core": "^2.1.110",
+    "@djangocfg/i18n": "^2.1.111",
+    "@djangocfg/ui-core": "^2.1.111",
     "lucide-react": "^0.545.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
@@ -61,19 +76,27 @@
     "@rjsf/validator-ajv8": "^6.1.2",
     "@vidstack/react": "next",
     "@wavesurfer/react": "^1.0.12",
+    "maplibre-gl": "^4.7.1",
     "media-icons": "next",
     "mermaid": "^11.12.0",
     "prism-react-renderer": "^2.4.1",
     "react-json-tree": "^0.20.0",
     "react-lottie-player": "^2.1.0",
+    "react-map-gl": "^8.1.0",
     "react-markdown": "10.1.0",
     "react-zoom-pan-pinch": "^3.7.0",
     "remark-gfm": "4.0.1",
     "vidstack": "next",
     "wavesurfer.js": "^7.12.1"
   },
+  "optionalDependencies": {
+    "@mapbox/mapbox-gl-draw": "^1.4.3",
+    "@maplibre/maplibre-gl-geocoder": "^1.7.0"
+  },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.110",
+    "@djangocfg/i18n": "^2.1.111",
+    "@djangocfg/typescript-config": "^2.1.111",
+    "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",

package/src/components/index.ts

@@ -0,0 +1,17 @@
+// Lazy loading utilities
+export {
+  LazyWrapper,
+  LoadingFallback,
+  CardLoadingFallback,
+  MapLoadingFallback,
+  Spinner,
+  createLazyComponent,
+} from './lazy-wrapper';
+export type {
+  LazyWrapperProps,
+  LoadingFallbackProps,
+  CreateLazyComponentOptions,
+} from './lazy-wrapper';
+
+// Markdown
+export * from './markdown';

package/src/components/lazy-wrapper.tsx

@@ -0,0 +1,281 @@
+'use client';
+
+import * as React from 'react';
+import { Suspense, type ReactNode, type ComponentType } from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+import { useTypedT, type I18nTranslations } from '@djangocfg/i18n';
+
+// ============================================================================
+// Loading Fallback Components
+// ============================================================================
+
+export interface LoadingFallbackProps {
+  /** Minimum height of the loading container */
+  minHeight?: string | number;
+  /** Show loading text */
+  showText?: boolean;
+  /** Custom loading text */
+  text?: string;
+  /** Additional CSS classes */
+  className?: string;
+}
+
+/**
+ * Spinner - Simple spinning loader
+ */
+export function Spinner({ className }: { className?: string }) {
+  const t = useTypedT<I18nTranslations>();
+  const loadingLabel = t('ui.states.loading');
+
+  return (
+    <div
+      className={cn(
+        'inline-block h-8 w-8 animate-spin rounded-full',
+        'border-4 border-solid border-current border-r-transparent',
+        'align-[-0.125em] motion-reduce:animate-[spin_1.5s_linear_infinite]',
+        className
+      )}
+      role="status"
+      aria-label={loadingLabel}
+    />
+  );
+}
+
+/**
+ * LoadingFallback - Default loading state for lazy components
+ */
+export function LoadingFallback({
+  minHeight = 200,
+  showText = true,
+  text,
+  className,
+}: LoadingFallbackProps) {
+  const t = useTypedT<I18nTranslations>();
+  const loadingText = text ?? t('ui.form.loading');
+  const height = typeof minHeight === 'number' ? `${minHeight}px` : minHeight;
+
+  return (
+    <div
+      className={cn(
+        'flex items-center justify-center bg-muted/30 rounded-lg',
+        className
+      )}
+      style={{ minHeight: height }}
+    >
+      <div className="text-center">
+        <Spinner className="text-primary" />
+        {showText && (
+          <p className="mt-3 text-sm text-muted-foreground">{loadingText}</p>
+        )}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * CardLoadingFallback - Loading state styled as a card
+ */
+export function CardLoadingFallback({
+  title,
+  description,
+  minHeight = 200,
+  className,
+}: {
+  title?: string;
+  description?: string;
+  minHeight?: string | number;
+  className?: string;
+}) {
+  const t = useTypedT<I18nTranslations>();
+  const cardTitle = title ?? t('ui.states.loading');
+  const height = typeof minHeight === 'number' ? `${minHeight}px` : minHeight;
+
+  return (
+    <div
+      className={cn(
+        'relative bg-card rounded-lg border border-border overflow-hidden',
+        className
+      )}
+    >
+      <div className="p-4 border-b border-border bg-muted/50">
+        <h6 className="text-sm font-semibold text-foreground">{cardTitle}</h6>
+        {description && (
+          <p className="text-xs text-muted-foreground mt-1">{description}</p>
+        )}
+      </div>
+      <div className="p-4">
+        <div
+          className="flex justify-center items-center"
+          style={{ minHeight: height }}
+        >
+          <Spinner className="text-primary" />
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * MapLoadingFallback - Loading state for map components
+ */
+export function MapLoadingFallback({
+  minHeight = 400,
+  className,
+}: {
+  minHeight?: string | number;
+  className?: string;
+}) {
+  const t = useTypedT<I18nTranslations>();
+  const loadingText = t('ui.form.loading');
+  const height = typeof minHeight === 'number' ? `${minHeight}px` : minHeight;
+
+  return (
+    <div
+      className={cn(
+        'relative bg-muted/50 rounded-lg overflow-hidden',
+        'flex items-center justify-center',
+        className
+      )}
+      style={{ minHeight: height }}
+    >
+      <div className="text-center">
+        <div className="relative">
+          <Spinner className="text-primary h-10 w-10" />
+          <div className="absolute inset-0 flex items-center justify-center">
+            <svg
+              className="h-5 w-5 text-muted-foreground"
+              fill="none"
+              viewBox="0 0 24 24"
+              stroke="currentColor"
+            >
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                strokeWidth={2}
+                d="M17.657 16.657L13.414 20.9a1.998 1.998 0 01-2.827 0l-4.244-4.243a8 8 0 1111.314 0z"
+              />
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                strokeWidth={2}
+                d="M15 11a3 3 0 11-6 0 3 3 0 016 0z"
+              />
+            </svg>
+          </div>
+        </div>
+        <p className="mt-3 text-sm text-muted-foreground">{loadingText}</p>
+      </div>
+    </div>
+  );
+}
+
+// ============================================================================
+// Lazy Wrapper
+// ============================================================================
+
+export interface LazyWrapperProps {
+  children: ReactNode;
+  /** Custom fallback component */
+  fallback?: ReactNode;
+  /** Use card-style fallback */
+  card?: boolean;
+  /** Card title (when card=true) */
+  cardTitle?: string;
+  /** Card description (when card=true) */
+  cardDescription?: string;
+  /** Minimum height for fallback */
+  minHeight?: string | number;
+  /** Additional CSS classes for fallback */
+  className?: string;
+}
+
+/**
+ * LazyWrapper - Suspense wrapper with configurable fallbacks
+ *
+ * @example
+ * // Basic usage
+ * <LazyWrapper>
+ *   <LazyComponent />
+ * </LazyWrapper>
+ *
+ * @example
+ * // Card style fallback
+ * <LazyWrapper card cardTitle="Diagram" minHeight={300}>
+ *   <Mermaid chart={...} />
+ * </LazyWrapper>
+ *
+ * @example
+ * // Custom fallback
+ * <LazyWrapper fallback={<MyCustomLoader />}>
+ *   <HeavyComponent />
+ * </LazyWrapper>
+ */
+export function LazyWrapper({
+  children,
+  fallback,
+  card = false,
+  cardTitle,
+  cardDescription,
+  minHeight = 200,
+  className,
+}: LazyWrapperProps) {
+  const defaultFallback = card ? (
+    <CardLoadingFallback
+      title={cardTitle}
+      description={cardDescription}
+      minHeight={minHeight}
+      className={className}
+    />
+  ) : (
+    <LoadingFallback minHeight={minHeight} className={className} />
+  );
+
+  return <Suspense fallback={fallback ?? defaultFallback}>{children}</Suspense>;
+}
+
+// ============================================================================
+// Lazy Component Factory
+// ============================================================================
+
+export interface CreateLazyComponentOptions<P> {
+  /** Loading fallback component */
+  fallback?: ReactNode | ((props: P) => ReactNode);
+  /** Display name for the component */
+  displayName?: string;
+}
+
+/**
+ * createLazyComponent - Factory for creating lazy-loaded components
+ *
+ * @example
+ * const LazyMermaid = createLazyComponent(
+ *   () => import('./Mermaid.client'),
+ *   {
+ *     displayName: 'Mermaid',
+ *     fallback: <CardLoadingFallback title="Diagram" />,
+ *   }
+ * );
+ */
+export function createLazyComponent<P extends object>(
+  loader: () => Promise<{ default: ComponentType<P> }>,
+  options: CreateLazyComponentOptions<P> = {}
+): ComponentType<P> {
+  const LazyComponent = React.lazy(loader);
+
+  const WrappedComponent = (props: P) => {
+    const fallback =
+      typeof options.fallback === 'function'
+        ? options.fallback(props)
+        : options.fallback ?? <LoadingFallback />;
+
+    return (
+      <Suspense fallback={fallback}>
+        <LazyComponent {...props} />
+      </Suspense>
+    );
+  };
+
+  WrappedComponent.displayName = options.displayName ?? 'LazyComponent';
+
+  return WrappedComponent;
+}

package/src/index.ts

@@ -5,24 +5,109 @@
  * Works in any React environment: Next.js, Vite, Wails, CRA
  *
  * Bundle sizes:
+ * - Map: ~800KB (MapLibre GL maps)
  * - Mermaid: ~800KB (diagram rendering)
  * - PrettyCode: ~500KB (code syntax highlighting)
- * - JsonTree: ~100KB (JSON visualization)
- * - LottiePlayer: ~200KB (Lottie animation player)
- * - JsonForm: ~300KB (JSON Schema form generator)
  * - OpenapiViewer: ~400KB (OpenAPI schema viewer & playground)
- * - VideoPlayer: ~150KB (Professional video player with Vidstack)
+ * - JsonForm: ~300KB (JSON Schema form generator)
+ * - LottiePlayer: ~200KB (Lottie animation player)
  * - AudioPlayer: ~200KB (Audio player with WaveSurfer.js)
+ * - VideoPlayer: ~150KB (Professional video player with Vidstack)
+ * - JsonTree: ~100KB (JSON visualization)
+ * - Gallery: ~50KB (Image/video gallery)
  * - ImageViewer: ~50KB (Image viewer with zoom/pan/rotate)
+ *
+ * For tree-shaking, use subpath imports:
+ * - import { Gallery } from '@djangocfg/ui-tools/gallery'
+ * - import { MapContainer } from '@djangocfg/ui-tools/map'
  */
 
 'use client';
 
-// Re-export everything from tools
+// ============================================================================
+// Lazy Loading Utilities
+// ============================================================================
+
+export {
+  // Components
+  LazyWrapper,
+  LoadingFallback,
+  CardLoadingFallback,
+  MapLoadingFallback,
+  Spinner,
+  // Factory
+  createLazyComponent,
+} from './components';
+export type {
+  LazyWrapperProps,
+  LoadingFallbackProps,
+  CreateLazyComponentOptions,
+} from './components';
+
+// ============================================================================
+// Lazy Components (heavy tools, loaded on demand)
+// ============================================================================
+
+// Map (~800KB)
+export {
+  LazyMapContainer,
+  LazyMapView,
+} from './tools/Map/lazy';
+export type {
+  MapContainerProps,
+  MapViewport,
+  MapStyleKey,
+  MarkerData,
+} from './tools/Map/lazy';
+
+// Mermaid (~800KB)
+export { LazyMermaid } from './tools/Mermaid/lazy';
+export type { MermaidProps } from './tools/Mermaid/lazy';
+
+// PrettyCode (~500KB)
+export { LazyPrettyCode } from './tools/PrettyCode/lazy';
+export type { PrettyCodeProps } from './tools/PrettyCode/lazy';
+
+// OpenapiViewer (~400KB)
+export { LazyOpenapiViewer } from './tools/OpenapiViewer/lazy';
+export type { PlaygroundConfig, SchemaSource, PlaygroundProps } from './tools/OpenapiViewer/lazy';
+
+// JsonForm (~300KB)
+export { LazyJsonSchemaForm } from './tools/JsonForm/lazy';
+
+// LottiePlayer (~200KB)
+export { LazyLottiePlayer } from './tools/LottiePlayer/lazy';
+
+// AudioPlayer (~200KB)
+export {
+  LazyHybridAudioPlayer,
+  LazyHybridSimplePlayer,
+} from './tools/AudioPlayer/lazy';
+
+// VideoPlayer (~150KB)
+export { LazyVideoPlayer } from './tools/VideoPlayer/lazy';
+
+// JsonTree (~100KB)
+export { LazyJsonTree } from './tools/JsonTree/lazy';
+export type { JsonTreeProps } from './tools/JsonTree/lazy';
+
+// ImageViewer (~50KB)
+export { LazyImageViewer } from './tools/ImageViewer/lazy';
+
+// ============================================================================
+// Tools (from ./tools/index.ts) - Direct imports (no lazy loading)
+// ============================================================================
+
 export * from './tools';
 
-// Re-export components (markdown, etc.)
+// ============================================================================
+// Components (Markdown, etc.)
+// ============================================================================
+
 export * from './components/markdown';
 
-// Re-export stores
+// ============================================================================
+// Stores
+// ============================================================================
+
 export * from './stores/mediaCache';

package/src/tools/AudioPlayer/components/HybridAudioPlayer.tsx

@@ -15,7 +15,7 @@
  * - Timer display
  */
 
-import { memo } from 'react';
+import { memo, useMemo } from 'react';
 import {
   Play,
   Pause,
@@ -27,6 +27,7 @@ import {
   Loader2,
   Repeat,
 } from 'lucide-react';
+import { useTypedT, type I18nTranslations } from '@djangocfg/i18n';
 import { Button, Slider, cn } from '../../_shared';
 import { useHybridAudioContext } from '../context/HybridAudioProvider';
 import { HybridWaveform } from './HybridWaveform';
@@ -72,8 +73,16 @@ export const HybridAudioPlayer = memo(function HybridAudioPlayer({
   className,
   style,
 }: HybridAudioPlayerProps) {
+  const t = useTypedT<I18nTranslations>();
   const { state, controls } = useHybridAudioContext();
 
+  const labels = useMemo(() => ({
+    restart: t('tools.audio.restart'),
+    back: t('tools.audio.back'),
+    forward: t('tools.audio.forward'),
+    volume: t('tools.audio.volume'),
+  }), [t]);
+
   const isLoading = !state.isReady;
 
   const handleVolumeChange = (value: number[]) => {
@@ -119,7 +128,7 @@ export const HybridAudioPlayer = memo(function HybridAudioPlayer({
             className="h-9 w-9"
             onClick={controls.restart}
             disabled={!state.isReady}
-            title="Restart"
+            title={labels.restart}
           >
             <RotateCcw className="h-4 w-4" />
           </Button>
@@ -131,7 +140,7 @@ export const HybridAudioPlayer = memo(function HybridAudioPlayer({
             className="h-9 w-9"
             onClick={() => controls.skip(-5)}
             disabled={!state.isReady}
-            title="Back 5 seconds"
+            title={labels.back}
           >
             <SkipBack className="h-4 w-4" />
           </Button>
@@ -161,7 +170,7 @@ export const HybridAudioPlayer = memo(function HybridAudioPlayer({
             className="h-9 w-9"
             onClick={() => controls.skip(5)}
             disabled={!state.isReady}
-            title="Forward 5 seconds"
+            title={labels.forward}
           >
             <SkipForward className="h-4 w-4" />
           </Button>
@@ -189,7 +198,7 @@ export const HybridAudioPlayer = memo(function HybridAudioPlayer({
                 step={1}
                 onValueChange={handleVolumeChange}
                 className="w-20"
-                aria-label="Volume"
+                aria-label={labels.volume}
               />
             </>
           )}

package/src/tools/AudioPlayer/lazy.tsx

@@ -0,0 +1,85 @@
+'use client';
+
+/**
+ * Lazy-loaded AudioPlayer Components
+ *
+ * Heavy WaveSurfer.js (~200KB) is loaded only when component is rendered.
+ * Use this for automatic code-splitting with Suspense fallback.
+ *
+ * For direct imports without lazy loading, use:
+ * import { HybridAudioPlayer } from '@djangocfg/ui-tools/audio'
+ */
+
+import { createLazyComponent, LoadingFallback } from '../../components';
+import type {
+  HybridAudioPlayerProps,
+  HybridSimplePlayerProps,
+} from './components';
+
+// ============================================================================
+// Re-export types
+// ============================================================================
+
+export type { HybridAudioPlayerProps, HybridSimplePlayerProps };
+
+// ============================================================================
+// Audio Loading Fallback
+// ============================================================================
+
+function AudioLoadingFallback() {
+  return (
+    <div className="flex items-center justify-center p-6 bg-muted/30 rounded-lg">
+      <div className="flex flex-col items-center gap-2">
+        <div className="relative">
+          <div className="h-10 w-10 animate-spin rounded-full border-4 border-muted border-t-primary" />
+          <div className="absolute inset-0 flex items-center justify-center">
+            <svg
+              className="h-5 w-5 text-muted-foreground"
+              fill="none"
+              viewBox="0 0 24 24"
+              stroke="currentColor"
+            >
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                strokeWidth={2}
+                d="M9 19V6l12-3v13M9 19c0 1.105-1.343 2-3 2s-3-.895-3-2 1.343-2 3-2 3 .895 3 2zm12-3c0 1.105-1.343 2-3 2s-3-.895-3-2 1.343-2 3-2 3 .895 3 2zM9 10l12-3"
+              />
+            </svg>
+          </div>
+        </div>
+        <span className="text-sm text-muted-foreground">Loading audio player...</span>
+      </div>
+    </div>
+  );
+}
+
+// ============================================================================
+// Lazy Components
+// ============================================================================
+
+/**
+ * LazyHybridAudioPlayer - Lazy-loaded full-featured audio player
+ *
+ * Automatically shows loading state while WaveSurfer loads (~200KB)
+ */
+export const LazyHybridAudioPlayer = createLazyComponent<HybridAudioPlayerProps>(
+  () => import('./components').then((mod) => ({ default: mod.HybridAudioPlayer })),
+  {
+    displayName: 'LazyHybridAudioPlayer',
+    fallback: <AudioLoadingFallback />,
+  }
+);
+
+/**
+ * LazyHybridSimplePlayer - Lazy-loaded simple audio player
+ *
+ * Automatically shows loading state while WaveSurfer loads (~200KB)
+ */
+export const LazyHybridSimplePlayer = createLazyComponent<HybridSimplePlayerProps>(
+  () => import('./components').then((mod) => ({ default: mod.HybridSimplePlayer })),
+  {
+    displayName: 'LazyHybridSimplePlayer',
+    fallback: <AudioLoadingFallback />,
+  }
+);