@unofficialbox/box-open-elements 0.5.0 → 0.6.0

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

@@ -20,11 +20,13 @@ const createInitialState = (config) => ({
         totalCount: null,
     },
     selectedItemIds: [],
+    sort: null,
     view: createInitialExplorerViewState(),
 });
 export class ContentExplorerController extends Controller {
     config;
     activeLoadRequestId = 0;
+    activeLoadAbortController = null;
     actionsController;
     collectionController;
     navigationController;
@@ -104,11 +106,21 @@ export class ContentExplorerController extends Controller {
         if (!this.state.connected) {
             return;
         }
+        // Invalidate and abort any in-flight load, then reset the sub-controllers
+        // BEFORE snapshotting their state so the facade and navigation agree on
+        // being back at the root.
+        this.activeLoadRequestId += 1;
+        this.activeLoadAbortController?.abort();
+        this.activeLoadAbortController = null;
+        this.collectionController.reset();
+        this.navigationController.reset();
         this.setState({
             ...this.state,
+            availableActionsByItemId: {},
             breadcrumbs: [],
             connected: false,
-            currentFolder: this.navigationController.getState().currentFolder,
+            currentFolder: null,
+            currentFolderId: this.config.rootFolderId,
             error: null,
             items: [],
             loading: false,
@@ -116,9 +128,6 @@ export class ContentExplorerController extends Controller {
             selectedItemIds: [],
             view: createInitialExplorerViewState(),
         });
-        this.activeLoadRequestId += 1;
-        this.collectionController.reset();
-        this.navigationController.reset();
         this.emit("viewChanged", { view: this.state.view });
         this.emit("disconnected", undefined);
     }
@@ -259,6 +268,108 @@ export class ContentExplorerController extends Controller {
             await this.navigateTo(item.id);
         }
     }
+    async setSort(sortOrSortBy, direction) {
+        const sort = sortOrSortBy === null
+            ? null
+            : typeof sortOrSortBy === "string"
+                ? { sortBy: sortOrSortBy, direction: direction ?? "ASC" }
+                : sortOrSortBy;
+        const current = this.state.sort;
+        if (current?.sortBy === sort?.sortBy && current?.direction === sort?.direction) {
+            return;
+        }
+        this.setState({
+            ...this.state,
+            sort,
+        });
+        this.emit("sortChanged", { sort });
+        if (this.state.connected) {
+            this.collectionController.reset();
+            await this.reload();
+        }
+    }
+    /** Create a folder in the current folder, then refresh the collection. */
+    async createFolder(name) {
+        const createFolder = this.config.transport.createFolder;
+        if (!createFolder) {
+            throw new Error("Explorer transport does not support folder creation");
+        }
+        const trimmed = name.trim();
+        if (!trimmed || !this.state.connected) {
+            return null;
+        }
+        return this.runMutation("create-folder", undefined, async () => {
+            const item = await createFolder({
+                parentFolderId: this.state.currentFolderId,
+                name: trimmed,
+                token: this.config.token,
+                language: this.config.language,
+            });
+            this.emit("itemMutated", { kind: "create-folder", item, itemId: item.id });
+            return item;
+        });
+    }
+    /** Rename an item in the current collection, then refresh. */
+    async renameItem(itemId, name) {
+        const renameItem = this.config.transport.renameItem;
+        if (!renameItem) {
+            throw new Error("Explorer transport does not support rename");
+        }
+        const item = this.state.items.find(entry => entry.id === itemId);
+        const trimmed = name.trim();
+        if (!item || !trimmed || !this.state.connected) {
+            return null;
+        }
+        return this.runMutation("rename", itemId, async () => {
+            const renamed = await renameItem({
+                itemId,
+                itemType: item.type,
+                name: trimmed,
+                token: this.config.token,
+                language: this.config.language,
+            });
+            this.emit("itemMutated", { kind: "rename", item: renamed, itemId });
+            return renamed;
+        });
+    }
+    /** Delete an item from the current collection, then refresh. */
+    async deleteItem(itemId) {
+        const deleteItem = this.config.transport.deleteItem;
+        if (!deleteItem) {
+            throw new Error("Explorer transport does not support delete");
+        }
+        const item = this.state.items.find(entry => entry.id === itemId);
+        if (!item || !this.state.connected) {
+            return false;
+        }
+        const result = await this.runMutation("delete", itemId, async () => {
+            await deleteItem({
+                itemId,
+                itemType: item.type,
+                token: this.config.token,
+                language: this.config.language,
+            });
+            this.emit("itemMutated", { kind: "delete", itemId });
+            return true;
+        });
+        return result ?? false;
+    }
+    async runMutation(kind, itemId, perform) {
+        try {
+            const result = await perform();
+            await this.reload();
+            return result;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : `Explorer ${kind} failed`;
+            this.setState({
+                ...this.state,
+                error: { code: "mutation_failed", message },
+            });
+            this.emit("mutationFailed", { kind, message, ...(itemId ? { itemId } : {}) });
+            return null;
+        }
+    }
     async reload() {
         await this.loadPage({ append: false });
     }
@@ -277,6 +388,11 @@ export class ContentExplorerController extends Controller {
         }
         const requestId = this.activeLoadRequestId + 1;
         this.activeLoadRequestId = requestId;
+        // Abort the superseded in-flight request so the transport can cancel its
+        // network work; the requestId guard already discards its response.
+        this.activeLoadAbortController?.abort();
+        const abortController = typeof AbortController === "function" ? new AbortController() : null;
+        this.activeLoadAbortController = abortController;
         this.setState({
             ...this.state,
             error: null,
@@ -284,6 +400,7 @@ export class ContentExplorerController extends Controller {
         this.collectionController.startLoading();
         const pagination = this.collectionController.getState().pagination;
         const requestOffset = append ? (pagination.nextOffset ?? this.collectionController.getState().items.length) : 0;
+        const sort = this.state.sort;
         try {
             if (this.state.view.mode === "search") {
                 const searchItems = this.config.transport.searchItems;
@@ -296,8 +413,10 @@ export class ContentExplorerController extends Controller {
                     ancestorFolderId: this.state.view.searchAncestorFolderId ?? undefined,
                     limit: pagination.limit,
                     offset: requestOffset,
+                    ...(sort ? { sortBy: sort.sortBy, sortDirection: sort.direction } : {}),
                     token: this.config.token,
                     language: this.config.language,
+                    ...(abortController ? { signal: abortController.signal } : {}),
                 });
                 this.applyLoadedSearch(requestId, result, append);
                 return;
@@ -306,14 +425,21 @@ export class ContentExplorerController extends Controller {
                 folderId: this.state.currentFolderId,
                 limit: pagination.limit,
                 offset: requestOffset,
+                ...(sort ? { sortBy: sort.sortBy, sortDirection: sort.direction } : {}),
                 token: this.config.token,
                 language: this.config.language,
+                ...(abortController ? { signal: abortController.signal } : {}),
             });
             this.applyLoadedFolder(requestId, result, append);
         }
         catch (error) {
             this.applyLoadFailure(requestId, error, append);
         }
+        finally {
+            if (this.activeLoadAbortController === abortController) {
+                this.activeLoadAbortController = null;
+            }
+        }
     }
     applyLoadedSearch(requestId, result, append) {
         if (requestId !== this.activeLoadRequestId) {

package/dist/patterns/content-explorer/navigation/controller.js

@@ -18,15 +18,17 @@ export class ExplorerNavigationController extends Controller {
         if (folderId === this.state.currentFolderId) {
             return null;
         }
-        const nextFolder = {
-            id: folderId,
-            name: folderId,
-            type: "folder",
-        };
-        const nextBreadcrumbs = [
-            ...this.state.breadcrumbs.filter(crumb => crumb.id !== folderId),
-            nextFolder,
-        ];
+        // Navigating to a crumb already in the trail truncates back to it (a
+        // breadcrumb is a path, so an ancestor click must drop its descendants);
+        // navigating anywhere else appends a provisional crumb that the loaded
+        // folder's real metadata replaces via applyLoadedFolder.
+        const existingIndex = this.state.breadcrumbs.findIndex(crumb => crumb.id === folderId);
+        const nextFolder = existingIndex >= 0
+            ? { ...this.state.breadcrumbs[existingIndex], type: "folder" }
+            : { id: folderId, name: folderId, type: "folder" };
+        const nextBreadcrumbs = existingIndex >= 0
+            ? this.state.breadcrumbs.slice(0, existingIndex + 1)
+            : [...this.state.breadcrumbs, nextFolder];
         this.setState({
             breadcrumbs: nextBreadcrumbs,
             currentFolder: nextFolder,

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

@@ -65,6 +65,21 @@ export interface ExplorerItemAction {
     id: string;
     itemTypes?: ExplorerItem["type"][];
     label: string;
+    /**
+     * Permission flag an item must not explicitly deny for this action to be
+     * enabled. An item with the flag `false` gets the action `disabled`; an item
+     * without permission data keeps it enabled (permissions unknown ≠ denied).
+     */
+    requiresPermission?: keyof ExplorerItemPermissions;
+    /** Resolved availability — populated by the actions controller, not authored. */
+    disabled?: boolean;
+}
+/** Sort field vocabulary mirroring box-ui-elements' ContentExplorer. */
+export type ExplorerSortBy = "name" | "date" | "size";
+export type ExplorerSortDirection = "ASC" | "DESC";
+export interface ExplorerSortState {
+    sortBy: ExplorerSortBy;
+    direction: ExplorerSortDirection;
 }
 export interface ExplorerFolder {
     id: string;
@@ -83,6 +98,8 @@ export interface ExplorerTransportRequest {
     folderId: string;
     limit?: number;
     offset?: number;
+    sortBy?: ExplorerSortBy;
+    sortDirection?: ExplorerSortDirection;
     token: string;
     language?: string;
     signal?: AbortSignal;
@@ -92,10 +109,32 @@ export interface ExplorerSearchRequest {
     ancestorFolderId?: string;
     limit?: number;
     offset?: number;
+    sortBy?: ExplorerSortBy;
+    sortDirection?: ExplorerSortDirection;
+    token: string;
+    language?: string;
+    signal?: AbortSignal;
+}
+/** Shared shape for the mutation requests a transport may support. */
+export interface ExplorerMutationContext {
     token: string;
     language?: string;
     signal?: AbortSignal;
 }
+export interface ExplorerCreateFolderRequest extends ExplorerMutationContext {
+    parentFolderId: string;
+    name: string;
+}
+export interface ExplorerRenameItemRequest extends ExplorerMutationContext {
+    itemId: string;
+    itemType: ExplorerItem["type"];
+    name: string;
+}
+export interface ExplorerDeleteItemRequest extends ExplorerMutationContext {
+    itemId: string;
+    itemType: ExplorerItem["type"];
+}
+export type ExplorerMutationKind = "create-folder" | "rename" | "delete";
 export interface ExplorerPaginationState {
     hasMoreItems: boolean;
     limit: number;
@@ -124,6 +163,9 @@ export interface ExplorerSearchResult {
 export interface ExplorerTransport {
     loadFolderItems(request: ExplorerTransportRequest): Promise<ExplorerTransportResult>;
     searchItems?(request: ExplorerSearchRequest): Promise<ExplorerSearchResult>;
+    createFolder?(request: ExplorerCreateFolderRequest): Promise<ExplorerItem>;
+    renameItem?(request: ExplorerRenameItemRequest): Promise<ExplorerItem>;
+    deleteItem?(request: ExplorerDeleteItemRequest): Promise<void>;
 }
 export interface ExplorerFetchLike {
     (input: string | URL | Request, init?: RequestInit): Promise<Response>;
@@ -139,7 +181,7 @@ export interface ExplorerSessionConfig {
     transport: ExplorerTransport;
 }
 export interface ExplorerErrorState {
-    code: "load_failed";
+    code: "load_failed" | "mutation_failed";
     message: string;
 }
 export interface ExplorerState {
@@ -153,6 +195,7 @@ export interface ExplorerState {
     loading: boolean;
     pagination: ExplorerPaginationState;
     selectedItemIds: string[];
+    sort: ExplorerSortState | null;
     view: ExplorerViewState;
 }
 export interface ExplorerEvents {
@@ -198,6 +241,9 @@ export interface ExplorerEvents {
     selectionChanged: {
         selectedItemIds: string[];
     };
+    sortChanged: {
+        sort: ExplorerSortState | null;
+    };
     viewChanged: {
         view: ExplorerViewState;
     };
@@ -206,4 +252,15 @@ export interface ExplorerEvents {
         items: ExplorerItem[];
         pagination: ExplorerPaginationState;
     };
+    itemMutated: {
+        kind: ExplorerMutationKind;
+        /** Present for create-folder and rename; absent for delete. */
+        item?: ExplorerItem;
+        itemId: string;
+    };
+    mutationFailed: {
+        kind: ExplorerMutationKind;
+        message: string;
+        itemId?: string;
+    };
 }

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

@@ -0,0 +1,71 @@
+import { ContentPickerController } from "./controller.js";
+import type { PickerItemType, PickerState } from "./types.js";
+import type { ExplorerItem, ExplorerState, ExplorerTransport } from "../content-explorer/types.js";
+import { BaseElement } from "../../core/index.js";
+export declare class ContentPicker extends BaseElement {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    private controller;
+    private pendingStart;
+    private focusItemId;
+    /**
+     * Set when a rebuild destroyed in-element focus before its target existed
+     * (e.g. navigation is still loading the next folder); the next update keeps
+     * trying to restore until a target renders.
+     */
+    private pendingFocusRestore;
+    private unsubscribeFns;
+    private transportValue;
+    get language(): string | null;
+    set language(value: string | null);
+    get pageSize(): number | undefined;
+    set pageSize(value: number | undefined);
+    get rootFolderId(): string | null;
+    set rootFolderId(value: string | null);
+    get token(): string | null;
+    set token(value: string | null);
+    get maxSelectable(): number | undefined;
+    set maxSelectable(value: number | undefined);
+    /** Comma-separated in markup, e.g. `extensions="pdf,docx"`. */
+    get extensions(): string[];
+    set extensions(value: string[]);
+    /** Comma-separated in markup, e.g. `selectable-types="file,web_link"`. */
+    get selectableTypes(): PickerItemType[];
+    set selectableTypes(value: PickerItemType[]);
+    get chooseLabel(): string;
+    set chooseLabel(value: string);
+    get cancelLabel(): string;
+    set cancelLabel(value: string);
+    get transport(): ExplorerTransport | null;
+    set transport(value: ExplorerTransport | null);
+    get state(): Readonly<PickerState> | null;
+    get explorerState(): Readonly<ExplorerState> | null;
+    /** The live session controller. Null until configured and connected. */
+    get pickerController(): ContentPickerController | null;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    navigateTo(folderId: string): Promise<void>;
+    search(query: string): Promise<void>;
+    clearSearch(): Promise<void>;
+    loadNextPage(): Promise<void>;
+    togglePick(itemId: string): void;
+    clearPicks(): void;
+    choose(): ExplorerItem[] | null;
+    cancel(): void;
+    private updateStringAttribute;
+    private scheduleStart;
+    private startController;
+    private readConfig;
+    private subscribeToController;
+    private teardownController;
+    /**
+     * Only interactive rows (pickable items and navigable folders) participate
+     * in keyboard navigation — disabled rows cannot take focus, so including
+     * them would strand arrow-key movement and the roving tab stop.
+     */
+    private getFocusableItemIds;
+    protected renderTemplate(): void;
+    protected update(): void;
+    private isFocusInsideHost;
+}