@box/metadata-template-browser 1.16.3

package/dist/types/lib/contexts/reducer.d.ts

@@ -0,0 +1,106 @@
+import { BreadcrumbEntry, LevelCache, MetadataNamespace, MetadataTemplate } from '../types';
+export declare enum BrowserActionType {
+    NavigateTo = "NAVIGATE_TO",
+    NavigateBack = "NAVIGATE_BACK",
+    BrowseFetchStart = "BROWSE_FETCH_START",
+    BrowseLoaded = "BROWSE_LOADED",
+    InitialLoadError = "INITIAL_LOAD_ERROR",
+    BrowseError = "BROWSE_ERROR",
+    LoadMoreStart = "LOAD_MORE_START",
+    LoadMoreNamespacesLoaded = "LOAD_MORE_NAMESPACES_LOADED",
+    LoadMoreTemplatesLoaded = "LOAD_MORE_TEMPLATES_LOADED",
+    LoadMoreError = "LOAD_MORE_ERROR",
+    SearchValueChange = "SEARCH_VALUE_CHANGE",
+    SearchFetchStart = "SEARCH_FETCH_START",
+    SearchLoaded = "SEARCH_LOADED",
+    SearchError = "SEARCH_ERROR",
+    SearchClear = "SEARCH_CLEAR",
+    LoadMoreSearchLoaded = "LOAD_MORE_SEARCH_LOADED",
+    TemplateSelect = "TEMPLATE_SELECT"
+}
+/** Complete reducer state for the metadata template browser, split into navigation, browse, search, and selection slices. */
+export interface BrowserState {
+    namespaceFQN: string;
+    path: BreadcrumbEntry[];
+    namespaces: MetadataNamespace[];
+    templates: MetadataTemplate[];
+    isNamespacesExhausted: boolean;
+    namespaceNextMarker: string | undefined;
+    templateNextMarker: string | undefined;
+    isFetching: boolean;
+    isFetchingMore: boolean;
+    initialLoadError: string | null;
+    browseError: string | null;
+    loadMoreError: string | null;
+    searchValue: string;
+    searchQuery: string;
+    searchResults: MetadataTemplate[];
+    searchNextMarker: string | undefined;
+    isFetchingSearch: boolean;
+    searchError: string | null;
+    selectedTemplateId: string | null;
+}
+/** Union of all dispatchable actions that drive `BrowserState` transitions. */
+export type BrowserAction = {
+    type: BrowserActionType.NavigateTo;
+    namespace: MetadataNamespace;
+} | {
+    type: BrowserActionType.NavigateBack;
+    fqn: string;
+    cached: LevelCache;
+} | {
+    type: BrowserActionType.BrowseFetchStart;
+} | {
+    type: BrowserActionType.BrowseLoaded;
+    namespaces: MetadataNamespace[];
+    namespaceNextMarker?: string;
+    templates: MetadataTemplate[];
+    templateNextMarker?: string;
+} | {
+    type: BrowserActionType.InitialLoadError;
+    error: string;
+} | {
+    type: BrowserActionType.BrowseError;
+    error: string;
+} | {
+    type: BrowserActionType.LoadMoreStart;
+} | {
+    type: BrowserActionType.LoadMoreNamespacesLoaded;
+    entries: MetadataNamespace[];
+    nextMarker?: string;
+    /** First page of templates, populated only when namespaces become exhausted on this page. */
+    templates?: MetadataTemplate[];
+    templateNextMarker?: string;
+} | {
+    type: BrowserActionType.LoadMoreTemplatesLoaded;
+    entries: MetadataTemplate[];
+    nextMarker?: string;
+} | {
+    type: BrowserActionType.LoadMoreError;
+    error: string;
+} | {
+    type: BrowserActionType.SearchValueChange;
+    value: string;
+} | {
+    type: BrowserActionType.SearchFetchStart;
+    query: string;
+} | {
+    type: BrowserActionType.SearchLoaded;
+    results: MetadataTemplate[];
+    nextMarker?: string;
+} | {
+    type: BrowserActionType.SearchError;
+    error: string;
+} | {
+    type: BrowserActionType.SearchClear;
+} | {
+    type: BrowserActionType.LoadMoreSearchLoaded;
+    entries: MetadataTemplate[];
+    nextMarker?: string;
+} | {
+    type: BrowserActionType.TemplateSelect;
+    template: MetadataTemplate;
+};
+export declare const initialState: BrowserState;
+/** Pure reducer for `BrowserState`. */
+export declare function browserReducer(state: BrowserState, action: BrowserAction): BrowserState;

