@unofficialbox/box-open-elements 0.1.0

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

@@ -0,0 +1,76 @@
+/**
+ * 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.
+ */
+const readFilterBarDetail = (event) => {
+    const detail = event.detail;
+    const value = detail?.value;
+    if (!value || typeof value !== "object") {
+        return null;
+    }
+    return {
+        filters: Array.isArray(value.filters) ? value.filters : [],
+        query: typeof value.query === "string" ? value.query : "",
+        sort: typeof value.sort === "string" ? value.sort : "",
+        view: typeof value.view === "string" ? value.view : "",
+    };
+};
+const runExplorerSearch = (explorer, query, onError) => {
+    const result = query ? explorer.search(query) : explorer.clearSearch();
+    void Promise.resolve(result).catch(error => {
+        onError?.(error);
+    });
+};
+/**
+ * Wire `box-filter-bar` search → explorer search/clearSearch.
+ * Returns an unsubscribe function.
+ */
+export const bindFilterBarToExplorer = (filterBar, explorer, options = {}) => {
+    let lastView;
+    const onSearch = (event) => {
+        // filter-bar emits `search` with `detail.value` = FilterBarState
+        const detail = event.detail;
+        const fromState = detail?.value?.query;
+        const query = (typeof fromState === "string" ? fromState : detail?.query ?? filterBar.query ?? "").trim();
+        runExplorerSearch(explorer, query, options.onError);
+    };
+    const onValueChanged = (event) => {
+        const state = readFilterBarDetail(event);
+        if (!state) {
+            return;
+        }
+        options.onValueChange?.(state);
+        if (state.view !== lastView) {
+            lastView = state.view;
+            options.onViewChange?.(state.view, state);
+        }
+    };
+    filterBar.addEventListener("search", onSearch);
+    filterBar.addEventListener("value-changed", onValueChanged);
+    return () => {
+        filterBar.removeEventListener("search", onSearch);
+        filterBar.removeEventListener("value-changed", onValueChanged);
+    };
+};
+/**
+ * Wire `box-saved-view-picker` → explorer search using host-owned presets.
+ */
+export const bindSavedViewPickerToExplorer = (picker, explorer, options) => {
+    const onValueChanged = (event) => {
+        const viewId = event.detail?.value;
+        if (!viewId) {
+            return;
+        }
+        const preset = options.resolvePreset(viewId);
+        if (!preset) {
+            return;
+        }
+        const query = (preset.query ?? "").trim();
+        runExplorerSearch(explorer, query, options.onError);
+    };
+    picker.addEventListener("value-changed", onValueChanged);
+    return () => {
+        picker.removeEventListener("value-changed", onValueChanged);
+    };
+};

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

@@ -0,0 +1,18 @@
+export * from "./types.js";
+export * from "./collection/index.js";
+export * from "./navigation/index.js";
+export * from "./actions/index.js";
+export * from "./selection/index.js";
+export * from "./controller.js";
+export * from "./contracts.js";
+export * from "./box-transport.js";
+export * from "./schemas.js";
+export * from "./adapters/action-menu.js";
+export * from "./adapters/toolbar.js";
+export * from "./adapters/list.js";
+export * from "./adapters/table.js";
+export * from "./adapters/items.js";
+export * from "./adapters/breadcrumbs.js";
+export * from "./adapters/item-summary.js";
+export * from "./content-explorer.js";
+export * from "./host-bindings.js";

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

@@ -0,0 +1,24 @@
+// Shared explorer contracts and state types
+export * from "./types.js";
+// Headless blocks
+export * from "./collection/index.js";
+export * from "./navigation/index.js";
+export * from "./actions/index.js";
+export * from "./selection/index.js";
+// Composition root, data-source contracts, Box transport, wire schemas
+export * from "./controller.js";
+export * from "./contracts.js";
+export * from "./box-transport.js";
+export * from "./schemas.js";
+// Presentation adapters
+export * from "./adapters/action-menu.js";
+export * from "./adapters/toolbar.js";
+export * from "./adapters/list.js";
+export * from "./adapters/table.js";
+export * from "./adapters/items.js";
+export * from "./adapters/breadcrumbs.js";
+export * from "./adapters/item-summary.js";
+// Composed workflow surface
+export * from "./content-explorer.js";
+// Host-level chrome bindings (filter-bar / saved-view → search)
+export * from "./host-bindings.js";

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

