@unofficialbox/box-open-elements 0.4.0 → 0.6.0

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

@@ -0,0 +1,39 @@
+import { Controller } from "../../core/controller.js";
+import type { UploadFileLike, UploadQueueItem, UploaderEvents, UploaderSessionConfig, UploaderState } from "./types.js";
+/**
+ * Headless upload queue: validates files against the session constraints,
+ * runs up to `concurrency` transport uploads at a time, tracks per-item
+ * progress, and supports cancel / retry / remove. The transport does the
+ * actual moving of bytes; this controller never touches the network.
+ */
+export declare class ContentUploaderController extends Controller<UploaderState, UploaderEvents> {
+    readonly config: UploaderSessionConfig;
+    private counter;
+    private readonly files;
+    private readonly abortControllers;
+    constructor(config: UploaderSessionConfig);
+    get concurrency(): number;
+    get autoStart(): boolean;
+    /**
+     * Validate and enqueue files. Rejected files emit `itemRejected` and never
+     * enter the queue. Returns the accepted queue items.
+     */
+    addFiles(files: UploadFileLike[]): UploadQueueItem[];
+    /** Begin (or resume) uploading queued items, up to the concurrency limit. */
+    start(): void;
+    /** Abort an in-flight upload or withdraw a queued item. */
+    cancelItem(itemId: string): void;
+    /** Requeue a failed or cancelled item and resume the pump. */
+    retryItem(itemId: string): void;
+    /** Drop a settled item from the queue. In-flight items must be cancelled first. */
+    removeItem(itemId: string): void;
+    /** Drop every settled (succeeded / cancelled) item; failed stay for retry. */
+    clearCompleted(): void;
+    destroy(): void;
+    private getItem;
+    private setItems;
+    private patchItem;
+    private pump;
+    private uploadItem;
+    private checkDrained;
+}

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