package/dist/types/lib/contexts/use-template-browser-actions.d.ts

@@ -0,0 +1,9 @@
+import { MutableRefObject } from 'react';
+import { BrowserActionsContextValue, EventService, ItemsService, LevelCache } from '../types';
+import { BrowserAction, BrowserState } from './reducer';
+/**
+ * Returns a stable memoized object of all browser action creators.
+ * Services and state are accessed via refs to avoid recreating actions on
+ * every render. Consumed exclusively by `BrowserActionsContextProvider`.
+ */
+export declare function useTemplateBrowserActions(itemsServiceRef: MutableRefObject<ItemsService>, eventServiceRef: MutableRefObject<EventService>, stateRef: MutableRefObject<BrowserState>, dispatch: React.Dispatch<BrowserAction>, levelCache: MutableRefObject<Map<string, LevelCache>>): BrowserActionsContextValue;

package/dist/types/lib/hooks/use-is-initial-browse-loading.d.ts

@@ -0,0 +1,7 @@
+/**
+ * True while the template browser cannot show meaningful browse rows yet: the
+ * consumer is still loading external data, or the root-level browse fetch is in
+ * flight before any namespace or template rows exist. Used to keep search chrome
+ * visible (disabled) and show loading only in the list region.
+ */
+export declare function useIsInitialBrowseLoading(): boolean;

package/dist/types/lib/metadata-template-browser.d.ts

@@ -0,0 +1,23 @@
+import { EventService, ItemsService } from './types';
+export interface MetadataTemplateBrowserProps {
+    /** Enterprise ID used as the root namespace FQN (e.g. "enterprise_123"). */
+    enterpriseId: string;
+    /** Data-fetching service implementation for namespaces, templates, and search. */
+    itemsService: ItemsService;
+    /** Observer callbacks invoked on state transitions (namespace change, search, template selection, template edit). */
+    eventService: EventService;
+    /**
+     * When true, suppresses the initial data fetch and shows loading in the list
+     * region only (search stays visible and disabled; breadcrumbs hidden until load completes).
+     */
+    isLoading?: boolean;
+    /** When true, disables the search input and all row interactions. */
+    isDisabled?: boolean;
+    /** Template ID to auto-select after the initial load completes. */
+    initialSelectedTemplateId?: string;
+}
+/**
+ * Public entry point for the metadata template browser.
+ * Wraps the provider and controller into a single composable component.
+ */
+export declare function MetadataTemplateBrowser({ enterpriseId, itemsService, eventService, isLoading, isDisabled, initialSelectedTemplateId, }: Readonly<MetadataTemplateBrowserProps>): import("react/jsx-runtime").JSX.Element;

package/dist/types/lib/stories/shared/constants.d.ts

@@ -0,0 +1,16 @@
+import { BreadcrumbEntry, MetadataNamespace } from '../../types';
+export declare const ROOT_NAMESPACE = "enterprise_123";
+export declare const DEFAULT_SCOPE = "enterprise_123";
+export declare const LEGAL_FQN = "enterprise_123.legal";
+export declare const CONTRACTS_FQN = "enterprise_123.legal.contracts";
+export declare const NAMESPACE_DOMAINS: string[];
+export declare const TEMPLATE_AREAS: string[];
+export interface DefaultTemplateSpec {
+    count: number;
+    canEdit?: boolean | ((index: number) => boolean);
+}
+export declare const toTitleCase: (value: string) => string;
+export declare const getNamespaceDisplayName: (namespaceFqn: string) => string;
+export declare const DEFAULT_NAMESPACES_BY_FQN: Record<string, MetadataNamespace[]>;
+export declare const DEFAULT_TEMPLATE_SPECS_BY_FQN: Record<string, DefaultTemplateSpec>;
+export declare const createAncestors: (namespace: string) => BreadcrumbEntry[];

package/dist/types/lib/stories/shared/create-mock-event-service.d.ts