@@ -0,0 +1,10 @@
+import { Controller } from "../../../core/controller.js";
+import type { ExplorerFolder, ExplorerTransportResult } from "../types.js";
+import type { ExplorerNavigationControllerOptions, ExplorerNavigationEvents, ExplorerNavigationState } from "./types.js";
+export declare class ExplorerNavigationController extends Controller<ExplorerNavigationState, ExplorerNavigationEvents> {
+    private readonly options;
+    constructor(options: ExplorerNavigationControllerOptions);
+    reset(): void;
+    navigateTo(folderId: string): ExplorerFolder | null;
+    applyLoadedFolder(result: ExplorerTransportResult): void;
+}

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

@@ -0,0 +1,48 @@
+import { Controller } from "../../../core/controller.js";
+const createInitialState = (options) => ({
+    breadcrumbs: [],
+    currentFolder: null,
+    currentFolderId: options.rootFolderId,
+});
+export class ExplorerNavigationController extends Controller {
+    options;
+    constructor(options) {
+        super(createInitialState(options));
+        this.options = options;
+    }
+    reset() {
+        this.setState(createInitialState(this.options));
+        this.emit("breadcrumbsChanged", { breadcrumbs: this.state.breadcrumbs });
+    }
+    navigateTo(folderId) {
+        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,
+        ];
+        this.setState({
+            breadcrumbs: nextBreadcrumbs,
+            currentFolder: nextFolder,
+            currentFolderId: folderId,
+        });
+        this.emit("breadcrumbsChanged", { breadcrumbs: nextBreadcrumbs });
+        this.emit("folderChanged", { folder: nextFolder });
+        return nextFolder;
+    }
+    applyLoadedFolder(result) {
+        this.setState({
+            breadcrumbs: result.breadcrumbs,
+            currentFolder: result.folder,
+            currentFolderId: result.folderId,
+        });
+        this.emit("breadcrumbsChanged", { breadcrumbs: result.breadcrumbs });
+        this.emit("folderLoaded", { folder: result.folder });
+    }
+}

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

@@ -0,0 +1,2 @@
+export { ExplorerNavigationController } from "./controller.js";
+export type { ExplorerNavigationControllerOptions, ExplorerNavigationEvents, ExplorerNavigationState, } from "./types.js";

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

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

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

@@ -0,0 +1,20 @@
+import type { ExplorerBreadcrumb, ExplorerFolder } from "../types.js";
+export interface ExplorerNavigationControllerOptions {
+    rootFolderId: string;
+}
+export interface ExplorerNavigationState {
+    breadcrumbs: ExplorerBreadcrumb[];
+    currentFolder: ExplorerFolder | null;
+    currentFolderId: string;
+}
+export interface ExplorerNavigationEvents {
+    breadcrumbsChanged: {
+        breadcrumbs: ExplorerBreadcrumb[];
+    };
+    folderChanged: {
+        folder: ExplorerFolder;
+    };
+    folderLoaded: {
+        folder: ExplorerFolder;
+    };
+}

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

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

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

@@ -0,0 +1,6 @@
+import type { JsonSchema } from "../../core/json-schema.js";
+export declare const explorerItemSchema: JsonSchema;
+export declare const explorerFolderSchema: JsonSchema;
+export declare const explorerPaginationSchema: JsonSchema;
+export declare const explorerTransportResultSchema: JsonSchema;
+export declare const explorerSearchResultSchema: JsonSchema;

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

