@unofficialbox/box-open-elements 0.1.0

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

@@ -0,0 +1,234 @@
+import { BaseElement } from "../../../core/index.js";
+import { defineBoxSearchFieldElement, } from "../../../components/forms/search-field.js";
+import { applyRovingTabindex, handleRovingKeydown } from "../../../foundations/a11y/index.js";
+import { boeNeutralInteractiveStyles } from "../../../foundations/tokens/index.js";
+import { boeMotionDuration, boeMotionEasing } from "../../../foundations/motion/index.js";
+import { boePanel } from "../../../foundations/geometry/index.js";
+const DEFAULT_TAG_NAME = "box-explorer-toolbar";
+const toKebabCase = (value) => value.replace(/[A-Z]/g, letter => `-${letter.toLowerCase()}`);
+const elementStyles = `
+        :host {
+          display: block;
+          color: inherit;
+          font: inherit;
+        }
+
+        [part="toolbar"] {
+          display: flex;
+          flex-wrap: wrap;
+          align-items: end;
+          gap: ${boePanel.gap};
+          padding: 0.55rem 0.65rem;
+          border: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 84%, var(--boe-token-surface-surface, #ffffff) 16%);
+          border-radius: ${boePanel.radius};
+          background: var(--boe-token-surface-surface, #ffffff);
+          box-shadow: 0 1px 2px rgba(15, 23, 42, 0.04);
+        }
+
+        [part="search"] {
+          flex: 1 1 14rem;
+          min-width: 12rem;
+        }
+
+        [part="status"],
+        [part="selection-count"] {
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+          font-size: 0.85rem;
+          white-space: nowrap;
+          padding-bottom: 0.45rem;
+        }
+
+        [part="selection-count"] {
+          margin-right: auto;
+        }
+
+        [part="status"][data-status="failed"] {
+          color: color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 72%, black 28%);
+        }
+
+        [part="refresh"],
+        [part="clear-selection"] {
+          appearance: none;
+          font: inherit;
+          font-size: 0.88rem;
+          font-weight: 500;
+          padding: 0.42rem 0.8rem;
+          border: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 86%, var(--boe-token-surface-surface, #ffffff) 14%);
+          border-radius: ${boePanel.radius};
+          background: var(--boe-token-surface-surface, #ffffff);
+          color: var(--boe-token-text-text, #222222);
+          cursor: pointer;
+          transition:
+            border-color ${boeMotionDuration.interactive} ${boeMotionEasing.standard},
+            background-color ${boeMotionDuration.interactive} ${boeMotionEasing.standard},
+            color ${boeMotionDuration.interactive} ${boeMotionEasing.standard},
+            box-shadow ${boeMotionDuration.interactive} ${boeMotionEasing.standard};
+        }
+
+        ${boeNeutralInteractiveStyles('[part="refresh"]')}
+        ${boeNeutralInteractiveStyles('[part="clear-selection"]')}
+      `;
+export class BoxExplorerToolbarElement extends BaseElement {
+    controllerValue = null;
+    unsubscribeFns = [];
+    listenersBound = false;
+    get controller() {
+        return this.controllerValue;
+    }
+    set controller(value) {
+        this.controllerValue = value;
+        this.bindController();
+        if (this.isRendered) {
+            this.update();
+        }
+    }
+    connectedCallback() {
+        defineBoxSearchFieldElement();
+        this.bindController();
+        super.connectedCallback();
+    }
+    disconnectedCallback() {
+        this.teardownSubscriptions();
+    }
+    bindController() {
+        this.teardownSubscriptions();
+        if (!this.isConnected || !this.controllerValue) {
+            return;
+        }
+        for (const eventName of [
+            "loadingChanged",
+            "selectionChanged",
+            "loadFailed",
+            "viewChanged",
+            "searchSucceeded",
+            "loadSucceeded",
+        ]) {
+            this.unsubscribeFns.push(this.controllerValue.subscribe(eventName, payload => {
+                this.dispatchEvent(new CustomEvent(toKebabCase(String(eventName)), {
+                    bubbles: true,
+                    composed: true,
+                    detail: payload,
+                }));
+                if (this.isRendered) {
+                    this.update();
+                }
+            }));
+        }
+    }
+    teardownSubscriptions() {
+        for (const unsubscribe of this.unsubscribeFns) {
+            unsubscribe();
+        }
+        this.unsubscribeFns = [];
+    }
+    getSearchField() {
+        return this.shadowRoot?.querySelector('[part="search"]');
+    }
+    syncSearchField(query, loading) {
+        const searchField = this.getSearchField();
+        if (!searchField) {
+            return;
+        }
+        const active = this.shadowRoot?.activeElement;
+        const searchFocused = active === searchField || (active != null && searchField.contains(active));
+        if (!searchFocused && searchField.value !== query) {
+            searchField.value = query;
+        }
+        searchField.disabled = loading;
+    }
+    renderTemplate() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        defineBoxSearchFieldElement();
+        this.shadowRoot.innerHTML = `
+      <style>${elementStyles}</style>
+      <div part="toolbar" role="toolbar" aria-label="Explorer toolbar">
+        <box-search-field
+          part="search"
+          label="Search"
+          placeholder="Search files and folders"
+        ></box-search-field>
+        <span part="status" data-status="ready" role="status" aria-live="polite">ready</span>
+        <span part="selection-count">0 selected</span>
+        <button type="button" part="refresh">Refresh</button>
+        <button type="button" part="clear-selection" disabled>Clear Selection</button>
+      </div>
+    `;
+        this.listenersBound = false;
+    }
+    setupListeners() {
+        if (!this.shadowRoot || this.listenersBound) {
+            return;
+        }
+        this.listenersBound = true;
+        const toolbar = this.shadowRoot.querySelector('[part="toolbar"]');
+        const searchField = this.getSearchField();
+        searchField?.addEventListener("search", event => {
+            const value = String(event.detail?.value ?? "").trim();
+            if (value) {
+                void this.controllerValue?.search(value);
+            }
+            else {
+                void this.controllerValue?.clearSearch();
+            }
+        });
+        searchField?.addEventListener("clear", () => {
+            void this.controllerValue?.clearSearch();
+        });
+        this.shadowRoot.querySelector('[part="refresh"]')?.addEventListener("click", () => {
+            void this.controllerValue?.refresh();
+        });
+        this.shadowRoot.querySelector('[part="clear-selection"]')?.addEventListener("click", () => {
+            this.controllerValue?.clearSelection();
+        });
+        toolbar?.addEventListener("keydown", event => {
+            const buttons = Array.from(this.shadowRoot?.querySelectorAll('[part="refresh"], [part="clear-selection"]') ?? []).filter(button => !button.disabled);
+            handleRovingKeydown(event, buttons, { orientation: "horizontal" });
+        });
+    }
+    update() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        const state = this.controllerValue?.getState();
+        const loading = state?.loading ?? false;
+        const selectedCount = state?.selectedItemIds.length ?? 0;
+        const hasError = Boolean(state?.error);
+        const statusText = loading ? "loading" : hasError ? "failed" : "ready";
+        const searchQuery = state?.view.searchQuery ?? "";
+        const status = this.shadowRoot.querySelector('[part="status"]');
+        const selectionCount = this.shadowRoot.querySelector('[part="selection-count"]');
+        const refresh = this.shadowRoot.querySelector('[part="refresh"]');
+        const clearSelection = this.shadowRoot.querySelector('[part="clear-selection"]');
+        if (status) {
+            status.dataset.status = statusText;
+            status.textContent = statusText;
+        }
+        if (selectionCount) {
+            selectionCount.textContent = `${selectedCount} selected`;
+        }
+        if (refresh) {
+            refresh.disabled = loading;
+        }
+        if (clearSelection) {
+            clearSelection.disabled = selectedCount === 0;
+        }
+        this.syncSearchField(searchQuery, loading);
+        const activePart = this.shadowRoot.activeElement?.getAttribute("part") ?? null;
+        const buttons = Array.from(this.shadowRoot.querySelectorAll('[part="refresh"], [part="clear-selection"]')).filter(button => !button.disabled);
+        const restoreIndex = activePart
+            ? buttons.findIndex(button => button.getAttribute("part") === activePart)
+            : -1;
+        applyRovingTabindex(buttons, restoreIndex >= 0 ? restoreIndex : 0);
+    }
+}
+export const defineBoxExplorerToolbarElement = (tagName = DEFAULT_TAG_NAME) => {
+    defineBoxSearchFieldElement();
+    const existingElement = customElements.get(tagName);
+    if (existingElement) {
+        return existingElement;
+    }
+    customElements.define(tagName, BoxExplorerToolbarElement);
+    return BoxExplorerToolbarElement;
+};

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

