@unofficialbox/box-open-elements 0.1.0

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

@@ -0,0 +1,32 @@
+import type { ExplorerFetchLike, ExplorerSearchResult, ExplorerTransport, ExplorerTransportResult } from "./types.js";
+export interface ContentExplorerRequestContext {
+    locale?: string;
+    requestId?: string;
+    signal?: AbortSignal;
+}
+export interface ContentExplorerListFolderInput {
+    folderId: string;
+    limit?: number;
+    offset?: number;
+    context?: ContentExplorerRequestContext;
+}
+export interface ContentExplorerSearchInput {
+    query: string;
+    ancestorFolderId?: string;
+    limit?: number;
+    offset?: number;
+    context?: ContentExplorerRequestContext;
+}
+export interface ContentExplorerDataSource {
+    listFolderItems(input: ContentExplorerListFolderInput): Promise<ExplorerTransportResult>;
+    search?(input: ContentExplorerSearchInput): Promise<ExplorerSearchResult>;
+}
+export interface ContentExplorerHttpDataSourceOptions {
+    baseUrl?: string;
+    fetch?: ExplorerFetchLike;
+    headers?: Record<string, string>;
+    buildListFolderUrl?: (input: ContentExplorerListFolderInput) => string;
+    buildSearchUrl?: (input: ContentExplorerSearchInput) => string;
+}
+export declare const createExplorerTransportFromDataSource: (dataSource: ContentExplorerDataSource) => ExplorerTransport;
+export declare const createHttpContentExplorerDataSource: (options?: ContentExplorerHttpDataSourceOptions) => ContentExplorerDataSource;

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