@@ -0,0 +1,120 @@
+export const explorerItemSchema = {
+    type: "object",
+    additionalProperties: false,
+    required: ["id", "name", "type"],
+    properties: {
+        id: { type: "string" },
+        name: { type: "string" },
+        type: { enum: ["file", "folder", "web_link"] },
+        size: { type: ["number", "null"] },
+        modifiedAt: { type: ["string", "null"] },
+        createdAt: { type: ["string", "null"] },
+        extension: { type: ["string", "null"] },
+        owner: {
+            type: ["object", "null"],
+            additionalProperties: false,
+            required: ["id", "name"],
+            properties: {
+                id: { type: "string" },
+                name: { type: "string" },
+                type: { enum: ["user", "group"] },
+            },
+        },
+        permissions: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                canDownload: { type: "boolean" },
+                canPreview: { type: "boolean" },
+                canShare: { type: "boolean" },
+                canDelete: { type: "boolean" },
+                canRename: { type: "boolean" },
+                canUpload: { type: "boolean" },
+            },
+        },
+        sharedLink: {
+            type: ["object", "null"],
+            additionalProperties: false,
+            required: ["isShared"],
+            properties: {
+                isShared: { type: "boolean" },
+                access: { enum: ["open", "company", "collaborators"] },
+                url: { type: "string" },
+            },
+        },
+        preview: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                canPreview: { type: "boolean" },
+                extension: { type: ["string", "null"] },
+                mimeType: { type: ["string", "null"] },
+            },
+        },
+        parent: {
+            type: ["object", "null"],
+            additionalProperties: false,
+            required: ["id"],
+            properties: {
+                id: { type: "string" },
+                name: { type: "string" },
+            },
+        },
+    },
+};
+export const explorerFolderSchema = {
+    type: "object",
+    additionalProperties: false,
+    required: ["id", "name", "type"],
+    properties: {
+        id: { type: "string" },
+        name: { type: "string" },
+        type: { const: "folder" },
+    },
+};
+export const explorerPaginationSchema = {
+    type: "object",
+    additionalProperties: false,
+    required: ["hasMoreItems", "limit", "offset", "totalCount"],
+    properties: {
+        hasMoreItems: { type: "boolean" },
+        limit: { type: "number" },
+        offset: { type: "number" },
+        totalCount: { type: ["number", "null"] },
+        nextOffset: { type: "number" },
+    },
+};
+export const explorerTransportResultSchema = {
+    $id: "box-open-elements/patterns/content-explorer/ExplorerTransportResult",
+    type: "object",
+    additionalProperties: false,
+    required: ["breadcrumbs", "folder", "folderId", "items", "pagination"],
+    properties: {
+        breadcrumbs: {
+            type: "array",
+            items: explorerFolderSchema,
+        },
+        folder: explorerFolderSchema,
+        folderId: { type: "string" },
+        items: {
+            type: "array",
+            items: explorerItemSchema,
+        },
+        pagination: explorerPaginationSchema,
+    },
+};
+export const explorerSearchResultSchema = {
+    $id: "box-open-elements/patterns/content-explorer/ExplorerSearchResult",
+    type: "object",
+    additionalProperties: false,
+    required: ["query", "items", "pagination"],
+    properties: {
+        query: { type: "string" },
+        ancestorFolderId: { type: "string" },
+        items: {
+            type: "array",
+            items: explorerItemSchema,
+        },
+        pagination: explorerPaginationSchema,
+    },
+};

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

@@ -0,0 +1,12 @@
+import { Controller } from "../../../core/controller.js";
+import type { ExplorerSelectableItem, ExplorerSelectionControllerOptions, ExplorerSelectionEvents, ExplorerSelectionState } from "./types.js";
+export declare class ExplorerSelectionController extends Controller<ExplorerSelectionState, ExplorerSelectionEvents> {
+    private availableItemIds;
+    constructor(options?: ExplorerSelectionControllerOptions);
+    setItems(items: ExplorerSelectableItem[]): void;
+    select(itemIds: string[]): void;
+    toggleSelection(itemId: string): void;
+    clearSelection(): void;
+    private filterValidIds;
+    private applySelectionMode;
+}

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

@@ -0,0 +1,54 @@
+import { Controller } from "../../../core/controller.js";
+const createInitialState = (options) => ({
+    selectedItemIds: [],
+    selectionMode: options.selectionMode ?? "multiple",
+});
+export class ExplorerSelectionController extends Controller {
+    availableItemIds = new Set();
+    constructor(options = {}) {
+        super(createInitialState(options));
+    }
+    setItems(items) {
+        this.availableItemIds = new Set(items.map(item => item.id));
+        const selectedItemIds = this.filterValidIds(this.state.selectedItemIds);
+        this.setState({
+            ...this.state,
+            selectedItemIds,
+        });
+        this.emit("selectionChanged", { selectedItemIds });
+    }
+    select(itemIds) {
+        const selectedItemIds = this.applySelectionMode(this.filterValidIds(itemIds));
+        this.setState({
+            ...this.state,
+            selectedItemIds,
+        });
+        this.emit("selectionChanged", { selectedItemIds });
+    }
+    toggleSelection(itemId) {
+        if (!this.availableItemIds.has(itemId)) {
+            return;
+        }
+        const existing = new Set(this.state.selectedItemIds);
+        if (existing.has(itemId)) {
+            existing.delete(itemId);
+        }
+        else if (this.state.selectionMode === "single") {
+            existing.clear();
+            existing.add(itemId);
+        }
+        else {
+            existing.add(itemId);
+        }
+        this.select([...existing]);
+    }
+    clearSelection() {
+        this.select([]);
+    }
+    filterValidIds(itemIds) {
+        return itemIds.filter(itemId => this.availableItemIds.has(itemId));
+    }
+    applySelectionMode(itemIds) {
+        return this.state.selectionMode === "single" ? itemIds.slice(0, 1) : itemIds;
+    }
+}

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

