@shipstatic/drop 0.1.5 → 0.1.7

package/dist/index.d.cts

@@ -52,6 +52,26 @@ interface ProcessedFile extends StaticFile {
     /** Upload progress (0-100) - only set during upload */
     progress?: number;
 }
+/**
+ * State machine values for the drop hook
+ */
+type DropStateValue = 'idle' | 'dragging' | 'processing' | 'ready' | 'error';
+/**
+ * Status information with title and details
+ */
+interface DropStatus {
+    title: string;
+    details: string;
+}
+/**
+ * State machine state for the drop hook
+ */
+interface DropState {
+    value: DropStateValue;
+    files: ProcessedFile[];
+    sourceName: string;
+    status: DropStatus | null;
+}
 
 interface DropOptions {
     /** Ship SDK instance (required for validation) */
@@ -64,17 +84,33 @@ interface DropOptions {
     stripPrefix?: boolean;
 }
 interface DropReturn {
-    /** All processed files with their status */
-    files: ProcessedFile[];
-    /** Name of the source (file/folder/ZIP) that was dropped/selected */
-    sourceName: string;
-    /** Current status text */
-    statusText: string;
+    /** Current state of the drop hook */
+    state: DropState;
     /** Whether currently processing files (ZIP extraction, etc.) */
     isProcessing: boolean;
-    /** Last validation error if any */
-    validationError: ClientError | null;
-    /** Process files from drop (resets and replaces existing files) */
+    /** Whether user is currently dragging over the dropzone */
+    isDragging: boolean;
+    /** Get props to spread on dropzone element (handles drag & drop) */
+    getDropzoneProps: () => {
+        onDragOver: (e: React.DragEvent) => void;
+        onDragLeave: (e: React.DragEvent) => void;
+        onDrop: (e: React.DragEvent) => void;
+        onClick: () => void;
+    };
+    /** Get props to spread on hidden file input element */
+    getInputProps: () => {
+        ref: React.RefObject<HTMLInputElement | null>;
+        type: 'file';
+        style: {
+            display: string;
+        };
+        multiple: boolean;
+        webkitdirectory: string;
+        onChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
+    };
+    /** Programmatically trigger file picker */
+    open: () => void;
+    /** Manually process files (for advanced usage) */
     processFiles: (files: File[]) => Promise<void>;
     /** Clear all files and reset state */
     clearAll: () => void;
@@ -88,9 +124,19 @@ interface DropReturn {
     }) => void;
 }
 /**
- * Headless drop hook
- * Handles file processing, ZIP extraction, and validation
- * Does NOT handle uploading - that's the consumer's responsibility
+ * Headless drop hook for file upload workflows
+ *
+ * @example
+ * ```tsx
+ * const drop = useDrop({ ship });
+ *
+ * return (
+ *   <div {...drop.getDropzoneProps()} style={{...}}>
+ *     <input {...drop.getInputProps()} />
+ *     {drop.isDragging ? "📂 Drop" : "📁 Click"}
+ *   </div>
+ * );
+ * ```
  */
 declare function useDrop(options: DropOptions): DropReturn;
 
@@ -157,4 +203,4 @@ declare function normalizePath(path: string): string;
  */
 declare function isZipFile(file: File): boolean;
 
-export { type ClientError, type DropOptions, type DropReturn, FILE_STATUSES, type FileStatus, type ProcessedFile, type ZipExtractionResult, createProcessedFile, extractZipToFiles, formatFileSize, getValidFiles, isZipFile, normalizePath, stripCommonPrefix, useDrop };
+export { type ClientError, type DropOptions, type DropReturn, type DropState, type DropStateValue, type DropStatus, FILE_STATUSES, type FileStatus, type ProcessedFile, type ZipExtractionResult, createProcessedFile, extractZipToFiles, formatFileSize, getValidFiles, isZipFile, normalizePath, stripCommonPrefix, useDrop };

package/dist/index.d.ts

@@ -52,6 +52,26 @@ interface ProcessedFile extends StaticFile {
     /** Upload progress (0-100) - only set during upload */
     progress?: number;
 }
