@shipstatic/drop 0.1.6 → 0.1.8

package/README.md

@@ -4,10 +4,26 @@
 
 A focused React hook for preparing files for deployment with [@shipstatic/ship](https://github.com/shipstatic/ship). Handles ZIP extraction, path normalization, and validation - everything needed before calling `ship.deploy()`.
 
-**v0.1.6 Update:** Now includes built-in drag & drop support with prop getters! No need to manually implement drag & drop handlers - just spread `{...drop.getDropzoneProps()}` on your container and `{...drop.getInputProps()}` on the input element. Folder structure preservation is handled automatically.
+Built-in drag & drop support with prop getters! No need to manually implement drag & drop handlers - just spread `{...drop.getDropzoneProps()}` on your container and `{...drop.getInputProps()}` on the input element. Folder structure preservation is handled automatically.
 
 **Note:** MD5 calculation is handled by Ship SDK during deployment. Drop focuses on file processing and UI state management.
 
+## Table of Contents
+
+- [Why Headless?](#why-headless)
+- [Features](#features)
+- [Installation](#installation)
+- [Requirements](#requirements)
+- [Quick Start](#quick-start)
+- [Configuration Architecture](#️-configuration-architecture)
+- [Advanced Usage](#advanced-programmatic-file-picker)
+- [API Reference](#api)
+- [State Machine](#state-machine)
+- [Error Handling](#error-handling)
+- [Types](#types)
+- [Ship SDK Integration](#direct-ship-sdk-integration)
+- [Architecture Decisions](#architecture-decisions)
+
 ## Why Headless?
 
 This package provides **zero UI components** - just a React hook with built-in drag & drop functionality. You bring your own styling.
@@ -16,8 +32,7 @@ This package provides **zero UI components** - just a React hook with built-in d
 1. **Built-in drag & drop** - Proper folder support with `webkitGetAsEntry` API, all handled internally
 2. **Prop getters API** - Similar to `react-dropzone`, just spread props on your elements
 3. **Full styling control** - No imposed CSS, design system, or theming
-4. **Smaller bundle** - No UI components means less bloat
-5. **Ship SDK integration** - Purpose-built for Ship deployments, not a generic file upload library
+4. **Ship SDK integration** - Purpose-built for Ship deployments, not a generic file upload library
 
 **What's different from other libraries:**
 - Generic dropzone libraries don't preserve folder structure properly
@@ -34,6 +49,7 @@ This package provides **zero UI components** - just a React hook with built-in d
 - 🔒 **Path Sanitization** - Defense-in-depth protection against directory traversal attacks
 - 📁 **Folder Structure Preservation** - Proper folder paths via `webkitRelativePath`
 - 🎨 **Headless UI** - No visual components, just logic and state management
+- 📘 **Full TypeScript Support** - Complete type definitions with discriminated unions for state machine
 - 🚀 **Focused Scope** - File processing and UI state only. MD5 calculation and deployment handled by Ship SDK
 
 ## Installation
@@ -44,6 +60,17 @@ npm install @shipstatic/drop
 pnpm add @shipstatic/drop
 ```
 
+## Requirements
+
+- **React**: ^18.0.0 or ^19.0.0
+- **TypeScript**: Full TypeScript support with exported types
+- **Browsers**: Modern browsers with support for:
+  - File API (universal support)
+  - DataTransfer API for drag & drop (universal support)
+  - `webkitGetAsEntry` for folder uploads (Chrome, Edge, Safari 11.1+, Firefox 50+)
+
+**Note on folder uploads**: The folder drag & drop feature uses the `webkitGetAsEntry` API. While widely supported, older browsers may only support file-by-file selection. ZIP extraction works universally as a fallback.
+
 ## Quick Start
 
 ```tsx
@@ -80,11 +107,15 @@ function MyUploader() {
         {drop.isDragging ? '📂 Drop here' : '📁 Click or drag files/folders'}
       </div>
 
-      {/* Status */}
-      <p>{drop.statusText}</p>
+      {/* Status - using state machine */}
+      {drop.state.status && (
+        <p>
+          <strong>{drop.state.status.title}:</strong> {drop.state.status.details}
+        </p>
+      )}
 
       {/* File list */}
-      {drop.files.map(file => (
+      {drop.state.files.map(file => (
         <div key={file.id}>
           {file.name} - {file.status}
         </div>
@@ -93,7 +124,7 @@ function MyUploader() {
       {/* Upload button */}
       <button
         onClick={handleUpload}
-        disabled={drop.getValidFiles().length === 0}
+        disabled={drop.state.value !== 'ready'}
       >
         Upload {drop.getValidFiles().length} files
       </button>
@@ -203,19 +234,15 @@ interface DropOptions {
 
 ```typescript
 interface DropReturn {
-  // State
-  /** 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;
+  // State machine
+  /** Current state of the drop hook */
+  state: DropState;
+
+  // Convenience getters (computed from state)
   /** Whether currently processing files (ZIP extraction, etc.) */
   isProcessing: boolean;
   /** Whether user is currently dragging over the dropzone */
   isDragging: boolean;
-  /** Last validation error if any */
-  validationError: ClientError | null;
 
   // Primary API: Prop getters for easy integration
   /** Get props to spread on dropzone element (handles drag & drop) */
@@ -231,7 +258,7 @@ interface DropReturn {
     type: 'file';
     style: { display: string };
     multiple: boolean;
-    webkitdirectory: string;
+    webkitdirectory: string; // Note: React expects string ('') for boolean attributes
     onChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
   };
 
@@ -253,19 +280,111 @@ interface DropReturn {
     progress?: number;
   }) => void;
 }
+
+// State machine types
+type DropStateValue =
+  | 'idle'       // The hook is ready for files
+  | 'dragging'   // The user is dragging files over the dropzone
+  | 'processing' // Files are being validated and processed
+  | 'ready'      // Files are valid and ready for deployment
+  | 'error';     // An error occurred during processing
+
+interface DropState {
+  value: DropStateValue;
+  files: ProcessedFile[];
+  sourceName: string;
+  status: DropStatus | null;
+}
+
+interface DropStatus {
+  title: string;
+  details: string;
+}
+```
+
+## State Machine
+
+The drop hook uses a state machine for predictable, clear state management. Instead of multiple boolean flags, you have a single `state.value` that represents exactly what's happening.
+
+### State Flow
+
+```
+idle → dragging → idle (drag leave without drop)
+idle → dragging → processing → ready (successful)
+idle → dragging → processing → error (failed)
+ready → dragging → processing → ... (new drop)
+error → dragging → processing → ... (retry)
+```
+
+### Using the State Machine
+
+```tsx
+function StatusIndicator({ drop }) {
+  const { state } = drop;
+
+  switch (state.value) {
+    case 'idle':
+      return <p>Drop files here or click to select</p>;
+
+    case 'dragging':
+      return <p>Drop your files now!</p>;
+
+    case 'processing':
+      return <p>{state.status?.details || 'Processing...'}</p>;
+
+    case 'ready':
+      return (
+        <div>
+          <p>✓ {state.files.length} files ready</p>
+          <button>Upload to Ship</button>
+        </div>
+      );
+
+    case 'error':
+      return (
+        <div>
+          <p>✗ {state.status?.title}</p>
+          <p>{state.status?.details}</p>
+          <button onClick={drop.clearAll}>Try Again</button>
+        </div>
+      );
+  }
+}
+```
+
+### Convenience Getters
+
+For simpler use cases, boolean convenience getters are provided:
+
+```tsx
+// These are computed from state.value (read-only projections)
+drop.isProcessing  // true when state.value === 'processing'
+drop.isDragging    // true when state.value === 'dragging'
+
+// For error information, use the state object
+drop.state.value === 'error'  // Check if in error state
+drop.state.status?.title      // Error title
+drop.state.status?.details    // Error details
 ```
 
+### Benefits
+
+- **No impossible states** - Can't be `isProcessing=true` AND `isDragging=true`
+- **Clear transitions** - State flow is explicit and predictable
+- **Better TypeScript** - Discriminated unions provide type safety
+- **Easier debugging** - Single source of truth for what's happening
+
 ## Error Handling
 
 ### Per-File Error Display
 
-Each file in the `files` array contains its own `status` and `statusMessage`, allowing you to display granular errors for individual files:
+Each file in the `state.files` array contains its own `status` and `statusMessage`, allowing you to display granular errors for individual files:
 
 ```tsx
 function FileList({ drop }) {
   return (
     <div>
-      {drop.files.map(file => (
+      {drop.state.files.map(file => (
         <div key={file.id}>
           <span>{file.path}</span>
 
@@ -282,7 +401,7 @@ function FileList({ drop }) {
       ))}
 
       {/* If validation fails, allow user to clear all and try again */}
-      {drop.validationError && (
+      {drop.state.value === 'error' && (
         <button onClick={drop.clearAll}>
           Clear All & Try Again
         </button>
@@ -298,15 +417,15 @@ function FileList({ drop }) {
 - `empty_file` - File is 0 bytes
 - `ready` - File passed all validation and is ready for upload
 
-### Validation Error Summary
+### Error State Summary
 
-The `validationError` provides a summary when any files fail validation:
+When files fail validation or processing, check the error state:
 
 ```tsx
-{drop.validationError && (
+{drop.state.value === 'error' && drop.state.status && (
   <div>
-    <p>{drop.validationError.error}</p>
-    <p>{drop.validationError.details}</p>
+    <p>{drop.state.status.title}</p>
+    <p>{drop.state.status.details}</p>
   </div>
 )}
 ```
@@ -336,10 +455,10 @@ Use `clearAll()` to reset and try again:
 
 ```tsx
 // If validation fails, show user which files failed
-{drop.validationError && (
+{drop.state.value === 'error' && (
   <div>
     <p>Validation failed. Please fix the issues and try again:</p>
-    {drop.files.map(file => (
+    {drop.state.files.map(file => (
       <div key={file.id}>
         {file.path}: {file.statusMessage}
       </div>

package/dist/index.cjs

@@ -37,9 +37,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 // node_modules/.pnpm/jszip@3.10.1/node_modules/jszip/dist/jszip.min.js
 var require_jszip_min = __commonJS({
-  "node_modules/.pnpm/jszip@3.10.1/node_modules/jszip/dist/jszip.min.js"(exports, module) {
+  "node_modules/.pnpm/jszip@3.10.1/node_modules/jszip/dist/jszip.min.js"(exports$1, module) {
     !(function(e) {
-      if ("object" == typeof exports && "undefined" != typeof module) module.exports = e();
+      if ("object" == typeof exports$1 && "undefined" != typeof module) module.exports = e();
       else if ("function" == typeof define && define.amd) define([], e);
       else {
         ("undefined" != typeof window ? window : "undefined" != typeof global ? global : "undefined" != typeof self ? self : this).JSZip = e();
@@ -2349,7 +2349,7 @@ var require_jszip_min = __commonJS({
 
 // node_modules/.pnpm/mime-db@1.54.0/node_modules/mime-db/db.json
 var require_db = __commonJS({
-  "node_modules/.pnpm/mime-db@1.54.0/node_modules/mime-db/db.json"(exports, module) {
+  "node_modules/.pnpm/mime-db@1.54.0/node_modules/mime-db/db.json"(exports$1, module) {
     module.exports = {
       "application/1d-interleaved-parityfec": {
         source: "iana"
@@ -11697,7 +11697,7 @@ var require_db = __commonJS({
 
 // node_modules/.pnpm/mime-db@1.54.0/node_modules/mime-db/index.js
 var require_mime_db = __commonJS({
-  "node_modules/.pnpm/mime-db@1.54.0/node_modules/mime-db/index.js"(exports, module) {
+  "node_modules/.pnpm/mime-db@1.54.0/node_modules/mime-db/index.js"(exports$1, module) {
     module.exports = require_db();
   }
 });
@@ -11835,35 +11835,39 @@ function stripCommonPrefix(files) {
   }));
 }
 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);
+  try {
+    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();
         }
-      );
-      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);
       }
-    };
-    await readEntriesBatch();
-    for (const childEntry of allEntries) {
-      const entryPath = childEntry.isDirectory ? currentPath ? `${currentPath}/${childEntry.name}` : childEntry.name : currentPath;
-      await traverseFileTree(childEntry, files, entryPath);
     }
+  } catch (error) {
+    console.warn(`Error traversing file tree for entry ${entry.name}:`, error);
   }
 }
 function useDrop(options) {
@@ -11873,28 +11877,32 @@ function useDrop(options) {
     onFilesReady,
     stripPrefix = true
   } = options;
-  const [files, setFiles] = react.useState([]);
-  const [sourceName, setSourceName] = react.useState("");
-  const [statusText, setStatusText] = react.useState("");
-  const [isProcessing, setIsProcessing] = react.useState(false);
-  const [isDragging, setIsDragging] = react.useState(false);
-  const [validationError, setValidationError] = react.useState(null);
+  const initialState = {
+    value: "idle",
+    files: [],
+    sourceName: "",
+    status: null
+  };
+  const [state, setState] = react.useState(initialState);
   const isProcessingRef = react.useRef(false);
   const inputRef = react.useRef(null);
+  const isProcessing = react.useMemo(() => state.value === "processing", [state.value]);
+  const isDragging = react.useMemo(() => state.value === "dragging", [state.value]);
   const processFiles = react.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])) {
@@ -11907,12 +11915,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);
@@ -11928,29 +11938,44 @@ function useDrop(options) {
       const filePaths = allFiles.map(getFilePath);
       const validPaths = new Set(ship.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$1.getConfig();
       const validation = ship.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) {
@@ -11959,69 +11984,92 @@ 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$1, onValidationError, onFilesReady, stripPrefix]);
   const clearAll = react.useCallback(() => {
-    setFiles([]);
-    setSourceName("");
-    setStatusText("");
-    setValidationError(null);
-    setIsDragging(false);
+    setState(initialState);
     isProcessingRef.current = false;
-    setIsProcessing(false);
   }, []);
   const getValidFilesCallback = react.useCallback(() => {
-    return getValidFiles(files);
-  }, [files]);
-  const updateFileStatus = react.useCallback((fileId, state) => {
-    setFiles((prev) => prev.map(
-      (file) => file.id === fileId ? { ...file, ...state } : file
-    ));
+    return getValidFiles(state.files);
+  }, [state.files]);
+  const updateFileStatus = react.useCallback((fileId, fileState) => {
+    setState((prev) => ({
+      ...prev,
+      files: prev.files.map(
+        (file) => file.id === fileId ? { ...file, ...fileState } : file
+      )
+    }));
   }, []);
   const handleDragOver = react.useCallback((e) => {
     e.preventDefault();
-    setIsDragging(true);
+    setState((prev) => {
+      if (prev.value === "idle" || prev.value === "ready" || prev.value === "error") {
+        return { ...prev, value: "dragging" };
+      }
+      return prev;
+    });
   }, []);
   const handleDragLeave = react.useCallback((e) => {
     e.preventDefault();
-    setIsDragging(false);
+    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 = react.useCallback(async (e) => {
     e.preventDefault();
-    setIsDragging(false);
     const items = Array.from(e.dataTransfer.items);
-    const files2 = [];
+    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,
-            files2,
-            entry.isDirectory ? entry.name : ""
-          );
+        try {
+          const entry = item.webkitGetAsEntry?.();
+          if (entry) {
+            hasEntries = true;
+            await traverseFileTree(
+              entry,
+              files,
+              entry.isDirectory ? entry.name : ""
+            );
+          } else {
+            const file = item.getAsFile();
+            if (file) {
+              files.push(file);
+            }
+          }
+        } catch (error) {
+          console.warn("Error processing drop item:", error);
+          const file = item.getAsFile();
+          if (file) {
+            files.push(file);
+          }
         }
       }
     }
     if (!hasEntries && e.dataTransfer.files.length > 0) {
-      files2.push(...Array.from(e.dataTransfer.files));
+      files.push(...Array.from(e.dataTransfer.files));
     }
-    if (files2.length > 0) {
-      await processFiles(files2);
+    if (files.length > 0) {
+      await processFiles(files);
+    } else if (state.value === "dragging") {
+      setState((prev) => ({ ...prev, value: "idle" }));
     }
-  }, [processFiles]);
+  }, [processFiles, state.value]);
   const handleInputChange = react.useCallback((e) => {
-    const files2 = Array.from(e.target.files || []);
-    if (files2.length > 0) {
-      processFiles(files2);
+    const files = Array.from(e.target.files || []);
+    if (files.length > 0) {
+      processFiles(files);
     }
   }, [processFiles]);
   const open = react.useCallback(() => {
@@ -12042,13 +12090,11 @@ function useDrop(options) {
     onChange: handleInputChange
   }), [handleInputChange]);
   return {
-    // State
-    files,
-    sourceName,
-    statusText,
+    // State machine
+    state,
+    // Convenience getters (computed from state)
     isProcessing,
     isDragging,
-    validationError,
     // Primary API: Prop getters
     getDropzoneProps,
     getInputProps,