@@ -0,0 +1,2 @@
+export { ExplorerSelectionController } from "./controller.js";
+export type { ExplorerSelectableItem, ExplorerSelectionControllerOptions, ExplorerSelectionEvents, ExplorerSelectionState, } from "./types.js";

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

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

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

@@ -0,0 +1,14 @@
+import type { ExplorerItem, ExplorerSelectionMode } from "../types.js";
+export interface ExplorerSelectionControllerOptions {
+    selectionMode?: ExplorerSelectionMode;
+}
+export interface ExplorerSelectionState {
+    selectedItemIds: string[];
+    selectionMode: ExplorerSelectionMode;
+}
+export interface ExplorerSelectionEvents {
+    selectionChanged: {
+        selectedItemIds: string[];
+    };
+}
+export type ExplorerSelectableItem = Pick<ExplorerItem, "id">;

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

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

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

@@ -0,0 +1,209 @@
+export interface ExplorerItemPermissions {
+    canDownload?: boolean;
+    canPreview?: boolean;
+    canShare?: boolean;
+    canDelete?: boolean;
+    canRename?: boolean;
+    canUpload?: boolean;
+}
+export interface ExplorerItemOwner {
+    id: string;
+    name: string;
+    type?: "user" | "group";
+}
+/** Lightweight list-row signal; full share state stays in patterns/share. */
+export interface ExplorerItemSharedLinkSummary {
+    isShared: boolean;
+    access?: "open" | "company" | "collaborators";
+    url?: string;
+}
+export interface ExplorerItemPreviewAffordance {
+    canPreview?: boolean;
+    extension?: string | null;
+    mimeType?: string | null;
+}
+export interface ExplorerItem {
+    id: string;
+    name: string;
+    type: "file" | "folder" | "web_link";
+    size?: number | null;
+    modifiedAt?: string | null;
+    createdAt?: string | null;
+    extension?: string | null;
+    owner?: ExplorerItemOwner | null;
+    permissions?: ExplorerItemPermissions;
+    sharedLink?: ExplorerItemSharedLinkSummary | null;
+    preview?: ExplorerItemPreviewAffordance;
+    /** Useful in search results; omit in folder listing when redundant. */
+    parent?: {
+        id: string;
+        name?: string;
+    } | null;
+}
+export type ExplorerSelectionMode = "multiple" | "single";
+/**
+ * Presentation gesture mapping for explorer item rows:
+ * - `split` (default): click/Space select; Enter/dblclick activate
+ * - `legacy`: click/Enter/Space both select and activate
+ */
+export type ExplorerItemGesture = "split" | "legacy";
+export declare const resolveExplorerItemGesture: (value: string | null | undefined) => ExplorerItemGesture;
+/** Legacy click/Space also activates; split mode selects only. */
+export declare const shouldActivateOnClick: (gesture: ExplorerItemGesture) => boolean;
+/** Legacy Enter also toggles selection before activate; split mode activates only. */
+export declare const shouldToggleOnEnter: (gesture: ExplorerItemGesture) => boolean;
+export type ExplorerViewMode = "folder" | "search";
+export interface ExplorerViewState {
+    mode: ExplorerViewMode;
+    /** Non-null when mode === "search". */
+    searchQuery: string | null;
+    /** Folder scope for search; defaults to current folder when entering search. */
+    searchAncestorFolderId: string | null;
+}
+export declare const createInitialExplorerViewState: () => ExplorerViewState;
+export interface ExplorerItemAction {
+    id: string;
+    itemTypes?: ExplorerItem["type"][];
+    label: string;
+}
+export interface ExplorerFolder {
+    id: string;
+    name: string;
+    type: "folder";
+}
+export interface ExplorerBreadcrumb {
+    id: string;
+    name: string;
+    type: "folder";
+}
+export interface ExplorerItemCollection {
+    entries: ExplorerItem[];
+}
+export interface ExplorerTransportRequest {
+    folderId: string;
+    limit?: number;
+    offset?: number;
+    token: string;
+    language?: string;
+    signal?: AbortSignal;
+}
+export interface ExplorerSearchRequest {
+    query: string;
+    ancestorFolderId?: string;
+    limit?: number;
+    offset?: number;
+    token: string;
+    language?: string;
+    signal?: AbortSignal;
+}
+export interface ExplorerPaginationState {
+    hasMoreItems: boolean;
+    limit: number;
+    offset: number;
+    totalCount: number | null;
+    /**
+     * Upstream cursor for the next page when client-side filtering shrinks `items`
+     * (e.g. unsupported Box entry types). Controllers should prefer this over
+     * `items.length` when requesting the next page.
+     */
+    nextOffset?: number;
+}
+export interface ExplorerTransportResult {
+    breadcrumbs: ExplorerBreadcrumb[];
+    folder: ExplorerFolder;
+    folderId: string;
+    items: ExplorerItem[];
+    pagination: ExplorerPaginationState;
+}
+export interface ExplorerSearchResult {
+    query: string;
+    ancestorFolderId?: string;
+    items: ExplorerItem[];
+    pagination: ExplorerPaginationState;
+}
+export interface ExplorerTransport {
+    loadFolderItems(request: ExplorerTransportRequest): Promise<ExplorerTransportResult>;
+    searchItems?(request: ExplorerSearchRequest): Promise<ExplorerSearchResult>;
+}
+export interface ExplorerFetchLike {
+    (input: string | URL | Request, init?: RequestInit): Promise<Response>;
+}
+export interface ExplorerSessionConfig {
+    container?: Element | null;
+    itemActions?: ExplorerItemAction[];
+    rootFolderId: string;
+    selectionMode?: ExplorerSelectionMode;
+    token: string;
+    language?: string;
+    pageSize?: number;
+    transport: ExplorerTransport;
+}
+export interface ExplorerErrorState {
+    code: "load_failed";
+    message: string;
+}
+export interface ExplorerState {
+    availableActionsByItemId: Record<string, ExplorerItemAction[]>;
+    breadcrumbs: ExplorerBreadcrumb[];
+    connected: boolean;
+    currentFolder: ExplorerFolder | null;
+    currentFolderId: string;
+    error: ExplorerErrorState | null;
+    items: ExplorerItem[];
+    loading: boolean;
+    pagination: ExplorerPaginationState;
+    selectedItemIds: string[];
+    view: ExplorerViewState;
+}
+export interface ExplorerEvents {
+    breadcrumbsChanged: {
+        breadcrumbs: ExplorerBreadcrumb[];
+    };
+    connected: {
+        folderId: string;
+    };
+    disconnected: undefined;
+    folderChanged: {
+        folder: ExplorerFolder;
+    };
+    loadFailed: {
+        folderId: string;
+        message: string;
+    };
+    loadSucceeded: {
+        folder: ExplorerFolder;
+        folderId: string;
+        items: ExplorerItem[];
+        pagination: ExplorerPaginationState;
+    };
+    loadingChanged: {
+        loading: boolean;
+    };
+    folderLoaded: {
+        folder: ExplorerFolder;
+    };
+    itemActivated: {
+        item: ExplorerItem;
+    };
+    itemsChanged: {
+        items: ExplorerItem[];
+    };
+    itemActionInvoked: {
+        action: ExplorerItemAction;
+        item: ExplorerItem;
+    };
+    paginationChanged: {
+        pagination: ExplorerPaginationState;
+    };
+    selectionChanged: {
+        selectedItemIds: string[];
+    };
+    viewChanged: {
+        view: ExplorerViewState;
+    };
+    searchSucceeded: {
+        query: string;
+        items: ExplorerItem[];
+        pagination: ExplorerPaginationState;
+    };
+}

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

@@ -0,0 +1,10 @@
+export const resolveExplorerItemGesture = (value) => value === "legacy" ? "legacy" : "split";
+/** Legacy click/Space also activates; split mode selects only. */
+export const shouldActivateOnClick = (gesture) => gesture === "legacy";
+/** Legacy Enter also toggles selection before activate; split mode activates only. */
+export const shouldToggleOnEnter = (gesture) => gesture === "legacy";
+export const createInitialExplorerViewState = () => ({
+    mode: "folder",
+    searchQuery: null,
+    searchAncestorFolderId: null,
+});