@shipstatic/drop 0.1.7 → 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
@@ -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;
   };
 

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) {
@@ -12029,14 +12033,27 @@ function useDrop(options) {
     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 : ""
-          );
+        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);
+          }
         }
       }
     }