@@ -0,0 +1,227 @@
+import { Controller } from "../../core/controller.js";
+import { resolveUploadRejection, summarizeUploadQueue } from "./types.js";
+const DEFAULT_CONCURRENCY = 2;
+const isAbortError = (error) => error instanceof Error && (error.name === "AbortError" || error.message === "AbortError");
+/**
+ * Headless upload queue: validates files against the session constraints,
+ * runs up to `concurrency` transport uploads at a time, tracks per-item
+ * progress, and supports cancel / retry / remove. The transport does the
+ * actual moving of bytes; this controller never touches the network.
+ */
+export class ContentUploaderController extends Controller {
+    config;
+    counter = 0;
+    files = new Map();
+    abortControllers = new Map();
+    constructor(config) {
+        super({ items: [], uploading: false });
+        this.config = config;
+    }
+    get concurrency() {
+        const value = this.config.concurrency ?? DEFAULT_CONCURRENCY;
+        return Number.isFinite(value) && value > 0 ? Math.floor(value) : DEFAULT_CONCURRENCY;
+    }
+    get autoStart() {
+        return this.config.autoStart ?? true;
+    }
+    /**
+     * Validate and enqueue files. Rejected files emit `itemRejected` and never
+     * enter the queue. Returns the accepted queue items.
+     */
+    addFiles(files) {
+        const added = [];
+        for (const file of files) {
+            const rejection = resolveUploadRejection(file, this.config);
+            if (rejection) {
+                this.emit("itemRejected", { file, reason: rejection });
+                continue;
+            }
+            this.counter += 1;
+            const item = {
+                id: `upload-${this.counter}`,
+                name: file.name,
+                size: file.size,
+                status: "queued",
+                progress: 0,
+            };
+            this.files.set(item.id, file);
+            added.push(item);
+        }
+        if (added.length) {
+            this.setItems([...this.state.items, ...added]);
+            for (const item of added) {
+                this.emit("itemAdded", { item });
+            }
+            if (this.autoStart) {
+                this.start();
+            }
+        }
+        return added;
+    }
+    /** Begin (or resume) uploading queued items, up to the concurrency limit. */
+    start() {
+        this.pump();
+    }
+    /** Abort an in-flight upload or withdraw a queued item. */
+    cancelItem(itemId) {
+        const item = this.getItem(itemId);
+        if (!item) {
+            return;
+        }
+        if (item.status === "uploading") {
+            // The upload promise handler transitions the item to "cancelled".
+            this.abortControllers.get(itemId)?.abort();
+            return;
+        }
+        if (item.status === "queued") {
+            const cancelled = this.patchItem(itemId, { status: "cancelled" });
+            if (cancelled) {
+                this.emit("itemCancelled", { item: cancelled });
+            }
+            this.checkDrained();
+        }
+    }
+    /** Requeue a failed or cancelled item and resume the pump. */
+    retryItem(itemId) {
+        const item = this.getItem(itemId);
+        if (!item || (item.status !== "failed" && item.status !== "cancelled")) {
+            return;
+        }
+        this.patchItem(itemId, { status: "queued", progress: 0, errorMessage: undefined });
+        this.start();
+    }
+    /** Drop a settled item from the queue. In-flight items must be cancelled first. */
+    removeItem(itemId) {
+        const item = this.getItem(itemId);
+        if (!item || item.status === "uploading") {
+            return;
+        }
+        this.files.delete(itemId);
+        this.setItems(this.state.items.filter(entry => entry.id !== itemId));
+        this.emit("itemRemoved", { itemId });
+    }
+    /** Drop every settled (succeeded / cancelled) item; failed stay for retry. */
+    clearCompleted() {
+        const remaining = this.state.items.filter(item => item.status !== "succeeded" && item.status !== "cancelled");
+        if (remaining.length === this.state.items.length) {
+            return;
+        }
+        for (const item of this.state.items) {
+            if (item.status === "succeeded" || item.status === "cancelled") {
+                this.files.delete(item.id);
+            }
+        }
+        this.setItems(remaining);
+    }
+    destroy() {
+        for (const abortController of this.abortControllers.values()) {
+            abortController.abort();
+        }
+        this.abortControllers.clear();
+        super.destroy();
+    }
+    getItem(itemId) {
+        return this.state.items.find(item => item.id === itemId);
+    }
+    setItems(items) {
+        this.setState({
+            items,
+            uploading: items.some(item => item.status === "uploading"),
+        });
+        this.emit("queueChanged", { items });
+    }
+    patchItem(itemId, patch) {
+        let patched;
+        const items = this.state.items.map(item => {
+            if (item.id !== itemId) {
+                return item;
+            }
+            patched = { ...item, ...patch };
+            return patched;
+        });
+        if (patched) {
+            this.setItems(items);
+        }
+        return patched;
+    }
+    pump() {
+        while (summarizeUploadQueue(this.state.items).uploading < this.concurrency &&
+            this.state.items.some(item => item.status === "queued")) {
+            const next = this.state.items.find(item => item.status === "queued");
+            if (!next) {
+                return;
+            }
+            void this.uploadItem(next.id);
+        }
+    }
+    async uploadItem(itemId) {
+        const file = this.files.get(itemId);
+        const item = this.getItem(itemId);
+        if (!file || !item || item.status !== "queued") {
+            return;
+        }
+        const abortController = typeof AbortController === "function" ? new AbortController() : null;
+        if (abortController) {
+            this.abortControllers.set(itemId, abortController);
+        }
+        const started = this.patchItem(itemId, { status: "uploading", progress: 0 });
+        if (started) {
+            this.emit("itemStarted", { item: started });
+        }
+        try {
+            const result = await this.config.transport.uploadFile({
+                file,
+                fileName: item.name,
+                folderId: this.config.folderId,
+                token: this.config.token,
+                language: this.config.language,
+                ...(abortController ? { signal: abortController.signal } : {}),
+                onProgress: fraction => {
+                    const clamped = Math.max(0, Math.min(1, fraction));
+                    const progressed = this.patchItem(itemId, { progress: clamped });
+                    if (progressed) {
+                        this.emit("itemProgress", { item: progressed });
+                    }
+                },
+            });
+            const succeeded = this.patchItem(itemId, {
+                status: "succeeded",
+                progress: 1,
+                fileId: result.fileId,
+            });
+            if (succeeded) {
+                this.emit("itemSucceeded", { item: succeeded });
+            }
+        }
+        catch (error) {
+            if (abortController?.signal.aborted || isAbortError(error)) {
+                const cancelled = this.patchItem(itemId, { status: "cancelled" });
+                if (cancelled) {
+                    this.emit("itemCancelled", { item: cancelled });
+                }
+            }
+            else {
+                const message = error instanceof Error ? error.message : "Upload failed";
+                const failed = this.patchItem(itemId, { status: "failed", errorMessage: message });
+                if (failed) {
+                    this.emit("itemFailed", { item: failed });
+                }
+            }
+        }
+        finally {
+            this.abortControllers.delete(itemId);
+            this.pump();
+            this.checkDrained();
+        }
+    }
+    checkDrained() {
+        const summary = summarizeUploadQueue(this.state.items);
+        if (summary.total > 0 && summary.queued === 0 && summary.uploading === 0) {
+            this.emit("queueDrained", {
+                succeeded: summary.succeeded,
+                failed: summary.failed,
+                cancelled: summary.cancelled,
+            });
+        }
+    }
+}

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

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./controller.js";
+export * from "./box-transport.js";
+export * from "./content-uploader.js";

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