@@ -0,0 +1,2 @@
+import { EventService } from '../../types';
+export declare const createMockEventService: (overrides?: Partial<EventService>) => EventService;

package/dist/types/lib/stories/shared/create-mock-items-service.d.ts

@@ -0,0 +1,53 @@
+import { ItemsService, MetadataNamespace, MetadataTemplate } from '../../types';
+type ItemsServiceMethod = 'getNamespaces' | 'getTemplates' | 'getSearchResults';
+/**
+ * Returns an error for a given call or null/undefined to let it succeed.
+ * Receives a 0-based call index that increments on every call to the method.
+ */
+type ErrorResolver = (callIndex: number) => Error | string | null | undefined;
+/** Static error (always throws) or a per-call resolver function. */
+type ErrorConfig = Error | string | ErrorResolver;
+/**
+ * Returns the latency in milliseconds for a given call.
+ * Receives a 0-based call index that increments on every call to the method.
+ * Return 0 to skip the delay for that call.
+ */
+type LatencyResolver = (callIndex: number) => number;
+export interface CreateMockItemsServiceOptions {
+    /** Global latency applied to all methods. Defaults to 0. */
+    latency?: number;
+    /**
+     * Per-method latency overrides. Takes precedence over the global `latency`.
+     * Use a LatencyResolver to vary the delay per call (0-based call index).
+     *
+     * @example
+     * // First call slow (e.g. initial search), all subsequent calls instant:
+     * latencyPerCall: { getSearchResults: callIndex => callIndex === 0 ? 500 : 0 }
+     *
+     * @example
+     * // Method always slow (e.g. to hold in loading state):
+     * latencyPerCall: { getSearchResults: () => 999999 }
+     */
+    latencyPerCall?: Partial<Record<ItemsServiceMethod, LatencyResolver>>;
+    namespacesByFqn?: Record<string, MetadataNamespace[]>;
+    templatesByFqn?: Record<string, MetadataTemplate[]>;
+    searchResultsByQuery?: Record<string, MetadataTemplate[]>;
+    /**
+     * Configures errors for each method. Pass a string or Error to always throw,
+     * or an ErrorResolver function to control behavior per call (0-based call index).
+     *
+     * @example
+     * // Always fail:
+     * errors: { getNamespaces: 'Network error' }
+     *
+     * @example
+     * // Fail only the first call (e.g. to test retry recovery):
+     * errors: { getNamespaces: callIndex => callIndex === 0 ? 'Network error' : null }
+     */
+    errors?: Partial<Record<ItemsServiceMethod, ErrorConfig>>;
+    /** Throws only on paginated calls (when a marker is present) to the given method. */
+    loadMoreErrors?: Partial<Record<ItemsServiceMethod, Error | string>>;
+}
+export declare const DEFAULT_TEMPLATES_BY_FQN: Record<string, MetadataTemplate[]>;
+export declare const createMockItemsService: (options?: CreateMockItemsServiceOptions) => ItemsService;
+export {};

package/dist/types/lib/stories/shared/generate-namespaces.d.ts

@@ -0,0 +1,6 @@
+import { MetadataNamespace } from '../../types';
+export interface GenerateNamespacesOptions {
+    parentFqn?: string;
+    offset?: number;
+}
+export declare const generateNamespaces: (count: number, options?: GenerateNamespacesOptions) => MetadataNamespace[];

package/dist/types/lib/stories/shared/generate-templates.d.ts

@@ -0,0 +1,8 @@
+import { BreadcrumbEntry, MetadataTemplate } from '../../types';
+export interface GenerateTemplatesOptions {
+    namespace?: string;
+    canEdit?: boolean | ((index: number) => boolean);
+    ancestors?: BreadcrumbEntry[] | ((index: number) => BreadcrumbEntry[]);
+}
+export declare const createTemplate: (overrides?: Partial<MetadataTemplate>) => MetadataTemplate;
+export declare const generateTemplates: (count: number, options?: GenerateTemplatesOptions) => MetadataTemplate[];

package/dist/types/lib/stories/shared/index.d.ts

@@ -0,0 +1,8 @@
+export * from './constants';
+export * from './story-interaction-helpers';
+export * from './create-mock-event-service';
+export * from './create-mock-items-service';
+export * from './generate-namespaces';
+export * from './generate-templates';
+export * from './paginate-items';
+export * from './story-container';

