@drawnagency/primitives 0.1.76 → 0.1.78

package/src/components/shell/MediaLibraryModal.tsx

@@ -1,17 +1,27 @@
-import { useState, useRef, useCallback } from "react";
-import { Search, Upload, Trash2 } from "lucide-react";
+import { useState, useRef, useCallback, useMemo, useEffect } from "react";
+import { Search, Upload, Trash2, FolderPlus, FolderInput } from "lucide-react";
 import { cn } from "../../lib/cn";
 import { Button } from "../shared/Button";
 import { UploadRejectionAlert } from "../shared/UploadRejectionAlert";
 import { Select } from "../shared/Select";
-import type { MediaItem, MediaKind } from "../../media/types";
-import { displayFilename, formatFileSize, mimeToExt } from "../../media/utils";
+import type { MediaFolder, MediaItem, MediaKind } from "../../media/types";
+import { displayFilename, displayName, formatFileSize, mimeToExt } from "../../media/utils";
+import {
+  childFolderIds, descendantFolderIds, folderPathIds, folderPathNames, itemFolderId, recursiveItemCounts,
+} from "../../lib/media-folders";
+import { buildMediaDragData } from "../../lib/media-dnd";
+import { useMediaDraggable } from "../../hooks/useMediaFolderDnd";
+import { MediaFolderTree, type MediaFolderDndBindings } from "./MediaFolderTree";
+import { MediaFolderTile } from "./MediaFolderTile";
+import { MediaBreadcrumb } from "./MediaBreadcrumb";
+import { MoveToFolderDialog } from "./MoveToFolderDialog";
+import { collectDroppedFiles, type DroppedFile } from "../../media/folder-drop";
 
 export interface MediaLibraryModalProps {
   mode: "select" | "manage";
   items: MediaItem[];
   onSelect: (id: string) => void;
-  onUpload: (files: File[]) => void;
+  onUpload: (files: File[], targetFolderId?: string | null) => void;
   onDelete: (ids: string[]) => void;
   onAltChange?: (id: string, alt: string) => void;
   referenceCountMap: Record<string, number>;
@@ -24,6 +34,15 @@ export interface MediaLibraryModalProps {
   // client-side size pre-check below, which never reaches the pipeline.
   uploadError?: string | null;
   onDismissUploadError?: () => void;
+  folders?: Record<string, MediaFolder>;
+  onCreateFolder?: (name: string, parentId: string | null) => string;
+  onRenameFolder?: (id: string, name: string) => void;
+  onMoveFolder?: (id: string, parentId: string | null) => void;
+  onDeleteFolder?: (id: string, contents: "move" | "delete") => void;
+  onMoveMedia?: (ids: string[], folderId: string | null) => void;
+  onFolderUpload?: (entries: { file: File; relativePath: string }[], currentFolderId: string | null) => void;
+  uploadNotice?: string | null;
+  onDismissUploadNotice?: () => void;
 }
 
 type KindFilter = "all" | MediaKind;
@@ -42,9 +61,13 @@ function thumbnailSrc(item: MediaItem, localUrls: Record<string, string>): strin
 }
 
 
