@unofficialbox/box-open-elements 0.16.0 → 0.18.0

package/dist/patterns/content-uploader/controller.d.ts

@@ -11,14 +11,51 @@ export declare class ContentUploaderController extends Controller<UploaderState,
     private counter;
     private readonly files;
     private readonly abortControllers;
+    /** Directory path -> the in-flight or settled promise for its folder id. */
+    private readonly folderIds;
+    /**
+     * Aborted only when the controller is destroyed.
+     *
+     * Folder creation is shared by every file in that folder, so it cannot belong
+     * to any one of them: cancelling the file that happened to start first would
+     * abort the shared request and fail all its siblings — as an abort, so they
+     * would report themselves cancelled by the person, which never happened.
+     */
+    private readonly lifetime;
     constructor(config: UploaderSessionConfig);
     get concurrency(): number;
     get autoStart(): boolean;
+    /**
+     * Slots left before `fileLimit` is reached. Settled items still count: the
+     * limit is on the queue a person is looking at, not on throughput.
+     */
+    private remainingCapacity;
+    /**
+     * Resolve a directory path to a destination folder id, creating each segment
+     * that does not exist yet.
+     *
+     * The **promise** is memoised rather than the id, because concurrent uploads
+     * into the same folder resolve the same path at the same moment; caching only
+     * the settled value would let two of them each create "docs" and scatter the
+     * files across two folders with the same name.
+     */
+    private resolveFolderId;
     /**
      * Validate and enqueue files. Rejected files emit `itemRejected` and never
      * enter the queue. Returns the accepted queue items.
      */
     addFiles(files: UploadFileLike[]): UploadQueueItem[];
+    /**
+     * Enqueue files that carry a directory path, as a dropped folder does.
+     *
+     * A path is only honoured when the transport can create folders. Without
+     * that capability the files are refused rather than flattened into the
+     * destination root — see `UploadTransport.createFolder`.
+     */
+    addEntries(entries: Array<{
+        file: UploadFileLike;
+        path?: string;
+    }>): UploadQueueItem[];
     /** Begin (or resume) uploading queued items, up to the concurrency limit. */
     start(): void;
     /** Abort an in-flight upload or withdraw a queued item. */

package/dist/patterns/content-uploader/controller.js