@@ -0,0 +1,8 @@
+// Upload queue contracts, constraints, and state types
+export * from "./types.js";
+// Headless queue controller
+export * from "./controller.js";
+// Box multipart upload transport
+export * from "./box-transport.js";
+// Composed workflow surface
+export * from "./content-uploader.js";

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

@@ -0,0 +1,120 @@
+/**
+ * The minimum surface the uploader needs from a file: browsers hand us `File`
+ * objects, tests and non-DOM callers can pass any Blob-like with a name.
+ */
+export interface UploadFileLike {
+    name: string;
+    size: number;
+}
+export type UploadItemStatus = "queued" | "uploading" | "succeeded" | "failed" | "cancelled";
+export interface UploadQueueItem {
+    /** Locally-assigned queue id — not the Box file id. */
+    id: string;
+    name: string;
+    size: number;
+    status: UploadItemStatus;
+    /** 0–1 fraction reported by the transport; 1 once the upload succeeds. */
+    progress: number;
+    /** Present when `status` is "failed". */
+    errorMessage?: string;
+    /** Remote file id from the transport once the upload succeeds. */
+    fileId?: string;
+}
+export interface UploadRequest {
+    file: UploadFileLike;
+    fileName: string;
+    folderId: string;
+    token: string;
+    language?: string;
+    signal?: AbortSignal;
+    /** Report fractional progress (0–1). Transports may only report completion. */
+    onProgress?: (fraction: number) => void;
+}
+export interface UploadResult {
+    fileId: string;
+    name?: string;
+    size?: number;
+}
+/**
+ * One narrow capability: move a single file to the destination folder. How —
+ * multipart, chunked upload sessions, a BFF — is the transport's business;
+ * the queue orchestration above it never changes.
+ */
+export interface UploadTransport {
+    uploadFile(request: UploadRequest): Promise<UploadResult>;
+}
+export interface UploaderConstraints {
+    /**
+     * Extension allowlist (case-insensitive, no leading dot) matched against
+     * the file name's suffix. Empty or omitted accepts every extension.
+     */
+    extensions?: string[];
+    /** Reject files larger than this many bytes. Omitted means no limit. */
+    maxFileSizeBytes?: number;
+}
+export interface UploaderSessionConfig extends UploaderConstraints {
+    folderId: string;
+    token: string;
+    transport: UploadTransport;
+    language?: string;
+    /** Simultaneous uploads. Defaults to 2. */
+    concurrency?: number;
+    /** Start uploading as soon as files are added. Defaults to true. */
+    autoStart?: boolean;
+}
+export type UploadRejectionReason = "extension-not-allowed" | "file-too-large";
+export interface UploaderState {
+    items: UploadQueueItem[];
+    /** True while any item is actively uploading. */
+    uploading: boolean;
+}
+export interface UploaderEvents {
+    itemAdded: {
+        item: UploadQueueItem;
+    };
+    itemRejected: {
+        file: UploadFileLike;
+        reason: UploadRejectionReason;
+    };
+    itemStarted: {
+        item: UploadQueueItem;
+    };
+    itemProgress: {
+        item: UploadQueueItem;
+    };
+    itemSucceeded: {
+        item: UploadQueueItem;
+    };
+    itemFailed: {
+        item: UploadQueueItem;
+    };
+    itemCancelled: {
+        item: UploadQueueItem;
+    };
+    itemRemoved: {
+        itemId: string;
+    };
+    queueChanged: {
+        items: UploadQueueItem[];
+    };
+    /** Fired when the last active item settles and nothing is queued. */
+    queueDrained: {
+        succeeded: number;
+        failed: number;
+        cancelled: number;
+    };
+}
+/**
+ * Pure acceptance check — the single source of truth for what the uploader
+ * lets into its queue. Returns the rejection reason, or null when accepted.
+ */
+export declare const resolveUploadRejection: (file: UploadFileLike, constraints: UploaderConstraints) => UploadRejectionReason | null;
+export interface UploadQueueSummary {
+    total: number;
+    queued: number;
+    uploading: number;
+    succeeded: number;
+    failed: number;
+    cancelled: number;
+}
+export declare const summarizeUploadQueue: (items: readonly UploadQueueItem[]) => UploadQueueSummary;

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