@@ -0,0 +1,44 @@
+import type { ExplorerFetchLike, ExplorerItem, ExplorerTransport } from "./types.js";
+interface BoxOwnedBy {
+    id?: string;
+    name?: string;
+    type?: string;
+}
+interface BoxSharedLink {
+    url?: string;
+    access?: string;
+    effective_access?: string;
+}
+interface BoxPermissions {
+    can_download?: boolean;
+    can_preview?: boolean;
+    can_share?: boolean;
+    can_delete?: boolean;
+    can_rename?: boolean;
+    can_upload?: boolean;
+}
+interface BoxFolderItem {
+    id: string;
+    name: string;
+    type: string;
+    size?: number | null;
+    modified_at?: string | null;
+    created_at?: string | null;
+    extension?: string | null;
+    owned_by?: BoxOwnedBy | null;
+    shared_link?: BoxSharedLink | null;
+    permissions?: BoxPermissions | null;
+    parent?: {
+        id?: string;
+        name?: string;
+        type?: string;
+    } | null;
+}
+export interface BoxExplorerTransportOptions {
+    apiBaseUrl?: string;
+    fields?: string[];
+    fetch?: ExplorerFetchLike;
+}
+export declare const normalizeBoxExplorerItem: (entry: BoxFolderItem) => ExplorerItem | null;
+export declare const createBoxExplorerTransport: (options?: BoxExplorerTransportOptions) => ExplorerTransport;
+export {};

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