+/**
+ * State machine values for the drop hook
+ */
+type DropStateValue = 'idle' | 'dragging' | 'processing' | 'ready' | 'error';
+/**
+ * Status information with title and details
+ */
+interface DropStatus {
+    title: string;
+    details: string;
+}
+/**
+ * State machine state for the drop hook
+ */
+interface DropState {
+    value: DropStateValue;
+    files: ProcessedFile[];
+    sourceName: string;
+    status: DropStatus | null;
+}
 
 interface DropOptions {
     /** Ship SDK instance (required for validation) */
@@ -64,17 +84,33 @@ interface DropOptions {
     stripPrefix?: boolean;
 }
 interface DropReturn {
-    /** All processed files with their status */
-    files: ProcessedFile[];
-    /** Name of the source (file/folder/ZIP) that was dropped/selected */
-    sourceName: string;
-    /** Current status text */
-    statusText: string;
+    /** Current state of the drop hook */
+    state: DropState;
     /** Whether currently processing files (ZIP extraction, etc.) */
     isProcessing: boolean;
-    /** Last validation error if any */
-    validationError: ClientError | null;
-    /** Process files from drop (resets and replaces existing files) */
+    /** Whether user is currently dragging over the dropzone */
+    isDragging: boolean;
+    /** Get props to spread on dropzone element (handles drag & drop) */
+    getDropzoneProps: () => {
+        onDragOver: (e: React.DragEvent) => void;
+        onDragLeave: (e: React.DragEvent) => void;
+        onDrop: (e: React.DragEvent) => void;
+        onClick: () => void;
+    };
+    /** Get props to spread on hidden file input element */
+    getInputProps: () => {
+        ref: React.RefObject<HTMLInputElement | null>;
+        type: 'file';
+        style: {
+            display: string;
+        };
+        multiple: boolean;
+        webkitdirectory: string;
+        onChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
+    };
+    /** Programmatically trigger file picker */
+    open: () => void;
+    /** Manually process files (for advanced usage) */
     processFiles: (files: File[]) => Promise<void>;
     /** Clear all files and reset state */
     clearAll: () => void;
@@ -88,9 +124,19 @@ interface DropReturn {
     }) => void;
 }
 /**
- * Headless drop hook
- * Handles file processing, ZIP extraction, and validation
- * Does NOT handle uploading - that's the consumer's responsibility
+ * Headless drop hook for file upload workflows
+ *
+ * @example
+ * ```tsx
+ * const drop = useDrop({ ship });
+ *
+ * return (
+ *   <div {...drop.getDropzoneProps()} style={{...}}>
+ *     <input {...drop.getInputProps()} />
+ *     {drop.isDragging ? "📂 Drop" : "📁 Click"}
+ *   </div>
+ * );
+ * ```
  */
 declare function useDrop(options: DropOptions): DropReturn;
 
@@ -157,4 +203,4 @@ declare function normalizePath(path: string): string;
  */
 declare function isZipFile(file: File): boolean;
 
-export { type ClientError, type DropOptions, type DropReturn, FILE_STATUSES, type FileStatus, type ProcessedFile, type ZipExtractionResult, createProcessedFile, extractZipToFiles, formatFileSize, getValidFiles, isZipFile, normalizePath, stripCommonPrefix, useDrop };
+export { type ClientError, type DropOptions, type DropReturn, type DropState, type DropStateValue, type DropStatus, FILE_STATUSES, type FileStatus, type ProcessedFile, type ZipExtractionResult, createProcessedFile, extractZipToFiles, formatFileSize, getValidFiles, isZipFile, normalizePath, stripCommonPrefix, useDrop };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { useState, useRef, useCallback } from 'react';
+import { useState, useRef, useMemo, useCallback } from 'react';
 import { formatFileSize as formatFileSize$1, getValidFiles as getValidFiles$1, filterJunk, validateFiles } from '@shipstatic/ship';
 
 var __create = Object.create;
@@ -11832,6 +11832,38 @@ function stripCommonPrefix(files) {
     path: f.path.startsWith(prefix) ? f.path.slice(prefix.length) : f.path
   }));
 }