package/dist/types/lib/stories/shared/paginate-items.d.ts

@@ -0,0 +1,2 @@
+import { FetchParams, FetchResponse } from '../../types';
+export declare const paginateItems: <T>(items: T[], params: FetchParams) => FetchResponse<T>;

package/dist/types/lib/stories/shared/story-container.d.ts

@@ -0,0 +1,5 @@
+interface StoryContainerProps {
+    children: React.ReactNode;
+}
+export declare function StoryContainer({ children }: StoryContainerProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/types/lib/stories/shared/story-interaction-helpers.d.ts

@@ -0,0 +1,30 @@
+import { within } from 'storybook/test';
+/**
+ * Return type of `within(canvasElement)` in story `play` functions — bound Testing Library queries.
+ */
+export type StoryPlayCanvas = ReturnType<typeof within>;
+/**
+ * Small delay between keystrokes so controlled inputs and lodash debounce behave consistently
+ * under Playwright’s headless Chromium on CI (Linux), where zero-delay typing can batch oddly.
+ */
+export declare const SEARCH_INPUT_KEY_DELAY_MS = 15;
+/**
+ * Resolves when the search field exists and is interactive. While initial browse (or consumer
+ * loading) is in flight, the input stays `disabled`; `findByRole('searchbox')` alone returns too
+ * early on slow CI. `focusAndTypeInSearchBox` calls this automatically; import it only for
+ * stories that assert loaded chrome (e.g. search enabled) without going through that helper.
+ */
+export declare function waitForSearchBoxInteractive(canvas: StoryPlayCanvas): Promise<HTMLElement>;
+/**
+ * Waits for an interactive search box, focuses the field, types with a stable per-key delay,
+ * then returns the searchbox for follow-up typing (e.g. appending to the same field).
+ */
+export declare function focusAndTypeInSearchBox(canvas: StoryPlayCanvas, text: string): Promise<HTMLElement>;
+/**
+ * Waits for the search-results grid after debounced search has run.
+ */
+export declare function findSearchResultsGrid(canvas: StoryPlayCanvas): Promise<HTMLElement>;
+/**
+ * Waits for the list loading region shown during an in-flight search.
+ */
+export declare function findLoadingTemplatesStatus(canvas: StoryPlayCanvas): Promise<HTMLElement>;

package/dist/types/lib/types.d.ts

@@ -0,0 +1,116 @@
+export declare enum TemplateRowVariant {
+    Browse = "browse",
+    Search = "search"
+}
+export interface MetadataNamespace {
+    id: string;
+    displayName: string;
+}
+export interface MetadataTemplate {
+    id: string;
+    type?: string;
+    copyInstanceOnItemCopy?: boolean;
+    displayName: string;
+    fields?: MetadataField[];
+    hidden?: boolean;
+    scope?: string;
+    templateKey?: string;
+    namespace?: string;
+    canEdit?: boolean;
+    ancestors?: BreadcrumbEntry[];
+}
+export interface MetadataField {
+    id: string;
+    type?: MetadataFieldType;
+    description?: string;
+    displayName: string;
+    hidden?: boolean;
+    key: string;
+    options?: MetadataFieldOption[] | null;
+}
+export type MetadataFieldType = 'date' | 'enum' | 'float' | 'integer' | 'multiSelect' | 'string' | 'taxonomy';
+export interface MetadataFieldOption {
+    id: string;
+    key: string;
+}
+export interface FetchParams {
+    limit: number;
+    marker?: string;
+    signal?: AbortSignal;
+}
+export interface FetchResponse<T> {
+    entries: T[];
+    next_marker?: string;
+}
+export interface ItemsService {
+    getNamespaces?: (namespaceFQN: string, params: FetchParams) => Promise<FetchResponse<MetadataNamespace>>;
+    getTemplates?: (namespaceFQN: string, params: FetchParams) => Promise<FetchResponse<MetadataTemplate>>;
+    getSearchResults?: (query: string, params: FetchParams) => Promise<FetchResponse<MetadataTemplate>>;
+}
+export interface EventService {
+    onNamespaceChange?: (namespaceFQN: string) => Promise<void>;
+    onSearchChange?: (query: string) => Promise<void>;
+    onTemplateSelect?: (template: MetadataTemplate) => Promise<void>;
+    onTemplateEdit?: (templateId: string) => void;
+}
+export interface BreadcrumbEntry {
+    fqn: string;
+    displayName: string;
+}
+export interface SearchStateContextValue {
+    searchValue: string;
+    searchQuery: string;
+    searchResults: MetadataTemplate[];
+    searchNextMarker: string | undefined;
+    isFetchingSearch: boolean;
+    searchError: string | null;
+}
+export interface NavigationStateContextValue {
+    namespaceFQN: string;
+    path: BreadcrumbEntry[];
+}
+export interface BrowseStateContextValue {
+    namespaces: MetadataNamespace[];
+    templates: MetadataTemplate[];
+    isNamespacesExhausted: boolean;
+    namespaceNextMarker: string | undefined;
+    templateNextMarker: string | undefined;
+    isFetching: boolean;
+    isFetchingMore: boolean;
+    initialLoadError: string | null;
+    browseError: string | null;
+    loadMoreError: string | null;
+}
+export interface SelectionStateContextValue {
+    selectedTemplateId: string | null;
+}
+/** Embedding-app flags: consumer loading gate and global interaction disabled (e.g. submit). */
+export interface ConsumerStateContextValue {
+    isLoading: boolean;
+    isDisabled: boolean;
+}
+export interface BrowserActionsContextValue {
+    /** Fetches the root level on mount: namespaces and templates under the enterprise FQN. */
+    initialLoad: () => Promise<void>;
+    /** Navigates into a namespace, loading its child namespaces and templates. */
+    navigateTo: (namespace: MetadataNamespace) => Promise<void>;
+    /** Navigates back to the level identified by `fqn`, restoring it from cache. */
+    navigateBack: (fqn: string) => void;
+    /** Updates the search query; an empty string exits search mode and returns to browse. */
+    setSearchValue: (value: string) => void;
+    /** Fetches the next page of results for the current browse level or search query. */
+    loadMore: () => Promise<void>;
+    /** Notifies the event service that the user has selected a template. */
+    selectTemplate: (template: MetadataTemplate) => Promise<void>;
+    /** Notifies the event service that the user wants to edit a template. */
+    editTemplate: (templateId: string) => void;
+    /** Re-runs the failing operation based on the current mode (browse or search). */
+    retry: () => Promise<void>;
+}
+export interface LevelCache {
+    namespaces: MetadataNamespace[];
+    templates: MetadataTemplate[];
+    namespaceNextMarker: string | undefined;
+    templateNextMarker: string | undefined;
+    isNamespacesExhausted: boolean;
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+    "name": "@box/metadata-template-browser",
+    "version": "1.16.3",
+    "license": "SEE LICENSE IN LICENSE",
+    "peerDependencies": {
+        "@box/blueprint-web": "^13.15.1",
+        "@box/blueprint-web-assets": "^4.111.7",
+        "lodash": "^4.17.15",
+        "react": "^18.0.0",
+        "react-aria-components": "1.7.1",
+        "react-dom": "^18.0.0",
+        "react-intl": "^6.4.2"
+    },
+    "devDependencies": {
+        "@box/blueprint-web": "^13.15.1",
+        "@box/blueprint-web-assets": "^4.111.7",
+        "@box/eslint-plugin-blueprint": "1.1.6",
+        "@box/storybook-utils": "0.17.7",
+        "react-intl": "^6.4.2"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "files": [
+        "dist"
+    ],
+    "main": "./dist/esm/index.js",
+    "module": "./dist/esm/index.js",
+    "types": "./dist/types/index.d.ts",
+    "exports": {
+        ".": {
+            "require": "./dist/esm/index.js",
+            "import": "./dist/esm/index.js",
+            "types": "./dist/types/index.d.ts"
+        },
+        "./*": {
+            "require": "./dist/esm/*",
+            "import": "./dist/esm/*",
+            "types": "./dist/types/*"
+        },
+        "./i18n/*": {
+            "require": "./dist/i18n/*",
+            "import": "./dist/i18n/*"
+        }
+    },
+    "sideEffects": [
+        "**/*.css"
+    ]
+}