@@ -13,6 +13,17 @@ export class ContentUploaderController extends Controller {
     counter = 0;
     files = new Map();
     abortControllers = new Map();
+    /** Directory path -> the in-flight or settled promise for its folder id. */
+    folderIds = new Map();
+    /**
+     * Aborted only when the controller is destroyed.
+     *
+     * Folder creation is shared by every file in that folder, so it cannot belong
+     * to any one of them: cancelling the file that happened to start first would
+     * abort the shared request and fail all its siblings — as an abort, so they
+     * would report themselves cancelled by the person, which never happened.
+     */
+    lifetime = typeof AbortController === "function" ? new AbortController() : null;
     constructor(config) {
         super({ items: [], uploading: false });
         this.config = config;
@@ -24,18 +35,99 @@ export class ContentUploaderController extends Controller {
     get autoStart() {
         return this.config.autoStart ?? true;
     }
+    /**
+     * Slots left before `fileLimit` is reached. Settled items still count: the
+     * limit is on the queue a person is looking at, not on throughput.
+     */
+    remainingCapacity() {
+        const limit = this.config.fileLimit;
+        if (limit === undefined || !Number.isFinite(limit)) {
+            return Number.POSITIVE_INFINITY;
+        }
+        return Math.max(0, Math.floor(limit) - this.state.items.length);
+    }
+    /**
+     * Resolve a directory path to a destination folder id, creating each segment
+     * that does not exist yet.
+     *
+     * The **promise** is memoised rather than the id, because concurrent uploads
+     * into the same folder resolve the same path at the same moment; caching only
+     * the settled value would let two of them each create "docs" and scatter the
+     * files across two folders with the same name.
+     */
+    resolveFolderId(path) {
+        if (!path) {
+            return Promise.resolve(this.config.folderId);
+        }
+        const existing = this.folderIds.get(path);
+        if (existing) {
+            return existing;
+        }
+        const separator = path.lastIndexOf("/");
+        const parentPath = separator > 0 ? path.slice(0, separator) : "";
+        const name = separator > 0 ? path.slice(separator + 1) : path;
+        const pending = (async () => {
+            const parentFolderId = await this.resolveFolderId(parentPath);
+            const createFolder = this.config.transport.createFolder;
+            if (!createFolder) {
+                throw new Error("This transport cannot create folders");
+            }
+            const signal = this.lifetime?.signal;
+            const result = await createFolder.call(this.config.transport, {
+                name,
+                parentFolderId,
+                token: this.config.token,
+                ...(signal ? { signal } : {}),
+            });
+            return result.folderId;
+        })();
+        this.folderIds.set(path, pending);
+        // A failed creation must not be cached, or every file in that folder fails
+        // against a poisoned entry instead of retrying the folder.
+        void pending.catch(() => {
+            if (this.folderIds.get(path) === pending) {
+                this.folderIds.delete(path);
+            }
+        });
+        return pending;
+    }
     /**
      * Validate and enqueue files. Rejected files emit `itemRejected` and never
      * enter the queue. Returns the accepted queue items.
      */
     addFiles(files) {
+        return this.addEntries(files.map(file => ({ file, path: "" })));
+    }
+    /**
+     * Enqueue files that carry a directory path, as a dropped folder does.
+     *
+     * A path is only honoured when the transport can create folders. Without
+     * that capability the files are refused rather than flattened into the
+     * destination root — see `UploadTransport.createFolder`.
+     */
+    addEntries(entries) {
         const added = [];
-        for (const file of files) {
+        const canCreateFolders = typeof this.config.transport.createFolder === "function";
+        // Counted against the live queue, so two drops in a row cannot together
+        // exceed the limit the way two independent checks would let them.
+        let remaining = this.remainingCapacity();
+        for (const entry of entries) {
+            const { file } = entry;
+            const path = entry.path ?? "";
+            if (path && !canCreateFolders) {
+                this.emit("itemRejected", { file, reason: "folder-unsupported" });
+                continue;
+            }
             const rejection = resolveUploadRejection(file, this.config);
             if (rejection) {
                 this.emit("itemRejected", { file, reason: rejection });
                 continue;
             }
+            if (remaining <= 0) {
+                this.emit("itemRejected", { file, reason: "file-limit-reached" });
+                continue;
+            }
+            remaining -= 1;
             this.counter += 1;
             const item = {
                 id: `upload-${this.counter}`,
@@ -43,6 +135,7 @@ export class ContentUploaderController extends Controller {
                 size: file.size,
                 status: "queued",
                 progress: 0,
+                ...(path ? { path } : {}),
             };
             this.files.set(item.id, file);
             added.push(item);
@@ -118,6 +211,8 @@ export class ContentUploaderController extends Controller {
             abortController.abort();
         }
         this.abortControllers.clear();
+        this.lifetime?.abort();
+        this.folderIds.clear();
         super.destroy();
     }
     getItem(itemId) {
@@ -169,10 +264,24 @@ export class ContentUploaderController extends Controller {
             this.emit("itemStarted", { item: started });
         }
         try {
+            // Resolved per upload rather than at enqueue time, so a folder is only
+            // created when a file in it actually starts — a queue cancelled before it
+            // ran leaves no empty folders behind.
+            const folderId = await this.resolveFolderId(item.path ?? "");
+            // Cancelling during folder creation cannot abort the shared request, so
+            // the cancellation is honoured here instead, before any bytes move.
+            if (abortController?.signal.aborted) {
+                // A plain Error, not a DOMException: the latter is not `instanceof
+                // Error` in a browser, so the abort check below would miss it and the
+                // item would report itself failed rather than cancelled.
+                const aborted = new Error("AbortError");
+                aborted.name = "AbortError";
+                throw aborted;
+            }
             const result = await this.config.transport.uploadFile({
                 file,
                 fileName: item.name,
-                folderId: this.config.folderId,
+                folderId,
                 token: this.config.token,
                 language: this.config.language,
                 ...(abortController ? { signal: abortController.signal } : {}),

package/dist/patterns/content-uploader/types.d.ts

@@ -19,6 +19,11 @@ export interface UploadQueueItem {
     errorMessage?: string;
     /** Remote file id from the transport once the upload succeeds. */
     fileId?: string;
+    /**
+     * Directory path relative to the destination folder, e.g. `"docs/2026"`, for
+     * a file that arrived inside a dropped folder. Empty for a loose file.
+     */
+    path?: string;
 }
 export interface UploadRequest {
     file: UploadFileLike;
@@ -35,6 +40,16 @@ export interface UploadResult {
     name?: string;
     size?: number;
 }
+export interface CreateFolderRequest {
+    name: string;
+    /** The folder to create it in. */
+    parentFolderId: string;
+    token: string;
+    signal?: AbortSignal;
+}
+export interface CreateFolderResult {
+    folderId: string;
+}
 /**
  * One narrow capability: move a single file to the destination folder. How —
  * multipart, chunked upload sessions, a BFF — is the transport's business;
@@ -42,6 +57,29 @@ export interface UploadResult {
  */
 export interface UploadTransport {
     uploadFile(request: UploadRequest): Promise<UploadResult>;
+    /**
+     * Recreate a dropped folder tree in the destination. **Optional**, because
+     * adding it as a requirement would break every transport already written
+     * against this interface, and because plenty of destinations have no notion
+     * of folders at all.
+     *
+     * Without it a folder drop is *refused* — every file in it is rejected with
+     * `folder-unsupported`. The alternative, flattening the tree into the
+     * destination root, silently scatters a hundred files out of the structure
+     * the person dropped them in, and there is no undo for that.
+     *
+     * A transport that implements this should be idempotent about an existing
+     * name, or map the conflict to the existing folder's id: a retried upload
+     * asks for the same folder again.
+     *
+     * Folder creation is **not** undone if the uploads into it then fail or are
+     * cancelled, so an interrupted folder upload leaves the folders it had got to
+     * behind, some of them empty. There is no atomic "create this tree" anywhere
+     * underneath, so the alternative would be the uploader deleting folders on a
+     * destination it does not own — far worse than a stray empty folder. Retrying
+     * reuses them; a host that wants them cleaned up owns that decision.
+     */
+    createFolder?(request: CreateFolderRequest): Promise<CreateFolderResult>;
 }
 export interface UploaderConstraints {
     /**
@@ -51,6 +89,16 @@ export interface UploaderConstraints {
     extensions?: string[];
     /** Reject files larger than this many bytes. Omitted means no limit. */
     maxFileSizeBytes?: number;
+    /**
+     * Most files the queue will hold. Further files are rejected with
+     * `file-limit-reached` rather than enqueued.
+     *
+     * Omitted means no limit, which is the wrong default for a drop target — a
+     * dropped folder can carry thousands of files, and the queue has no natural
+     * back pressure. Hosts should set one; `box-content-uploader` defaults it to
+     * 100, matching box-ui-elements.
+     */
+    fileLimit?: number;
 }
 export interface UploaderSessionConfig extends UploaderConstraints {
     folderId: string;
@@ -62,7 +110,9 @@ export interface UploaderSessionConfig extends UploaderConstraints {
     /** Start uploading as soon as files are added. Defaults to true. */
     autoStart?: boolean;
 }
-export type UploadRejectionReason = "extension-not-allowed" | "file-too-large";
+export type UploadRejectionReason = "extension-not-allowed" | "file-too-large" | "file-limit-reached"
+/** A folder was dropped but the transport cannot create folders. */
+ | "folder-unsupported";
 export interface UploaderState {
     items: UploadQueueItem[];
     /** True while any item is actively uploading. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unofficialbox/box-open-elements",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Box Open Elements: an open, framework-agnostic design system and web component library for Box-style experiences",
   "license": "MIT",
   "homepage": "https://unofficialbox.github.io/box-open-elements",