-function UploadZone({ onUpload }: { onUpload: (files: File[]) => void }) {
+function UploadZone({ onUpload, onFolderUpload }: {
+  onUpload: (files: File[]) => void;
+  onFolderUpload?: (files: DroppedFile[]) => void;
+}) {
   const [dragging, setDragging] = useState(false);
   const inputRef = useRef<HTMLInputElement>(null);
+  const folderInputRef = useRef<HTMLInputElement>(null);
 
   const handleFiles = useCallback(
     (files: FileList | null) => {
@@ -55,42 +78,107 @@ function UploadZone({ onUpload }: { onUpload: (files: File[]) => void }) {
   );
 
   return (
-    <button
-      type="button"
+    <div
+      role="button"
+      tabIndex={0}
       onClick={() => inputRef.current?.click()}
-      onDragOver={(e) => {
-        e.preventDefault();
-        setDragging(true);
+      onKeyDown={(e) => {
+        if (e.key === "Enter" || e.key === " ") { e.preventDefault(); inputRef.current?.click(); }
       }}
+      onDragOver={(e) => { e.preventDefault(); setDragging(true); }}
       onDragLeave={() => setDragging(false)}
       onDrop={(e) => {
         e.preventDefault();
         setDragging(false);
-        handleFiles(e.dataTransfer.files);
+        const flat = e.dataTransfer.files;
+        if (onFolderUpload) {
+          void collectDroppedFiles(e.dataTransfer)
+            .then((dropped) => {
+              if (dropped) onFolderUpload(dropped);
+              else handleFiles(flat);
+            })
+            .catch(() => handleFiles(flat));
+        } else {
+          handleFiles(flat);
+        }
       }}
       className={cn(
         "flex w-full cursor-pointer flex-col items-center justify-center gap-2 rounded-lg border-2 border-dashed px-6 py-8 text-center transition-colors",
-        dragging
-          ? "border-primary bg-primary/5"
-          : "border-base-200 hover:border-base-300",
+        dragging ? "border-primary bg-primary/5" : "border-base-200 hover:border-base-300",
       )}
     >
       <Upload size={24} className="text-base-contrast-light" />
       <span className="text-sm text-base-contrast-light">
-        Drag &amp; drop files or click to browse
+        {onFolderUpload
+          ? "Drag & drop files or folders, or click to browse"
+          : "Drag & drop files or click to browse"}
       </span>
+      {onFolderUpload && (
+        <button
+          type="button"
+          onClick={(e) => { e.stopPropagation(); folderInputRef.current?.click(); }}
+          // Enter/Space keydown bubbles to the zone root BEFORE the button's
+          // synthetic click fires — stop it so the zone doesn't also open
+          // the flat file picker (see the matching chevron fix in
+          // MediaFolderTree.tsx).
+          onKeyDown={(e) => { if (e.key === "Enter" || e.key === " ") e.stopPropagation(); }}
+          className="text-xs text-primary underline-offset-2 hover:underline"
+        >
+          Upload a folder
+        </button>
+      )}
+      {/* Programmatic .click() on these hidden inputs dispatches a click event
+          that bubbles to the zone's own onClick — without stopPropagation the
+          folder picker would ALSO open the flat picker (only reproducible in a
+          real browser; jsdom surfaces no native choosers). */}
       <input
         ref={inputRef}
         type="file"
         multiple
         accept="image/*,video/*"
         className="hidden"
-        onChange={(e) => {
-          handleFiles(e.target.files);
-          e.target.value = "";
-        }}
+        onClick={(e) => e.stopPropagation()}
+        onChange={(e) => { handleFiles(e.target.files); e.target.value = ""; }}
       />
-    </button>
+      {onFolderUpload && (
+        <input
+          ref={folderInputRef}
+          type="file"
+          multiple
+          className="hidden"
+          onClick={(e) => e.stopPropagation()}
+          {...({ webkitdirectory: "" } as Record<string, string>)}
+          onChange={(e) => {
+            const files = Array.from(e.target.files ?? []);
+            if (files.length > 0) {
+              onFolderUpload(
+                files.map((f) => ({
+                  file: f,
+                  relativePath:
+                    (f as File & { webkitRelativePath?: string }).webkitRelativePath || f.name,
+                })),
+              );
+            }
+            e.target.value = "";
+          }}
+        />
+      )}
+    </div>
+  );
+}
+
+function MediaCard({ item, manage, isSelected, dragIds, onClick, children }: {
+  item: MediaItem; manage: boolean; isSelected: boolean;
+  dragIds: string[]; onClick: () => void; children: React.ReactNode;
+}) {
+  const drag = useMediaDraggable<HTMLDivElement>({
+    enabled: manage,
+    getDragData: () => buildMediaDragData(dragIds),
+  });
+  return (
+    <div ref={drag.ref} className={cn("group flex flex-col gap-1.5", drag.isDragging && "opacity-40")} onClick={onClick}>
+      {children}
+    </div>
   );
 }
 
@@ -107,15 +195,101 @@ export function MediaLibraryModal({
   uploadProgress = {},
   uploadError = null,
   onDismissUploadError,
+  folders = {},
+  onCreateFolder,
+  onRenameFolder,
+  onMoveFolder,
+  onDeleteFolder,
+  onMoveMedia,
+  onFolderUpload,
+  uploadNotice = null,
+  onDismissUploadNotice,
 }: MediaLibraryModalProps) {
   const [search, setSearch] = useState("");
   const [kindFilter, setKindFilter] = useState<KindFilter>("all");
   const [selected, setSelected] = useState<Set<string>>(new Set());
   const [rejectedFiles, setRejectedFiles] = useState<string[]>([]);
 
+  const [currentFolderId, setCurrentFolderId] = useState<string | null>(null);
+  const [expandedIds, setExpandedIds] = useState<Set<string>>(new Set());
+  const [newFolderOpen, setNewFolderOpen] = useState(false);
+  const [newFolderName, setNewFolderName] = useState("");
+  const [showMobileTree, setShowMobileTree] = useState(false);
+  const [moveDialogOpen, setMoveDialogOpen] = useState(false);
+  const [folderToDelete, setFolderToDelete] = useState<string | null>(null);
+
+  const manage = mode === "manage";
+  const filtering = search !== "" || kindFilter !== "all";
+
+  const itemsById = useMemo(
+    () => Object.fromEntries(items.map((i) => [i.id, i])),
+    [items],
+  );
+  const counts = useMemo(() => recursiveItemCounts(folders, items), [folders, items]);
+
+  const folderDeleteInfo = useMemo(() => {
+    if (!folderToDelete || !folders[folderToDelete]) return null;
+    const doomed = descendantFolderIds(folders, folderToDelete);
+    const contained = items.filter((item) => {
+      const fid = itemFolderId(folders, item);
+      return fid !== null && doomed.has(fid);
+    });
+    const inUse = contained.filter((item) => (referenceCountMap[item.id] ?? 0) > 0).length;
+    return { name: folders[folderToDelete].name, count: contained.length, inUse };
+  }, [folderToDelete, folders, items, referenceCountMap]);
+
+  // Fresh state for drop handlers without re-registering dnd targets.
+  const foldersRef = useRef(folders);
+  foldersRef.current = folders;
+  const itemsByIdRef = useRef(itemsById);
+  itemsByIdRef.current = itemsById;
+
+  const dnd: MediaFolderDndBindings | undefined =
+    manage && onMoveMedia
+      ? {
+          foldersRef, itemsByIdRef,
+          onMoveMedia,
+          onMoveFolder: onMoveFolder ?? (() => {}),
+        }
+      : undefined;
+
+  const navigate = useCallback((id: string | null) => {
+    setCurrentFolderId(id);
+    if (id) setExpandedIds((prev) => new Set([...prev, ...folderPathIds(foldersRef.current, id)]));
+  }, []);
+
+  const expand = useCallback((id: string) => {
+    setExpandedIds((prev) => (prev.has(id) ? prev : new Set([...prev, id])));
+  }, []);
+  const toggleExpand = useCallback((id: string) => {
+    setExpandedIds((prev) => {
+      const next = new Set(prev);
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+      return next;
+    });
+  }, []);
+
+  // Current folder deleted (or healed away) -> back to root.
+  useEffect(() => {
+    if (currentFolderId && !folders[currentFolderId]) setCurrentFolderId(null);
+  }, [folders, currentFolderId]);
+
+  const childIds = filtering ? [] : childFolderIds(folders, currentFolderId);
+
+  const commitNewFolder = () => {
+    const name = newFolderName.trim();
+    if (name && onCreateFolder) {
+      onCreateFolder(name, currentFolderId);
+      if (currentFolderId) expand(currentFolderId);
+    }
+    setNewFolderOpen(false);
+    setNewFolderName("");
+  };
+
   const handleUpload = useCallback((files: File[]) => {
     if (!maxFileSize) {
-      onUpload(files);
+      onUpload(files, currentFolderId);
       return;
     }
     const valid: File[] = [];
@@ -132,15 +306,15 @@ export function MediaLibraryModal({
       }
     }
     if (rejected.length > 0) setRejectedFiles(rejected);
-    if (valid.length > 0) onUpload(valid);
-  }, [maxFileSize, onUpload]);
+    if (valid.length > 0) onUpload(valid, currentFolderId);
+  }, [maxFileSize, onUpload, currentFolderId]);
 
   const filtered = items.filter((item) => {
-    const matchesSearch = item.originalName
-      .toLowerCase()
-      .includes(search.toLowerCase());
+    const matchesSearch = displayName(item).toLowerCase().includes(search.toLowerCase());
     const matchesKind = kindFilter === "all" || item.kind === kindFilter;
-    return matchesSearch && matchesKind;
+    if (!matchesSearch || !matchesKind) return false;
+    if (!filtering && itemFolderId(folders, item) !== currentFolderId) return false;
+    return true;
   });
 
   function toggleSelect(id: string) {
@@ -160,9 +334,19 @@ export function MediaLibraryModal({
   const selectedIds = Array.from(selected);
   const totalUsage = selectedIds.reduce((sum, id) => sum + (referenceCountMap[id] ?? 0), 0);
 
+  // The move dialog's no-op target is the selection's folder — not the folder
+  // being viewed (selection survives navigation). Heterogeneous selections have
+  // no single no-op target, so nothing is disabled.
+  const selectionFolderIds = new Set(
+    Array.from(selected).map((id) => (itemsById[id] ? itemFolderId(folders, itemsById[id]) : null)),
+  );
+  const moveDialogCurrentTarget =
+    selectionFolderIds.size === 1 ? Array.from(selectionFolderIds)[0] : undefined;
+
   function handleBatchDelete() {
     if (totalUsage > 0) {
       setConfirmDelete(true);
+      setFolderToDelete(null); // the two delete confirmations are mutually exclusive
       return;
     }
     onDelete(selectedIds);
@@ -176,230 +360,428 @@ export function MediaLibraryModal({
   }
 
   const uploadingHashes = Object.keys(uploadProgress);
+  const folderTreeProps = {
+    folders,
+    counts,
+    totalCount: items.length,
+    currentFolderId,
+    expandedIds,
+    onExpand: expand,
+    onToggleExpand: toggleExpand,
+    dnd,
+  };
 
   return (
-    <div className="flex flex-col gap-4">
-      <UploadZone onUpload={handleUpload} />
-
-      {/* Direct-to-bucket large-video upload progress */}
-      {uploadingHashes.length > 0 && (
-        <div className="space-y-1.5">
-          {uploadingHashes.map((hash) => {
-            const pct = Math.round((uploadProgress[hash] ?? 0) * 100);
-            return (
-              <div key={hash} className="flex items-center gap-2">
-                <span className="shrink-0 text-xs text-base-contrast-light">Uploading video…</span>
-                <div className="h-1.5 flex-1 overflow-hidden rounded-full bg-base-200">
-                  <div
-                    className="h-full rounded-full bg-primary transition-[width]"
-                    style={{ width: `${pct}%` }}
-                  />
-                </div>
-                <span className="w-9 shrink-0 text-right text-xs text-base-contrast-light">{pct}%</span>
-              </div>
-            );
-          })}
-        </div>
-      )}
+    <div className="flex h-full">
+      <div className="hidden w-1/5 min-w-48 shrink-0 overflow-y-auto border-r border-base-200 p-4 md:block">
+        <MediaFolderTree {...folderTreeProps} onNavigate={navigate} />
+      </div>
 
-      {/* Sticky toolbar + confirmation */}
-      <div className="sticky top-[-16px] z-10 -mx-6 space-y-3 bg-base px-6 pb-3 pt-4">
-        <div className="flex items-center gap-2">
-          <div className="relative flex-1">
-            <Search
-              size={14}
-              className="pointer-events-none absolute left-2.5 top-1/2 -translate-y-1/2 text-base-contrast-light"
-            />
-            <input
-              type="text"
-              placeholder="Search media..."
-              value={search}
-              onChange={(e) => setSearch(e.target.value)}
-              className="w-full rounded border border-base-200 bg-base py-1.5 pl-8 pr-3 text-sm text-base-contrast placeholder:text-base-contrast-light focus:outline-none focus:ring-1 focus:ring-primary"
+      {/* Each column carries its own padding (modal body is noPadding) so the
+          scrollbars sit at the pane edges; it doubles as paint room for focus
+          rings inside the scroll clip. */}
+      <div className="flex min-w-0 flex-1 flex-col gap-4 overflow-y-auto p-4">
+        <button
+          type="button"
+          aria-label="Show folders"
+          onClick={() => setShowMobileTree((v) => !v)}
+          className="flex items-center gap-1.5 self-start rounded border border-base-200 px-2.5 py-1.5 text-xs text-base-contrast-light md:hidden"
+        >
+          Folders
+        </button>
+        {showMobileTree && (
+          <div className="rounded-lg border border-base-200 p-2 md:hidden">
+            <MediaFolderTree
+              {...folderTreeProps}
+              onNavigate={(id) => { navigate(id); setShowMobileTree(false); }}
             />
           </div>
+        )}
+
+        <UploadZone
+          onUpload={handleUpload}
+          onFolderUpload={
+            // Folder upload creates folders — a management operation, so it is
+            // manage-mode only. Select mode gets a plain UploadZone (regular
+            // file uploads while picking remain available).
+            manage && onFolderUpload
+              ? (dropped) => {
+                  const valid = dropped.filter(({ file }) => {
+                    const isBucketEligibleVideo = file.type === "video/mp4" || file.type === "video/webm";
+                    return !maxFileSize || file.size <= maxFileSize || isBucketEligibleVideo;
+                  });
+                  const rejected = dropped.length - valid.length;
+                  if (rejected > 0) setRejectedFiles(dropped.filter((d) => !valid.includes(d)).map((d) => d.file.name));
+                  if (valid.length > 0) onFolderUpload(valid, currentFolderId);
+                }
+              : undefined
+          }
+        />
 
-          <Select
-            value={kindFilter}
-            onChange={(v) => setKindFilter(v as KindFilter)}
-            options={[
-              { value: "all", label: "All types" },
-              { value: "image", label: "Images" },
-              { value: "animated", label: "Animated" },
-              { value: "video", label: "Video" },
-            ]}
-            selectClassName="py-1.5 pr-7 pl-2.5"
-          />
-
-          {mode === "manage" && selected.size > 0 && (
-            <Button
-              variant="destructive"
-              size="sm"
-              onClick={handleBatchDelete}
-              className="flex items-center gap-1.5"
-            >
-              <Trash2 size={13} />
-              Delete {selected.size}
-            </Button>
+        {/* Direct-to-bucket large-video upload progress */}
+        {uploadingHashes.length > 0 && (
+          <div className="space-y-1.5">
+            {uploadingHashes.map((hash) => {
+              const pct = Math.round((uploadProgress[hash] ?? 0) * 100);
+              return (
+                <div key={hash} className="flex items-center gap-2">
+                  <span className="shrink-0 text-xs text-base-contrast-light">Uploading video…</span>
+                  <div className="h-1.5 flex-1 overflow-hidden rounded-full bg-base-200">
+                    <div
+                      className="h-full rounded-full bg-primary transition-[width]"
+                      style={{ width: `${pct}%` }}
+                    />
+                  </div>
+                  <span className="w-9 shrink-0 text-right text-xs text-base-contrast-light">{pct}%</span>
+                </div>
+              );
+            })}
+          </div>
+        )}
+
+        {/* Sticky toolbar + confirmation */}
+        {/* -top-4/-mt-4/pt-4 extend the sticky box up through the column's
+            p-4 strip, which scrolled content would otherwise peek through. */}
+        <div
+          className={cn(
+            "sticky -top-4 z-10 -mt-4 space-y-3 bg-base pb-3 pt-4",
+            (moveDialogOpen || newFolderOpen) && "border-b border-base-200",
           )}
-        </div>
+        >
+          <div className="flex items-center gap-2">
+            <div className="relative flex-1">
+              <Search
+                size={14}
+                className="pointer-events-none absolute left-2.5 top-1/2 -translate-y-1/2 text-base-contrast-light"
+              />
+              <input
+                type="text"
+                placeholder="Search media..."
+                value={search}
+                onChange={(e) => setSearch(e.target.value)}
+                className="w-full rounded border border-base-200 bg-base py-1.5 pl-8 pr-3 text-sm text-base-contrast placeholder:text-base-contrast-light focus:outline-none focus:ring-1 focus:ring-primary"
+              />
+            </div>
 
-        {/* Delete confirmation */}
-        {confirmDelete && (
-          <div className="flex flex-col items-center rounded-lg border border-red-200 bg-red-50 px-4 py-3 lg:flex-row lg:justify-between dark:border-red-900/50 dark:bg-red-950/30">
-            <p className="mb-2 text-center text-sm text-red-800 lg:mb-0 lg:text-left dark:text-red-200">
-              Some of these images are being used. Deleting these will remove them from these references.
-            </p>
-            <div className="flex shrink-0 items-center gap-2">
-              <Button variant="secondary" size="sm" onClick={() => setConfirmDelete(false)}>
-                Cancel
+            <Select
+              value={kindFilter}
+              onChange={(v) => setKindFilter(v as KindFilter)}
+              options={[
+                { value: "all", label: "All types" },
+                { value: "image", label: "Images" },
+                { value: "animated", label: "Animated" },
+                { value: "video", label: "Video" },
+              ]}
+              selectClassName="py-1.5 pr-7 pl-2.5"
+            />
+
+            {manage && onCreateFolder && !filtering && (
+              <Button variant="secondary" size="sm" onClick={() => setNewFolderOpen(true)} className="flex items-center gap-1.5">
+                <FolderPlus size={13} />
+                New folder
               </Button>
-              <Button variant="destructive" size="sm" onClick={handleConfirmDelete}>
-                Confirm Delete
+            )}
+
+            {mode === "manage" && selected.size > 0 && onMoveMedia && (
+              <Button variant="secondary" size="sm" onClick={() => setMoveDialogOpen(true)} className="flex items-center gap-1.5">
+                <FolderInput size={13} />
+                Move {selected.size}
               </Button>
-            </div>
+            )}
+
+            {mode === "manage" && selected.size > 0 && (
+              <Button
+                variant="destructive"
+                size="sm"
+                onClick={handleBatchDelete}
+                className="flex items-center gap-1.5"
+              >
+                <Trash2 size={13} />
+                Delete {selected.size}
+              </Button>
+            )}
           </div>
-        )}
 
-        {/* File size rejection alert */}
-        {rejectedFiles.length > 0 && maxFileSize && (
-          <UploadRejectionAlert
-            message={
-              rejectedFiles.length === 1
-                ? `"${rejectedFiles[0]}" exceeds the ${formatFileSize(maxFileSize)} file size limit.`
-                : `${rejectedFiles.length} files exceed the ${formatFileSize(maxFileSize)} file size limit.`
-            }
-            onDismiss={() => setRejectedFiles([])}
-          />
+          {moveDialogOpen && onMoveMedia && (
+            <div>
+              <p className="mb-2 text-sm font-medium text-base-contrast">Move {selected.size} item{selected.size === 1 ? "" : "s"} to…</p>
+              <MoveToFolderDialog
+                folders={folders}
+                currentTarget={moveDialogCurrentTarget}
+                onMove={(target) => { onMoveMedia(Array.from(selected), target); setSelected(new Set()); }}
+                onClose={() => setMoveDialogOpen(false)}
+              />
+            </div>
+          )}
+
+          {newFolderOpen && (
+            <div className="flex items-center gap-2">
+              <input
+                autoFocus
+                placeholder="Folder name"
+                value={newFolderName}
+                onChange={(e) => setNewFolderName(e.target.value)}
+                onKeyDown={(e) => {
+                  if (e.key === "Enter") commitNewFolder();
+                  if (e.key === "Escape") { setNewFolderOpen(false); setNewFolderName(""); }
+                }}
+                className="flex-1 rounded border border-base-200 bg-base px-2 py-1 text-sm text-base-contrast focus:outline-none focus:ring-1 focus:ring-primary"
+              />
+              <Button variant="secondary" size="sm" onClick={() => { setNewFolderOpen(false); setNewFolderName(""); }}>Cancel</Button>
+              <Button variant="primary" size="sm" onClick={commitNewFolder}>Create</Button>
+            </div>
+          )}
+
+          {/* Delete confirmation */}
+          {confirmDelete && (
+            <div className="flex flex-col items-center rounded-lg border border-red-200 bg-red-50 px-4 py-3 lg:flex-row lg:justify-between dark:border-red-900/50 dark:bg-red-950/30">
+              <p className="mb-2 text-center text-sm text-red-800 lg:mb-0 lg:text-left dark:text-red-200">
+                Some of these images are being used. Deleting these will remove them from these references.
+              </p>
+              <div className="flex shrink-0 items-center gap-2">
+                <Button variant="secondary" size="sm" onClick={() => setConfirmDelete(false)}>
+                  Cancel
+                </Button>
+                <Button variant="destructive" size="sm" onClick={handleConfirmDelete}>
+                  Confirm Delete
+                </Button>
+              </div>
+            </div>
+          )}
+
+          {folderToDelete && folderDeleteInfo && onDeleteFolder && (
+            <div className="flex flex-col gap-2 rounded-lg border border-red-200 bg-red-50 px-4 py-3 dark:border-red-900/50 dark:bg-red-950/30">
+              <p className="text-sm text-red-800 dark:text-red-200">
+                Delete &ldquo;{folderDeleteInfo.name}&rdquo;? It contains {folderDeleteInfo.count} item{folderDeleteInfo.count === 1 ? "" : "s"}
+                {folderDeleteInfo.inUse > 0 && (
+                  <> — {folderDeleteInfo.inUse === 1 ? "1 is in use" : `${folderDeleteInfo.inUse} are in use`} and will be removed from those sections</>
+                )}
+                .
+              </p>
+              <div className="flex flex-wrap items-center justify-end gap-2">
+                <Button variant="secondary" size="sm" onClick={() => setFolderToDelete(null)}>Cancel</Button>
+                <Button variant="secondary" size="sm"
+                  onClick={() => { onDeleteFolder(folderToDelete, "move"); setFolderToDelete(null); }}>
+                  Move contents to parent
+                </Button>
+                <Button variant="destructive" size="sm"
+                  onClick={() => { onDeleteFolder(folderToDelete, "delete"); setFolderToDelete(null); }}>
+                  Delete {folderDeleteInfo.count} item{folderDeleteInfo.count === 1 ? "" : "s"}
+                </Button>
+              </div>
+            </div>
+          )}
+
+          {/* File size rejection alert */}
+          {rejectedFiles.length > 0 && maxFileSize && (
+            <UploadRejectionAlert
+              message={
+                rejectedFiles.length === 1
+                  ? `"${rejectedFiles[0]}" exceeds the ${formatFileSize(maxFileSize)} file size limit.`
+                  : `${rejectedFiles.length} files exceed the ${formatFileSize(maxFileSize)} file size limit.`
+              }
+              onDismiss={() => setRejectedFiles([])}
+            />
+          )}
+
+          {/* Async upload failure (oversized/disallowed file, upload-intent error,
+              direct-to-bucket PUT failure) — distinct from the client-side check above. */}
+          {uploadError && (
+            <UploadRejectionAlert
+              message={uploadError}
+              onDismiss={() => onDismissUploadError?.()}
+            />
+          )}
+
+          {/* Informational, non-error upload notice (e.g. dedup skip). */}
+          {uploadNotice && (
+            <UploadRejectionAlert
+              message={uploadNotice}
+              onDismiss={() => onDismissUploadNotice?.()}
+            />
+          )}
+        </div>
+
+        {!filtering && (
+          <MediaBreadcrumb folders={folders} currentFolderId={currentFolderId} onNavigate={navigate} dnd={dnd} />
         )}
 
-        {/* Async upload failure (oversized/disallowed file, upload-intent error,
-            direct-to-bucket PUT failure) — distinct from the client-side check above. */}
-        {uploadError && (
-          <UploadRejectionAlert
-            message={uploadError}
-            onDismiss={() => onDismissUploadError?.()}
-          />
+        {childIds.length > 0 && (
+          <div className="grid grid-cols-2 gap-3 sm:grid-cols-3 md:grid-cols-4 lg:grid-cols-5">
+            {childIds.map((fid) => (
+              <MediaFolderTile
+                key={fid}
+                id={fid}
+                name={folders[fid].name}
+                count={counts[fid] ?? 0}
+                onOpen={navigate}
+                manage={manage}
+                onRename={onRenameFolder}
+                onDeleteRequest={
+                  manage && onDeleteFolder
+                    ? (id) => {
+                        const doomed = descendantFolderIds(folders, id);
+                        const hasContents =
+                          items.some((item) => {
+                            const fid = itemFolderId(folders, item);
+                            return fid !== null && doomed.has(fid);
+                          }) || doomed.size > 1;
+                        if (hasContents) {
+                          setFolderToDelete(id);
+                          setConfirmDelete(false); // the two delete confirmations are mutually exclusive
+                        } else onDeleteFolder(id, "move"); // empty: no dialog needed
+                      }
+                    : undefined
+                }
+                dnd={dnd}
+                ariaLabel={`Open folder ${folders[fid].name}`}
+              />
+            ))}
+          </div>
         )}
-      </div>
 
-      {/* Grid */}
-      {filtered.length === 0 ? (
-        <div className="flex flex-col items-center justify-center gap-2 py-12 text-center">
-          <p className="text-sm font-medium text-base-contrast">
-            {items.length === 0 ? "No media uploaded yet" : "No results found"}
-          </p>
-          <p className="text-xs text-base-contrast-light">
-            {items.length === 0
-              ? "Upload files using the drop zone above."
-              : "Try a different search or filter."}
-          </p>
-        </div>
-      ) : (
-        <div className="grid grid-cols-2 gap-3 sm:grid-cols-3 md:grid-cols-4 lg:grid-cols-5">
-          {filtered.map((item) => {
-            const isSelected = selected.has(item.id);
-            const refCount = referenceCountMap[item.id] ?? 0;
-            const usageLabel = refCount === 0 ? "Not used" : `Used ${refCount}x`;
-
-            return (
-              <div
-                key={item.id}
-                className="group flex flex-col gap-1.5"
-                onClick={() => {
-                  if (mode === "select") {
-                    onSelect(item.id);
-                  } else {
-                    toggleSelect(item.id);
-                  }
-                }}
-              >
-                {/* Thumbnail */}
-                <div
-                  className={cn(
-                    "relative aspect-square cursor-pointer overflow-hidden rounded-lg border-2 transition-colors",
-                    mode === "select"
-                      ? "border-transparent hover:border-primary"
-                      : isSelected
-                        ? "border-primary"
-                        : "border-transparent hover:border-base-300",
-                  )}
+        {/* Grid */}
+        {filtered.length === 0 ? (
+          childIds.length === 0 && (
+            <div className="flex flex-col items-center justify-center gap-2 py-12 text-center">
+              <p className="text-sm font-medium text-base-contrast">
+                {!filtering && currentFolderId !== null
+                  ? "This folder is empty"
+                  : items.length === 0
+                    ? "No media uploaded yet"
+                    : "No results found"}
+              </p>
+              <p className="text-xs text-base-contrast-light">
+                {!filtering && currentFolderId !== null
+                  ? "Drag media here or upload into this folder."
+                  : items.length === 0
+                    ? "Upload files using the drop zone above."
+                    : "Try a different search or filter."}
+              </p>
+            </div>
+          )
+        ) : (
+          <div className="grid grid-cols-2 gap-3 sm:grid-cols-3 md:grid-cols-4 lg:grid-cols-5">
+            {filtered.map((item) => {
+              const isSelected = selected.has(item.id);
+              const refCount = referenceCountMap[item.id] ?? 0;
+              const usageLabel = refCount === 0 ? "Not used" : `Used ${refCount}x`;
+              const dragIds = selected.has(item.id) && selected.size > 0 ? Array.from(selected) : [item.id];
+
+              return (
+                <MediaCard
+                  key={item.id}
+                  item={item}
+                  manage={manage}
+                  isSelected={isSelected}
+                  dragIds={dragIds}
+                  onClick={() => {
+                    if (mode === "select") {
+                      onSelect(item.id);
+                    } else {
+                      toggleSelect(item.id);
+                    }
+                  }}
                 >
-                  <div className="h-full w-full bg-base-accent">
-                    {item.kind === "video" ? (
-                      <video
-                        src={thumbnailSrc(item, localUrlMap)}
-                        muted
-                        playsInline
-                        className="h-full w-full object-cover"
-                        onMouseEnter={(e) => e.currentTarget.play().catch(() => {})}
-                        onMouseLeave={(e) => { e.currentTarget.pause(); e.currentTarget.currentTime = 0; }}
-                      />
-                    ) : (
-                      <img
-                        src={thumbnailSrc(item, localUrlMap)}
-                        alt={item.originalName}
-                        className="h-full w-full object-cover"
-                      />
+                  {/* Thumbnail */}
+                  <div
+                    className={cn(
+                      "relative aspect-square cursor-pointer overflow-hidden rounded-lg border-2 transition-colors",
+                      mode === "select"
+                        ? "border-transparent hover:border-primary"
+                        : isSelected
+                          ? "border-primary"
+                          : "border-transparent hover:border-base-300",
                     )}
-                  </div>
-
-                  {/* Selection radio — top-left */}
-                  {mode === "manage" && (
-                    <div className={cn(
-                      "absolute top-1.5 left-1.5 flex h-5 w-5 items-center justify-center rounded-full border-2 transition-colors",
-                      isSelected
-                        ? "border-primary bg-primary"
-                        : "border-white/80 bg-white/40 opacity-0 group-hover:opacity-100",
-                    )}>
-                      {isSelected && (
-                        <div className="h-2 w-2 rounded-full bg-white" />
+                  >
+                    <div className="h-full w-full bg-base-accent">
+                      {item.kind === "video" ? (
+                        <video
+                          src={thumbnailSrc(item, localUrlMap)}
+                          muted
+                          playsInline
+                          className="h-full w-full object-cover"
+                          onMouseEnter={(e) => e.currentTarget.play().catch(() => {})}
+                          onMouseLeave={(e) => { e.currentTarget.pause(); e.currentTarget.currentTime = 0; }}
+                        />
+                      ) : (
+                        <img
+                          src={thumbnailSrc(item, localUrlMap)}
+                          // alt deliberately stays originalName — an accessibility
+                          // fallback description, not a display name.
+                          alt={item.originalName}
+                          // Images are natively draggable — the browser's own image
+                          // drag would hijack the card's pragmatic-dnd draggable.
+                          draggable={false}
+                          className="h-full w-full object-cover"
+                        />
                       )}
                     </div>
-                  )}
-
-                  {/* Usage pill — top-right, visible on hover or when selected */}
-                  {mode === "manage" && (
-                    <div className={cn(
-                      "absolute top-1.5 right-1.5 rounded-full px-2 py-0.5 text-[11px] font-medium transition-opacity",
-                      isSelected
-                        ? "opacity-100"
-                        : "opacity-0 group-hover:opacity-100",
-                      refCount > 0
-                        ? "bg-black/50 text-white"
-                        : "bg-black/50 text-white/70",
-                    )}>
-                      {usageLabel}
-                    </div>
-                  )}
 
-                  {/* Filename overlay — bottom, visible on hover */}
-                  <div className="absolute inset-x-0 bottom-0 bg-gradient-to-t from-black/60 to-transparent px-2 pb-1.5 pt-4 opacity-0 transition-opacity group-hover:opacity-100">
-                    <p className="truncate text-[11px] text-white">
-                      {displayFilename(item.originalName, item.mimeType)}
-                    </p>
+                    {/* Selection radio — top-left */}
+                    {mode === "manage" && (
+                      <div className={cn(
+                        "absolute top-1.5 left-1.5 flex h-5 w-5 items-center justify-center rounded-full border-2 transition-colors",
+                        isSelected
+                          ? "border-primary bg-primary"
+                          : "border-white/80 bg-white/40 opacity-0 group-hover:opacity-100",
+                      )}>
+                        {isSelected && (
+                          <div className="h-2 w-2 rounded-full bg-white" />
+                        )}
+                      </div>
+                    )}
+
+                    {/* Usage pill — top-right, visible on hover or when selected */}
+                    {mode === "manage" && (
+                      <div className={cn(
+                        "absolute top-1.5 right-1.5 rounded-full px-2 py-0.5 text-[11px] font-medium transition-opacity",
+                        isSelected
+                          ? "opacity-100"
+                          : "opacity-0 group-hover:opacity-100",
+                        refCount > 0
+                          ? "bg-black/50 text-white"
+                          : "bg-black/50 text-white/70",
+                      )}>
+                        {usageLabel}
+                      </div>
+                    )}
+
+                    {/* Folder path chip — bottom-left, shown only during global search results */}
+                    {filtering && itemFolderId(folders, item) !== null && (
+                      <div className="absolute bottom-1.5 left-1.5 max-w-[calc(100%-12px)] truncate rounded-full bg-black/50 px-2 py-0.5 text-[11px] text-white">
+                        {folderPathNames(folders, itemFolderId(folders, item) as string).join(" / ")}
+                      </div>
+                    )}
+
+                    {/* Filename overlay — bottom, visible on hover */}
+                    <div className="absolute inset-x-0 bottom-0 bg-gradient-to-t from-black/60 to-transparent px-2 pb-1.5 pt-4 opacity-0 transition-opacity group-hover:opacity-100">
+                      <p className="truncate text-[11px] text-white">
+                        {displayFilename(displayName(item), item.mimeType)}
+                      </p>
+                    </div>
                   </div>
-                </div>
 
-                {/* Alt text below image */}
-                <div className="px-0.5">
-                  <label className="text-[10px] font-medium uppercase leading-none tracking-wide text-base-contrast-light/50">
-                    Alt text
-                  </label>
-                  <textarea
-                    value={item.alt}
-                    placeholder="Describe this image for accessibility"
-                    rows={2}
-                    onClick={(e) => e.stopPropagation()}
-                    onChange={(e) => onAltChange?.(item.id, e.target.value)}
-                    className="w-full resize-none border-0 bg-transparent p-0 text-xs leading-snug text-base-contrast placeholder:text-base-contrast-light/40 focus:outline-none focus:ring-0"
-                  />
-                </div>
-              </div>
-            );
-          })}
-        </div>
-      )}
+                  {/* Alt text below image */}
+                  <div className="px-0.5">
+                    <label className="text-[10px] font-medium uppercase leading-none tracking-wide text-base-contrast-light/50">
+                      Alt text
+                    </label>
+                    <textarea
+                      value={item.alt}
+                      placeholder="Describe this image for accessibility"
+                      rows={2}
+                      onClick={(e) => e.stopPropagation()}
+                      onChange={(e) => onAltChange?.(item.id, e.target.value)}
+                      className="w-full resize-none border-0 bg-transparent p-0 text-xs leading-snug text-base-contrast placeholder:text-base-contrast-light/40 focus:outline-none focus:ring-0"
+                    />
+                  </div>
+                </MediaCard>
+              );
+            })}
+          </div>
+        )}
+      </div>
     </div>
   );
 }