+async function traverseFileTree(entry, files, currentPath = "") {
+  if (entry.isFile) {
+    const file = await new Promise((resolve, reject) => {
+      entry.file(resolve, reject);
+    });
+    const relativePath = currentPath ? `${currentPath}/${file.name}` : file.name;
+    Object.defineProperty(file, "webkitRelativePath", {
+      value: relativePath,
+      writable: false
+    });
+    files.push(file);
+  } else if (entry.isDirectory) {
+    const dirReader = entry.createReader();
+    let allEntries = [];
+    const readEntriesBatch = async () => {
+      const batch = await new Promise(
+        (resolve, reject) => {
+          dirReader.readEntries(resolve, reject);
+        }
+      );
+      if (batch.length > 0) {
+        allEntries = allEntries.concat(batch);
+        await readEntriesBatch();
+      }
+    };
+    await readEntriesBatch();
+    for (const childEntry of allEntries) {
+      const entryPath = childEntry.isDirectory ? currentPath ? `${currentPath}/${childEntry.name}` : childEntry.name : currentPath;
+      await traverseFileTree(childEntry, files, entryPath);
+    }
+  }
+}
 function useDrop(options) {
   const {
     ship,
@@ -11839,26 +11871,32 @@ function useDrop(options) {
     onFilesReady,
     stripPrefix = true
   } = options;
-  const [files, setFiles] = useState([]);
-  const [sourceName, setSourceName] = useState("");
-  const [statusText, setStatusText] = useState("");
-  const [isProcessing, setIsProcessing] = useState(false);
-  const [validationError, setValidationError] = useState(null);
+  const initialState = {
+    value: "idle",
+    files: [],
+    sourceName: "",
+    status: null
+  };
+  const [state, setState] = useState(initialState);
   const isProcessingRef = useRef(false);
+  const inputRef = useRef(null);
+  const isProcessing = useMemo(() => state.value === "processing", [state.value]);
+  const isDragging = useMemo(() => state.value === "dragging", [state.value]);
   const processFiles = useCallback(async (newFiles) => {
     if (isProcessingRef.current) {
       console.warn("File processing already in progress. Ignoring duplicate call.");
       return;
     }
     if (!newFiles || newFiles.length === 0) {
-      setStatusText("No files selected.");
       return;
     }
     isProcessingRef.current = true;
-    setIsProcessing(true);
-    setFiles([]);
-    setValidationError(null);
-    setStatusText("Processing files...");
+    setState({
+      value: "processing",
+      files: [],
+      sourceName: "",
+      status: { title: "Processing...", details: "Validating and preparing files." }
+    });
     try {
       let detectedSourceName = "";
       if (newFiles.length === 1 && isZipFile(newFiles[0])) {
@@ -11871,12 +11909,14 @@ function useDrop(options) {
           detectedSourceName = newFiles[0].name;
         }
       }
-      setSourceName(detectedSourceName);
       const allFiles = [];
       const shouldExtractZip = newFiles.length === 1 && isZipFile(newFiles[0]);
       if (shouldExtractZip) {
         const zipFile = newFiles[0];
-        setStatusText(`Extracting ${zipFile.name}...`);
+        setState((prev) => ({
+          ...prev,
+          status: { title: "Extracting...", details: `Extracting ${zipFile.name}...` }
+        }));
         const { files: extractedFiles, errors } = await extractZipToFiles(zipFile);
         if (errors.length > 0) {
           console.warn("ZIP extraction errors:", errors);
@@ -11892,29 +11932,44 @@ function useDrop(options) {
       const filePaths = allFiles.map(getFilePath);
       const validPaths = new Set(filterJunk(filePaths));
       const cleanFiles = allFiles.filter((f) => validPaths.has(getFilePath(f)));
-      setStatusText("Processing files...");
+      setState((prev) => ({
+        ...prev,
+        status: { title: "Processing...", details: "Processing files..." }
+      }));
       const processedFiles = await Promise.all(
         cleanFiles.map((file) => createProcessedFile(file))
       );
       const finalFiles = stripPrefix ? stripCommonPrefix(processedFiles) : processedFiles;
       const config = await ship.getConfig();
       const validation = validateFiles(finalFiles, config);
-      setFiles(validation.files);
-      setValidationError(validation.error);
       if (validation.error) {
-        setStatusText(validation.error.details);
+        setState({
+          value: "error",
+          files: validation.files,
+          sourceName: detectedSourceName,
+          status: { title: validation.error.error, details: validation.error.details }
+        });
         onValidationError?.(validation.error);
       } else if (validation.validFiles.length > 0) {
-        setStatusText(`${validation.validFiles.length} file(s) ready.`);
+        setState({
+          value: "ready",
+          files: validation.files,
+          sourceName: detectedSourceName,
+          status: { title: "Ready", details: `${validation.validFiles.length} file(s) are ready.` }
+        });
         onFilesReady?.(validation.validFiles);
       } else {
         const noValidError = {
           error: "No Valid Files",
-          details: "No files are valid for upload after processing.",
+          details: "None of the provided files could be processed.",
           isClientError: true
         };
-        setStatusText(noValidError.details);
-        setValidationError(noValidError);
+        setState({
+          value: "error",
+          files: validation.files,
+          sourceName: detectedSourceName,
+          status: { title: noValidError.error, details: noValidError.details }
+        });
         onValidationError?.(noValidError);
       }
     } catch (error) {
@@ -11923,38 +11978,112 @@ function useDrop(options) {
         details: `Failed to process files: ${error instanceof Error ? error.message : String(error)}`,
         isClientError: true
       };
-      setStatusText(processingError.details);
-      setValidationError(processingError);
+      setState((prev) => ({
+        ...prev,
+        value: "error",
+        status: { title: processingError.error, details: processingError.details }
+      }));
       onValidationError?.(processingError);
     } finally {
       isProcessingRef.current = false;
-      setIsProcessing(false);
     }
   }, [ship, onValidationError, onFilesReady, stripPrefix]);
   const clearAll = useCallback(() => {
-    setFiles([]);
-    setSourceName("");
-    setStatusText("");
-    setValidationError(null);
+    setState(initialState);
     isProcessingRef.current = false;
-    setIsProcessing(false);
   }, []);
   const getValidFilesCallback = useCallback(() => {
-    return getValidFiles(files);
-  }, [files]);
-  const updateFileStatus = useCallback((fileId, state) => {
-    setFiles((prev) => prev.map(
-      (file) => file.id === fileId ? { ...file, ...state } : file
-    ));
+    return getValidFiles(state.files);
+  }, [state.files]);
+  const updateFileStatus = useCallback((fileId, fileState) => {
+    setState((prev) => ({
+      ...prev,
+      files: prev.files.map(
+        (file) => file.id === fileId ? { ...file, ...fileState } : file
+      )
+    }));
+  }, []);
+  const handleDragOver = useCallback((e) => {
+    e.preventDefault();
+    setState((prev) => {
+      if (prev.value === "idle" || prev.value === "ready" || prev.value === "error") {
+        return { ...prev, value: "dragging" };
+      }
+      return prev;
+    });
+  }, []);
+  const handleDragLeave = useCallback((e) => {
+    e.preventDefault();
+    setState((prev) => {
+      if (prev.value !== "dragging") return prev;
+      const nextValue = prev.files.length > 0 ? prev.status?.title === "Ready" ? "ready" : "error" : "idle";
+      return { ...prev, value: nextValue };
+    });
+  }, []);
+  const handleDrop = useCallback(async (e) => {
+    e.preventDefault();
+    const items = Array.from(e.dataTransfer.items);
+    const files = [];
+    let hasEntries = false;
+    for (const item of items) {
+      if (item.kind === "file") {
+        const entry = item.webkitGetAsEntry?.();
+        if (entry) {
+          hasEntries = true;
+          await traverseFileTree(
+            entry,
+            files,
+            entry.isDirectory ? entry.name : ""
+          );
+        }
+      }
+    }
+    if (!hasEntries && e.dataTransfer.files.length > 0) {
+      files.push(...Array.from(e.dataTransfer.files));
+    }
+    if (files.length > 0) {
+      await processFiles(files);
+    } else if (state.value === "dragging") {
+      setState((prev) => ({ ...prev, value: "idle" }));
+    }
+  }, [processFiles, state.value]);
+  const handleInputChange = useCallback((e) => {
+    const files = Array.from(e.target.files || []);
+    if (files.length > 0) {
+      processFiles(files);
+    }
+  }, [processFiles]);
+  const open = useCallback(() => {
+    inputRef.current?.click();
   }, []);
+  const getDropzoneProps = useCallback(() => ({
+    onDragOver: handleDragOver,
+    onDragLeave: handleDragLeave,
+    onDrop: handleDrop,
+    onClick: open
+  }), [handleDragOver, handleDragLeave, handleDrop, open]);
+  const getInputProps = useCallback(() => ({
+    ref: inputRef,
+    type: "file",
+    style: { display: "none" },
+    multiple: true,
+    webkitdirectory: "",
+    onChange: handleInputChange
+  }), [handleInputChange]);
   return {
-    files,
-    sourceName,
-    statusText,
+    // State machine
+    state,
+    // Convenience getters (computed from state)
     isProcessing,
-    validationError,
+    isDragging,
+    // Primary API: Prop getters
+    getDropzoneProps,
+    getInputProps,
+    // Actions
+    open,
     processFiles,
     clearAll,
+    // Helpers
     getValidFiles: getValidFilesCallback,
     updateFileStatus
   };