@@ -0,0 +1,114 @@
+const resolveFetch = (providedFetch) => {
+    if (providedFetch) {
+        return providedFetch;
+    }
+    if (typeof globalThis.fetch !== "function") {
+        throw new Error("A fetch implementation is required to use the explorer HTTP data source.");
+    }
+    return globalThis.fetch.bind(globalThis);
+};
+const resolveUrlBase = () => {
+    if (typeof globalThis.location?.href === "string" && globalThis.location.href.length > 0) {
+        return globalThis.location.href;
+    }
+    return "http://localhost";
+};
+const defaultListFolderUrl = (baseUrl, input) => {
+    const root = baseUrl.replace(/\/$/, "");
+    const url = new URL(`${root}/folders/${encodeURIComponent(input.folderId)}/items`, resolveUrlBase());
+    if (typeof input.limit === "number") {
+        url.searchParams.set("limit", String(input.limit));
+    }
+    if (typeof input.offset === "number") {
+        url.searchParams.set("offset", String(input.offset));
+    }
+    return url.toString();
+};
+const defaultSearchUrl = (baseUrl, input) => {
+    const root = baseUrl.replace(/\/$/, "");
+    const url = new URL(`${root}/search`, resolveUrlBase());
+    url.searchParams.set("query", input.query);
+    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));
+    }
+    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 parse issues and fall back to status text
+    }
+    return `Explorer request failed with status ${response.status}`;
+};
+export const createExplorerTransportFromDataSource = (dataSource) => {
+    const transport = {
+        loadFolderItems(request) {
+            return dataSource.listFolderItems({
+                folderId: request.folderId,
+                limit: request.limit,
+                offset: request.offset,
+                context: {
+                    locale: request.language,
+                    signal: request.signal,
+                },
+            });
+        },
+    };
+    if (dataSource.search) {
+        const search = dataSource.search.bind(dataSource);
+        transport.searchItems = request => search({
+            query: request.query,
+            ancestorFolderId: request.ancestorFolderId,
+            limit: request.limit,
+            offset: request.offset,
+            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 response = await fetchImpl(url, {
+            method: "GET",
+            credentials: "same-origin",
+            cache: "no-store",
+            headers: {
+                accept: "application/json",
+                ...(input.context?.locale ? { "accept-language": input.context.locale } : {}),
+                ...(input.context?.requestId ? { "x-request-id": input.context.requestId } : {}),
+                ...options.headers,
+            },
+            signal: input.context?.signal,
+        });
+        if (!response.ok) {
+            throw new Error(await getErrorMessage(response));
+        }
+        return (await response.json());
+    };
+    return {
+        async listFolderItems(input) {
+            const url = options.buildListFolderUrl?.(input) ?? defaultListFolderUrl(baseUrl, input);
+            return requestJson(url, input);
+        },
+        async search(input) {
+            const url = options.buildSearchUrl?.(input) ?? defaultSearchUrl(baseUrl, input);
+            return requestJson(url, input);
+        },
+    };
+};

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

@@ -0,0 +1,34 @@
+import { Controller } from "../../core/controller.js";
+import type { ExplorerEvents, ExplorerItem, ExplorerSelectionMode, ExplorerSessionConfig, ExplorerState } from "./types.js";
+export declare class ContentExplorerController extends Controller<ExplorerState, ExplorerEvents> {
+    readonly config: ExplorerSessionConfig;
+    private activeLoadRequestId;
+    private readonly actionsController;
+    private readonly collectionController;
+    private readonly navigationController;
+    private readonly selectionController;
+    constructor(config: ExplorerSessionConfig);
+    get selectionMode(): ExplorerSelectionMode;
+    connect(): Promise<void>;
+    disconnect(): void;
+    private setView;
+    search(query: string, options?: {
+        ancestorFolderId?: string;
+    }): Promise<void>;
+    clearSearch(): Promise<void>;
+    navigateTo(folderId: string): Promise<void>;
+    setItems(items: ExplorerItem[]): void;
+    select(itemIds: string[]): void;
+    toggleSelection(itemId: string): void;
+    clearSelection(): void;
+    getItemActions(itemId: string): import("./types.js").ExplorerItemAction[];
+    invokeItemAction(itemId: string, actionId: string): void;
+    activateItem(itemId: string): Promise<void>;
+    reload(): Promise<void>;
+    refresh(): Promise<void>;
+    loadNextPage(): Promise<void>;
+    private loadPage;
+    private applyLoadedSearch;
+    private applyLoadedFolder;
+    private applyLoadFailure;
+}

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

@@ -0,0 +1,399 @@
+import { Controller } from "../../core/controller.js";
+import { ExplorerActionsController } from "./actions/controller.js";
+import { ExplorerCollectionController } from "./collection/controller.js";
+import { ExplorerNavigationController } from "./navigation/controller.js";
+import { ExplorerSelectionController } from "./selection/controller.js";
+import { createInitialExplorerViewState } from "./types.js";
+const createInitialState = (config) => ({
+    availableActionsByItemId: {},
+    breadcrumbs: [],
+    connected: false,
+    currentFolder: null,
+    currentFolderId: config.rootFolderId,
+    error: null,
+    items: [],
+    loading: false,
+    pagination: {
+        hasMoreItems: false,
+        limit: config.pageSize ?? 100,
+        offset: 0,
+        totalCount: null,
+    },
+    selectedItemIds: [],
+    view: createInitialExplorerViewState(),
+});
+export class ContentExplorerController extends Controller {
+    config;
+    activeLoadRequestId = 0;
+    actionsController;
+    collectionController;
+    navigationController;
+    selectionController;
+    constructor(config) {
+        super(createInitialState(config));
+        this.config = config;
+        this.actionsController = new ExplorerActionsController({ itemActions: config.itemActions });
+        this.collectionController = new ExplorerCollectionController({ pageSize: config.pageSize });
+        this.navigationController = new ExplorerNavigationController({ rootFolderId: config.rootFolderId });
+        this.selectionController = new ExplorerSelectionController({ selectionMode: config.selectionMode });
+        this.actionsController.subscribe("itemActionInvoked", payload => {
+            this.emit("itemActionInvoked", payload);
+        });
+        this.collectionController.subscribe("itemsChanged", ({ items }) => {
+            this.setState({
+                ...this.state,
+                items,
+            });
+            this.emit("itemsChanged", { items });
+        });
+        this.collectionController.subscribe("loadingChanged", ({ loading }) => {
+            this.setState({
+                ...this.state,
+                loading,
+            });
+            this.emit("loadingChanged", { loading });
+        });
+        this.collectionController.subscribe("paginationChanged", ({ pagination }) => {
+            this.setState({
+                ...this.state,
+                pagination,
+            });
+            this.emit("paginationChanged", { pagination });
+        });
+        this.navigationController.subscribe("breadcrumbsChanged", ({ breadcrumbs }) => {
+            this.setState({
+                ...this.state,
+                breadcrumbs,
+            });
+            this.emit("breadcrumbsChanged", { breadcrumbs });
+        });
+        this.navigationController.subscribe("folderChanged", ({ folder }) => {
+            this.setState({
+                ...this.state,
+                currentFolder: folder,
+                currentFolderId: folder.id,
+            });
+            this.emit("folderChanged", { folder });
+        });
+        this.navigationController.subscribe("folderLoaded", ({ folder }) => {
+            const navigationState = this.navigationController.getState();
+            this.setState({
+                ...this.state,
+                breadcrumbs: navigationState.breadcrumbs,
+                currentFolder: folder,
+                currentFolderId: navigationState.currentFolderId,
+            });
+            this.emit("folderLoaded", { folder });
+        });
+    }
+    get selectionMode() {
+        return this.config.selectionMode ?? "multiple";
+    }
+    async connect() {
+        if (this.state.connected) {
+            return;
+        }
+        this.setState({
+            ...this.state,
+            connected: true,
+        });
+        this.emit("connected", { folderId: this.state.currentFolderId });
+        await this.reload();
+    }
+    disconnect() {
+        if (!this.state.connected) {
+            return;
+        }
+        this.setState({
+            ...this.state,
+            breadcrumbs: [],
+            connected: false,
+            currentFolder: this.navigationController.getState().currentFolder,
+            error: null,
+            items: [],
+            loading: false,
+            pagination: this.collectionController.getState().pagination,
+            selectedItemIds: [],
+            view: createInitialExplorerViewState(),
+        });
+        this.activeLoadRequestId += 1;
+        this.collectionController.reset();
+        this.navigationController.reset();
+        this.emit("viewChanged", { view: this.state.view });
+        this.emit("disconnected", undefined);
+    }
+    setView(view) {
+        this.setState({
+            ...this.state,
+            view,
+        });
+        this.emit("viewChanged", { view });
+    }
+    async search(query, options) {
+        const trimmed = query.trim();
+        if (!trimmed) {
+            await this.clearSearch();
+            return;
+        }
+        if (!this.config.transport.searchItems) {
+            throw new Error("Explorer transport does not support search");
+        }
+        if (!this.state.connected) {
+            return;
+        }
+        const ancestorFolderId = options?.ancestorFolderId ?? this.state.currentFolderId;
+        this.setView({
+            mode: "search",
+            searchQuery: trimmed,
+            searchAncestorFolderId: ancestorFolderId,
+        });
+        this.setState({
+            ...this.state,
+            error: null,
+            items: [],
+            selectedItemIds: [],
+            availableActionsByItemId: {},
+            pagination: this.collectionController.getState().pagination,
+        });
+        this.collectionController.reset();
+        this.actionsController.setItems([]);
+        this.selectionController.setItems([]);
+        await this.reload();
+    }
+    async clearSearch() {
+        if (this.state.view.mode === "folder" && !this.state.view.searchQuery) {
+            return;
+        }
+        this.setView(createInitialExplorerViewState());
+        this.setState({
+            ...this.state,
+            error: null,
+            items: [],
+            selectedItemIds: [],
+            availableActionsByItemId: {},
+        });
+        this.collectionController.reset();
+        this.actionsController.setItems([]);
+        this.selectionController.setItems([]);
+        if (this.state.connected) {
+            await this.reload();
+        }
+    }
+    async navigateTo(folderId) {
+        const nextFolder = this.navigationController.navigateTo(folderId);
+        if (!nextFolder) {
+            return;
+        }
+        if (this.state.view.mode === "search") {
+            this.setView(createInitialExplorerViewState());
+        }
+        this.setState({
+            ...this.state,
+            currentFolder: nextFolder,
+            currentFolderId: folderId,
+            error: null,
+            items: [],
+            pagination: this.collectionController.getState().pagination,
+            selectedItemIds: [],
+            availableActionsByItemId: {},
+        });
+        this.collectionController.reset();
+        this.actionsController.setItems([]);
+        this.selectionController.setItems([]);
+        await this.reload();
+    }
+    setItems(items) {
+        this.collectionController.setItems(items);
+        this.actionsController.setItems(items);
+        this.selectionController.setItems(items);
+        const selectedItemIds = this.selectionController.getState().selectedItemIds;
+        this.setState({
+            ...this.state,
+            availableActionsByItemId: this.actionsController.getState().availableActionsByItemId,
+            error: null,
+            items: this.collectionController.getState().items,
+            selectedItemIds,
+        });
+        this.emit("selectionChanged", { selectedItemIds });
+    }
+    select(itemIds) {
+        this.selectionController.select(itemIds);
+        const selectedItemIds = this.selectionController.getState().selectedItemIds;
+        this.setState({
+            ...this.state,
+            selectedItemIds,
+        });
+        this.emit("selectionChanged", { selectedItemIds });
+    }
+    toggleSelection(itemId) {
+        this.selectionController.toggleSelection(itemId);
+        const selectedItemIds = this.selectionController.getState().selectedItemIds;
+        this.setState({
+            ...this.state,
+            selectedItemIds,
+        });
+        this.emit("selectionChanged", { selectedItemIds });
+    }
+    clearSelection() {
+        this.selectionController.clearSelection();
+        const selectedItemIds = this.selectionController.getState().selectedItemIds;
+        this.setState({
+            ...this.state,
+            selectedItemIds,
+        });
+        this.emit("selectionChanged", { selectedItemIds });
+    }
+    getItemActions(itemId) {
+        return this.actionsController.getItemActions(itemId);
+    }
+    invokeItemAction(itemId, actionId) {
+        this.actionsController.invokeItemAction(itemId, actionId);
+    }
+    async activateItem(itemId) {
+        const item = this.state.items.find(entry => entry.id === itemId);
+        if (!item) {
+            return;
+        }
+        this.emit("itemActivated", { item });
+        if (item.type === "folder") {
+            await this.navigateTo(item.id);
+        }
+    }
+    async reload() {
+        await this.loadPage({ append: false });
+    }
+    async refresh() {
+        await this.reload();
+    }
+    async loadNextPage() {
+        if (!this.state.connected || !this.collectionController.canLoadNextPage()) {
+            return;
+        }
+        await this.loadPage({ append: true });
+    }
+    async loadPage({ append }) {
+        if (!this.state.connected) {
+            return;
+        }
+        const requestId = this.activeLoadRequestId + 1;
+        this.activeLoadRequestId = requestId;
+        this.setState({
+            ...this.state,
+            error: null,
+        });
+        this.collectionController.startLoading();
+        const pagination = this.collectionController.getState().pagination;
+        const requestOffset = append ? (pagination.nextOffset ?? this.collectionController.getState().items.length) : 0;
+        try {
+            if (this.state.view.mode === "search") {
+                const searchItems = this.config.transport.searchItems;
+                if (!searchItems) {
+                    throw new Error("Explorer transport does not support search");
+                }
+                const query = this.state.view.searchQuery ?? "";
+                const result = await searchItems({
+                    query,
+                    ancestorFolderId: this.state.view.searchAncestorFolderId ?? undefined,
+                    limit: pagination.limit,
+                    offset: requestOffset,
+                    token: this.config.token,
+                    language: this.config.language,
+                });
+                this.applyLoadedSearch(requestId, result, append);
+                return;
+            }
+            const result = await this.config.transport.loadFolderItems({
+                folderId: this.state.currentFolderId,
+                limit: pagination.limit,
+                offset: requestOffset,
+                token: this.config.token,
+                language: this.config.language,
+            });
+            this.applyLoadedFolder(requestId, result, append);
+        }
+        catch (error) {
+            this.applyLoadFailure(requestId, error, append);
+        }
+    }
+    applyLoadedSearch(requestId, result, append) {
+        if (requestId !== this.activeLoadRequestId) {
+            return;
+        }
+        this.collectionController.applyLoadResult(result, append);
+        const items = this.collectionController.getState().items;
+        this.actionsController.setItems(items);
+        this.selectionController.setItems(items);
+        this.selectionController.select(this.state.selectedItemIds);
+        const selectedItemIds = this.selectionController.getState().selectedItemIds;
+        this.setState({
+            ...this.state,
+            availableActionsByItemId: this.actionsController.getState().availableActionsByItemId,
+            error: null,
+            items,
+            loading: this.collectionController.getState().loading,
+            pagination: this.collectionController.getState().pagination,
+            selectedItemIds,
+            view: {
+                mode: "search",
+                searchQuery: result.query,
+                searchAncestorFolderId: result.ancestorFolderId ?? this.state.view.searchAncestorFolderId,
+            },
+        });
+        this.emit("selectionChanged", { selectedItemIds });
+        this.emit("searchSucceeded", {
+            query: result.query,
+            items,
+            pagination: this.collectionController.getState().pagination,
+        });
+    }
+    applyLoadedFolder(requestId, result, append) {
+        if (requestId !== this.activeLoadRequestId) {
+            return;
+        }
+        this.collectionController.applyLoadResult(result, append);
+        this.navigationController.applyLoadedFolder(result);
+        const items = this.collectionController.getState().items;
+        this.actionsController.setItems(items);
+        this.selectionController.setItems(items);
+        this.selectionController.select(this.state.selectedItemIds);
+        const selectedItemIds = this.selectionController.getState().selectedItemIds;
+        this.setState({
+            ...this.state,
+            availableActionsByItemId: this.actionsController.getState().availableActionsByItemId,
+            breadcrumbs: this.navigationController.getState().breadcrumbs,
+            currentFolder: this.navigationController.getState().currentFolder,
+            currentFolderId: this.navigationController.getState().currentFolderId,
+            error: null,
+            items,
+            loading: this.collectionController.getState().loading,
+            pagination: this.collectionController.getState().pagination,
+            selectedItemIds,
+        });
+        this.emit("selectionChanged", { selectedItemIds });
+        this.emit("loadSucceeded", { folder: result.folder, folderId: result.folderId, items, pagination: result.pagination });
+    }
+    applyLoadFailure(requestId, error, append) {
+        if (requestId !== this.activeLoadRequestId) {
+            return;
+        }
+        const message = error instanceof Error ? error.message : "Failed to load folder items";
+        this.collectionController.applyLoadFailure();
+        const collectionState = this.collectionController.getState();
+        this.setState({
+            ...this.state,
+            error: {
+                code: "load_failed",
+                message,
+            },
+            loading: collectionState.loading,
+            availableActionsByItemId: append ? this.actionsController.getState().availableActionsByItemId : {},
+            items: append ? collectionState.items : [],
+            selectedItemIds: append ? this.state.selectedItemIds : [],
+        });
+        if (!append) {
+            this.collectionController.setItems([]);
+        }
+        this.emit("selectionChanged", { selectedItemIds: append ? this.state.selectedItemIds : [] });
+        this.emit("loadFailed", { folderId: this.state.currentFolderId, message });
+    }
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Host-level wiring between search chrome (filter bar / saved views) and an
+ * explorer surface that exposes search / clearSearch. Keeps transport and
+ * recents out of these helpers — hosts own presets and presentation mode.
+ */
+export type ExplorerSearchHost = {
+    search: (query: string) => void | Promise<void>;
+    clearSearch: () => void | Promise<void>;
+};
+export type FilterBarValue = {
+    filters: string[];
+    query: string;
+    sort: string;
+    view: string;
+};
+export type FilterBarLike = EventTarget & {
+    query?: string;
+};
+export type SavedViewPreset = {
+    id: string;
+    /** Search query to apply; empty/undefined clears search. */
+    query?: string;
+};
+export type BindFilterBarOptions = {
+    /**
+     * Optional hook when the filter-bar `view` select changes (list/table/etc.).
+     * Explorer itself does not switch presentation modes — the host does.
+     * Fires only when `view` differs from the previous value.
+     */
+    onViewChange?: (view: string, state: FilterBarValue) => void;
+    /** Fired for every `value-changed` (filters/sort/query/view). */
+    onValueChange?: (state: FilterBarValue) => void;
+    /** Called when search/clearSearch rejects (avoids unhandled rejections). */
+    onError?: (error: unknown) => void;
+};
+/**
+ * Wire `box-filter-bar` search → explorer search/clearSearch.
+ * Returns an unsubscribe function.
+ */
+export declare const bindFilterBarToExplorer: (filterBar: FilterBarLike, explorer: ExplorerSearchHost, options?: BindFilterBarOptions) => (() => void);
+export type BindSavedViewOptions = {
+    /** Resolve a picked view id to a preset the host owns (local, not server). */
+    resolvePreset: (viewId: string) => SavedViewPreset | null | undefined;
+    /** Called when search/clearSearch rejects (avoids unhandled rejections). */
+    onError?: (error: unknown) => void;
+};
+/**
+ * Wire `box-saved-view-picker` → explorer search using host-owned presets.
+ */
+export declare const bindSavedViewPickerToExplorer: (picker: EventTarget, explorer: ExplorerSearchHost, options: BindSavedViewOptions) => (() => void);