@@ -0,0 +1,229 @@
+const DEFAULT_API_BASE_URL = "https://api.box.com/2.0";
+const DEFAULT_FIELDS = [
+    "id",
+    "name",
+    "type",
+    "size",
+    "modified_at",
+    "created_at",
+    "extension",
+    "owned_by",
+    "shared_link",
+    "permissions",
+    "parent",
+];
+const isSupportedItemType = (type) => type === "file" || type === "folder" || type === "web_link";
+const mapOwner = (ownedBy) => {
+    if (ownedBy == null) {
+        return ownedBy === null ? null : undefined;
+    }
+    if (!ownedBy.id || !ownedBy.name) {
+        return undefined;
+    }
+    const type = ownedBy.type === "group" || ownedBy.type === "user" ? ownedBy.type : undefined;
+    return { id: ownedBy.id, name: ownedBy.name, ...(type ? { type } : {}) };
+};
+const mapPermissions = (permissions) => {
+    if (!permissions) {
+        return undefined;
+    }
+    return {
+        ...(typeof permissions.can_download === "boolean" ? { canDownload: permissions.can_download } : {}),
+        ...(typeof permissions.can_preview === "boolean" ? { canPreview: permissions.can_preview } : {}),
+        ...(typeof permissions.can_share === "boolean" ? { canShare: permissions.can_share } : {}),
+        ...(typeof permissions.can_delete === "boolean" ? { canDelete: permissions.can_delete } : {}),
+        ...(typeof permissions.can_rename === "boolean" ? { canRename: permissions.can_rename } : {}),
+        ...(typeof permissions.can_upload === "boolean" ? { canUpload: permissions.can_upload } : {}),
+    };
+};
+const mapSharedLink = (sharedLink) => {
+    if (sharedLink === undefined) {
+        return undefined;
+    }
+    if (sharedLink === null || !sharedLink.url) {
+        return sharedLink === null ? null : { isShared: false };
+    }
+    const accessRaw = sharedLink.effective_access ?? sharedLink.access;
+    const access = accessRaw === "open" || accessRaw === "company" || accessRaw === "collaborators" ? accessRaw : undefined;
+    return {
+        isShared: true,
+        ...(access ? { access } : {}),
+        url: sharedLink.url,
+    };
+};
+export const normalizeBoxExplorerItem = (entry) => {
+    if (!isSupportedItemType(entry.type)) {
+        return null;
+    }
+    const owner = mapOwner(entry.owned_by);
+    const permissions = mapPermissions(entry.permissions);
+    const sharedLink = mapSharedLink(entry.shared_link);
+    const parent = entry.parent?.id != null
+        ? { id: entry.parent.id, ...(entry.parent.name ? { name: entry.parent.name } : {}) }
+        : entry.parent === null
+            ? null
+            : undefined;
+    const item = {
+        id: entry.id,
+        name: entry.name,
+        type: entry.type,
+    };
+    if (entry.size !== undefined) {
+        item.size = entry.size;
+    }
+    if (entry.modified_at !== undefined) {
+        item.modifiedAt = entry.modified_at;
+    }
+    if (entry.created_at !== undefined) {
+        item.createdAt = entry.created_at;
+    }
+    if (entry.extension !== undefined) {
+        item.extension = entry.extension;
+    }
+    if (owner !== undefined) {
+        item.owner = owner;
+    }
+    if (permissions && Object.keys(permissions).length > 0) {
+        item.permissions = permissions;
+    }
+    if (sharedLink !== undefined) {
+        item.sharedLink = sharedLink;
+    }
+    if (entry.extension !== undefined || permissions?.canPreview !== undefined) {
+        item.preview = {
+            ...(typeof permissions?.canPreview === "boolean" ? { canPreview: permissions.canPreview } : {}),
+            ...(entry.extension !== undefined ? { extension: entry.extension } : {}),
+        };
+    }
+    if (parent !== undefined) {
+        item.parent = parent;
+    }
+    return item;
+};
+const normalizeItems = (entries) => ({
+    entries: entries
+        .map(normalizeBoxExplorerItem)
+        .filter((entry) => entry !== null),
+});
+const normalizeFolder = (payload, folderId) => ({
+    id: payload.id ?? folderId,
+    name: payload.name ?? folderId,
+    type: "folder",
+});
+const normalizeBreadcrumbs = (payload, folder) => {
+    const parents = payload.path_collection?.entries?.filter((entry) => entry.type === "folder") ?? [];
+    return [...parents, folder];
+};
+const resolveFetch = (providedFetch) => {
+    if (providedFetch) {
+        return providedFetch;
+    }
+    if (typeof globalThis.fetch !== "function") {
+        throw new Error("A fetch implementation is required to use the Box explorer transport");
+    }
+    return globalThis.fetch.bind(globalThis);
+};
+const createFolderItemsUrl = (apiBaseUrl, folderId, fields, limit, offset) => {
+    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 offset === "number") {
+        url.searchParams.set("offset", String(offset));
+    }
+    return url.toString();
+};
+const createSearchUrl = (apiBaseUrl, query, fields, ancestorFolderId, limit, offset) => {
+    const url = new URL(`${apiBaseUrl.replace(/\/$/, "")}/search`);
+    url.searchParams.set("query", query);
+    url.searchParams.set("fields", fields.join(","));
+    if (ancestorFolderId) {
+        url.searchParams.set("ancestor_folder_ids", ancestorFolderId);
+    }
+    if (typeof limit === "number") {
+        url.searchParams.set("limit", String(limit));
+    }
+    if (typeof offset === "number") {
+        url.searchParams.set("offset", String(offset));
+    }
+    return url.toString();
+};
+const getErrorMessage = async (response) => {
+    try {
+        const payload = (await response.json());
+        if (payload.message) {
+            return payload.code ? `${payload.code}: ${payload.message}` : payload.message;
+        }
+    }
+    catch {
+        // Ignore JSON parse issues and fall back to status text.
+    }
+    return `Box API request failed with status ${response.status}`;
+};
+const toPagination = (payload, rawEntriesLength, request) => {
+    const offset = payload.offset ?? request.offset ?? 0;
+    const limit = payload.limit ?? request.limit ?? rawEntriesLength;
+    const totalCount = payload.total_count ?? null;
+    const nextOffset = offset + rawEntriesLength;
+    return {
+        hasMoreItems: totalCount === null ? rawEntriesLength === limit : nextOffset < totalCount,
+        limit,
+        offset,
+        totalCount,
+        nextOffset,
+    };
+};
+export const createBoxExplorerTransport = (options = {}) => {
+    const apiBaseUrl = options.apiBaseUrl ?? DEFAULT_API_BASE_URL;
+    const fields = options.fields ?? DEFAULT_FIELDS;
+    const fetchImpl = resolveFetch(options.fetch);
+    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",
+                },
+                method: "GET",
+                signal: request.signal,
+            });
+            if (!response.ok) {
+                throw new Error(await getErrorMessage(response));
+            }
+            const payload = (await response.json());
+            const rawEntries = payload.entries ?? [];
+            const { entries } = normalizeItems(rawEntries);
+            const folder = normalizeFolder(payload, request.folderId);
+            return {
+                breadcrumbs: normalizeBreadcrumbs(payload, folder),
+                folder,
+                folderId: request.folderId,
+                items: entries,
+                pagination: toPagination(payload, rawEntries.length, request),
+            };
+        },
+        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",
+                },
+                method: "GET",
+                signal: request.signal,
+            });
+            if (!response.ok) {
+                throw new Error(await getErrorMessage(response));
+            }
+            const payload = (await response.json());
+            const rawEntries = payload.entries ?? [];
+            const { entries } = normalizeItems(rawEntries);
+            return {
+                query: request.query,
+                ...(request.ancestorFolderId ? { ancestorFolderId: request.ancestorFolderId } : {}),
+                items: entries,
+                pagination: toPagination(payload, rawEntries.length, request),
+            };
+        },
+    };
+};

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

