@unofficialbox/box-open-elements 0.16.0 → 0.18.0

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

@@ -5,15 +5,70 @@ export declare class DropZone extends BaseElement {
     private dragging;
     private zoneEl;
     private inputEl;
+    private folderInputEl;
     private labelEl;
     private messageEl;
+    private browseEl;
+    private folderBrowseEl;
+    private separatorEl;
+    private illustrationEl;
     get label(): string;
     set label(value: string);
     get message(): string;
     set message(value: string);
     get description(): string;
     set description(value: string);
+    /**
+     * Offer folder selection from the browse controls as well as files.
+     *
+     * A single `<input>` is either a file picker or a folder picker, never both —
+     * so this adds a *second* control backed by its own `webkitdirectory` input
+     * rather than converting the first, which is how box-ui-elements does it and
+     * means a person is never made to choose between the two.
+     *
+     * Drag-and-drop reads folders regardless; a dropped directory is always
+     * traversed whatever this is set to.
+     */
+    get directories(): boolean;
+    set directories(value: boolean);
+    /** Text of the file-browse control. */
+    get browseLabel(): string;
+    set browseLabel(value: string);
+    /** Text of the folder-browse control, shown only when `directories` is set. */
+    get folderLabel(): string;
+    set folderLabel(value: string);
+    /**
+     * `"compact"` (default) keeps the small inline target; `"hero"` is the tall
+     * centred empty state, with room for an illustration in the `illustration`
+     * slot.
+     */
+    get variant(): string;
+    set variant(value: string);
+    /**
+     * 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";
@@ -10,12 +11,19 @@ const dropZoneStyles = `
     font: inherit;
   }
 
+  /* Without this, the host's own display:block beats the UA rule for [hidden]
+     and the element stays visible when a host hides it. */
+  :host([hidden]) {
+    display: none;
+  }
+
   [part="zone"] {
     position: relative;
     display: grid;
     gap: 0.55rem;
     justify-items: start;
     padding: 0.75rem;
+    text-align: start;
     border: 1.5px dashed color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 16%, var(--boe-token-stroke-stroke, #e8e8e8) 84%);
     border-radius: ${boeRadius.large};
     background: var(--boe-token-surface-surface-secondary, #fbfbfb);
@@ -48,7 +56,9 @@ const dropZoneStyles = `
       0 14px 28px rgba(15, 23, 42, 0.05);
   }
 
-  [part="input"] {
+  /* The inputs are never the focusable control — the browse buttons are — so
+     they are taken out of the tab order rather than merely hidden. */
+  [part~="file-input"] {
     position: absolute;
     inline-size: 1px;
     block-size: 1px;
@@ -56,8 +66,6 @@ const dropZoneStyles = `
     pointer-events: none;
   }
 
-  ${boeFocusVisibleStyles('[part="input"]')}
-
   [part="label"] {
     font-size: 1rem;
     font-weight: 700;
@@ -69,17 +77,99 @@ const dropZoneStyles = `
     line-height: 1.5;
     max-width: 34ch;
   }
+
+  [part="actions"] {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: baseline;
+    gap: 0.25rem 0.5rem;
+  }
+
+  [part~="browse"] {
+    appearance: none;
+    margin: 0;
+    padding: 0;
+    border: 0;
+    background: none;
+    font: inherit;
+    font-weight: 600;
+    color: var(--boe-token-surface-surface-brand, #0061d5);
+    text-decoration: none;
+    cursor: pointer;
+    border-radius: ${boeRadius.control};
+  }
+
+  [part~="browse"]:hover {
+    text-decoration: underline;
+  }
+
+  ${boeFocusVisibleStyles('[part~="browse"]')}
+
+  [part="separator"] {
+    color: var(--boe-token-text-text-secondary, #6f6f6f);
+  }
+
+  /* Hero: the full-height empty state, centred, with room for an illustration.
+     Matches the shape box-ui-elements gives its uploader. */
+  :host([variant="hero"]) [part="zone"] {
+    justify-items: center;
+    align-content: center;
+    gap: 0.35rem;
+    min-block-size: 18rem;
+    padding: 2rem 1.5rem;
+    text-align: center;
+  }
+
+  :host([variant="hero"]) [part="label"] {
+    font-size: 1.0625rem;
+  }
+
+  :host([variant="hero"]) [part~="description"] {
+    max-width: 42ch;
+  }
+
+  [part="illustration"] {
+    display: none;
+  }
+
+  :host([variant="hero"]) [part="illustration"] {
+    display: block;
+    /* The art carries its own padding inside the viewBox, so the box is set a
+       little larger than the 130px box-ui-elements uses for the drawn area. */
+    inline-size: min(10.5rem, 70%);
+    margin-block-end: 0.15rem;
+  }
+
+  ::slotted([slot="illustration"]) {
+    display: block;
+    inline-size: 100%;
+    block-size: auto;
+  }
 `;
 export class DropZone extends BaseElement {
     static tagName = DEFAULT_TAG_NAME;
     static get observedAttributes() {
-        return ["description", "label", "message"];
+        return [
+            "accept",
+            "browse-label",
+            "description",
+            "directories",
+            "folder-label",
+            "label",
+            "message",
+            "variant",
+        ];
     }
     dragging = false;
     zoneEl;
     inputEl;
+    folderInputEl;
     labelEl;
     messageEl;
+    browseEl;
+    folderBrowseEl;
+    separatorEl;
+    illustrationEl;
     get label() {
         return this.getAttribute("label") ?? "Upload files";
     }
@@ -98,20 +188,95 @@ export class DropZone extends BaseElement {
     set description(value) {
         this.setAttribute("description", value);
     }
+    /**
+     * Offer folder selection from the browse controls as well as files.
+     *
+     * A single `<input>` is either a file picker or a folder picker, never both —
+     * so this adds a *second* control backed by its own `webkitdirectory` input
+     * rather than converting the first, which is how box-ui-elements does it and
+     * means a person is never made to choose between the two.
+     *
+     * Drag-and-drop reads folders regardless; a dropped directory is always
+     * traversed whatever this is set to.
+     */
+    get directories() {
+        return this.hasAttribute("directories");
+    }
+    set directories(value) {
+        this.toggleAttribute("directories", value);
+    }
+    /** Text of the file-browse control. */
+    get browseLabel() {
+        return this.getAttribute("browse-label") ?? "Browse your device";
+    }
+    set browseLabel(value) {
+        this.setAttribute("browse-label", value);
+    }
+    /** Text of the folder-browse control, shown only when `directories` is set. */
+    get folderLabel() {
+        return this.getAttribute("folder-label") ?? "Select folders";
+    }
+    set folderLabel(value) {
+        this.setAttribute("folder-label", value);
+    }
+    /**
+     * `"compact"` (default) keeps the small inline target; `"hero"` is the tall
+     * centred empty state, with room for an illustration in the `illustration`
+     * slot.
+     */
+    get variant() {
+        return this.getAttribute("variant") === "hero" ? "hero" : "compact";
+    }
+    set variant(value) {
+        this.setAttribute("variant", 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;
         }
+        // A div rather than a label wrapping the input: the browse controls are
+        // real buttons, and a button inside a label is both ambiguous to assistive
+        // technology and prone to firing the picker twice.
         this.shadowRoot.innerHTML = `
       <style>${dropZoneStyles}</style>
-      <label part="zone">
-        <input type="file" part="input" multiple />
+      <div part="zone">
+        <input type="file" part="input file-input" multiple tabindex="-1" aria-hidden="true" />
+        <input type="file" part="folder-input file-input" multiple tabindex="-1" aria-hidden="true" webkitdirectory />
+        <span part="illustration"><slot name="illustration"></slot></span>
         <strong part="label"></strong>
         <span part="description message"></span>
-      </label>
+        <span part="actions">
+          <button type="button" part="browse browse-files"></button>
+          <span part="separator" hidden>or</span>
+          <button type="button" part="browse browse-folders" hidden></button>
+        </span>
+      </div>
     `;
         this.zoneEl = this.shadowRoot.querySelector('[part="zone"]');
-        this.inputEl = this.shadowRoot.querySelector('[part="input"]');
+        this.inputEl = this.shadowRoot.querySelector('[part~="input"]');
+        this.folderInputEl = this.shadowRoot.querySelector('[part~="folder-input"]');
+        this.browseEl = this.shadowRoot.querySelector('[part~="browse-files"]');
+        this.folderBrowseEl = this.shadowRoot.querySelector('[part~="browse-folders"]');
+        this.separatorEl = this.shadowRoot.querySelector('[part="separator"]');
+        this.illustrationEl = this.shadowRoot.querySelector('[part="illustration"]');
         this.labelEl = this.shadowRoot.querySelector('[part="label"]');
         this.messageEl = this.shadowRoot.querySelector('[part~="description"]');
     }
@@ -134,22 +299,63 @@ 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);
+            });
+        });
+        // Clicking the body of the zone still opens the file picker, as it did when
+        // the zone was a label. Clicks that land on a button are left alone, or the
+        // picker would be asked to open twice.
+        this.zoneEl.addEventListener("click", event => {
+            if (event.target.closest('[part~="browse"]')) {
+                return;
+            }
+            this.inputEl.click();
+        });
+        this.browseEl.addEventListener("click", () => {
+            this.inputEl.click();
         });
-        this.inputEl.addEventListener("change", () => {
-            const files = Array.from(this.inputEl.files ?? []);
-            this.dispatchEvent(new CustomEvent("files-selected", {
-                bubbles: true,
-                composed: true,
-                detail: { files },
-            }));
+        this.folderBrowseEl.addEventListener("click", () => {
+            this.folderInputEl.click();
         });
+        for (const input of [this.inputEl, this.folderInputEl]) {
+            input.addEventListener("change", () => {
+                // A folder picked through `webkitdirectory` reports its tree through
+                // each file's webkitRelativePath rather than through entries.
+                this.emitSelection(entriesFromFileList(Array.from(input.files ?? [])));
+                // Cleared so choosing the same folder twice in a row still fires.
+                input.value = "";
+            });
+        }
+    }
+    /**
+     * 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) {
@@ -158,6 +364,21 @@ export class DropZone extends BaseElement {
         this.zoneEl.dataset.dragging = String(this.dragging);
         this.labelEl.textContent = this.label;
         this.messageEl.textContent = this.message;
+        // Hidden rather than left empty, so it does not open a gap in the stack.
+        this.messageEl.hidden = this.message.trim() === "";
+        this.browseEl.textContent = this.browseLabel;
+        this.folderBrowseEl.textContent = this.folderLabel;
+        // The folder control is a second input rather than a mode on the first, so
+        // files and folders are both reachable instead of mutually exclusive.
+        const directories = this.directories;
+        this.folderBrowseEl.hidden = !directories;
+        this.separatorEl.hidden = !directories;
+        // webkitdirectory is a property as well as an attribute, and only the
+        // property is honoured reliably once the input exists.
+        this.folderInputEl.webkitdirectory = true;
+        // A folder picker offers folders, so an extension filter would only mislead.
+        this.inputEl.accept = this.accept;
+        this.illustrationEl.hidden = this.variant !== "hero";
     }
 }
 DropZone.register();

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";