@unofficialbox/box-open-elements 0.15.0 → 0.17.0

package/dist/components/files/drop-zone.d.ts

@@ -13,7 +13,41 @@ export declare class DropZone extends BaseElement {
     set message(value: string);
     get description(): string;
     set description(value: string);
+    /**
+     * Make the browse dialog pick a folder rather than files.
+     *
+     * Drag-and-drop reads folders regardless — a dropped directory is always
+     * traversed. This only governs the click-to-browse path, where the platform
+     * makes it either/or: an input is a file picker or a folder picker, never
+     * both.
+     */
+    get directories(): boolean;
+    set directories(value: boolean);
+    /**
+     * What the browse dialog offers, in the `<input accept>` syntax —
+     * `".pdf,.docx"` or `"image/*"`.
+     *
+     * A hint, never a guarantee: it greys out other files in the picker, but a
+     * person can still choose "All files", and it has no effect at all on a drop.
+     * Whatever accepts the selection afterwards stays the real check.
+     */
+    get accept(): string;
+    set accept(value: string);
     protected renderTemplate(): void;
     protected setupListeners(): void;
+    /**
+     * Report a selection.
+     *
+     * `files` stays a flat list so existing hosts keep working unchanged;
+     * `entries` adds the directory each file came from, which is the only way a
+     * host can recreate a dropped folder. `skipped` names anything the browser
+     * refused to read, so a lost file is reported rather than simply absent.
+     *
+     * Nothing is dispatched when there is nothing to say — a drag that lands on
+     * the zone carrying no files is not an upload of nothing. A drop where
+     * everything was skipped still reports, because that is a failure, not
+     * silence.
+     */
+    private emitSelection;
     protected update(): void;
 }

package/dist/components/files/drop-zone.js

@@ -1,4 +1,5 @@
 import { BaseElement } from "../../core/index.js";
+import { captureDropEntries, collectEntries, entriesFromFileList, } from "../../foundations/files/index.js";
 import { boeFocusRingShadow, boeFocusVisibleStyles, } from "../../foundations/tokens/index.js";
 import { boeMotionDuration, boeMotionEasing } from "../../foundations/motion/index.js";
 import { boeRadius } from "../../foundations/geometry/index.js";