@@ -0,0 +1,38 @@
+const normalizeExtension = (value) => value.replace(/^\./, "").toLowerCase();
+const resolveFileExtension = (name) => {
+    const dotIndex = name.lastIndexOf(".");
+    if (dotIndex <= 0 || dotIndex === name.length - 1) {
+        return null;
+    }
+    return normalizeExtension(name.slice(dotIndex + 1));
+};
+/**
+ * Pure acceptance check — the single source of truth for what the uploader
+ * lets into its queue. Returns the rejection reason, or null when accepted.
+ */
+export const resolveUploadRejection = (file, constraints) => {
+    if (constraints.extensions?.length) {
+        const extension = resolveFileExtension(file.name);
+        if (!extension || !constraints.extensions.map(normalizeExtension).includes(extension)) {
+            return "extension-not-allowed";
+        }
+    }
+    if (constraints.maxFileSizeBytes != null && file.size > constraints.maxFileSizeBytes) {
+        return "file-too-large";
+    }
+    return null;
+};
+export const summarizeUploadQueue = (items) => {
+    const summary = {
+        total: items.length,
+        queued: 0,
+        uploading: 0,
+        succeeded: 0,
+        failed: 0,
+        cancelled: 0,
+    };
+    for (const item of items) {
+        summary[item.status] += 1;
+    }
+    return summary;
+};

package/dist/patterns/diff/compare-view.d.ts

@@ -0,0 +1,47 @@
+import type { CompareSyncMode } from "./types.js";
+import { BaseElement } from "../../core/index.js";
+/**
+ * Side-by-side comparison shell with scroll-locked panes — doc-vs-doc review
+ * for the cases the diff table cannot serve, where the two things being
+ * compared are rendered documents rather than lines of text.
+ *
+ * The scroll maths lives in `mapScrollPosition`, which is pure, so the
+ * interesting behaviour is testable without a layout engine and a host can
+ * reuse it to drive its own panes.
+ *
+ * The subtle part is the **feedback loop**. Scrolling the left pane sets the
+ * right pane's `scrollTop`, which fires the right pane's own scroll event,
+ * which would scroll the left pane back — the two panes fight, and a slow
+ * drag turns into a stutter. Each programmatic scroll therefore marks the
+ * pane it is about to move, and that pane's next scroll event is swallowed.
+ *
+ * The mark is cleared immediately when the assignment does not actually move
+ * the pane (already there, or clamped at an end): no scroll event will fire
+ * in that case, so a mark left set would swallow the user's *next* real
+ * scroll instead.
+ */
+export declare class CompareView extends BaseElement {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    private hostEl;
+    private leftEl;
+    private rightEl;
+    private toggleEl;
+    /** The pane whose next scroll event came from us, not from the user. */
+    private echoPane;
+    get heading(): string;
+    set heading(value: string);
+    get leftLabel(): string;
+    set leftLabel(value: string);
+    get rightLabel(): string;
+    set rightLabel(value: string);
+    /** Scroll lock. On by default — comparing is the point of the component. */
+    get sync(): boolean;
+    set sync(value: boolean);
+    get syncMode(): CompareSyncMode;
+    set syncMode(value: CompareSyncMode);
+    private syncFrom;
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    protected update(): void;
+}