@@ -0,0 +1,17 @@
+import { Controller } from "../../../core/controller.js";
+import type { ExplorerItem, ExplorerPaginationState } from "../types.js";
+import type { ExplorerCollectionControllerOptions, ExplorerCollectionEvents, ExplorerCollectionState } from "./types.js";
+export interface ExplorerCollectionLoadResult {
+    items: ExplorerItem[];
+    pagination: ExplorerPaginationState;
+}
+export declare class ExplorerCollectionController extends Controller<ExplorerCollectionState, ExplorerCollectionEvents> {
+    private readonly options;
+    constructor(options?: ExplorerCollectionControllerOptions);
+    reset(): void;
+    setItems(items: ExplorerCollectionState["items"]): void;
+    startLoading(): void;
+    applyLoadResult(result: ExplorerCollectionLoadResult, append: boolean): void;
+    applyLoadFailure(): void;
+    canLoadNextPage(): boolean;
+}

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

@@ -0,0 +1,67 @@
+import { Controller } from "../../../core/controller.js";
+const DEFAULT_PAGE_SIZE = 100;
+const createInitialPaginationState = (options = {}) => ({
+    hasMoreItems: false,
+    limit: options.pageSize ?? DEFAULT_PAGE_SIZE,
+    offset: 0,
+    totalCount: null,
+});
+const createInitialState = (options = {}) => ({
+    items: [],
+    loading: false,
+    pagination: createInitialPaginationState(options),
+});
+export class ExplorerCollectionController extends Controller {
+    options;
+    constructor(options = {}) {
+        super(createInitialState(options));
+        this.options = options;
+    }
+    reset() {
+        this.setState(createInitialState(this.options));
+        this.emit("itemsChanged", { items: this.state.items });
+        this.emit("paginationChanged", { pagination: this.state.pagination });
+        this.emit("loadingChanged", { loading: this.state.loading });
+    }
+    setItems(items) {
+        this.setState({
+            ...this.state,
+            items,
+        });
+        this.emit("itemsChanged", { items });
+    }
+    startLoading() {
+        if (this.state.loading) {
+            return;
+        }
+        this.setState({
+            ...this.state,
+            loading: true,
+        });
+        this.emit("loadingChanged", { loading: true });
+    }
+    applyLoadResult(result, append) {
+        const items = append ? [...this.state.items, ...result.items] : result.items;
+        this.setState({
+            items,
+            loading: false,
+            pagination: result.pagination,
+        });
+        this.emit("itemsChanged", { items });
+        this.emit("paginationChanged", { pagination: result.pagination });
+        this.emit("loadingChanged", { loading: false });
+    }
+    applyLoadFailure() {
+        if (!this.state.loading) {
+            return;
+        }
+        this.setState({
+            ...this.state,
+            loading: false,
+        });
+        this.emit("loadingChanged", { loading: false });
+    }
+    canLoadNextPage() {
+        return !this.state.loading && this.state.pagination.hasMoreItems;
+    }
+}

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

@@ -0,0 +1,2 @@
+export { ExplorerCollectionController } from "./controller.js";
+export type { ExplorerCollectionControllerOptions, ExplorerCollectionEvents, ExplorerCollectionState, } from "./types.js";

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

@@ -0,0 +1 @@
+export { ExplorerCollectionController } from "./controller.js";

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

@@ -0,0 +1,20 @@
+import type { ExplorerItem, ExplorerPaginationState } from "../types.js";
+export interface ExplorerCollectionControllerOptions {
+    pageSize?: number;
+}
+export interface ExplorerCollectionState {
+    items: ExplorerItem[];
+    loading: boolean;
+    pagination: ExplorerPaginationState;
+}
+export interface ExplorerCollectionEvents {
+    itemsChanged: {
+        items: ExplorerItem[];
+    };
+    loadingChanged: {
+        loading: boolean;
+    };
+    paginationChanged: {
+        pagination: ExplorerPaginationState;
+    };
+}

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

@@ -0,0 +1 @@
+export {};