@getmicdrop/svelte-components 5.17.4 → 5.19.0

package/dist/recipes/ImageUploader/ImageUploader.svelte

@@ -1,992 +1,994 @@
-<script lang="ts">
-  /**
-   * ImageUploader - Unified image upload component
-   *
-   * Supports:
-   * - Single image mode (event posters, venue images)
-   * - Multi-image mode with grid layout (performer photos)
-   * - Optional cropping with aspect ratio selection
-   * - Optional drag-to-reorder for multi-image
-   * - Different shapes: square, wide
-   * - Image compression before upload callback
-   */
-
-  import { browser } from '../../__LIB_ENVIRONMENT__.js';
-  import FilePond, { registerPlugin } from 'svelte-filepond';
-  import FilePondPluginImagePreview from 'filepond-plugin-image-preview';
-  import FilePondPluginImageExifOrientation from 'filepond-plugin-image-exif-orientation';
-  import FilePondPluginFileValidateType from 'filepond-plugin-file-validate-type';
-  import FilePondPluginFileValidateSize from 'filepond-plugin-file-validate-size';
-  import 'filepond/dist/filepond.min.css';
-  import 'filepond-plugin-image-preview/dist/filepond-plugin-image-preview.css';
-
-  import Sortable from 'sortablejs';
-  import CropImage from '../CropImage/CropImage.svelte';
-  import { optimizeImage } from '../../utils/imageOptimizer';
-  import Badge from '../../primitives/Badges/Badge.svelte';
-  import Button from '../../primitives/Button/Button.svelte';
-  import { CloseOutline, ImageOutline, PlusOutline, TrashBinOutline } from '../../primitives/Icons';
-  import { typography } from '../../tokens/typography';
-
-  // Register FilePond plugins once
-  registerPlugin(
-    FilePondPluginImagePreview,
-    FilePondPluginImageExifOrientation,
-    FilePondPluginFileValidateType,
-    FilePondPluginFileValidateSize
-  );
-
-  // Types
-  type Shape = 'square' | 'wide';
-  type AspectRatio = '1:1' | '2:1' | '16:9' | '4:3' | 'free';
-  type Size = 'sm' | 'md' | 'lg';
-
-  /**
-   * Default labels for user-visible strings in ImageUploader.
-   * Consumers can override via the `labels` prop.
-   */
-  const defaultLabels = {
-    uploadPhotoTitle: 'Upload photo',
-    mainBadge: 'Main',
-    replace: 'Replace',
-    delete: 'Delete',
-    removePhoto: 'Remove photo',
-    addPhotoAria: 'Add photo - drag and drop or click to upload',
-    fileTypes: 'JPG, PNG, WebP',
-    uploadedAlt: 'Uploaded',
-    closeModal: 'Close',
-  };
-
-  interface Props {
-    /** Single image or array of images (URLs) */
-    images?: string | string[];
-    /** Maximum number of images (only for multi mode) */
-    maxImages?: number;
-    /** Enable cropping step */
-    enableCrop?: boolean;
-    /** Crop aspect ratio */
-    cropAspectRatio?: AspectRatio;
-    /** Enable drag-to-reorder (only for multi mode) */
-    enableReorder?: boolean;
-    /** Dropzone shape - affects aspect ratio and styling */
-    shape?: Shape;
-    /** Size of image slots: sm (~64px), md (~96px), lg (~200px+) */
-    size?: Size;
-    /** Show "Main" badge on first image (multi mode) */
-    showMainBadge?: boolean;
-    /** Maximum file size (e.g., "10MB") */
-    maxFileSize?: string;
-    /** Accepted file types */
-    acceptedTypes?: string[];
-    /** Label shown when empty */
-    emptyLabel?: string;
-    /** Constraints text shown inside dropzone (e.g., "Max 10MB, 2160px") */
-    constraintsText?: string;
-    /** Helper text shown below dropzone */
-    helperText?: string;
-    /** Callback when image is uploaded - receives File, optionally returns URL
-     * If returns URL: component adds to images (self-managed)
-     * If returns void/null: parent must manage images (controlled) */
-    onUpload?: (file: File) => Promise<string | null | void> | void;
-    /** Callback when image is removed */
-    onRemove?: (index: number) => void;
-    /** Callback when images are reordered - receives new array */
-    onReorder?: (images: string[]) => void;
-    /** Callback when images are reordered - receives indices (for store integration) */
-    onReorderIndices?: (data: { from: number; to: number }) => void;
-    /** Callback when user clicks to set main image (moves to first position) */
-    onSetMain?: (data: { index: number }) => void;
-    /** Callback when images change (single source of truth) */
-    onchange?: (images: string[]) => void;
-    /** Show upload error */
-    error?: string;
-    /** Disabled state */
-    disabled?: boolean;
-    /** Custom class for wrapper */
-    class?: string;
-    /** Override user-visible strings */
-    labels?: Partial<typeof defaultLabels>;
-  }
-
-  let {
-    images = $bindable([]),
-    maxImages = 6,
-    enableCrop = false,
-    cropAspectRatio = '1:1',
-    enableReorder = true,
-    shape = 'square',
-    size = 'md',
-    showMainBadge = true,
-    maxFileSize = '20MB',
-    acceptedTypes = ['image/jpeg', 'image/png', 'image/webp', 'image/heic', 'image/heif'],
-    emptyLabel = 'Drag & drop or click to upload',
-    constraintsText = '',
-    helperText = '',
-    onUpload,
-    onRemove,
-    onReorder,
-    onReorderIndices,
-    onSetMain,
-    onchange,
-    error = '',
-    disabled = false,
-    class: className = '',
-    labels: userLabels = {},
-  }: Props = $props();
-
-  let labels = $derived({ ...defaultLabels, ...userLabels });
-
-  // Normalize images to array
-  let imageArray = $derived(
-    Array.isArray(images)
-      ? images.filter(Boolean)
-      : images
-        ? [images]
-        : []
-  );
-
-  // Determine mode based on maxImages
-  let isMultiMode = $derived(maxImages > 1);
-  let canAddMore = $derived(imageArray.length < maxImages);
-
-  // FilePond state
-  let filePondFiles = $state<unknown[]>([]);
-  let filePondInstance = $state<unknown>(undefined);
-  let showFilePondModal = $state(false);
-  let targetSlotIndex = $state<number | null>(null);
-
-  // Crop state
-  let showCropModal = $state(false);
-  let imageForCrop = $state('');
-  let isUploading = $state(false);
-
-  // Reorder state
-  let gridContainer = $state<HTMLDivElement | undefined>(undefined);
-  let sortableInstance: Sortable | null = null;
-  let isDragging = $state(false);
-  let gridRenderKey = $state(0);
-
-  // Direct drag-drop state for dropzone
-  let isDropzoneDragOver = $state(false);
-
-  // Native modal dropzone state
-  let isModalDragOver = $state(false);
-  let modalFileInput = $state<HTMLInputElement | undefined>(undefined);
-
-  // Single-mode file input for replace functionality
-  let singleModeFileInput = $state<HTMLInputElement | undefined>(undefined);
-
-  // Prevent browser from opening dragged files in new tab
-  // This MUST be at document level to intercept before browser default behavior
-  $effect(() => {
-    if (!browser) return;
-
-    const preventBrowserDefault = (e: DragEvent) => {
-      // Only prevent if it's a file drag (not text selection, etc.)
-      if (e.dataTransfer?.types?.includes('Files')) {
-        e.preventDefault();
-      }
-    };
-
-    window.addEventListener('dragover', preventBrowserDefault, true);
-    window.addEventListener('drop', preventBrowserDefault, true);
-
-    return () => {
-      window.removeEventListener('dragover', preventBrowserDefault, true);
-      window.removeEventListener('drop', preventBrowserDefault, true);
-    };
-  });
-
-  // Shape to aspect ratio mapping
-  const shapeAspects: Record<Shape, string> = {
-    square: 'aspect-square',
-    wide: 'aspect-video',
-  };
-
-  // Size configuration - layout classes, slot width, and element sizes
-  const sizeConfig: Record<Size, { containerClass: string; slotClass: string; iconClass: string; badgeSize: 'small' | 'medium'; removeSize: string }> = {
-    sm: {
-      containerClass: 'flex flex-wrap gap-1.5',
-      slotClass: 'w-16 h-16',  // 64px fixed
-      iconClass: 'w-4 h-4',
-      badgeSize: 'small',
-      removeSize: 'w-4 h-4',
-    },
-    md: {
-      containerClass: 'flex flex-wrap gap-2',
-      slotClass: 'w-24 h-24', // 96px fixed
-      iconClass: 'w-5 h-5',
-      badgeSize: 'small',
-      removeSize: 'w-5 h-5',
-    },
-    lg: {
-      containerClass: 'grid grid-cols-3 gap-4',
-      slotClass: '', // Let grid control width (uses aspect-square)
-      iconClass: 'w-8 h-8',
-      badgeSize: 'medium',
-      removeSize: 'w-6 h-6',
-    },
-  };
-
-  // Get current size config
-  let currentSizeConfig = $derived(sizeConfig[size]);
-
-  // Crop aspect ratio to number
-  const aspectRatioValues: Record<AspectRatio, number> = {
-    '1:1': 1,
-    '2:1': 2,
-    '16:9': 16 / 9,
-    '4:3': 4 / 3,
-    'free': 0,
-  };
-
-  // FilePond options
-  const filePondOptions = $derived({
-    allowMultiple: false,
-    maxFiles: 1,
-    acceptedFileTypes: acceptedTypes,
-    maxFileSize: maxFileSize,
-    // Drag-drop configuration
-    allowDrop: true,
-    dropOnPage: false, // Only accept drops on the FilePond element
-    dropOnElement: true,
-    labelIdle: `
-      <div class="filepond-custom-label">
-        <svg class="w-8 h-8 mb-5 text-gray-400 dark:text-gray-500" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 4v16m8-8H4" />
-        </svg>
-        <span class="text-sm font-medium text-gray-600 dark:text-gray-300">${emptyLabel}</span>
-        <span class="text-[11px] text-gray-400 dark:text-gray-500 mt-2 block">${labels.fileTypes}</span>
-        ${constraintsText ? `<span class="text-[10px] text-gray-400/50 dark:text-gray-500/50 mt-1 block">${constraintsText}</span>` : ''}
-      </div>
-    `,
-    credits: false,
-    instantUpload: false,
-    allowRevert: true,
-    allowProcess: false,
-    imagePreviewHeight: shape === 'wide' ? 150 : 200,
-    stylePanelLayout: 'compact',
-    stylePanelAspectRatio: shape === 'wide' ? '16:9' : '1:1',
-  });
-
-  // Handle FilePond file add
-  function handleFilePondAddFile(err: unknown, fileItem: unknown) {
-    if (err) {
-      console.error('FilePond error:', err);
-      return;
-    }
-
-    const item = fileItem as { file: File } | undefined;
-    const file = item?.file;
-    if (!file) return;
-
-    if (enableCrop) {
-      // Show crop modal
-      const objectUrl = URL.createObjectURL(file);
-      imageForCrop = objectUrl;
-      showCropModal = true;
-    } else {
-      // Optimize then upload
-      optimizeImage(file).then((optimizedFile) => {
-        handleUpload(optimizedFile);
-      });
-    }
-
-    // Clear FilePond
-    setTimeout(() => {
-      if (filePondInstance && typeof (filePondInstance as { removeFiles: () => void }).removeFiles === 'function') {
-        (filePondInstance as { removeFiles: () => void }).removeFiles();
-      }
-    }, 100);
-
-    showFilePondModal = false;
-  }
-
-  // Handle crop save
-  async function handleCropSave(croppedFile: File) {
-    showCropModal = false;
-    if (imageForCrop.startsWith('blob:')) {
-      URL.revokeObjectURL(imageForCrop);
-    }
-    imageForCrop = '';
-    await handleUpload(croppedFile);
-  }
-
-  // Handle crop cancel
-  function handleCropCancel() {
-    showCropModal = false;
-    if (imageForCrop.startsWith('blob:')) {
-      URL.revokeObjectURL(imageForCrop);
-    }
-    imageForCrop = '';
-  }
-
-  // Handle upload
-  // Supports two modes:
-  // 1. Self-managed: onUpload returns URL, component adds to images
-  // 2. Controlled: onUpload returns void, parent manages images array
-  async function handleUpload(file: File) {
-    if (!onUpload) {
-      console.warn('ImageUploader: onUpload callback not provided');
-      return;
-    }
-
-    isUploading = true;
-
-    try {
-      const result = await onUpload(file);
-
-      // If onUpload returns a URL, component manages adding to images (self-managed mode)
-      // If onUpload returns void/null, parent is expected to manage images (controlled mode)
-      if (typeof result === 'string' && result) {
-        const url = result;
-        const newImages = [...imageArray];
-        if (targetSlotIndex !== null && targetSlotIndex < newImages.length) {
-          // Replace existing image
-          newImages[targetSlotIndex] = url;
-        } else {
-          // Add new image
-          newImages.push(url);
-        }
-
-        // Update images and notify
-        if (Array.isArray(images)) {
-          images = newImages;
-        } else {
-          images = newImages[0] || '';
-        }
-        onchange?.(newImages);
-      }
-      // If result is void/null/undefined, parent handles adding to images
-    } catch (err) {
-      console.error('Upload failed:', err);
-    } finally {
-      isUploading = false;
-      targetSlotIndex = null;
-    }
-  }
-
-  // Handle remove
-  // In controlled mode (onReorderIndices provided), just fire callback
-  // In self-managed mode, update images internally
-  function handleRemoveImage(index: number) {
-    // Always fire the callback
-    onRemove?.(index);
-
-    // Only manage state internally if not in controlled mode
-    if (!onReorderIndices) {
-      const newImages = [...imageArray];
-      newImages.splice(index, 1);
-
-      if (Array.isArray(images)) {
-        images = newImages;
-      } else {
-        images = newImages[0] || '';
-      }
-
-      onchange?.(newImages);
-    }
-
-    gridRenderKey++;
-  }
-
-  // Open upload modal/dropzone
-  function openUploadModal(slotIndex?: number) {
-    if (disabled) return;
-    targetSlotIndex = slotIndex ?? null;
-    if (isMultiMode) {
-      showFilePondModal = true;
-    }
-  }
-
-  // Handle direct drag-drop on dropzone (bypasses modal)
-  function handleDropzoneDragOver(e: DragEvent) {
-    e.preventDefault();
-    e.stopPropagation();
-    if (disabled || !canAddMore) return;
-    isDropzoneDragOver = true;
-  }
-
-  function handleDropzoneDragLeave(e: DragEvent) {
-    e.preventDefault();
-    e.stopPropagation();
-    isDropzoneDragOver = false;
-  }
-
-  function handleDropzoneDrop(e: DragEvent, slotIndex?: number) {
-    e.preventDefault();
-    e.stopPropagation();
-    isDropzoneDragOver = false;
-
-    if (disabled || !canAddMore) return;
-
-    const files = e.dataTransfer?.files;
-    if (!files || files.length === 0) return;
-
-    const file = files[0];
-
-    // Check if it's an accepted image type
-    if (!acceptedTypes.some(type => file.type === type || type.includes('*'))) {
-      console.warn('File type not accepted:', file.type);
-      return;
-    }
-
-    targetSlotIndex = slotIndex ?? null;
-
-    if (enableCrop) {
-      // Show crop modal
-      const objectUrl = URL.createObjectURL(file);
-      imageForCrop = objectUrl;
-      showCropModal = true;
-    } else {
-      // Optimize then upload
-      optimizeImage(file).then((optimizedFile) => {
-        handleUpload(optimizedFile);
-      });
-    }
-  }
-
-  // Handle modal dropzone drop
-  function handleModalDrop(e: DragEvent) {
-    e.preventDefault();
-    e.stopPropagation();
-    isModalDragOver = false;
-    showFilePondModal = false;
-
-    if (disabled || !canAddMore) return;
-
-    const files = e.dataTransfer?.files;
-    if (!files || files.length === 0) return;
-
-    const file = files[0];
-
-    // Check if it's an accepted image type
-    if (!acceptedTypes.some(type => file.type === type || type.includes('*'))) {
-      console.warn('File type not accepted:', file.type);
-      return;
-    }
-
-    if (enableCrop) {
-      const objectUrl = URL.createObjectURL(file);
-      imageForCrop = objectUrl;
-      showCropModal = true;
-    } else {
-      optimizeImage(file).then((optimizedFile) => {
-        handleUpload(optimizedFile);
-      });
-    }
-  }
-
-  // Handle modal file input selection
-  function handleModalFileSelect(e: Event) {
-    const input = e.target as HTMLInputElement;
-    const file = input?.files?.[0];
-    if (!file) return;
-
-    showFilePondModal = false;
-
-    if (enableCrop) {
-      const objectUrl = URL.createObjectURL(file);
-      imageForCrop = objectUrl;
-      showCropModal = true;
-    } else {
-      optimizeImage(file).then((optimizedFile) => {
-        handleUpload(optimizedFile);
-      });
-    }
-
-    // Clear input for next selection
-    input.value = '';
-  }
-
-  // Handle single-mode file input selection (for replace)
-  function handleSingleModeFileSelect(e: Event) {
-    const input = e.target as HTMLInputElement;
-    const file = input?.files?.[0];
-    if (!file) return;
-
-    targetSlotIndex = 0; // Replace the existing image
-
-    if (enableCrop) {
-      const objectUrl = URL.createObjectURL(file);
-      imageForCrop = objectUrl;
-      showCropModal = true;
-    } else {
-      optimizeImage(file).then((optimizedFile) => {
-        handleUpload(optimizedFile);
-      });
-    }
-
-    // Clear input for next selection
-    input.value = '';
-  }
-
-  // Initialize sortable for multi-image grid
-  function initSortable() {
-    if (!browser || !gridContainer || !enableReorder || !isMultiMode) return;
-
-    if (sortableInstance) {
-      sortableInstance.destroy();
-    }
-
-    sortableInstance = new Sortable(gridContainer, {
-      animation: 200,
-      ghostClass: 'sortable-ghost',
-      chosenClass: 'sortable-chosen',
-      dragClass: 'sortable-drag',
-      delay: 150,
-      delayOnTouchOnly: true,
-      touchStartThreshold: 5,
-      filter: '.empty-slot, .remove-btn',
-      preventOnFilter: false,
-      onStart: () => {
-        isDragging = true;
-      },
-      onEnd: (evt) => {
-        isDragging = false;
-        const { oldIndex, newIndex } = evt;
-        if (oldIndex === undefined || newIndex === undefined || oldIndex === newIndex) return;
-
-        // Fire index-based callback for store integration (controlled mode)
-        onReorderIndices?.({ from: oldIndex, to: newIndex });
-
-        // For self-managed mode, update images internally
-        if (!onReorderIndices) {
-          const newImages = [...imageArray];
-          const [moved] = newImages.splice(oldIndex, 1);
-          newImages.splice(newIndex, 0, moved);
-
-          if (Array.isArray(images)) {
-            images = newImages;
-          }
-
-          onReorder?.(newImages);
-          onchange?.(newImages);
-        }
-
-        gridRenderKey++;
-
-        // Re-init after state update
-        if (sortableInstance) {
-          sortableInstance.destroy();
-          sortableInstance = null;
-        }
-      },
-    });
-  }
-
-  // Setup sortable on mount and when images change
-  $effect(() => {
-    if (browser && gridContainer && !isDragging && isMultiMode && enableReorder) {
-      // Use setTimeout to ensure DOM is ready
-      setTimeout(initSortable, 0);
-    }
-  });
-
-  // Cleanup
-  $effect(() => {
-    return () => {
-      if (sortableInstance) {
-        sortableInstance.destroy();
-      }
-    };
-  });
-
-  // Generate slots with progressive disclosure
-  // Only show filled images + 1 empty slot (up to maxImages)
-  let slots = $derived.by(() => {
-    const slotCount = Math.min(imageArray.length + 1, maxImages);
-    return Array.from({ length: slotCount }, (_, i) => ({
-      id: `slot-${i}`,
-      image: imageArray[i] || null,
-      isNext: i === imageArray.length,
-    }));
-  });
-</script>
-
-
-<!-- Single Image Mode -->
-{#if !isMultiMode}
-  <div class="image-uploader-single {className}">
-    {#if imageArray.length > 0}
-      <!-- Show existing image with remove option -->
-      <div class="relative {shapeAspects[shape]} bg-gray-100 dark:bg-gray-800 rounded-xl overflow-hidden group">
-        <img
-          src={imageArray[0]}
-          alt={labels.uploadedAlt}
-          class="w-full h-full object-contain"
-        />
-        {#if !disabled}
-          <div class="absolute inset-0 bg-black/50 opacity-0 group-hover:opacity-100 transition-opacity flex items-center justify-center gap-3">
-            <Button
-              variant="default"
-              size="sm"
-              onclick={() => singleModeFileInput?.click()}
-            >
-              <ImageOutline class="w-4 h-4 mr-1.5" />
-              {labels.replace}
-            </Button>
-            <Button
-              variant="red"
-              size="sm"
-              onclick={() => handleRemoveImage(0)}
-            >
-              <TrashBinOutline class="w-4 h-4 mr-1.5" />
-              {labels.delete}
-            </Button>
-          </div>
-          <!-- Hidden file input for replace -->
-          <input
-            bind:this={singleModeFileInput}
-            type="file"
-            accept={acceptedTypes.join(',')}
-            class="hidden"
-            data-testid="image-upload-input"
-            onchange={handleSingleModeFileSelect}
-          />
-        {/if}
-      </div>
-    {:else}
-      <!-- Empty dropzone with direct drag-drop support -->
-      <div
-        class="{shapeAspects[shape]} filepond-wrapper-single rounded-xl {shape === 'wide' ? 'filepond-wide' : ''}
-          {isDropzoneDragOver ? 'dropzone-drag-over' : ''}"
-        role="button"
-        tabindex="0"
-        ondragover={handleDropzoneDragOver}
-        ondragleave={handleDropzoneDragLeave}
-        ondrop={(e) => handleDropzoneDrop(e, 0)}
-      >
-        <FilePond
-          bind:this={filePondInstance}
-          bind:files={filePondFiles}
-          {...filePondOptions}
-          onaddfile={handleFilePondAddFile}
-        />
-      </div>
-    {/if}
-
-    {#if helperText}
-      <p class={`${typography.smMuted} mt-2`}>{helperText}</p>
-    {/if}
-
-    {#if error}
-      <p class={`${typography.smMuted} text-red-500 mt-2`}>{error}</p>
-    {/if}
-  </div>
-
-<!-- Multi Image Mode (Grid) -->
-{:else}
-  <div class="image-uploader-multi {className}">
-    {#key gridRenderKey}
-      <div
-        bind:this={gridContainer}
-        class="{currentSizeConfig.containerClass}"
-      >
-        {#each slots as slot, index (slot.id)}
-          <div
-            class="relative {size === 'lg' ? shapeAspects[shape] : ''} {currentSizeConfig.slotClass} rounded-lg overflow-hidden"
-            class:cursor-grab={slot.image && enableReorder && !disabled}
-            class:empty-slot={!slot.image}
-            data-slot-id={slot.id}
-          >
-            {#if slot.image}
-              <!-- Filled slot -->
-              <!-- svelte-ignore a11y_click_events_have_key_events -->
-              <!-- svelte-ignore a11y_no_static_element_interactions -->
-              <div
-                class="relative w-full h-full bg-gray-100 dark:bg-gray-800 group"
-                class:cursor-pointer={onSetMain && index !== 0 && !disabled}
-                onclick={() => {
-                  if (onSetMain && index !== 0 && !disabled) {
-                    onSetMain({ index });
-                  }
-                }}
-              >
-                <img
-                  src={slot.image}
-                  alt={labels.uploadedAlt}
-                  class="w-full h-full object-contain pointer-events-none"
-                  draggable="false"
-                />
-                {#if showMainBadge && index === 0}
-                  <div class="absolute bottom-1 left-1 z-10 pointer-events-none">
-                    <Badge variant="info" size={currentSizeConfig.badgeSize}>{labels.mainBadge}</Badge>
-                  </div>
-                {/if}
-                {#if !disabled}
-                  <button
-                    type="button"
-                    class="remove-btn absolute top-1 right-1 {currentSizeConfig.removeSize} bg-white/90 dark:bg-gray-900/90 rounded-full flex items-center justify-center opacity-0 group-hover:opacity-100 transition-opacity hover:bg-white dark:hover:bg-gray-900"
-                    onclick={(e) => { e.stopPropagation(); handleRemoveImage(index); }}
-                    aria-label={labels.removePhoto}
-                  >
-                    <CloseOutline class="w-3 h-3 text-gray-700 dark:text-gray-300" />
-                  </button>
-                {/if}
-              </div>
-            {:else if slot.isNext && canAddMore && !disabled}
-              <!-- Next available slot - dropzone with direct drag-drop support -->
-              <!-- svelte-ignore a11y_no_static_element_interactions -->
-              <div
-                class="w-full h-full border-2 border-dashed rounded-lg transition-colors flex items-center justify-center cursor-pointer
-                  {isDropzoneDragOver
-                    ? 'border-blue-500 bg-blue-100 dark:bg-blue-900/40'
-                    : 'border-gray-300 dark:border-gray-600 bg-gray-50 dark:bg-gray-800 hover:border-blue-400 hover:bg-blue-50 dark:hover:bg-blue-900/20'}"
-                role="button"
-                tabindex="0"
-                onclick={() => openUploadModal(index)}
-                onkeydown={(e) => { if (e.key === 'Enter' || e.key === ' ') openUploadModal(index); }}
-                ondragenter={(e) => { e.preventDefault(); e.stopPropagation(); isDropzoneDragOver = true; }}
-                ondragover={(e) => { e.preventDefault(); e.stopPropagation(); isDropzoneDragOver = true; }}
-                ondragleave={(e) => { e.preventDefault(); e.stopPropagation(); isDropzoneDragOver = false; }}
-                ondrop={(e) => handleDropzoneDrop(e, index)}
-                aria-label={labels.addPhotoAria}
-              >
-                <PlusOutline class={currentSizeConfig.iconClass + ' text-gray-400 dark:text-gray-500'} />
-              </div>
-            {/if}
-          </div>
-        {/each}
-      </div>
-    {/key}
-
-    {#if helperText}
-      <p class={`${typography.smMuted} mt-3`}>{helperText}</p>
-    {/if}
-
-    {#if error}
-      <p class={`${typography.smMuted} text-red-500 mt-2`}>{error}</p>
-    {/if}
-  </div>
-
-  <!-- Upload Modal for multi-image (native dropzone - more reliable than FilePond) -->
-  {#if showFilePondModal}
-    <!-- svelte-ignore a11y_click_events_have_key_events -->
-    <!-- svelte-ignore a11y_no_static_element_interactions -->
-    <div
-      class="fixed inset-0 z-50 flex items-center justify-center bg-gray-900/50 dark:bg-gray-900/80 p-4"
-      onclick={() => (showFilePondModal = false)}
-      ondragover={(e) => e.preventDefault()}
-      ondrop={(e) => e.preventDefault()}
-    >
-      <!-- svelte-ignore a11y_click_events_have_key_events -->
-      <!-- svelte-ignore a11y_no_static_element_interactions -->
-      <div
-        class="bg-white dark:bg-gray-800 rounded-xl shadow-xl w-full max-w-md overflow-hidden"
-        onclick={(e) => e.stopPropagation()}
-      >
-        <div class="flex items-center justify-between p-4 border-b border-gray-200 dark:border-gray-700">
-          <h3 class={typography.h3}>{labels.uploadPhotoTitle}</h3>
-          <button
-            type="button"
-            class="p-1.5 text-gray-400 hover:text-gray-600 dark:hover:text-gray-300 transition-colors"
-            onclick={() => (showFilePondModal = false)}
-            aria-label={labels.closeModal}
-          >
-            <CloseOutline class="w-5 h-5" />
-          </button>
-        </div>
-        <div class="p-4">
-          <!-- Native dropzone with file input -->
-          <div
-            class="dropzone-native border-2 border-dashed rounded-lg transition-all duration-200 min-h-[200px] flex flex-col items-center justify-center cursor-pointer
-              {isModalDragOver
-                ? 'border-blue-500 bg-blue-50 dark:bg-blue-900/30'
-                : 'border-gray-300 dark:border-gray-600 bg-gray-50 dark:bg-gray-800 hover:border-blue-400 hover:bg-blue-50/50 dark:hover:bg-blue-900/20'}"
-            role="button"
-            tabindex="0"
-            onclick={() => modalFileInput?.click()}
-            onkeydown={(e) => { if (e.key === 'Enter' || e.key === ' ') modalFileInput?.click(); }}
-            ondragenter={(e) => { e.preventDefault(); e.stopPropagation(); isModalDragOver = true; }}
-            ondragover={(e) => { e.preventDefault(); e.stopPropagation(); isModalDragOver = true; }}
-            ondragleave={(e) => { e.preventDefault(); e.stopPropagation(); isModalDragOver = false; }}
-            ondrop={(e) => handleModalDrop(e)}
-          >
-            <PlusOutline class="w-8 h-8 mb-2 text-gray-400" />
-            <span class={typography.smMuted}>{emptyLabel}</span>
-            <span class={`${typography.xsMuted} mt-1`}>{labels.fileTypes}</span>
-          </div>
-          <input
-            bind:this={modalFileInput}
-            type="file"
-            accept={acceptedTypes.join(',')}
-            class="hidden"
-            data-testid="image-upload-modal-input"
-            onchange={handleModalFileSelect}
-          />
-        </div>
-      </div>
-    </div>
-  {/if}
-{/if}
-
-<!-- Crop Modal -->
-{#if enableCrop}
-  <CropImage
-    bind:showModal={showCropModal}
-    imageSrc={imageForCrop}
-    onSave={handleCropSave}
-    onCancel={handleCropCancel}
-    isUploadingImage={isUploading}
-  />
-{/if}
-
-<style>
-  /* FilePond customizations */
-  :global(.filepond-wrapper .filepond--root) {
-    font-family: inherit;
-    min-height: 180px;
-  }
-
-  :global(.filepond-wrapper .filepond--panel-root) {
-    background-color: transparent;
-  }
-
-  :global(.filepond-wrapper .filepond--drop-label) {
-    color: inherit;
-    min-height: 180px;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-  }
-
-  /* Note: FilePond dark mode is handled via runtime JS injection
-     because Svelte's scoped :global() can't reliably override
-     FilePond's CSS that loads from node_modules */
-
-  :global(.filepond-wrapper .filepond--drop-label label) {
-    display: flex;
-    flex-direction: column;
-    align-items: center;
-    justify-content: center;
-    width: 100%;
-    height: 100%;
-    cursor: pointer;
-  }
-
-  :global(.filepond-wrapper .filepond--label-action) {
-    text-decoration: none;
-    color: inherit;
-  }
-
-  /* FilePond drag hover state */
-  :global(.filepond-wrapper .filepond--root[data-hopper-state="drag-over"]) {
-    border-color: rgb(59 130 246); /* blue-500 */
-    background-color: rgb(239 246 255); /* blue-50 */
-  }
-
-  :global(.dark .filepond-wrapper .filepond--root[data-hopper-state="drag-over"]) {
-    background-color: rgba(30, 58, 138, 0.3); /* blue-900/30 */
-  }
-
-  :global(.filepond-wrapper .filepond--root[data-hopper-state="drag-over"] .filepond--panel-root) {
-    border-color: rgb(59 130 246); /* blue-500 */
-  }
-
-  /* Modal FilePond styling */
-  :global(.filepond-wrapper) {
-    border: 2px dashed rgb(209 213 219); /* gray-300 */
-    border-radius: 0.5rem; /* rounded-lg */
-    background-color: rgb(249 250 251); /* gray-50 */
-    transition-property: color, background-color, border-color;
-    transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
-    transition-duration: 150ms;
-  }
-
-  :global(.dark .filepond-wrapper) {
-    border-color: rgb(75 85 99); /* gray-600 */
-    background-color: rgb(31 41 55); /* gray-800 */
-  }
-
-  :global(.filepond-wrapper:hover) {
-    border-color: rgb(96 165 250); /* blue-400 */
-  }
-
-  /* Single mode dropzone styling */
-  .filepond-wrapper-single {
-    border: 2px dashed rgb(209 213 219); /* gray-300 */
-    background-color: rgb(249 250 251); /* gray-50 */
-    transition-property: color, background-color, border-color;
-    transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
-    transition-duration: 150ms;
-  }
-
-  :global(.dark) .filepond-wrapper-single {
-    border-color: rgb(75 85 99); /* gray-600 */
-    background-color: rgb(31 41 55); /* gray-800 */
-  }
-
-  .filepond-wrapper-single:hover {
-    border-color: rgb(96 165 250); /* blue-400 */
-    background-color: rgb(239 246 255); /* blue-50 */
-  }
-
-  :global(.dark) .filepond-wrapper-single:hover {
-    background-color: rgba(30, 58, 138, 0.2); /* blue-900/20 */
-  }
-
-  .filepond-wrapper-single :global(.filepond--root) {
-    height: 100%;
-  }
-
-  .filepond-wrapper-single :global(.filepond--root .filepond--drop-label) {
-    height: 100%;
-    min-height: 0;
-  }
-
-  /* Wide shape specific styling */
-  .filepond-wide {
-    aspect-ratio: 16 / 9;
-  }
-
-  .filepond-wide :global(.filepond--root .filepond--drop-label label) {
-    display: flex;
-    flex-direction: column;
-    align-items: center;
-    justify-content: center;
-    height: 100%;
-    padding-top: 2rem;
-    padding-bottom: 2rem;
-  }
-
-  /* Direct drag-over state for dropzone */
-  .dropzone-drag-over {
-    border-color: rgb(59 130 246); /* blue-500 */
-    background-color: rgb(219 234 254); /* blue-100 */
-  }
-
-  :global(.dark) .dropzone-drag-over {
-    background-color: rgba(30, 58, 138, 0.4); /* blue-900/40 */
-  }
-
-  /* Custom label styling inside FilePond */
-  :global(.filepond-custom-label) {
-    display: flex;
-    flex-direction: column;
-    align-items: center;
-    justify-content: center;
-  }
-
-  /* Cursor for draggable items */
-  .cursor-grab {
-    cursor: grab;
-  }
-
-  .cursor-grab:active {
-    cursor: grabbing;
-  }
-
-  /* SortableJS classes - must be single class names, not space-separated */
-  :global(.sortable-ghost) {
-    opacity: 0.5;
-  }
-
-  :global(.sortable-chosen) {
-    box-shadow: 0 0 0 2px rgb(59 130 246); /* ring-2 ring-blue-500 */
-  }
-
-  :global(.sortable-drag) {
-    cursor: grabbing;
-  }
-</style>
+<script lang="ts">
+  /**
+   * ImageUploader - Unified image upload component
+   *
+   * Supports:
+   * - Single image mode (event posters, venue images)
+   * - Multi-image mode with grid layout (performer photos)
+   * - Optional cropping with aspect ratio selection
+   * - Optional drag-to-reorder for multi-image
+   * - Different shapes: square, wide
+   * - Image compression before upload callback
+   */
+
+  import { browser } from '../../__LIB_ENVIRONMENT__.js';
+  import FilePond, { registerPlugin } from 'svelte-filepond';
+  import FilePondPluginImagePreview from 'filepond-plugin-image-preview';
+  import FilePondPluginImageExifOrientation from 'filepond-plugin-image-exif-orientation';
+  import FilePondPluginFileValidateType from 'filepond-plugin-file-validate-type';
+  import FilePondPluginFileValidateSize from 'filepond-plugin-file-validate-size';
+  import 'filepond/dist/filepond.min.css';
+  import 'filepond-plugin-image-preview/dist/filepond-plugin-image-preview.css';
+
+  import Sortable from 'sortablejs';
+  import CropImage from '../CropImage/CropImage.svelte';
+  import { optimizeImage } from '../../utils/imageOptimizer';
+  import Badge from '../../primitives/Badges/Badge.svelte';
+  import Button from '../../primitives/Button/Button.svelte';
+  import { CloseOutline, ImageOutline, PlusOutline, TrashBinOutline } from '../../primitives/Icons';
+  import { typography } from '../../tokens/typography';
+
+  // Register FilePond plugins once
+  registerPlugin(
+    FilePondPluginImagePreview,
+    FilePondPluginImageExifOrientation,
+    FilePondPluginFileValidateType,
+    FilePondPluginFileValidateSize
+  );
+
+  // Types
+  type Shape = 'square' | 'wide';
+  type AspectRatio = '1:1' | '2:1' | '16:9' | '4:3' | 'free';
+  type Size = 'sm' | 'md' | 'lg';
+
+  /**
+   * Default labels for user-visible strings in ImageUploader.
+   * Consumers can override via the `labels` prop.
+   */
+  const defaultLabels = {
+    uploadPhotoTitle: 'Upload photo',
+    mainBadge: 'Main',
+    replace: 'Replace',
+    delete: 'Delete',
+    removePhoto: 'Remove photo',
+    addPhotoAria: 'Add photo - drag and drop or click to upload',
+    fileTypes: 'JPG, PNG, WebP',
+    uploadedAlt: 'Uploaded',
+    closeModal: 'Close',
+    emptyLabel: 'Drag & drop or click to upload',
+  };
+
+  interface Props {
+    /** Single image or array of images (URLs) */
+    images?: string | string[];
+    /** Maximum number of images (only for multi mode) */
+    maxImages?: number;
+    /** Enable cropping step */
+    enableCrop?: boolean;
+    /** Crop aspect ratio */
+    cropAspectRatio?: AspectRatio;
+    /** Enable drag-to-reorder (only for multi mode) */
+    enableReorder?: boolean;
+    /** Dropzone shape - affects aspect ratio and styling */
+    shape?: Shape;
+    /** Size of image slots: sm (~64px), md (~96px), lg (~200px+) */
+    size?: Size;
+    /** Show "Main" badge on first image (multi mode) */
+    showMainBadge?: boolean;
+    /** Maximum file size (e.g., "10MB") */
+    maxFileSize?: string;
+    /** Accepted file types */
+    acceptedTypes?: string[];
+    /** Label shown when empty */
+    emptyLabel?: string;
+    /** Constraints text shown inside dropzone (e.g., "Max 10MB, 2160px") */
+    constraintsText?: string;
+    /** Helper text shown below dropzone */
+    helperText?: string;
+    /** Callback when image is uploaded - receives File, optionally returns URL
+     * If returns URL: component adds to images (self-managed)
+     * If returns void/null: parent must manage images (controlled) */
+    onUpload?: (file: File) => Promise<string | null | void> | void;
+    /** Callback when image is removed */
+    onRemove?: (index: number) => void;
+    /** Callback when images are reordered - receives new array */
+    onReorder?: (images: string[]) => void;
+    /** Callback when images are reordered - receives indices (for store integration) */
+    onReorderIndices?: (data: { from: number; to: number }) => void;
+    /** Callback when user clicks to set main image (moves to first position) */
+    onSetMain?: (data: { index: number }) => void;
+    /** Callback when images change (single source of truth) */
+    onchange?: (images: string[]) => void;
+    /** Show upload error */
+    error?: string;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Custom class for wrapper */
+    class?: string;
+    /** Override user-visible strings */
+    labels?: Partial<typeof defaultLabels>;
+  }
+
+  let {
+    images = $bindable([]),
+    maxImages = 6,
+    enableCrop = false,
+    cropAspectRatio = '1:1',
+    enableReorder = true,
+    shape = 'square',
+    size = 'md',
+    showMainBadge = true,
+    maxFileSize = '20MB',
+    acceptedTypes = ['image/jpeg', 'image/png', 'image/webp', 'image/heic', 'image/heif'],
+    emptyLabel = undefined,
+    constraintsText = '',
+    helperText = '',
+    onUpload,
+    onRemove,
+    onReorder,
+    onReorderIndices,
+    onSetMain,
+    onchange,
+    error = '',
+    disabled = false,
+    class: className = '',
+    labels: userLabels = {},
+  }: Props = $props();
+
+  let labels = $derived({ ...defaultLabels, ...userLabels });
+  let resolvedEmptyLabel = $derived(emptyLabel ?? labels.emptyLabel);
+
+  // Normalize images to array
+  let imageArray = $derived(
+    Array.isArray(images)
+      ? images.filter(Boolean)
+      : images
+        ? [images]
+        : []
+  );
+
+  // Determine mode based on maxImages
+  let isMultiMode = $derived(maxImages > 1);
+  let canAddMore = $derived(imageArray.length < maxImages);
+
+  // FilePond state
+  let filePondFiles = $state<unknown[]>([]);
+  let filePondInstance = $state<unknown>(undefined);
+  let showFilePondModal = $state(false);
+  let targetSlotIndex = $state<number | null>(null);
+
+  // Crop state
+  let showCropModal = $state(false);
+  let imageForCrop = $state('');
+  let isUploading = $state(false);
+
+  // Reorder state
+  let gridContainer = $state<HTMLDivElement | undefined>(undefined);
+  let sortableInstance: Sortable | null = null;
+  let isDragging = $state(false);
+  let gridRenderKey = $state(0);
+
+  // Direct drag-drop state for dropzone
+  let isDropzoneDragOver = $state(false);
+
+  // Native modal dropzone state
+  let isModalDragOver = $state(false);
+  let modalFileInput = $state<HTMLInputElement | undefined>(undefined);
+
+  // Single-mode file input for replace functionality
+  let singleModeFileInput = $state<HTMLInputElement | undefined>(undefined);
+
+  // Prevent browser from opening dragged files in new tab
+  // This MUST be at document level to intercept before browser default behavior
+  $effect(() => {
+    if (!browser) return;
+
+    const preventBrowserDefault = (e: DragEvent) => {
+      // Only prevent if it's a file drag (not text selection, etc.)
+      if (e.dataTransfer?.types?.includes('Files')) {
+        e.preventDefault();
+      }
+    };
+
+    window.addEventListener('dragover', preventBrowserDefault, true);
+    window.addEventListener('drop', preventBrowserDefault, true);
+
+    return () => {
+      window.removeEventListener('dragover', preventBrowserDefault, true);
+      window.removeEventListener('drop', preventBrowserDefault, true);
+    };
+  });
+
+  // Shape to aspect ratio mapping
+  const shapeAspects: Record<Shape, string> = {
+    square: 'aspect-square',
+    wide: 'aspect-video',
+  };
+
+  // Size configuration - layout classes, slot width, and element sizes
+  const sizeConfig: Record<Size, { containerClass: string; slotClass: string; iconClass: string; badgeSize: 'small' | 'medium'; removeSize: string }> = {
+    sm: {
+      containerClass: 'flex flex-wrap gap-1.5',
+      slotClass: 'w-16 h-16',  // 64px fixed
+      iconClass: 'w-4 h-4',
+      badgeSize: 'small',
+      removeSize: 'w-4 h-4',
+    },
+    md: {
+      containerClass: 'flex flex-wrap gap-2',
+      slotClass: 'w-24 h-24', // 96px fixed
+      iconClass: 'w-5 h-5',
+      badgeSize: 'small',
+      removeSize: 'w-5 h-5',
+    },
+    lg: {
+      containerClass: 'grid grid-cols-3 gap-4',
+      slotClass: '', // Let grid control width (uses aspect-square)
+      iconClass: 'w-8 h-8',
+      badgeSize: 'medium',
+      removeSize: 'w-6 h-6',
+    },
+  };
+
+  // Get current size config
+  let currentSizeConfig = $derived(sizeConfig[size]);
+
+  // Crop aspect ratio to number
+  const aspectRatioValues: Record<AspectRatio, number> = {
+    '1:1': 1,
+    '2:1': 2,
+    '16:9': 16 / 9,
+    '4:3': 4 / 3,
+    'free': 0,
+  };
+
+  // FilePond options
+  const filePondOptions = $derived({
+    allowMultiple: false,
+    maxFiles: 1,
+    acceptedFileTypes: acceptedTypes,
+    maxFileSize: maxFileSize,
+    // Drag-drop configuration
+    allowDrop: true,
+    dropOnPage: false, // Only accept drops on the FilePond element
+    dropOnElement: true,
+    labelIdle: `
+      <div class="filepond-custom-label">
+        <svg class="w-8 h-8 mb-5 text-gray-400 dark:text-gray-500" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 4v16m8-8H4" />
+        </svg>
+        <span class="text-sm font-medium text-gray-600 dark:text-gray-300">${resolvedEmptyLabel}</span>
+        <span class="text-[11px] text-gray-400 dark:text-gray-500 mt-2 block">${labels.fileTypes}</span>
+        ${constraintsText ? `<span class="text-[10px] text-gray-400/50 dark:text-gray-500/50 mt-1 block">${constraintsText}</span>` : ''}
+      </div>
+    `,
+    credits: false,
+    instantUpload: false,
+    allowRevert: true,
+    allowProcess: false,
+    imagePreviewHeight: shape === 'wide' ? 150 : 200,
+    stylePanelLayout: 'compact',
+    stylePanelAspectRatio: shape === 'wide' ? '16:9' : '1:1',
+  });
+
+  // Handle FilePond file add
+  function handleFilePondAddFile(err: unknown, fileItem: unknown) {
+    if (err) {
+      console.error('FilePond error:', err);
+      return;
+    }
+
+    const item = fileItem as { file: File } | undefined;
+    const file = item?.file;
+    if (!file) return;
+
+    if (enableCrop) {
+      // Show crop modal
+      const objectUrl = URL.createObjectURL(file);
+      imageForCrop = objectUrl;
+      showCropModal = true;
+    } else {
+      // Optimize then upload
+      optimizeImage(file).then((optimizedFile) => {
+        handleUpload(optimizedFile);
+      });
+    }
+
+    // Clear FilePond
+    setTimeout(() => {
+      if (filePondInstance && typeof (filePondInstance as { removeFiles: () => void }).removeFiles === 'function') {
+        (filePondInstance as { removeFiles: () => void }).removeFiles();
+      }
+    }, 100);
+
+    showFilePondModal = false;
+  }
+
+  // Handle crop save
+  async function handleCropSave(croppedFile: File) {
+    showCropModal = false;
+    if (imageForCrop.startsWith('blob:')) {
+      URL.revokeObjectURL(imageForCrop);
+    }
+    imageForCrop = '';
+    await handleUpload(croppedFile);
+  }
+
+  // Handle crop cancel
+  function handleCropCancel() {
+    showCropModal = false;
+    if (imageForCrop.startsWith('blob:')) {
+      URL.revokeObjectURL(imageForCrop);
+    }
+    imageForCrop = '';
+  }
+
+  // Handle upload
+  // Supports two modes:
+  // 1. Self-managed: onUpload returns URL, component adds to images
+  // 2. Controlled: onUpload returns void, parent manages images array
+  async function handleUpload(file: File) {
+    if (!onUpload) {
+      console.warn('ImageUploader: onUpload callback not provided');
+      return;
+    }
+
+    isUploading = true;
+
+    try {
+      const result = await onUpload(file);
+
+      // If onUpload returns a URL, component manages adding to images (self-managed mode)
+      // If onUpload returns void/null, parent is expected to manage images (controlled mode)
+      if (typeof result === 'string' && result) {
+        const url = result;
+        const newImages = [...imageArray];
+        if (targetSlotIndex !== null && targetSlotIndex < newImages.length) {
+          // Replace existing image
+          newImages[targetSlotIndex] = url;
+        } else {
+          // Add new image
+          newImages.push(url);
+        }
+
+        // Update images and notify
+        if (Array.isArray(images)) {
+          images = newImages;
+        } else {
+          images = newImages[0] || '';
+        }
+        onchange?.(newImages);
+      }
+      // If result is void/null/undefined, parent handles adding to images
+    } catch (err) {
+      console.error('Upload failed:', err);
+    } finally {
+      isUploading = false;
+      targetSlotIndex = null;
+    }
+  }
+
+  // Handle remove
+  // In controlled mode (onReorderIndices provided), just fire callback
+  // In self-managed mode, update images internally
+  function handleRemoveImage(index: number) {
+    // Always fire the callback
+    onRemove?.(index);
+
+    // Only manage state internally if not in controlled mode
+    if (!onReorderIndices) {
+      const newImages = [...imageArray];
+      newImages.splice(index, 1);
+
+      if (Array.isArray(images)) {
+        images = newImages;
+      } else {
+        images = newImages[0] || '';
+      }
+
+      onchange?.(newImages);
+    }
+
+    gridRenderKey++;
+  }
+
+  // Open upload modal/dropzone
+  function openUploadModal(slotIndex?: number) {
+    if (disabled) return;
+    targetSlotIndex = slotIndex ?? null;
+    if (isMultiMode) {
+      showFilePondModal = true;
+    }
+  }
+
+  // Handle direct drag-drop on dropzone (bypasses modal)
+  function handleDropzoneDragOver(e: DragEvent) {
+    e.preventDefault();
+    e.stopPropagation();
+    if (disabled || !canAddMore) return;
+    isDropzoneDragOver = true;
+  }
+
+  function handleDropzoneDragLeave(e: DragEvent) {
+    e.preventDefault();
+    e.stopPropagation();
+    isDropzoneDragOver = false;
+  }
+
+  function handleDropzoneDrop(e: DragEvent, slotIndex?: number) {
+    e.preventDefault();
+    e.stopPropagation();
+    isDropzoneDragOver = false;
+
+    if (disabled || !canAddMore) return;
+
+    const files = e.dataTransfer?.files;
+    if (!files || files.length === 0) return;
+
+    const file = files[0];
+
+    // Check if it's an accepted image type
+    if (!acceptedTypes.some(type => file.type === type || type.includes('*'))) {
+      console.warn('File type not accepted:', file.type);
+      return;
+    }
+
+    targetSlotIndex = slotIndex ?? null;
+
+    if (enableCrop) {
+      // Show crop modal
+      const objectUrl = URL.createObjectURL(file);
+      imageForCrop = objectUrl;
+      showCropModal = true;
+    } else {
+      // Optimize then upload
+      optimizeImage(file).then((optimizedFile) => {
+        handleUpload(optimizedFile);
+      });
+    }
+  }
+
+  // Handle modal dropzone drop
+  function handleModalDrop(e: DragEvent) {
+    e.preventDefault();
+    e.stopPropagation();
+    isModalDragOver = false;
+    showFilePondModal = false;
+
+    if (disabled || !canAddMore) return;
+
+    const files = e.dataTransfer?.files;
+    if (!files || files.length === 0) return;
+
+    const file = files[0];
+
+    // Check if it's an accepted image type
+    if (!acceptedTypes.some(type => file.type === type || type.includes('*'))) {
+      console.warn('File type not accepted:', file.type);
+      return;
+    }
+
+    if (enableCrop) {
+      const objectUrl = URL.createObjectURL(file);
+      imageForCrop = objectUrl;
+      showCropModal = true;
+    } else {
+      optimizeImage(file).then((optimizedFile) => {
+        handleUpload(optimizedFile);
+      });
+    }
+  }
+
+  // Handle modal file input selection
+  function handleModalFileSelect(e: Event) {
+    const input = e.target as HTMLInputElement;
+    const file = input?.files?.[0];
+    if (!file) return;
+
+    showFilePondModal = false;
+
+    if (enableCrop) {
+      const objectUrl = URL.createObjectURL(file);
+      imageForCrop = objectUrl;
+      showCropModal = true;
+    } else {
+      optimizeImage(file).then((optimizedFile) => {
+        handleUpload(optimizedFile);
+      });
+    }
+
+    // Clear input for next selection
+    input.value = '';
+  }
+
+  // Handle single-mode file input selection (for replace)
+  function handleSingleModeFileSelect(e: Event) {
+    const input = e.target as HTMLInputElement;
+    const file = input?.files?.[0];
+    if (!file) return;
+
+    targetSlotIndex = 0; // Replace the existing image
+
+    if (enableCrop) {
+      const objectUrl = URL.createObjectURL(file);
+      imageForCrop = objectUrl;
+      showCropModal = true;
+    } else {
+      optimizeImage(file).then((optimizedFile) => {
+        handleUpload(optimizedFile);
+      });
+    }
+
+    // Clear input for next selection
+    input.value = '';
+  }
+
+  // Initialize sortable for multi-image grid
+  function initSortable() {
+    if (!browser || !gridContainer || !enableReorder || !isMultiMode) return;
+
+    if (sortableInstance) {
+      sortableInstance.destroy();
+    }
+
+    sortableInstance = new Sortable(gridContainer, {
+      animation: 200,
+      ghostClass: 'sortable-ghost',
+      chosenClass: 'sortable-chosen',
+      dragClass: 'sortable-drag',
+      delay: 150,
+      delayOnTouchOnly: true,
+      touchStartThreshold: 5,
+      filter: '.empty-slot, .remove-btn',
+      preventOnFilter: false,
+      onStart: () => {
+        isDragging = true;
+      },
+      onEnd: (evt) => {
+        isDragging = false;
+        const { oldIndex, newIndex } = evt;
+        if (oldIndex === undefined || newIndex === undefined || oldIndex === newIndex) return;
+
+        // Fire index-based callback for store integration (controlled mode)
+        onReorderIndices?.({ from: oldIndex, to: newIndex });
+
+        // For self-managed mode, update images internally
+        if (!onReorderIndices) {
+          const newImages = [...imageArray];
+          const [moved] = newImages.splice(oldIndex, 1);
+          newImages.splice(newIndex, 0, moved);
+
+          if (Array.isArray(images)) {
+            images = newImages;
+          }
+
+          onReorder?.(newImages);
+          onchange?.(newImages);
+        }
+
+        gridRenderKey++;
+
+        // Re-init after state update
+        if (sortableInstance) {
+          sortableInstance.destroy();
+          sortableInstance = null;
+        }
+      },
+    });
+  }
+
+  // Setup sortable on mount and when images change
+  $effect(() => {
+    if (browser && gridContainer && !isDragging && isMultiMode && enableReorder) {
+      // Use setTimeout to ensure DOM is ready
+      setTimeout(initSortable, 0);
+    }
+  });
+
+  // Cleanup
+  $effect(() => {
+    return () => {
+      if (sortableInstance) {
+        sortableInstance.destroy();
+      }
+    };
+  });
+
+  // Generate slots with progressive disclosure
+  // Only show filled images + 1 empty slot (up to maxImages)
+  let slots = $derived.by(() => {
+    const slotCount = Math.min(imageArray.length + 1, maxImages);
+    return Array.from({ length: slotCount }, (_, i) => ({
+      id: `slot-${i}`,
+      image: imageArray[i] || null,
+      isNext: i === imageArray.length,
+    }));
+  });
+</script>
+
+
+<!-- Single Image Mode -->
+{#if !isMultiMode}
+  <div class="image-uploader-single {className}">
+    {#if imageArray.length > 0}
+      <!-- Show existing image with remove option -->
+      <div class="relative {shapeAspects[shape]} bg-gray-100 dark:bg-gray-800 rounded-xl overflow-hidden group">
+        <img
+          src={imageArray[0]}
+          alt={labels.uploadedAlt}
+          class="w-full h-full object-contain"
+        />
+        {#if !disabled}
+          <div class="absolute inset-0 bg-black/50 opacity-0 group-hover:opacity-100 transition-opacity flex items-center justify-center gap-3">
+            <Button
+              variant="default"
+              size="sm"
+              onclick={() => singleModeFileInput?.click()}
+            >
+              <ImageOutline class="w-4 h-4 mr-1.5" />
+              {labels.replace}
+            </Button>
+            <Button
+              variant="red"
+              size="sm"
+              onclick={() => handleRemoveImage(0)}
+            >
+              <TrashBinOutline class="w-4 h-4 mr-1.5" />
+              {labels.delete}
+            </Button>
+          </div>
+          <!-- Hidden file input for replace -->
+          <input
+            bind:this={singleModeFileInput}
+            type="file"
+            accept={acceptedTypes.join(',')}
+            class="hidden"
+            data-testid="image-upload-input"
+            onchange={handleSingleModeFileSelect}
+          />
+        {/if}
+      </div>
+    {:else}
+      <!-- Empty dropzone with direct drag-drop support -->
+      <div
+        class="{shapeAspects[shape]} filepond-wrapper-single rounded-xl {shape === 'wide' ? 'filepond-wide' : ''}
+          {isDropzoneDragOver ? 'dropzone-drag-over' : ''}"
+        role="button"
+        tabindex="0"
+        ondragover={handleDropzoneDragOver}
+        ondragleave={handleDropzoneDragLeave}
+        ondrop={(e) => handleDropzoneDrop(e, 0)}
+      >
+        <FilePond
+          bind:this={filePondInstance}
+          bind:files={filePondFiles}
+          {...filePondOptions}
+          onaddfile={handleFilePondAddFile}
+        />
+      </div>
+    {/if}
+
+    {#if helperText}
+      <p class={`${typography.smMuted} mt-2`}>{helperText}</p>
+    {/if}
+
+    {#if error}
+      <p class={`${typography.smMuted} text-red-500 mt-2`}>{error}</p>
+    {/if}
+  </div>
+
+<!-- Multi Image Mode (Grid) -->
+{:else}
+  <div class="image-uploader-multi {className}">
+    {#key gridRenderKey}
+      <div
+        bind:this={gridContainer}
+        class="{currentSizeConfig.containerClass}"
+      >
+        {#each slots as slot, index (slot.id)}
+          <div
+            class="relative {size === 'lg' ? shapeAspects[shape] : ''} {currentSizeConfig.slotClass} rounded-lg overflow-hidden"
+            class:cursor-grab={slot.image && enableReorder && !disabled}
+            class:empty-slot={!slot.image}
+            data-slot-id={slot.id}
+          >
+            {#if slot.image}
+              <!-- Filled slot -->
+              <!-- svelte-ignore a11y_click_events_have_key_events -->
+              <!-- svelte-ignore a11y_no_static_element_interactions -->
+              <div
+                class="relative w-full h-full bg-gray-100 dark:bg-gray-800 group"
+                class:cursor-pointer={onSetMain && index !== 0 && !disabled}
+                onclick={() => {
+                  if (onSetMain && index !== 0 && !disabled) {
+                    onSetMain({ index });
+                  }
+                }}
+              >
+                <img
+                  src={slot.image}
+                  alt={labels.uploadedAlt}
+                  class="w-full h-full object-contain pointer-events-none"
+                  draggable="false"
+                />
+                {#if showMainBadge && index === 0}
+                  <div class="absolute bottom-1 left-1 z-10 pointer-events-none">
+                    <Badge variant="info" size={currentSizeConfig.badgeSize}>{labels.mainBadge}</Badge>
+                  </div>
+                {/if}
+                {#if !disabled}
+                  <button
+                    type="button"
+                    class="remove-btn absolute top-1 right-1 {currentSizeConfig.removeSize} bg-white/90 dark:bg-gray-900/90 rounded-full flex items-center justify-center opacity-0 group-hover:opacity-100 transition-opacity hover:bg-white dark:hover:bg-gray-900"
+                    onclick={(e) => { e.stopPropagation(); handleRemoveImage(index); }}
+                    aria-label={labels.removePhoto}
+                  >
+                    <CloseOutline class="w-3 h-3 text-gray-700 dark:text-gray-300" />
+                  </button>
+                {/if}
+              </div>
+            {:else if slot.isNext && canAddMore && !disabled}
+              <!-- Next available slot - dropzone with direct drag-drop support -->
+              <!-- svelte-ignore a11y_no_static_element_interactions -->
+              <div
+                class="w-full h-full border-2 border-dashed rounded-lg transition-colors flex items-center justify-center cursor-pointer
+                  {isDropzoneDragOver
+                    ? 'border-blue-500 bg-blue-100 dark:bg-blue-900/40'
+                    : 'border-gray-300 dark:border-gray-600 bg-gray-50 dark:bg-gray-800 hover:border-blue-400 hover:bg-blue-50 dark:hover:bg-blue-900/20'}"
+                role="button"
+                tabindex="0"
+                onclick={() => openUploadModal(index)}
+                onkeydown={(e) => { if (e.key === 'Enter' || e.key === ' ') openUploadModal(index); }}
+                ondragenter={(e) => { e.preventDefault(); e.stopPropagation(); isDropzoneDragOver = true; }}
+                ondragover={(e) => { e.preventDefault(); e.stopPropagation(); isDropzoneDragOver = true; }}
+                ondragleave={(e) => { e.preventDefault(); e.stopPropagation(); isDropzoneDragOver = false; }}
+                ondrop={(e) => handleDropzoneDrop(e, index)}
+                aria-label={labels.addPhotoAria}
+              >
+                <PlusOutline class={currentSizeConfig.iconClass + ' text-gray-400 dark:text-gray-500'} />
+              </div>
+            {/if}
+          </div>
+        {/each}
+      </div>
+    {/key}
+
+    {#if helperText}
+      <p class={`${typography.smMuted} mt-3`}>{helperText}</p>
+    {/if}
+
+    {#if error}
+      <p class={`${typography.smMuted} text-red-500 mt-2`}>{error}</p>
+    {/if}
+  </div>
+
+  <!-- Upload Modal for multi-image (native dropzone - more reliable than FilePond) -->
+  {#if showFilePondModal}
+    <!-- svelte-ignore a11y_click_events_have_key_events -->
+    <!-- svelte-ignore a11y_no_static_element_interactions -->
+    <div
+      class="fixed inset-0 z-50 flex items-center justify-center bg-gray-900/50 dark:bg-gray-900/80 p-4"
+      onclick={() => (showFilePondModal = false)}
+      ondragover={(e) => e.preventDefault()}
+      ondrop={(e) => e.preventDefault()}
+    >
+      <!-- svelte-ignore a11y_click_events_have_key_events -->
+      <!-- svelte-ignore a11y_no_static_element_interactions -->
+      <div
+        class="bg-white dark:bg-gray-800 rounded-xl shadow-xl w-full max-w-md overflow-hidden"
+        onclick={(e) => e.stopPropagation()}
+      >
+        <div class="flex items-center justify-between p-4 border-b border-gray-200 dark:border-gray-700">
+          <h3 class={typography.h3}>{labels.uploadPhotoTitle}</h3>
+          <button
+            type="button"
+            class="p-1.5 text-gray-400 hover:text-gray-600 dark:hover:text-gray-300 transition-colors"
+            onclick={() => (showFilePondModal = false)}
+            aria-label={labels.closeModal}
+          >
+            <CloseOutline class="w-5 h-5" />
+          </button>
+        </div>
+        <div class="p-4">
+          <!-- Native dropzone with file input -->
+          <div
+            class="dropzone-native border-2 border-dashed rounded-lg transition-all duration-200 min-h-[200px] flex flex-col items-center justify-center cursor-pointer
+              {isModalDragOver
+                ? 'border-blue-500 bg-blue-50 dark:bg-blue-900/30'
+                : 'border-gray-300 dark:border-gray-600 bg-gray-50 dark:bg-gray-800 hover:border-blue-400 hover:bg-blue-50/50 dark:hover:bg-blue-900/20'}"
+            role="button"
+            tabindex="0"
+            onclick={() => modalFileInput?.click()}
+            onkeydown={(e) => { if (e.key === 'Enter' || e.key === ' ') modalFileInput?.click(); }}
+            ondragenter={(e) => { e.preventDefault(); e.stopPropagation(); isModalDragOver = true; }}
+            ondragover={(e) => { e.preventDefault(); e.stopPropagation(); isModalDragOver = true; }}
+            ondragleave={(e) => { e.preventDefault(); e.stopPropagation(); isModalDragOver = false; }}
+            ondrop={(e) => handleModalDrop(e)}
+          >
+            <PlusOutline class="w-8 h-8 mb-2 text-gray-400" />
+            <span class={typography.smMuted}>{resolvedEmptyLabel}</span>
+            <span class={`${typography.xsMuted} mt-1`}>{labels.fileTypes}</span>
+          </div>
+          <input
+            bind:this={modalFileInput}
+            type="file"
+            accept={acceptedTypes.join(',')}
+            class="hidden"
+            data-testid="image-upload-modal-input"
+            onchange={handleModalFileSelect}
+          />
+        </div>
+      </div>
+    </div>
+  {/if}
+{/if}
+
+<!-- Crop Modal -->
+{#if enableCrop}
+  <CropImage
+    bind:showModal={showCropModal}
+    imageSrc={imageForCrop}
+    onSave={handleCropSave}
+    onCancel={handleCropCancel}
+    isUploadingImage={isUploading}
+  />
+{/if}
+
+<style>
+  /* FilePond customizations */
+  :global(.filepond-wrapper .filepond--root) {
+    font-family: inherit;
+    min-height: 180px;
+  }
+
+  :global(.filepond-wrapper .filepond--panel-root) {
+    background-color: transparent;
+  }
+
+  :global(.filepond-wrapper .filepond--drop-label) {
+    color: inherit;
+    min-height: 180px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+
+  /* Note: FilePond dark mode is handled via runtime JS injection
+     because Svelte's scoped :global() can't reliably override
+     FilePond's CSS that loads from node_modules */
+
+  :global(.filepond-wrapper .filepond--drop-label label) {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    width: 100%;
+    height: 100%;
+    cursor: pointer;
+  }
+
+  :global(.filepond-wrapper .filepond--label-action) {
+    text-decoration: none;
+    color: inherit;
+  }
+
+  /* FilePond drag hover state */
+  :global(.filepond-wrapper .filepond--root[data-hopper-state="drag-over"]) {
+    border-color: rgb(59 130 246); /* blue-500 */
+    background-color: rgb(239 246 255); /* blue-50 */
+  }
+
+  :global(.dark .filepond-wrapper .filepond--root[data-hopper-state="drag-over"]) {
+    background-color: rgba(30, 58, 138, 0.3); /* blue-900/30 */
+  }
+
+  :global(.filepond-wrapper .filepond--root[data-hopper-state="drag-over"] .filepond--panel-root) {
+    border-color: rgb(59 130 246); /* blue-500 */
+  }
+
+  /* Modal FilePond styling */
+  :global(.filepond-wrapper) {
+    border: 2px dashed rgb(209 213 219); /* gray-300 */
+    border-radius: 0.5rem; /* rounded-lg */
+    background-color: rgb(249 250 251); /* gray-50 */
+    transition-property: color, background-color, border-color;
+    transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+    transition-duration: 150ms;
+  }
+
+  :global(.dark .filepond-wrapper) {
+    border-color: rgb(75 85 99); /* gray-600 */
+    background-color: rgb(31 41 55); /* gray-800 */
+  }
+
+  :global(.filepond-wrapper:hover) {
+    border-color: rgb(96 165 250); /* blue-400 */
+  }
+
+  /* Single mode dropzone styling */
+  .filepond-wrapper-single {
+    border: 2px dashed rgb(209 213 219); /* gray-300 */
+    background-color: rgb(249 250 251); /* gray-50 */
+    transition-property: color, background-color, border-color;
+    transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+    transition-duration: 150ms;
+  }
+
+  :global(.dark) .filepond-wrapper-single {
+    border-color: rgb(75 85 99); /* gray-600 */
+    background-color: rgb(31 41 55); /* gray-800 */
+  }
+
+  .filepond-wrapper-single:hover {
+    border-color: rgb(96 165 250); /* blue-400 */
+    background-color: rgb(239 246 255); /* blue-50 */
+  }
+
+  :global(.dark) .filepond-wrapper-single:hover {
+    background-color: rgba(30, 58, 138, 0.2); /* blue-900/20 */
+  }
+
+  .filepond-wrapper-single :global(.filepond--root) {
+    height: 100%;
+  }
+
+  .filepond-wrapper-single :global(.filepond--root .filepond--drop-label) {
+    height: 100%;
+    min-height: 0;
+  }
+
+  /* Wide shape specific styling */
+  .filepond-wide {
+    aspect-ratio: 16 / 9;
+  }
+
+  .filepond-wide :global(.filepond--root .filepond--drop-label label) {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    height: 100%;
+    padding-top: 2rem;
+    padding-bottom: 2rem;
+  }
+
+  /* Direct drag-over state for dropzone */
+  .dropzone-drag-over {
+    border-color: rgb(59 130 246); /* blue-500 */
+    background-color: rgb(219 234 254); /* blue-100 */
+  }
+
+  :global(.dark) .dropzone-drag-over {
+    background-color: rgba(30, 58, 138, 0.4); /* blue-900/40 */
+  }
+
+  /* Custom label styling inside FilePond */
+  :global(.filepond-custom-label) {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+  }
+
+  /* Cursor for draggable items */
+  .cursor-grab {
+    cursor: grab;
+  }
+
+  .cursor-grab:active {
+    cursor: grabbing;
+  }
+
+  /* SortableJS classes - must be single class names, not space-separated */
+  :global(.sortable-ghost) {
+    opacity: 0.5;
+  }
+
+  :global(.sortable-chosen) {
+    box-shadow: 0 0 0 2px rgb(59 130 246); /* ring-2 ring-blue-500 */
+  }
+
+  :global(.sortable-drag) {
+    cursor: grabbing;
+  }
+</style>