@@ -73,7 +74,7 @@ const dropZoneStyles = `
 export class DropZone extends BaseElement {
     static tagName = DEFAULT_TAG_NAME;
     static get observedAttributes() {
-        return ["description", "label", "message"];
+        return ["accept", "description", "directories", "label", "message"];
     }
     dragging = false;
     zoneEl;
@@ -98,6 +99,38 @@ export class DropZone extends BaseElement {
     set description(value) {
         this.setAttribute("description", value);
     }
+    /**
+     * Make the browse dialog pick a folder rather than files.
+     *
+     * Drag-and-drop reads folders regardless — a dropped directory is always
+     * traversed. This only governs the click-to-browse path, where the platform
+     * makes it either/or: an input is a file picker or a folder picker, never
+     * both.
+     */
+    get directories() {
+        return this.hasAttribute("directories");
+    }
+    set directories(value) {
+        this.toggleAttribute("directories", value);
+    }
+    /**
+     * What the browse dialog offers, in the `<input accept>` syntax —
+     * `".pdf,.docx"` or `"image/*"`.
+     *
+     * A hint, never a guarantee: it greys out other files in the picker, but a
+     * person can still choose "All files", and it has no effect at all on a drop.
+     * Whatever accepts the selection afterwards stays the real check.
+     */
+    get accept() {
+        return this.getAttribute("accept") ?? "";
+    }
+    set accept(value) {
+        if (value) {
+            this.setAttribute("accept", value);
+            return;
+        }
+        this.removeAttribute("accept");
+    }
     renderTemplate() {
         if (!this.shadowRoot) {
             return;
@@ -134,23 +167,45 @@ export class DropZone extends BaseElement {
         this.zoneEl.addEventListener("drop", event => {
             event.preventDefault();
             this.dragging = false;
-            const files = Array.from(event.dataTransfer?.files ?? []);
-            this.dispatchEvent(new CustomEvent("files-selected", {
-                bubbles: true,
-                composed: true,
-                detail: { files },
-            }));
             this.update();
+            // Captured synchronously: the DataTransferItemList is emptied the moment
+            // this handler returns, so awaiting anything before reading it loses the
+            // drop entirely. Traversal happens afterwards, off the captured entries.
+            const captured = captureDropEntries(event.dataTransfer);
+            const skipped = [];
+            void collectEntries(captured, name => skipped.push(name)).then(entries => {
+                this.emitSelection(entries, skipped);
+            });
         });
         this.inputEl.addEventListener("change", () => {
-            const files = Array.from(this.inputEl.files ?? []);
-            this.dispatchEvent(new CustomEvent("files-selected", {
-                bubbles: true,
-                composed: true,
-                detail: { files },
-            }));
+            // `webkitdirectory` reports the tree through each file's
+            // webkitRelativePath rather than through entries.
+            this.emitSelection(entriesFromFileList(Array.from(this.inputEl.files ?? [])));
         });
     }
+    /**
+     * Report a selection.
+     *
+     * `files` stays a flat list so existing hosts keep working unchanged;
+     * `entries` adds the directory each file came from, which is the only way a
+     * host can recreate a dropped folder. `skipped` names anything the browser
+     * refused to read, so a lost file is reported rather than simply absent.
+     *
+     * Nothing is dispatched when there is nothing to say — a drag that lands on
+     * the zone carrying no files is not an upload of nothing. A drop where
+     * everything was skipped still reports, because that is a failure, not
+     * silence.
+     */
+    emitSelection(entries, skipped = []) {
+        if (!entries.length && !skipped.length) {
+            return;
+        }
+        this.dispatchEvent(new CustomEvent("files-selected", {
+            bubbles: true,
+            composed: true,
+            detail: { entries, files: entries.map(entry => entry.file), skipped },
+        }));
+    }
     update() {
         if (!this.zoneEl) {
             return;
@@ -158,6 +213,13 @@ export class DropZone extends BaseElement {
         this.zoneEl.dataset.dragging = String(this.dragging);
         this.labelEl.textContent = this.label;
         this.messageEl.textContent = this.message;
+        // webkitdirectory turns the browse dialog into a folder picker. It is a
+        // property as well as an attribute, and only the property is honoured
+        // reliably once the input exists.
+        const directories = this.directories;
+        this.inputEl.toggleAttribute("webkitdirectory", directories);
+        this.inputEl.webkitdirectory = directories;
+        this.inputEl.accept = this.accept;
     }
 }
 DropZone.register();

package/dist/components/output/formatted-duration.d.ts

@@ -0,0 +1,55 @@
+import { FormattedValue } from "./formatted-value.js";
+/**
+ * How long something takes or lasts, in the reader's locale.
+ *
+ * ```html
+ * <box-formatted-duration value="5400"></box-formatted-duration>
+ * ```
+ *
+ * `value` is a count of seconds or an ISO 8601 duration (`PT1H30M`), because
+ * hosts have both: an API field is usually a number, while `<time datetime>`
+ * wants the ISO form. Whichever comes in, the ISO form goes back out in
+ * `datetime`, so the exact quantity survives for anything reading the document
+ * rather than looking at it.
+ *
+ * Not to be confused with `box-relative-time`, which renders *when* something
+ * happened relative to now ("3 days ago"). This renders *how long* — a
+ * retention period, an SLA, a processing time — and carries no direction.
+ *
+ * `Intl.DurationFormat` does the rendering where the browser has it. Where it
+ * does not, the same output is composed from `Intl.NumberFormat`'s unit style
+ * and `Intl.ListFormat`, both long supported; the two paths were compared
+ * across styles and locales and agree.
+ */
+export declare class FormattedDuration extends FormattedValue {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    /** Seconds, or an ISO 8601 duration such as `PT1H30M`. */
+    get value(): string;
+    set value(next: string);
+    /**
+     * `short` (default, `1 hr, 30 min`), `long` (`1 hour, 30 minutes`) or
+     * `narrow` (`1h 30m`).
+     *
+     * Named `format-style` rather than `style` because `style` is a global HTML
+     * attribute: naming it after the `Intl` option would put CSS on the host and
+     * be silently ignored as a formatting instruction.
+     */
+    get formatStyle(): string;
+    set formatStyle(next: string);
+    /**
+     * How many units to show, default 2.
+     *
+     * A duration carries more precision than a reader wants: 1 day, 3 hours, 12
+     * minutes and 8 seconds is a number to scan past, not to read. Two units is
+     * enough to convey magnitude.
+     */
+    get maxUnits(): number;
+    set maxUnits(next: number);
+    protected usesTimeElement(): boolean;
+    protected formatted(): {
+        machine?: string;
+        text: string;
+    } | null;
+    private render;
+}

package/dist/components/output/formatted-duration.js

@@ -0,0 +1,131 @@
+import { FormattedValue } from "./formatted-value.js";
+import { parseDuration, resolveDurationParts, toIsoDuration, } from "../../foundations/format/index.js";
+const DEFAULT_TAG_NAME = "box-formatted-duration";
+/** Whether the split came out as a plain zero, which `Intl` renders as nothing. */
+const isZero = (parts) => Object.values(parts).every(amount => amount === 0);
+const DURATION_STYLES = new Set(["long", "short", "narrow"]);
+/** `Intl` names duration fields in the plural; the parts are singular. */
+const INTL_FIELD = {
+    day: "days",
+    hour: "hours",
+    minute: "minutes",
+    second: "seconds",
+};
+/** The unit identifiers `Intl.NumberFormat` uses, for the fallback path. */
+const NUMBER_UNIT = {
+    day: "day",
+    hour: "hour",
+    minute: "minute",
+    second: "second",
+};
+/**
+ * How long something takes or lasts, in the reader's locale.
+ *
+ * ```html
+ * <box-formatted-duration value="5400"></box-formatted-duration>
+ * ```
+ *
+ * `value` is a count of seconds or an ISO 8601 duration (`PT1H30M`), because
+ * hosts have both: an API field is usually a number, while `<time datetime>`
+ * wants the ISO form. Whichever comes in, the ISO form goes back out in
+ * `datetime`, so the exact quantity survives for anything reading the document
+ * rather than looking at it.
+ *
+ * Not to be confused with `box-relative-time`, which renders *when* something
+ * happened relative to now ("3 days ago"). This renders *how long* — a
+ * retention period, an SLA, a processing time — and carries no direction.
+ *
+ * `Intl.DurationFormat` does the rendering where the browser has it. Where it
+ * does not, the same output is composed from `Intl.NumberFormat`'s unit style
+ * and `Intl.ListFormat`, both long supported; the two paths were compared
+ * across styles and locales and agree.
+ */
+export class FormattedDuration extends FormattedValue {
+    static tagName = DEFAULT_TAG_NAME;
+    static get observedAttributes() {
+        return ["format-style", "locale", "max-units", "value"];
+    }
+    /** Seconds, or an ISO 8601 duration such as `PT1H30M`. */
+    get value() {
+        return this.getAttribute("value") ?? "";
+    }
+    set value(next) {
+        this.setAttribute("value", next);
+    }
+    /**
+     * `short` (default, `1 hr, 30 min`), `long` (`1 hour, 30 minutes`) or
+     * `narrow` (`1h 30m`).
+     *
+     * Named `format-style` rather than `style` because `style` is a global HTML
+     * attribute: naming it after the `Intl` option would put CSS on the host and
+     * be silently ignored as a formatting instruction.
+     */
+    get formatStyle() {
+        const raw = this.getAttribute("format-style");
+        return raw && DURATION_STYLES.has(raw) ? raw : "short";
+    }
+    set formatStyle(next) {
+        this.setAttribute("format-style", next);
+    }
+    /**
+     * How many units to show, default 2.
+     *
+     * A duration carries more precision than a reader wants: 1 day, 3 hours, 12
+     * minutes and 8 seconds is a number to scan past, not to read. Two units is
+     * enough to convey magnitude.
+     */
+    get maxUnits() {
+        const raw = Number(this.getAttribute("max-units"));
+        return Number.isFinite(raw) && raw >= 1 ? Math.trunc(raw) : 2;
+    }
+    set maxUnits(next) {
+        this.setAttribute("max-units", String(next));
+    }
+    usesTimeElement() {
+        // A duration is a valid `datetime` value, so `<time>` is honest here.
+        return true;
+    }
+    formatted() {
+        const seconds = parseDuration(this.value);
+        if (seconds === null) {
+            return null;
+        }
+        const parts = resolveDurationParts(seconds, this.maxUnits);
+        const machine = toIsoDuration(parts);
+        const style = this.formatStyle;
+        try {
+            return { machine, text: this.render(parts, style) };
+        }
+        catch {
+            // A locale Intl rejects, or a runtime missing both paths. The duration is
+            // real, so fall back to the machine form rather than losing it.
+            return { machine, text: machine };
+        }
+    }
+    render(parts, style) {
+        const durationFormat = Intl.DurationFormat;
+        if (durationFormat) {
+            const input = Object.fromEntries(Object.entries(parts).map(([unit, amount]) => [INTL_FIELD[unit], amount]));
+            // A zero duration otherwise formats to the empty string, leaving a visible
+            // element with no text in it — zero is a real answer. Scoped to that case:
+            // asking for it always appends "0 sec" to every other duration in
+            // browsers that honour the option, which Node's Intl quietly does not.
+            const options = isZero(parts)
+                ? { secondsDisplay: "always", style }
+                : { style };
+            return new durationFormat(this.locale, options).format(input);
+        }
+        const unitDisplay = style === "long" ? "long" : style === "narrow" ? "narrow" : "short";
+        const pieces = Object.entries(parts).map(([unit, amount]) => new Intl.NumberFormat(this.locale, {
+            style: "unit",
+            unit: NUMBER_UNIT[unit],
+            unitDisplay,
+        }).format(amount));
+        // `narrow` runs the units together (`1h 30m`); the wider styles take the
+        // locale's own unit-list joiner, which is what DurationFormat uses too.
+        return style === "narrow"
+            ? pieces.join(" ")
+            : new Intl.ListFormat(this.locale, { style: "long", type: "unit" }).format(pieces);
+    }
+}
+FormattedDuration.register();

package/dist/entries/formatted-duration.d.ts

@@ -0,0 +1 @@
+export * from "../components/output/formatted-duration.js";

package/dist/entries/formatted-duration.js

@@ -0,0 +1 @@
+export * from "../components/output/formatted-duration.js";

package/dist/foundations/files/directory-entries.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Reading dropped folders, using only what the platform provides.
+ *
+ * A drop carries two very different things. `DataTransfer.files` is a flat
+ * `FileList` that **cannot represent a directory** — drop a folder and you get
+ * nothing useful, silently. `DataTransfer.items` carries `FileSystemEntry`
+ * objects via `webkitGetAsEntry()`, which is the only way to see that a folder
+ * was dropped at all, let alone read what is inside it.
+ *
+ * Two rules here are load-bearing and easy to get wrong:
+ *
+ * 1. **`webkitGetAsEntry()` must be called synchronously** while the `drop`
+ *    event is being handled. The `DataTransferItemList` is emptied as soon as
+ *    the handler returns, so an `await` before the call leaves you with
+ *    nothing. Capture first (`captureDropEntries`), traverse afterwards
+ *    (`collectEntries`).
+ * 2. **`readEntries()` is batched.** It resolves with at most ~100 entries per
+ *    call and must be called repeatedly until it yields an empty array. Read it
+ *    once and a folder of 500 files quietly becomes a folder of 100.
+ */
+/** A file plus the directory path it was found under, relative to the drop. */
+export interface UploadEntry {
+    file: File;
+    /**
+     * Directory path relative to the drop root, e.g. `"docs/2026"`. Empty for a
+     * file dropped at the top level.
+     */
+    path: string;
+}
+/** Minimal shape of the entry objects, which TypeScript's DOM lib types loosely. */
+interface FileSystemEntryLike {
+    isDirectory: boolean;
+    isFile: boolean;
+    name: string;
+    createReader?: () => FileSystemDirectoryReaderLike;
+    file?: (onSuccess: (file: File) => void, onError?: (error: unknown) => void) => void;
+}
+interface FileSystemDirectoryReaderLike {
+    readEntries: (onSuccess: (entries: FileSystemEntryLike[]) => void, onError?: (error: unknown) => void) => void;
+}
+/** What a synchronous capture yields: an entry, or a plain file when there is none. */
+export interface CapturedDropItem {
+    entry: FileSystemEntryLike | null;
+    file: File | null;
+}
+/**
+ * Read the entries out of a drop **synchronously**, before the event handler
+ * returns and the item list is emptied.
+ */
+export declare const captureDropEntries: (dataTransfer: DataTransfer | null) => CapturedDropItem[];
+/**
+ * Resolve captured drop items into files, each tagged with the directory path
+ * it came from. Files dropped at the top level get an empty path.
+ *
+ * Never rejects. A file the browser refuses to hand over, or a directory it
+ * cannot finish reading, is reported through `onSkip` and everything else still
+ * comes back — losing one file must not lose the drop, but nor should it pass
+ * unmentioned, which is the failure mode this whole module exists to remove.
+ */
+export declare const collectEntries: (captured: CapturedDropItem[], onSkip?: (name: string) => void) => Promise<UploadEntry[]>;
+/**
+ * Derive the same shape from an `<input webkitdirectory>` selection, where the
+ * browser reports the tree through each file's `webkitRelativePath` rather than
+ * through entries.
+ */
+export declare const entriesFromFileList: (files: readonly File[]) => UploadEntry[];
+/** Whether any entry sits inside a folder, i.e. whether folder support is needed. */
+export declare const hasFolderEntries: (entries: readonly UploadEntry[]) => boolean;
+export {};

package/dist/foundations/files/directory-entries.js

@@ -0,0 +1,149 @@
+/**
+ * Reading dropped folders, using only what the platform provides.
+ *
+ * A drop carries two very different things. `DataTransfer.files` is a flat
+ * `FileList` that **cannot represent a directory** — drop a folder and you get
+ * nothing useful, silently. `DataTransfer.items` carries `FileSystemEntry`
+ * objects via `webkitGetAsEntry()`, which is the only way to see that a folder
+ * was dropped at all, let alone read what is inside it.
+ *
+ * Two rules here are load-bearing and easy to get wrong:
+ *
+ * 1. **`webkitGetAsEntry()` must be called synchronously** while the `drop`
+ *    event is being handled. The `DataTransferItemList` is emptied as soon as
+ *    the handler returns, so an `await` before the call leaves you with
+ *    nothing. Capture first (`captureDropEntries`), traverse afterwards
+ *    (`collectEntries`).
+ * 2. **`readEntries()` is batched.** It resolves with at most ~100 entries per
+ *    call and must be called repeatedly until it yields an empty array. Read it
+ *    once and a folder of 500 files quietly becomes a folder of 100.
+ */
+const getAsEntry = (item) => {
+    const candidate = item;
+    const method = candidate.webkitGetAsEntry ?? candidate.mozGetAsEntry ?? candidate.getAsEntry;
+    return typeof method === "function" ? method.call(item) ?? null : null;
+};
+/**
+ * A macOS bundle (`.app`, `.rtfd`, a Keynote file) arrives as a *directory*
+ * that the OS also describes as a zip. Descending into one would upload its
+ * internals as loose files and destroy the thing; it is uploaded whole.
+ */
+const isPackage = (item, entry) => entry !== null && entry.isDirectory && item.kind === "file" && item.type === "application/zip";
+/**
+ * Read the entries out of a drop **synchronously**, before the event handler
+ * returns and the item list is emptied.
+ */
+export const captureDropEntries = (dataTransfer) => {
+    if (!dataTransfer) {
+        return [];
+    }
+    const items = Array.from(dataTransfer.items ?? []).filter(item => item.kind === "file");
+    if (items.length) {
+        return items.map(item => {
+            const entry = getAsEntry(item);
+            // A package is captured as a file so traversal never descends into it,
+            // and getAsFile() is also only valid during the event.
+            return isPackage(item, entry)
+                ? { entry: null, file: item.getAsFile() }
+                : { entry, file: entry ? null : item.getAsFile() };
+        });
+    }
+    // No item list (older browsers, synthetic events): the flat file list is all
+    // there is, and it cannot describe folders.
+    return Array.from(dataTransfer.files ?? []).map(file => ({ entry: null, file }));
+};
+const readAllEntries = async (reader) => {
+    const all = [];
+    // readEntries resolves a batch at a time and signals the end with an empty
+    // array. Calling it once truncates any directory past the batch size.
+    for (;;) {
+        // A directory that cannot be read yields what was read before it failed,
+        // rather than throwing: one unreadable subfolder must not discard the
+        // hundreds of files that were read successfully around it.
+        const batch = await new Promise(resolve => {
+            try {
+                reader.readEntries(resolve, () => resolve(null));
+            }
+            catch {
+                resolve(null);
+            }
+        });
+        if (batch === null) {
+            return { entries: all, failed: true };
+        }
+        if (!batch.length) {
+            return { entries: all, failed: false };
+        }
+        all.push(...batch);
+    }
+};
+const readFile = async (entry) => {
+    if (typeof entry.file !== "function") {
+        return null;
+    }
+    return new Promise(resolve => {
+        entry.file(file => resolve(file), 
+        // An unreadable file inside an otherwise good folder should not abort the
+        // whole drop; it is skipped and the rest still uploads.
+        () => resolve(null));
+    });
+};
+const walk = async (entry, path, out, onSkip) => {
+    if (entry.isFile) {
+        const file = await readFile(entry);
+        if (file) {
+            out.push({ file, path });
+        }
+        else {
+            onSkip(path ? `${path}/${entry.name}` : entry.name);
+        }
+        return;
+    }
+    if (!entry.isDirectory || typeof entry.createReader !== "function") {
+        onSkip(path ? `${path}/${entry.name}` : entry.name);
+        return;
+    }
+    const childPath = path ? `${path}/${entry.name}` : entry.name;
+    const { entries: children, failed } = await readAllEntries(entry.createReader());
+    if (failed) {
+        onSkip(childPath);
+    }
+    for (const child of children) {
+        await walk(child, childPath, out, onSkip);
+    }
+};
+/**
+ * Resolve captured drop items into files, each tagged with the directory path
+ * it came from. Files dropped at the top level get an empty path.
+ *
+ * Never rejects. A file the browser refuses to hand over, or a directory it
+ * cannot finish reading, is reported through `onSkip` and everything else still
+ * comes back — losing one file must not lose the drop, but nor should it pass
+ * unmentioned, which is the failure mode this whole module exists to remove.
+ */
+export const collectEntries = async (captured, onSkip = () => { }) => {
+    const out = [];
+    for (const item of captured) {
+        if (item.entry) {
+            await walk(item.entry, "", out, onSkip);
+        }
+        else if (item.file) {
+            out.push({ file: item.file, path: "" });
+        }
+    }
+    return out;
+};
+/**
+ * Derive the same shape from an `<input webkitdirectory>` selection, where the
+ * browser reports the tree through each file's `webkitRelativePath` rather than
+ * through entries.
+ */
+export const entriesFromFileList = (files) => files.map(file => {
+    const relativePath = file.webkitRelativePath ?? "";
+    // webkitRelativePath includes the file name; the directory is everything
+    // before the last separator.
+    const separator = relativePath.lastIndexOf("/");
+    return { file, path: separator > 0 ? relativePath.slice(0, separator) : "" };
+});
+/** Whether any entry sits inside a folder, i.e. whether folder support is needed. */
+export const hasFolderEntries = (entries) => entries.some(entry => entry.path !== "");

package/dist/foundations/files/index.d.ts

@@ -0,0 +1 @@
+export * from "./directory-entries.js";

package/dist/foundations/files/index.js

@@ -0,0 +1,3 @@
+// Reading dropped files and folders from the platform's DataTransfer and
+// FileSystemEntry APIs, shared by box-drop-zone and the uploader pattern.
+export * from "./directory-entries.js";

package/dist/foundations/format/format.d.ts

@@ -80,3 +80,37 @@ export interface BoeFileSizeParts {
  * is reported whole.
  */
 export declare const resolveFileSizeParts: (bytes: number, units?: BoeByteUnits) => BoeFileSizeParts;
+/** The duration units a formatted duration can be broken into, largest first. */
+export type BoeDurationUnit = "day" | "hour" | "minute" | "second";
+/** A duration split into whole units, ready for `Intl` to render. */
+export type BoeDurationParts = Partial<Record<BoeDurationUnit, number>>;
+/**
+ * Parse a duration to whole seconds.
+ *
+ * Accepts a count of seconds (a number, or a numeric string) or an ISO 8601
+ * duration such as `PT1H30M`, because hosts have both: an API field is usually
+ * a number, while `<time datetime>` wants the ISO form. Weeks, months and years
+ * are deliberately not accepted — `P1M` is ambiguous between a month and a
+ * minute in the calendar sense, and a month is not a fixed number of seconds,
+ * so rendering one as though it were would be a lie about how long the duration
+ * actually is.
+ *
+ * Negative and unparseable input is `null`. A duration is an elapsed quantity,
+ * so a negative one is a host bug rather than a direction — `box-relative-time`
+ * is the component that expresses "ago".
+ */
+export declare const parseDuration: (value: string | number | null | undefined) => number | null;
+/**
+ * Split whole seconds into at most `maxUnits` consecutive units.
+ *
+ * Consecutive, not merely the largest: 90061 seconds is "1 day, 1 hour" rather
+ * than "1 day, 1 minute", because a reader scanning a duration wants its
+ * magnitude, and skipping an empty unit to reach a smaller non-empty one
+ * overstates the precision.
+ *
+ * A duration of zero returns whole seconds rather than nothing, so "0 sec"
+ * renders instead of the element disappearing — zero is a real answer.
+ */
+export declare const resolveDurationParts: (totalSeconds: number, maxUnits?: number) => BoeDurationParts;
+/** Render a parts object back to an ISO 8601 duration, for `<time datetime>`. */
+export declare const toIsoDuration: (parts: BoeDurationParts) => string;

package/dist/foundations/format/format.js

@@ -120,3 +120,102 @@ export const resolveFileSizeParts = (bytes, units = "decimal") => {
     const exponent = Math.min(Math.floor(Math.log(magnitude) / Math.log(base)), suffixes.length - 1);
     return { suffix: suffixes[exponent], value: bytes / base ** exponent };
 };
+const ISO_DURATION = /^P(?:(\d+(?:\.\d+)?)D)?(?:T(?:(\d+(?:\.\d+)?)H)?(?:(\d+(?:\.\d+)?)M)?(?:(\d+(?:\.\d+)?)S)?)?$/;
+const SECONDS_PER = {
+    day: 86_400,
+    hour: 3_600,
+    minute: 60,
+    second: 1,
+};
+const DURATION_ORDER = ["day", "hour", "minute", "second"];
+/**
+ * Parse a duration to whole seconds.
+ *
+ * Accepts a count of seconds (a number, or a numeric string) or an ISO 8601
+ * duration such as `PT1H30M`, because hosts have both: an API field is usually
+ * a number, while `<time datetime>` wants the ISO form. Weeks, months and years
+ * are deliberately not accepted — `P1M` is ambiguous between a month and a
+ * minute in the calendar sense, and a month is not a fixed number of seconds,
+ * so rendering one as though it were would be a lie about how long the duration
+ * actually is.
+ *
+ * Negative and unparseable input is `null`. A duration is an elapsed quantity,
+ * so a negative one is a host bug rather than a direction — `box-relative-time`
+ * is the component that expresses "ago".
+ */
+export const parseDuration = (value) => {
+    if (value == null || value === "") {
+        return null;
+    }
+    if (typeof value === "number") {
+        return Number.isFinite(value) && value >= 0 ? Math.round(value) : null;
+    }
+    const trimmed = value.trim();
+    if (/^\d+(\.\d+)?$/.test(trimmed)) {
+        return Math.round(Number(trimmed));
+    }
+    const match = ISO_DURATION.exec(trimmed);
+    if (!match || trimmed === "P" || trimmed === "PT") {
+        return null;
+    }
+    const [, days, hours, minutes, seconds] = match;
+    const total = Number(days ?? 0) * SECONDS_PER.day +
+        Number(hours ?? 0) * SECONDS_PER.hour +
+        Number(minutes ?? 0) * SECONDS_PER.minute +
+        Number(seconds ?? 0);
+    return Number.isFinite(total) ? Math.round(total) : null;
+};
+/**
+ * Split whole seconds into at most `maxUnits` consecutive units.
+ *
+ * Consecutive, not merely the largest: 90061 seconds is "1 day, 1 hour" rather
+ * than "1 day, 1 minute", because a reader scanning a duration wants its
+ * magnitude, and skipping an empty unit to reach a smaller non-empty one
+ * overstates the precision.
+ *
+ * A duration of zero returns whole seconds rather than nothing, so "0 sec"
+ * renders instead of the element disappearing — zero is a real answer.
+ */
+export const resolveDurationParts = (totalSeconds, maxUnits = 2) => {
+    const limit = Math.max(1, Math.trunc(maxUnits));
+    if (totalSeconds <= 0) {
+        return { second: 0 };
+    }
+    const collected = [];
+    let remaining = Math.round(totalSeconds);
+    let started = false;
+    for (const unit of DURATION_ORDER) {
+        const size = SECONDS_PER[unit];
+        const amount = Math.floor(remaining / size);
+        if (!started && amount === 0) {
+            continue;
+        }
+        started = true;
+        collected.push([unit, amount]);
+        remaining -= amount * size;
+        if (collected.length === limit) {
+            break;
+        }
+    }
+    // Trailing zeroes are noise: an exact hour is "1 hr", not "1 hr, 0 min". Only
+    // trailing ones go — an interior zero is load-bearing, since "1 day, 0 hr" as
+    // the first two units of 1d 0h 5m would otherwise become "1 day, 5 min" and
+    // claim a precision the split does not have.
+    while (collected.length > 1 && collected[collected.length - 1][1] === 0) {
+        collected.pop();
+    }
+    return Object.fromEntries(collected);
+};
+/** Render a parts object back to an ISO 8601 duration, for `<time datetime>`. */
+export const toIsoDuration = (parts) => {
+    const date = parts.day ? `${parts.day}D` : "";
+    const time = [
+        parts.hour ? `${parts.hour}H` : "",
+        parts.minute ? `${parts.minute}M` : "",
+        parts.second ? `${parts.second}S` : "",
+    ].join("");
+    if (!date && !time) {
+        return "PT0S";
+    }
+    return `P${date}${time ? `T${time}` : ""}`;
+};

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export type { ApplyDesignProfileOptions, DesignProfileChangeDetail, DesignProfil
 export { boxIconography, boxIconographyAliases } from "./foundations/icons/index.js";
 export * from "./foundations/layout/index.js";
 export * from "./foundations/format/index.js";
+export * from "./foundations/files/index.js";
 export { anchorFloating, parsePlacement, resolvePosition, trackAnchor, } from "./foundations/overlay/index.js";
 export type { OverlayAlign, OverlayPlacement, OverlaySide, PositionOptions, PositionResult, } from "./foundations/overlay/index.js";
 export * from "./components/actions/button.js";
@@ -89,6 +90,7 @@ export * from "./components/output/code-block.js";
 export * from "./components/output/formatted-date.js";
 export * from "./components/output/relative-time.js";
 export * from "./components/output/formatted-number.js";
+export * from "./components/output/formatted-duration.js";
 export * from "./components/output/formatted-file-size.js";
 export * from "./components/layout/app-shell.js";
 export * from "./components/layout/divider.js";

package/dist/index.js

@@ -9,6 +9,9 @@ export { boxIconography, boxIconographyAliases } from "./foundations/icons/index
 export * from "./foundations/layout/index.js";
 // Foundations: locale-aware typed-value formatting (shared by box-formatted-*)
 export * from "./foundations/format/index.js";
+// Foundations: reading dropped files and folders (shared by box-drop-zone and
+// the content-uploader pattern)
+export * from "./foundations/files/index.js";
 // Foundations: viewport-aware overlay positioning (for building custom overlays)
 export { anchorFloating, parsePlacement, resolvePosition, trackAnchor, } from "./foundations/overlay/index.js";
 // Components: actions
@@ -97,6 +100,7 @@ export * from "./components/output/code-block.js";
 export * from "./components/output/formatted-date.js";
 export * from "./components/output/relative-time.js";
 export * from "./components/output/formatted-number.js";
+export * from "./components/output/formatted-duration.js";
 export * from "./components/output/formatted-file-size.js";
 // Components: layout
 export * from "./components/layout/app-shell.js";

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

@@ -13,6 +13,7 @@ export declare class ContentUploader extends BaseElement {
     private footerEl;
     private summaryEl;
     private queueSignature;
+    private updateScheduled;
     get folderId(): string | null;
     set folderId(value: string | null);
     get token(): string | null;
@@ -30,6 +31,25 @@ export declare class ContentUploader extends BaseElement {
     /** Maximum accepted file size in bytes. */
     get maxFileSize(): number | undefined;
     set maxFileSize(value: number | undefined);
+    /**
+     * Most files the queue will hold, default 100 — the same ceiling
+     * box-ui-elements uses. Further files are rejected with
+     * `file-limit-reached` rather than enqueued.
+     *
+     * A default matters here in a way it does not for the other constraints: a
+     * dropped folder can carry thousands of files, and an unbounded queue has no
+     * back pressure at all.
+     */
+    get fileLimit(): number;
+    set fileLimit(value: number);
+    /**
+     * Make the browse dialog pick a folder rather than files.
+     *
+     * Dropping a folder works either way; the platform only forces the choice on
+     * the click-to-browse path.
+     */
+    get directories(): boolean;
+    set directories(value: boolean);
     get dropLabel(): string;
     set dropLabel(value: string);
     get dropMessage(): string;
@@ -39,10 +59,24 @@ export declare class ContentUploader extends BaseElement {
     get state(): Readonly<UploaderState> | null;
     /** The live queue controller. Null until configured. */
     get uploaderController(): ContentUploaderController | null;
+    /**
+     * Attributes that only affect how the drop zone presents itself. Everything
+     * else feeds the session config, so changing it re-creates the queue.
+     */
+    private static readonly PRESENTATION_ATTRIBUTES;
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
     connectedCallback(): void;
     disconnectedCallback(): void;
     addFiles(files: UploadFileLike[]): UploadQueueItem[];
+    /**
+     * Queue files that carry a directory path relative to the destination, the
+     * way a dropped folder does. Requires `createFolder` on the transport;
+     * without it each pathed file is rejected with `folder-unsupported`.
+     */
+    addEntries(entries: Array<{
+        file: UploadFileLike;
+        path?: string;
+    }>): UploadQueueItem[];
     start(): void;
     cancelItem(itemId: string): void;
     retryItem(itemId: string): void;
@@ -53,6 +87,15 @@ export declare class ContentUploader extends BaseElement {
     private startController;
     private readConfig;
     private subscribeToController;
+    /**
+     * Coalesce the re-render for a burst of controller events.
+     *
+     * A folder drop adds up to `fileLimit` items in one go, each emitting its own
+     * `itemAdded`; rendering per event rebuilt the whole queue once per file,
+     * which is quadratic in the size of the drop. One render per microtask turn
+     * gives the same result for a fraction of the work.
+     */
+    private scheduleUpdate;
     private teardownController;
     protected renderTemplate(): void;
     protected setupListeners(): void;

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

@@ -7,6 +7,8 @@ import { BaseElement } from "../../core/index.js";
 import { boeMotionDuration, boeMotionEasing } from "../../foundations/motion/index.js";
 import { boePanel, boeRadius } from "../../foundations/geometry/index.js";
 const DEFAULT_TAG_NAME = "box-content-uploader";
+/** Matches the box-ui-elements ceiling, so a port behaves the same way. */
+const DEFAULT_FILE_LIMIT = 100;
 const escapeHtml = (value) => value
     .replaceAll("&", "&")
     .replaceAll("<", "&lt;")
@@ -216,7 +218,9 @@ export class ContentUploader extends BaseElement {
             "concurrency",
             "drop-label",
             "drop-message",
+            "directories",
             "extensions",
+            "file-limit",
             "folder-id",
             "language",
             "max-file-size",
@@ -232,6 +236,7 @@ export class ContentUploader extends BaseElement {
     footerEl;
     summaryEl;
     queueSignature = "";
+    updateScheduled = false;
     get folderId() {
         return this.getAttribute("folder-id");
     }
@@ -293,6 +298,34 @@ export class ContentUploader extends BaseElement {
         }
         this.removeAttribute("max-file-size");
     }
+    /**
+     * Most files the queue will hold, default 100 — the same ceiling
+     * box-ui-elements uses. Further files are rejected with
+     * `file-limit-reached` rather than enqueued.
+     *
+     * A default matters here in a way it does not for the other constraints: a
+     * dropped folder can carry thousands of files, and an unbounded queue has no
+     * back pressure at all.
+     */
+    get fileLimit() {
+        const raw = Number(this.getAttribute("file-limit"));
+        return Number.isFinite(raw) && raw >= 1 ? Math.floor(raw) : DEFAULT_FILE_LIMIT;
+    }
+    set fileLimit(value) {
+        this.setAttribute("file-limit", String(value));
+    }
+    /**
+     * Make the browse dialog pick a folder rather than files.
+     *
+     * Dropping a folder works either way; the platform only forces the choice on
+     * the click-to-browse path.
+     */
+    get directories() {
+        return this.hasAttribute("directories");
+    }
+    set directories(value) {
+        this.toggleAttribute("directories", value);
+    }
     get dropLabel() {
         return this.getAttribute("drop-label") ?? "Upload files";
     }
@@ -319,9 +352,17 @@ export class ContentUploader extends BaseElement {
     get uploaderController() {
         return this.controller;
     }
+    /**
+     * Attributes that only affect how the drop zone presents itself. Everything
+     * else feeds the session config, so changing it re-creates the queue.
+     */
+    static PRESENTATION_ATTRIBUTES = new Set([
+        "directories",
+        "drop-label",
+        "drop-message",
+    ]);
     attributeChangedCallback(name, oldValue, newValue) {
-        // Drop-zone copy is presentation-only; everything else re-creates the queue.
-        if (name !== "drop-label" && name !== "drop-message") {
+        if (!ContentUploader.PRESENTATION_ATTRIBUTES.has(name)) {
             this.scheduleStart();
         }
         super.attributeChangedCallback(name, oldValue, newValue);
@@ -336,6 +377,14 @@ export class ContentUploader extends BaseElement {
     addFiles(files) {
         return this.controller?.addFiles(files) ?? [];
     }
+    /**
+     * Queue files that carry a directory path relative to the destination, the
+     * way a dropped folder does. Requires `createFolder` on the transport;
+     * without it each pathed file is rejected with `folder-unsupported`.
+     */
+    addEntries(entries) {
+        return this.controller?.addEntries(entries) ?? [];
+    }
     start() {
         this.controller?.start();
     }
@@ -396,6 +445,7 @@ export class ContentUploader extends BaseElement {
             autoStart: this.autoStart,
             concurrency: this.concurrency,
             extensions: this.extensions.length ? this.extensions : undefined,
+            fileLimit: this.fileLimit,
             folderId: this.folderId,
             language: this.language ?? undefined,
             maxFileSizeBytes: this.maxFileSize,
@@ -422,10 +472,28 @@ export class ContentUploader extends BaseElement {
                 composed: true,
                 detail: payload,
             }));
+            this.scheduleUpdate();
+        }));
+    }
+    /**
+     * Coalesce the re-render for a burst of controller events.
+     *
+     * A folder drop adds up to `fileLimit` items in one go, each emitting its own
+     * `itemAdded`; rendering per event rebuilt the whole queue once per file,
+     * which is quadratic in the size of the drop. One render per microtask turn
+     * gives the same result for a fraction of the work.
+     */
+    scheduleUpdate() {
+        if (!this.isRendered || this.updateScheduled) {
+            return;
+        }
+        this.updateScheduled = true;
+        queueMicrotask(() => {
+            this.updateScheduled = false;
             if (this.isRendered) {
                 this.update();
             }
-        }));
+        });
     }
     teardownController() {
         for (const unsubscribe of this.unsubscribeFns) {
@@ -458,9 +526,12 @@ export class ContentUploader extends BaseElement {
     }
     setupListeners() {
         this.dropZoneEl.addEventListener("files-selected", event => {
-            const files = event.detail?.files ?? [];
-            if (files.length) {
-                this.addFiles(files);
+            const detail = event.detail;
+            // Prefer entries: they carry the folder each file came from. `files` is
+            // the flat fallback for a host dispatching this event by hand.
+            const entries = detail?.entries ?? (detail?.files ?? []).map(file => ({ file, path: "" }));
+            if (entries.length) {
+                this.controller?.addEntries(entries);
             }
         });
         this.queueEl.addEventListener("click", event => {
@@ -536,6 +607,14 @@ export class ContentUploader extends BaseElement {
         }
         this.dropZoneEl.label = this.dropLabel;
         this.dropZoneEl.message = this.dropMessage;
+        this.dropZoneEl.directories = this.directories;
+        // Greys out the files the queue would reject anyway, so the picker stops
+        // offering a choice that ends in a rejection. The queue's own check still
+        // decides — `accept` is advisory, and does nothing for a drop.
+        // A leading dot is optional in `extensions`, as it is for the queue check.
+        this.dropZoneEl.accept = this.extensions
+            .map(extension => `.${extension.replace(/^\./, "")}`)
+            .join(",");
         const items = this.controller?.getState().items ?? [];
         // Structural changes rebuild the rows; progress ticks patch the bars in
         // place so in-row focus (Cancel while uploading) survives.

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.15.0",
+  "version": "0.17.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",