@unofficialbox/box-open-elements 0.5.0 → 0.6.0

package/dist/patterns/content-explorer/box-transport.js

@@ -123,29 +123,48 @@ const resolveFetch = (providedFetch) => {
     }
     return globalThis.fetch.bind(globalThis);
 };
-const createFolderItemsUrl = (apiBaseUrl, folderId, fields, limit, offset) => {
+/** Box folder-items sort param values match our vocabulary directly. */
+const applySortParams = (url, sortBy, sortDirection) => {
+    if (sortBy) {
+        url.searchParams.set("sort", sortBy);
+        url.searchParams.set("direction", sortDirection ?? "ASC");
+    }
+};
+const createFolderItemsUrl = (apiBaseUrl, folderId, fields, request) => {
     const url = new URL(`${apiBaseUrl.replace(/\/$/, "")}/folders/${folderId}/items`);
     url.searchParams.set("fields", fields.join(","));
-    if (typeof limit === "number") {
-        url.searchParams.set("limit", String(limit));
+    if (typeof request.limit === "number") {
+        url.searchParams.set("limit", String(request.limit));
     }
-    if (typeof offset === "number") {
-        url.searchParams.set("offset", String(offset));
+    if (typeof request.offset === "number") {
+        url.searchParams.set("offset", String(request.offset));
     }
+    applySortParams(url, request.sortBy, request.sortDirection);
+    return url.toString();
+};
+const createFolderInfoUrl = (apiBaseUrl, folderId) => {
+    const url = new URL(`${apiBaseUrl.replace(/\/$/, "")}/folders/${folderId}`);
+    url.searchParams.set("fields", "id,name,path_collection");
     return url.toString();
 };
-const createSearchUrl = (apiBaseUrl, query, fields, ancestorFolderId, limit, offset) => {
+const createSearchUrl = (apiBaseUrl, fields, request) => {
     const url = new URL(`${apiBaseUrl.replace(/\/$/, "")}/search`);
-    url.searchParams.set("query", query);
+    url.searchParams.set("query", request.query);
     url.searchParams.set("fields", fields.join(","));
-    if (ancestorFolderId) {
-        url.searchParams.set("ancestor_folder_ids", ancestorFolderId);
+    if (request.ancestorFolderId) {
+        url.searchParams.set("ancestor_folder_ids", request.ancestorFolderId);
     }
-    if (typeof limit === "number") {
-        url.searchParams.set("limit", String(limit));
+    if (typeof request.limit === "number") {
+        url.searchParams.set("limit", String(request.limit));
     }
-    if (typeof offset === "number") {
-        url.searchParams.set("offset", String(offset));
+    if (typeof request.offset === "number") {
+        url.searchParams.set("offset", String(request.offset));
+    }
+    // Box search only sorts by modified date (or relevance, its default); name
+    // and size sorts stay client concerns there, so only "date" maps through.
+    if (request.sortBy === "date") {
+        url.searchParams.set("sort", "modified_at");
+        url.searchParams.set("direction", (request.sortDirection ?? "DESC") === "ASC" ? "ASC" : "DESC");
     }
     return url.toString();
 };
@@ -178,13 +197,14 @@ export const createBoxExplorerTransport = (options = {}) => {
     const apiBaseUrl = options.apiBaseUrl ?? DEFAULT_API_BASE_URL;
     const fields = options.fields ?? DEFAULT_FIELDS;
     const fetchImpl = resolveFetch(options.fetch);
+    const requestHeaders = (request) => ({
+        Authorization: `Bearer ${request.token}`,
+        "Accept-Language": request.language ?? "en-US",
+    });
     return {
         async loadFolderItems(request) {
-            const response = await fetchImpl(createFolderItemsUrl(apiBaseUrl, request.folderId, fields, request.limit, request.offset), {
-                headers: {
-                    Authorization: `Bearer ${request.token}`,
-                    "Accept-Language": request.language ?? "en-US",
-                },
+            const response = await fetchImpl(createFolderItemsUrl(apiBaseUrl, request.folderId, fields, request), {
+                headers: requestHeaders(request),
                 method: "GET",
                 signal: request.signal,
             });
@@ -194,9 +214,34 @@ export const createBoxExplorerTransport = (options = {}) => {
             const payload = (await response.json());
             const rawEntries = payload.entries ?? [];
             const { entries } = normalizeItems(rawEntries);
-            const folder = normalizeFolder(payload, request.folderId);
+            // The real `GET /folders/:id/items` payload carries no folder metadata
+            // (no id/name/path_collection), which would degrade the folder header
+            // and breadcrumbs to raw ids. When the first page lacks it, fetch
+            // `GET /folders/:id` for the metadata — best-effort: a failed info
+            // request keeps the listing usable rather than failing it.
+            let folderSource = payload;
+            const missingMetadata = payload.name === undefined || payload.id === undefined || payload.path_collection === undefined;
+            if (!request.offset && missingMetadata) {
+                const info = await Promise.resolve()
+                    .then(() => fetchImpl(createFolderInfoUrl(apiBaseUrl, request.folderId), {
+                    headers: requestHeaders(request),
+                    method: "GET",
+                    signal: request.signal,
+                }))
+                    .then(infoResponse => infoResponse?.ok ? infoResponse.json() : null)
+                    .catch(() => null);
+                if (info) {
+                    folderSource = {
+                        ...payload,
+                        id: payload.id ?? info.id,
+                        name: payload.name ?? info.name,
+                        path_collection: payload.path_collection ?? info.path_collection,
+                    };
+                }
+            }
+            const folder = normalizeFolder(folderSource, request.folderId);
             return {
-                breadcrumbs: normalizeBreadcrumbs(payload, folder),
+                breadcrumbs: normalizeBreadcrumbs(folderSource, folder),
                 folder,
                 folderId: request.folderId,
                 items: entries,
@@ -204,11 +249,8 @@ export const createBoxExplorerTransport = (options = {}) => {
             };
         },
         async searchItems(request) {
-            const response = await fetchImpl(createSearchUrl(apiBaseUrl, request.query, fields, request.ancestorFolderId, request.limit, request.offset), {
-                headers: {
-                    Authorization: `Bearer ${request.token}`,
-                    "Accept-Language": request.language ?? "en-US",
-                },
+            const response = await fetchImpl(createSearchUrl(apiBaseUrl, fields, request), {
+                headers: requestHeaders(request),
                 method: "GET",
                 signal: request.signal,
             });
@@ -225,5 +267,55 @@ export const createBoxExplorerTransport = (options = {}) => {
                 pagination: toPagination(payload, rawEntries.length, request),
             };
         },
+        async createFolder(request) {
+            const response = await fetchImpl(`${apiBaseUrl.replace(/\/$/, "")}/folders`, {
+                headers: { ...requestHeaders(request), "Content-Type": "application/json" },
+                method: "POST",
+                body: JSON.stringify({ name: request.name, parent: { id: request.parentFolderId } }),
+                signal: request.signal,
+            });
+            if (!response.ok) {
+                throw new Error(await getErrorMessage(response));
+            }
+            const payload = (await response.json());
+            const item = normalizeBoxExplorerItem(payload);
+            if (!item) {
+                throw new Error("Box API returned an unsupported item for the created folder");
+            }
+            return item;
+        },
+        async renameItem(request) {
+            const segment = request.itemType === "folder" ? "folders" : request.itemType === "web_link" ? "web_links" : "files";
+            const response = await fetchImpl(`${apiBaseUrl.replace(/\/$/, "")}/${segment}/${request.itemId}`, {
+                headers: { ...requestHeaders(request), "Content-Type": "application/json" },
+                method: "PUT",
+                body: JSON.stringify({ name: request.name }),
+                signal: request.signal,
+            });
+            if (!response.ok) {
+                throw new Error(await getErrorMessage(response));
+            }
+            const payload = (await response.json());
+            const item = normalizeBoxExplorerItem(payload);
+            if (!item) {
+                throw new Error("Box API returned an unsupported item for the rename");
+            }
+            return item;
+        },
+        async deleteItem(request) {
+            const segment = request.itemType === "folder" ? "folders" : request.itemType === "web_link" ? "web_links" : "files";
+            const url = new URL(`${apiBaseUrl.replace(/\/$/, "")}/${segment}/${request.itemId}`);
+            if (request.itemType === "folder") {
+                url.searchParams.set("recursive", "true");
+            }
+            const response = await fetchImpl(url.toString(), {
+                headers: requestHeaders(request),
+                method: "DELETE",
+                signal: request.signal,
+            });
+            if (!response.ok && response.status !== 204) {
+                throw new Error(await getErrorMessage(response));
+            }
+        },
     };
 };

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

@@ -1,4 +1,5 @@
-import { type ExplorerItemAction, type ExplorerItem, type ExplorerItemGesture, type ExplorerSelectionMode, type ExplorerState, type ExplorerTransport } from "./types.js";
+import { ContentExplorerController } from "./controller.js";
+import { type ExplorerItemAction, type ExplorerItem, type ExplorerItemGesture, type ExplorerSelectionMode, type ExplorerSortState, type ExplorerState, type ExplorerTransport } from "./types.js";
 import { BaseElement } from "../../core/index.js";
 export interface ContentExplorerTemplateContext {
     element: ContentExplorer;
@@ -73,6 +74,16 @@ export declare class ContentExplorer extends BaseElement {
     toggleSelection(itemId: string): void;
     clearSelection(): void;
     invokeItemAction(itemId: string, actionId: string): void;
+    setSort(sort: ExplorerSortState | null): Promise<void>;
+    createFolder(name: string): Promise<ExplorerItem | null>;
+    renameItem(itemId: string, name: string): Promise<ExplorerItem | null>;
+    deleteItem(itemId: string): Promise<boolean>;
+    /**
+     * The live session controller, for pairing the shell with the standalone
+     * adapter elements (`box-explorer-toolbar`, `box-explorer-breadcrumbs`, …)
+     * or host-chrome bindings. Null until connected.
+     */
+    get explorerController(): ContentExplorerController | null;
     private updateStringAttribute;
     private scheduleStart;
     private startController;
@@ -82,4 +93,5 @@ export declare class ContentExplorer extends BaseElement {
     private getFocusableItemIds;
     protected renderTemplate(): void;
     protected update(): void;
+    private isFocusInsideHost;
 }

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

@@ -386,6 +386,26 @@ export class ContentExplorer extends BaseElement {
     invokeItemAction(itemId, actionId) {
         this.controller?.invokeItemAction(itemId, actionId);
     }
+    async setSort(sort) {
+        await this.controller?.setSort(sort);
+    }
+    async createFolder(name) {
+        return (await this.controller?.createFolder(name)) ?? null;
+    }
+    async renameItem(itemId, name) {
+        return (await this.controller?.renameItem(itemId, name)) ?? null;
+    }
+    async deleteItem(itemId) {
+        return (await this.controller?.deleteItem(itemId)) ?? false;
+    }
+    /**
+     * The live session controller, for pairing the shell with the standalone
+     * adapter elements (`box-explorer-toolbar`, `box-explorer-breadcrumbs`, …)
+     * or host-chrome bindings. Null until connected.
+     */
+    get explorerController() {
+        return this.controller;
+    }
     updateStringAttribute(name, value) {
         if (value === null || value === "") {
             this.removeAttribute(name);
@@ -564,6 +584,7 @@ export class ContentExplorer extends BaseElement {
                         "data-item-id": item.id,
                         part: "item-action",
                         type: "button",
+                        ...(action.disabled ? { disabled: "", "aria-disabled": "true" } : {}),
                     });
                     return this.templatesValue.renderItemAction
                         ? this.templatesValue.renderItemAction({
@@ -594,7 +615,7 @@ export class ContentExplorer extends BaseElement {
                         itemButtonAttributes,
                         state,
                     })
-                    : `<li data-item-id="${item.id}" role="presentation">
+                    : `<li data-item-id="${escapeHtml(item.id)}" role="presentation">
                     <button ${itemButtonAttributes}><span part="item-name">${escapeHtml(item.name)}</span>${meta ? `<span part="item-meta">${escapeHtml(meta)}</span>` : ""}</button>
                     ${actions ? `<div part="item-actions">${actions}</div>` : ""}
                   </li>`;
@@ -615,13 +636,15 @@ export class ContentExplorer extends BaseElement {
         if (!host) {
             return;
         }
+        // Sample focus BEFORE the rebuild wipes the focused node.
+        const hadFocusInside = this.isFocusInsideHost();
         host.innerHTML = `
       <section aria-busy="${state?.loading ? "true" : "false"}">
         ${folderMarkup}
         <p part="status" data-status="${statusText}" role="status" aria-live="polite">${statusText}</p>
         ${errorMarkup}
         <button type="button" part="refresh" aria-label="Refresh items" ${refreshDisabled}>Refresh</button>
-        <ul part="items" role="listbox" aria-label="Explorer items">${itemsMarkup}</ul>
+        <ul part="items" role="listbox" aria-label="Explorer items" aria-multiselectable="${(this.selectionMode ?? "multiple") === "multiple" ? "true" : "false"}">${itemsMarkup}</ul>
         ${loadMoreMarkup ? `<div part="load-more-region">${loadMoreMarkup}</div>` : ""}
       </section>
     `;
@@ -727,13 +750,23 @@ export class ContentExplorer extends BaseElement {
                 }
             });
         });
-        if (this.focusItemId) {
+        // Restore focus only when it already lived inside this element before the
+        // rebuild — an unrelated state update (loading tick, selection change from
+        // the API) must never steal focus from elsewhere on the page.
+        if (this.focusItemId && hadFocusInside) {
             queueMicrotask(() => {
                 const target = Array.from(this.shadowRoot?.querySelectorAll('[part="item"]') ?? []).find(node => node.dataset.itemId === this.focusItemId);
                 target?.focus();
             });
         }
     }
+    isFocusInsideHost() {
+        const active = document.activeElement;
+        if (!active) {
+            return false;
+        }
+        return active === this || (this.shadowRoot?.contains(active) ?? false);
+    }
 }
 SearchResultsHeader.register();
 ContentExplorer.register();

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

@@ -1,4 +1,4 @@
-import type { ExplorerFetchLike, ExplorerSearchResult, ExplorerTransport, ExplorerTransportResult } from "./types.js";
+import type { ExplorerFetchLike, ExplorerItem, ExplorerSearchResult, ExplorerSortBy, ExplorerSortDirection, ExplorerTransport, ExplorerTransportResult } from "./types.js";
 export interface ContentExplorerRequestContext {
     locale?: string;
     requestId?: string;
@@ -8,6 +8,8 @@ export interface ContentExplorerListFolderInput {
     folderId: string;
     limit?: number;
     offset?: number;
+    sortBy?: ExplorerSortBy;
+    sortDirection?: ExplorerSortDirection;
     context?: ContentExplorerRequestContext;
 }
 export interface ContentExplorerSearchInput {
@@ -15,11 +17,32 @@ export interface ContentExplorerSearchInput {
     ancestorFolderId?: string;
     limit?: number;
     offset?: number;
+    sortBy?: ExplorerSortBy;
+    sortDirection?: ExplorerSortDirection;
+    context?: ContentExplorerRequestContext;
+}
+export interface ContentExplorerCreateFolderInput {
+    parentFolderId: string;
+    name: string;
+    context?: ContentExplorerRequestContext;
+}
+export interface ContentExplorerRenameItemInput {
+    itemId: string;
+    itemType: ExplorerItem["type"];
+    name: string;
+    context?: ContentExplorerRequestContext;
+}
+export interface ContentExplorerDeleteItemInput {
+    itemId: string;
+    itemType: ExplorerItem["type"];
     context?: ContentExplorerRequestContext;
 }
 export interface ContentExplorerDataSource {
     listFolderItems(input: ContentExplorerListFolderInput): Promise<ExplorerTransportResult>;
     search?(input: ContentExplorerSearchInput): Promise<ExplorerSearchResult>;
+    createFolder?(input: ContentExplorerCreateFolderInput): Promise<ExplorerItem>;
+    renameItem?(input: ContentExplorerRenameItemInput): Promise<ExplorerItem>;
+    deleteItem?(input: ContentExplorerDeleteItemInput): Promise<void>;
 }
 export interface ContentExplorerHttpDataSourceOptions {
     baseUrl?: string;

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

@@ -13,15 +13,22 @@ const resolveUrlBase = () => {
     }
     return "http://localhost";
 };
-const defaultListFolderUrl = (baseUrl, input) => {
-    const root = baseUrl.replace(/\/$/, "");
-    const url = new URL(`${root}/folders/${encodeURIComponent(input.folderId)}/items`, resolveUrlBase());
+const applyPageAndSortParams = (url, input) => {
     if (typeof input.limit === "number") {
         url.searchParams.set("limit", String(input.limit));
     }
     if (typeof input.offset === "number") {
         url.searchParams.set("offset", String(input.offset));
     }
+    if (input.sortBy) {
+        url.searchParams.set("sortBy", input.sortBy);
+        url.searchParams.set("sortDirection", input.sortDirection ?? "ASC");
+    }
+};
+const defaultListFolderUrl = (baseUrl, input) => {
+    const root = baseUrl.replace(/\/$/, "");
+    const url = new URL(`${root}/folders/${encodeURIComponent(input.folderId)}/items`, resolveUrlBase());
+    applyPageAndSortParams(url, input);
     return url.toString();
 };
 const defaultSearchUrl = (baseUrl, input) => {
@@ -31,12 +38,7 @@ const defaultSearchUrl = (baseUrl, input) => {
     if (input.ancestorFolderId) {
         url.searchParams.set("ancestorFolderId", input.ancestorFolderId);
     }
-    if (typeof input.limit === "number") {
-        url.searchParams.set("limit", String(input.limit));
-    }
-    if (typeof input.offset === "number") {
-        url.searchParams.set("offset", String(input.offset));
-    }
+    applyPageAndSortParams(url, input);
     return url.toString();
 };
 const getErrorMessage = async (response) => {
@@ -58,6 +60,8 @@ export const createExplorerTransportFromDataSource = (dataSource) => {
                 folderId: request.folderId,
                 limit: request.limit,
                 offset: request.offset,
+                sortBy: request.sortBy,
+                sortDirection: request.sortDirection,
                 context: {
                     locale: request.language,
                     signal: request.signal,
@@ -72,35 +76,69 @@ export const createExplorerTransportFromDataSource = (dataSource) => {
             ancestorFolderId: request.ancestorFolderId,
             limit: request.limit,
             offset: request.offset,
+            sortBy: request.sortBy,
+            sortDirection: request.sortDirection,
             context: {
                 locale: request.language,
                 signal: request.signal,
             },
         });
     }
+    if (dataSource.createFolder) {
+        const createFolder = dataSource.createFolder.bind(dataSource);
+        transport.createFolder = request => createFolder({
+            parentFolderId: request.parentFolderId,
+            name: request.name,
+            context: { locale: request.language, signal: request.signal },
+        });
+    }
+    if (dataSource.renameItem) {
+        const renameItem = dataSource.renameItem.bind(dataSource);
+        transport.renameItem = request => renameItem({
+            itemId: request.itemId,
+            itemType: request.itemType,
+            name: request.name,
+            context: { locale: request.language, signal: request.signal },
+        });
+    }
+    if (dataSource.deleteItem) {
+        const deleteItem = dataSource.deleteItem.bind(dataSource);
+        transport.deleteItem = request => deleteItem({
+            itemId: request.itemId,
+            itemType: request.itemType,
+            context: { locale: request.language, signal: request.signal },
+        });
+    }
     return transport;
 };
 export const createHttpContentExplorerDataSource = (options = {}) => {
     const fetchImpl = resolveFetch(options.fetch);
     const baseUrl = options.baseUrl ?? "/api/content-explorer";
-    const requestJson = async (url, input) => {
+    const request = async (url, input, init = { method: "GET" }) => {
         const response = await fetchImpl(url, {
-            method: "GET",
+            method: init.method,
             credentials: "same-origin",
             cache: "no-store",
             headers: {
                 accept: "application/json",
+                ...(init.body !== undefined ? { "content-type": "application/json" } : {}),
                 ...(input.context?.locale ? { "accept-language": input.context.locale } : {}),
                 ...(input.context?.requestId ? { "x-request-id": input.context.requestId } : {}),
                 ...options.headers,
             },
+            ...(init.body !== undefined ? { body: JSON.stringify(init.body) } : {}),
             signal: input.context?.signal,
         });
         if (!response.ok) {
             throw new Error(await getErrorMessage(response));
         }
+        return response;
+    };
+    const requestJson = async (url, input, init) => {
+        const response = await request(url, input, init);
         return (await response.json());
     };
+    const root = baseUrl.replace(/\/$/, "");
     return {
         async listFolderItems(input) {
             const url = options.buildListFolderUrl?.(input) ?? defaultListFolderUrl(baseUrl, input);
@@ -110,5 +148,24 @@ export const createHttpContentExplorerDataSource = (options = {}) => {
             const url = options.buildSearchUrl?.(input) ?? defaultSearchUrl(baseUrl, input);
             return requestJson(url, input);
         },
+        async createFolder(input) {
+            const url = new URL(`${root}/folders`, resolveUrlBase()).toString();
+            return requestJson(url, input, {
+                method: "POST",
+                body: { parentFolderId: input.parentFolderId, name: input.name },
+            });
+        },
+        async renameItem(input) {
+            const url = new URL(`${root}/items/${encodeURIComponent(input.itemId)}`, resolveUrlBase()).toString();
+            return requestJson(url, input, {
+                method: "PUT",
+                body: { itemType: input.itemType, name: input.name },
+            });
+        },
+        async deleteItem(input) {
+            const url = new URL(`${root}/items/${encodeURIComponent(input.itemId)}`, resolveUrlBase());
+            url.searchParams.set("itemType", input.itemType);
+            await request(url.toString(), input, { method: "DELETE" });
+        },
     };
 };

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

@@ -1,8 +1,9 @@
 import { Controller } from "../../core/controller.js";
-import type { ExplorerEvents, ExplorerItem, ExplorerSelectionMode, ExplorerSessionConfig, ExplorerState } from "./types.js";
+import type { ExplorerEvents, ExplorerItem, ExplorerSelectionMode, ExplorerSessionConfig, ExplorerSortBy, ExplorerSortDirection, ExplorerSortState, ExplorerState } from "./types.js";
 export declare class ContentExplorerController extends Controller<ExplorerState, ExplorerEvents> {
     readonly config: ExplorerSessionConfig;
     private activeLoadRequestId;
+    private activeLoadAbortController;
     private readonly actionsController;
     private readonly collectionController;
     private readonly navigationController;
@@ -24,6 +25,20 @@ export declare class ContentExplorerController extends Controller<ExplorerState,
     getItemActions(itemId: string): import("./types.js").ExplorerItemAction[];
     invokeItemAction(itemId: string, actionId: string): void;
     activateItem(itemId: string): Promise<void>;
+    /**
+     * Set (or clear) the collection sort and reload from the first page. The
+     * transport receives the sort with every request; passing `null` restores
+     * the server's default ordering.
+     */
+    setSort(sort: ExplorerSortState | null): Promise<void>;
+    setSort(sortBy: ExplorerSortBy, direction: ExplorerSortDirection): Promise<void>;
+    /** Create a folder in the current folder, then refresh the collection. */
+    createFolder(name: string): Promise<ExplorerItem | null>;
+    /** Rename an item in the current collection, then refresh. */
+    renameItem(itemId: string, name: string): Promise<ExplorerItem | null>;
+    /** Delete an item from the current collection, then refresh. */
+    deleteItem(itemId: string): Promise<boolean>;
+    private runMutation;
     reload(): Promise<void>;
     refresh(): Promise<void>;
     loadNextPage(): Promise<void>;