@box/metadata-taxonomy-picker 2.18.0

package/dist/types/lib/stories/tests/pagination.interaction-tests.stories.d.ts

@@ -0,0 +1,90 @@
+import { StoryObj } from '@storybook/react-vite';
+import { MetadataTaxonomyPicker } from '../../../index';
+import { TaxonomyItemsService, TaxonomyPickerMode } from '../../types';
+declare const _default: {
+    parameters: {
+        docs: {
+            page: () => import("react/jsx-runtime").JSX.Element;
+        };
+        controls: {
+            exclude: RegExp;
+        };
+    };
+    title: string;
+    component: import('react').ForwardRefExoticComponent<import('../../types').MetadataTaxonomyPickerProps & import('react').RefAttributes<HTMLInputElement>>;
+    decorators: ((Story: import('storybook/internal/csf').PartialStoryFn<import('@storybook/react').ReactRenderer, {
+        mode: TaxonomyPickerMode;
+        multiSelect: boolean;
+        value: import('../../types').TaxonomyValue[];
+        onValueChange: (values: import('../../types').TaxonomyValue[]) => void;
+        itemsService: TaxonomyItemsService;
+        eventService?: import('../../types').TaxonomyPickerEventService | undefined;
+        levels?: import('../../types').TaxonomyLevel[] | undefined;
+        placeholder?: string | undefined;
+        disabled?: boolean | undefined;
+        label?: string | undefined;
+        containerClassName?: string | undefined;
+        portalElement?: (HTMLElement | (() => HTMLElement | null) | null) | undefined;
+        ref?: import('react').LegacyRef<HTMLInputElement> | undefined;
+        key?: import('react').Key | null | undefined;
+    }>) => import("react/jsx-runtime").JSX.Element)[];
+};
+export default _default;
+type Story = StoryObj<typeof MetadataTaxonomyPicker>;
+/**
+ * Acceptance: "When the user scrolls near the bottom of the list, the next
+ * page loads automatically — no Load More button needed."
+ */
+export declare const LoadsNextPageWhenScrolledNearBottom: Story;
+/**
+ * Acceptance: "New items append below existing ones — the user's scroll
+ * position and already-loaded items are preserved."
+ */
+export declare const AppendsNewItemsBelowExistingItemsWithoutDroppingPriorPage: Story;
+/**
+ * Acceptance: "Ghost rows appear at the bottom of the list while the next
+ * page is loading."
+ */
+export declare const ShowsGhostRowsWhileLoadingNextPage: Story;
+/**
+ * Acceptance: "When all items have been loaded (no more pages available),
+ * no further requests are made."
+ */
+export declare const DoesNotRequestFurtherPagesWhenAllItemsLoaded: Story;
+/**
+ * Acceptance: "When the user navigates back to a previously visited level,
+ * all pages they had loaded are restored from cache — they don't have to
+ * scroll and reload pages again."
+ */
+export declare const RestoresPaginatedSetAfterDrillDownAndBack: Story;
+/**
+ * Acceptance: pagination must also work in search mode — scrolling near the
+ * bottom of the search-results list loads the next page of matches and appends
+ * them below the existing results.
+ */
+export declare const SearchLoadsNextPageWhenScrolledNearBottom: Story;
+/**
+ * Acceptance: the same ghost-row feedback used in browse mode must appear in
+ * search mode while a "load more" page of results is being fetched.
+ */
+export declare const SearchShowsGhostRowsWhileLoadingNextPage: Story;
+/**
+ * When the entire search result set fits in a single page, the response carries
+ * no `next_marker` and the scroll-near-bottom handler must stop firing further
+ * search requests no matter how many times the user scrolls.
+ */
+export declare const SearchDoesNotRequestFurtherPagesWhenAllResultsLoaded: Story;
+/**
+ * If a search "load more" request rejects, the in-flight indicator must clear,
+ * the already-loaded results must stay visible, and an inline "Loading failed"
+ * row with a Reload button must appear at the bottom of the list. Clicking
+ * Reload must re-attempt from the same marker and succeed.
+ */
+export declare const SearchRecoversAfterLoadMoreFailure: Story;
+/**
+ * Same recovery contract as the search case: when a browse "load more" page
+ * fails, the existing items remain visible, an inline "Loading failed" row
+ * appears at the bottom of the list, and clicking Reload re-attempts the load
+ * from the current marker.
+ */
+export declare const BrowseRecoversAfterLoadMoreFailure: Story;

package/dist/types/lib/stories/tests/portal-and-ref.interaction-tests.stories.d.ts

@@ -0,0 +1,39 @@
+import { StoryObj } from '@storybook/react-vite';
+import { MetadataTaxonomyPicker } from '../../../index';
+import { MetadataTaxonomyPickerProps } from '../../types';
+declare const _default: {
+    parameters: {
+        docs: {
+            page: () => import("react/jsx-runtime").JSX.Element;
+        };
+        controls: {
+            exclude: RegExp;
+        };
+    };
+    title: string;
+    component: import('react').ForwardRefExoticComponent<MetadataTaxonomyPickerProps & import('react').RefAttributes<HTMLInputElement>>;
+};
+export default _default;
+type Story = StoryObj<typeof MetadataTaxonomyPicker>;
+/**
+ * When `portalElement` is supplied, the popover content renders inside that
+ * element instead of `document.body`.
+ */
+export declare const PortalElementRendersPopoverInsideContainer: Story;
+/**
+ * When `portalElement` is provided as a getter function, the picker resolves
+ * the element on render and portals the popover into it.
+ */
+export declare const PortalElementAcceptsGetterFunction: Story;
+/**
+ * When `portalElement` is omitted, the popover continues to portal into
+ * `document.body` (Radix's default behaviour) so existing call sites remain
+ * unaffected.
+ */
+export declare const NoPortalElementKeepsDefaultBodyPortal: Story;
+/**
+ * The forwarded ref attaches to the picker's trigger input, so consumers can
+ * focus the picker imperatively (e.g. on form validation errors or when
+ * orchestrating focus across multiple fields).
+ */
+export declare const ForwardedRefFocusesTriggerInput: Story;

package/dist/types/lib/stories/tests/search-interaction-tests.stories.d.ts

@@ -0,0 +1,124 @@
+import { StoryObj } from '@storybook/react-vite';
+import { MetadataTaxonomyPickerProps, TaxonomyPickerMode, TaxonomyValue } from '../../types';
+interface ControlledPickerProps extends Omit<MetadataTaxonomyPickerProps, 'value' | 'onValueChange'> {
+    initialValue?: TaxonomyValue[];
+}
+declare function ControlledPicker({ initialValue, ...props }: ControlledPickerProps): import("react/jsx-runtime").JSX.Element;
+declare const _default: {
+    beforeEach(): Promise<void>;
+    parameters: {
+        docs: {
+            page: () => import("react/jsx-runtime").JSX.Element;
+        };
+        controls: {
+            exclude: RegExp;
+        };
+    };
+    title: string;
+    component: import('react').ForwardRefExoticComponent<MetadataTaxonomyPickerProps & import('react').RefAttributes<HTMLInputElement>>;
+    render: (args: MetadataTaxonomyPickerProps & import('react').RefAttributes<HTMLInputElement>) => import("react/jsx-runtime").JSX.Element;
+    args: {
+        itemsService: import('../../types').TaxonomyItemsService;
+        mode: TaxonomyPickerMode.MultiLevel;
+        multiSelect: false;
+        placeholder: string;
+    };
+    decorators: ((Story: import('storybook/internal/csf').PartialStoryFn<import('@storybook/react').ReactRenderer, {
+        mode: TaxonomyPickerMode;
+        multiSelect: boolean;
+        value: TaxonomyValue[];
+        onValueChange: (values: TaxonomyValue[]) => void;
+        itemsService: import('../../types').TaxonomyItemsService;
+        eventService?: import('../../types').TaxonomyPickerEventService | undefined;
+        levels?: import('../../types').TaxonomyLevel[] | undefined;
+        placeholder?: string | undefined;
+        disabled?: boolean | undefined;
+        label?: string | undefined;
+        containerClassName?: string | undefined;
+        portalElement?: (HTMLElement | (() => HTMLElement | null) | null) | undefined;
+        ref?: import('react').LegacyRef<HTMLInputElement> | undefined;
+        key?: import('react').Key | null | undefined;
+    }>) => import("react/jsx-runtime").JSX.Element)[];
+};
+export default _default;
+type Story = StoryObj<typeof ControlledPicker>;
+/**
+ * Typing into the trigger updates the displayed text immediately — the value
+ * is not debounced, only the service call is.
+ */
+export declare const TypingUpdatesInputImmediately: Story;
+/**
+ * After 500 ms of inactivity the service receives a search request and the
+ * results replace the browse list.
+ */
+export declare const SearchRequestFiresAfterDebounce: Story;
+/**
+ * While the search request is in flight a loading skeleton is shown so the
+ * user has immediate feedback that something is happening.
+ */
+export declare const SearchShowsLoadingIndicator: Story;
+/**
+ * Search results replace the browse list and show the item's display name.
+ */
+export declare const SearchResultsReplaceBrowseItems: Story;
+/**
+ * Each search result row renders its ancestor chain as a subtitle line
+ * (e.g. "Region" or "Region > Country") so users understand where the
+ * item sits in the taxonomy tree.
+ */
+export declare const SearchResultsShowAncestorBreadcrumb: Story;
+/**
+ * "No results found" is displayed when the search query returns an empty list,
+ * giving users clear feedback instead of an unexplained blank list.
+ */
+export declare const SearchEmptyStateShowsNoResultsFound: Story;
+/**
+ * Clearing the input dismisses search results and brings browse items back,
+ * so the user can continue navigating where they left off.
+ */
+export declare const ClearingSearchRestoresBrowseItems: Story;
+/**
+ * Clearing the input before the debounce fires discards the pending request,
+ * so no search results ever appear — late-arriving responses are silently
+ * dropped and the browse list is shown straight away.
+ */
+export declare const ClearingBeforeDebounceFiresNeverShowsSearchResults: Story;
+/**
+ * Single-selecting a search result emits the value with ancestor information
+ * included — callers receive a complete `TaxonomyValue` regardless of whether
+ * the item was found via browse or search.
+ */
+export declare const SingleSelectSearchResultEmitsValueWithAncestors: Story;
+/**
+ * In multi-select mode, selecting a search result adds it to the value and
+ * keeps the popover open with search results still visible — the user stays
+ * in search mode to allow further selections.
+ */
+export declare const MultiSelectSearchResultTogglesWithoutExitingSearch: Story;
+/**
+ * Selecting a search result in multi-select mode emits the full `TaxonomyValue`
+ * shape including ancestor information.
+ */
+export declare const MultiSelectSearchResultEmitsValueWithAncestors: Story;
+/**
+ * A search result whose `hasChildren` flag is `true` shows a drill-down
+ * chevron, giving users a way to navigate into its children.
+ */
+export declare const SearchResultWithChildrenShowsDrillDownChevron: Story;
+/**
+ * While the user is composing with an IME the controller receives no input —
+ * the debounce never fires and browse items remain visible throughout.
+ */
+export declare const SearchStaysFrozenDuringIMEComposition: Story;
+/**
+ * When IME composition ends the committed text is forwarded to the controller
+ * in one shot, triggering a single debounced search that replaces browse items
+ * with results.
+ */
+export declare const SearchFiresWithCommittedTextOnCompositionEnd: Story;
+/**
+ * Clicking the drill-down chevron on a search result exits search mode and
+ * navigates into that item's children in the browse tree — the full end-to-end
+ * flow through the real picker shell.
+ */
+export declare const ClickingDrillDownChevronExitsSearchAndShowsChildren: Story;

package/dist/types/lib/stories/tests/shell-selection.interaction-tests.stories.d.ts

@@ -0,0 +1,56 @@
+import { StoryObj } from '@storybook/react-vite';
+import { TaxonomyPickerMode, MetadataTaxonomyPickerProps, TaxonomyValue } from '../../types';
+interface ControlledPickerProps extends Omit<MetadataTaxonomyPickerProps, 'value' | 'onValueChange'> {
+    initialValue?: TaxonomyValue[];
+}
+declare function ControlledPicker({ initialValue, ...props }: ControlledPickerProps): import("react/jsx-runtime").JSX.Element;
+declare const _default: {
+    beforeEach(): Promise<void>;
+    parameters: {
+        docs: {
+            page: () => import("react/jsx-runtime").JSX.Element;
+        };
+        controls: {
+            exclude: RegExp;
+        };
+    };
+    title: string;
+    component: import('react').ForwardRefExoticComponent<MetadataTaxonomyPickerProps & import('react').RefAttributes<HTMLInputElement>>;
+    render: (args: MetadataTaxonomyPickerProps & import('react').RefAttributes<HTMLInputElement>) => import("react/jsx-runtime").JSX.Element;
+    args: {
+        itemsService: import('../../types').TaxonomyItemsService;
+        mode: TaxonomyPickerMode.MultiLevel;
+        multiSelect: false;
+        placeholder: string;
+    };
+    decorators: ((Story: import('storybook/internal/csf').PartialStoryFn<import('@storybook/react').ReactRenderer, {
+        mode: TaxonomyPickerMode;
+        multiSelect: boolean;
+        value: TaxonomyValue[];
+        onValueChange: (values: TaxonomyValue[]) => void;
+        itemsService: import('../../types').TaxonomyItemsService;
+        eventService?: import('../../types').TaxonomyPickerEventService | undefined;
+        levels?: import('../../types').TaxonomyLevel[] | undefined;
+        placeholder?: string | undefined;
+        disabled?: boolean | undefined;
+        label?: string | undefined;
+        containerClassName?: string | undefined;
+        portalElement?: (HTMLElement | (() => HTMLElement | null) | null) | undefined;
+        ref?: import('react').LegacyRef<HTMLInputElement> | undefined;
+        key?: import('react').Key | null | undefined;
+    }>) => import("react/jsx-runtime").JSX.Element)[];
+};
+export default _default;
+type Story = StoryObj<typeof ControlledPicker>;
+export declare const SingleSelectClickEmitsValueWithFullNodeShape: Story;
+export declare const SingleSelectRadioClickEmitsValue: Story;
+export declare const SingleSelectReplacesPreviousValue: Story;
+export declare const MultiSelectAppendsValuesAcrossClicks: Story;
+export declare const MultiSelectTogglesOffWhenAlreadySelected: Story;
+export declare const SingleSelectShowsChipForSelectedValue: Story;
+export declare const SingleSelectShowsClearButtonForSelectedValue: Story;
+export declare const SingleSelectClearButtonClearsValue: Story;
+export declare const SingleSelectClearButtonDoesNothingWhenDisabled: Story;
+export declare const SingleSelectChipHasNoDeleteButton: Story;
+export declare const MultiSelectDoesNotShowSingleClearButton: Story;
+export declare const TypingInTriggerUpdatesControlledValue: Story;

package/dist/types/lib/stories/tests/single-level-mode.interaction-tests.stories.d.ts

@@ -0,0 +1,50 @@
+import { StoryObj } from '@storybook/react-vite';
+import { MetadataTaxonomyPickerProps, TaxonomyLevel, TaxonomyPickerMode, TaxonomyValue } from '../../types';
+interface ControlledPickerProps extends Omit<MetadataTaxonomyPickerProps, 'value' | 'onValueChange'> {
+    initialValue?: TaxonomyValue[];
+}
+declare function ControlledPicker({ initialValue, ...props }: ControlledPickerProps): import("react/jsx-runtime").JSX.Element;
+declare const _default: {
+    beforeEach(): Promise<void>;
+    parameters: {
+        docs: {
+            page: () => import("react/jsx-runtime").JSX.Element;
+        };
+        controls: {
+            exclude: RegExp;
+        };
+    };
+    title: string;
+    component: import('react').ForwardRefExoticComponent<MetadataTaxonomyPickerProps & import('react').RefAttributes<HTMLInputElement>>;
+    render: (args: MetadataTaxonomyPickerProps & import('react').RefAttributes<HTMLInputElement>) => import("react/jsx-runtime").JSX.Element;
+    args: {
+        mode: TaxonomyPickerMode.SingleLevel;
+        multiSelect: false;
+        itemsService: import('../../types').TaxonomyItemsService;
+        levels: TaxonomyLevel[];
+    };
+};
+export default _default;
+type Story = StoryObj<typeof ControlledPicker>;
+/** No drill-down chevrons render in a flat single-level taxonomy. */
+export declare const FlatTaxonomyShowsNoChevrons: Story;
+/** Single-level × single-select with a flat list: clicking a row selects it and closes the popover. */
+export declare const FlatSingleSelectClosesOnPick: Story;
+/** Single-level × multi-select with a flat list: clicking checkboxes toggles values; popover stays open. */
+export declare const FlatMultiSelectTogglesAndKeepsPopoverOpen: Story;
+/** Clicking a non-selectable row drills down and emits no selection. */
+export declare const NonSelectableRowClickDrillsDownInSingleLevelMode: Story;
+/** Latest selectable level renders selection controls but no chevron. */
+export declare const LatestSelectableLevelHasNoChevron: Story;
+/** Drill through non-selectable parents, then select a leaf at the latest selectable level. */
+export declare const DrillsThroughNonSelectableParentsAndSelectsLeaf: Story;
+/** Search returns matches only at the latest selectable level. */
+export declare const SearchReturnsOnlyLatestSelectableLevelResults: Story;
+/** Search stays global (parentId=null) after drill-down — sibling subtrees still match. */
+export declare const SearchStaysGlobalEvenAfterDrillDown: Story;
+/** The level-filter dropdown never renders in single-level mode. */
+export declare const LevelFilterHiddenInSingleLevelMode: Story;
+/** Chevrons stay on intermediate selectable levels and only drop at the deepest one. */
+export declare const ChevronsRemainOnIntermediateSelectableLevels: Story;
+/** Regression guard: multi-level mode still shows the level filter during search. */
+export declare const MultiLevelModeStillShowsLevelFilter: Story;

package/dist/types/lib/stories/tests/taxonomy-menu-item.interaction-tests.stories.d.ts

@@ -0,0 +1,70 @@
+import { StoryObj } from '@storybook/react-vite';
+import { TaxonomyMenuItem, TaxonomyMenuItemProps } from '../../components/taxonomy-menu-item';
+declare const _default: {
+    parameters: {
+        docs: {
+            page: () => import("react/jsx-runtime").JSX.Element;
+        };
+        controls: {
+            exclude: RegExp;
+        };
+    };
+    title: string;
+    component: import('react').NamedExoticComponent<TaxonomyMenuItemProps>;
+    render: (props: TaxonomyMenuItemProps) => import("react/jsx-runtime").JSX.Element;
+    args: {
+        id: string;
+        displayName: string;
+        selectable: true;
+        multiSelect: false;
+        isSelected: false;
+        showDrillDown: false;
+        onSelect: import('storybook/test').Mock<(...args: any[]) => any>;
+        onDrillDown: import('storybook/test').Mock<(...args: any[]) => any>;
+    };
+    decorators: ((Story: import('storybook/internal/csf').PartialStoryFn<import('@storybook/react').ReactRenderer, {
+        id: string;
+        displayName: string;
+        isSearchMode?: boolean | undefined;
+        selectable: boolean;
+        multiSelect: boolean;
+        isSelected: boolean;
+        showDrillDown: boolean;
+        ancestors?: import('../../types').TaxonomyAncestor[] | undefined;
+        onSelect: (id: string, closeAfterSelect?: boolean) => void;
+        onDrillDown?: ((id: string) => void) | undefined;
+        onFocusExit?: (() => void) | undefined;
+    }>) => import("react/jsx-runtime").JSX.Element)[];
+};
+export default _default;
+type Story = StoryObj<typeof TaxonomyMenuItem>;
+export declare const ClickRowCallsOnSelect: Story;
+export declare const ClickRowDoesNotCallOnSelectWhenNonSelectable: Story;
+/** Clicking a non-selectable row with drill-down triggers navigation, not selection. */
+export declare const ClickNonSelectableRowWithDrillDownCallsOnDrillDown: Story;
+/** A non-selectable, non-drillable row is inert — clicking it does nothing. */
+export declare const ClickNonSelectableLeafRowIsInert: Story;
+/** Keyboard activation (Enter/Space) on a non-selectable row also drills down. */
+export declare const KeyboardActivationOnNonSelectableRowDrillsDown: Story;
+export declare const ClickDrillDownCallsOnDrillDown: Story;
+export declare const CheckboxClickCallsOnSelectOnce: Story;
+export declare const ArrowRightFromRowFocusesDrillDownButton: Story;
+export declare const ArrowRightNoOpWithoutDrillDown: Story;
+export declare const ArrowLeftFromRowFocusesSelectionControl: Story;
+export declare const ArrowRightFromRowFocusesDrillDownWhenNonSelectable: Story;
+export declare const EnterOnDrillDownButtonCallsOnDrillDown: Story;
+export declare const SpaceOnDrillDownButtonCallsOnDrillDown: Story;
+export declare const ArrowLeftFromDrillDownFocusesSelectionControl: Story;
+export declare const ArrowRightFromSelectionControlFocusesDrillDown: Story;
+export declare const ArrowLeftFromSelectionControlFocusesRow: Story;
+export declare const SubControlsAreNotInTabOrder: Story;
+export declare const TabOnSelectionControlNavigatesToNextRow: Story;
+export declare const TabOnDrillDownNavigatesToNextRow: Story;
+export declare const TabOnRowMovesToNextRow: Story;
+export declare const ShiftTabOnRowMovesToPrevRow: Story;
+export declare const ArrowDownFromSelectionControlFocusesNextRow: Story;
+export declare const ArrowDownFromDrillDownFocusesNextRow: Story;
+export declare const ArrowUpFromSelectionControlFocusesPrevRow: Story;
+export declare const ShiftTabOnFirstRowFocusesInput: Story;
+export declare const ShiftTabOnFirstRowSelectionControlFocusesInput: Story;
+export declare const ShiftTabOnFirstRowDrillDownFocusesInput: Story;

package/dist/types/lib/stories/tests/visual-regression-tests.stories.d.ts

@@ -0,0 +1,38 @@
+import { StoryObj } from '@storybook/react-vite';
+import { MetadataTaxonomyPicker } from '../../../index';
+import { MetadataTaxonomyPickerProps, TaxonomyPickerMode, TaxonomyValue } from '../../types';
+declare const _default: {
+    parameters: {
+        chromatic: {
+            disableSnapshot: boolean;
+        };
+        docs: {
+            page: () => import("react/jsx-runtime").JSX.Element;
+        };
+        controls: {
+            exclude: RegExp;
+        };
+    };
+    title: string;
+    component: import('react').ForwardRefExoticComponent<MetadataTaxonomyPickerProps & import('react').RefAttributes<HTMLInputElement>>;
+    decorators: ((Story: import('storybook/internal/csf').PartialStoryFn<import('@storybook/react').ReactRenderer, {
+        mode: TaxonomyPickerMode;
+        multiSelect: boolean;
+        value: TaxonomyValue[];
+        onValueChange: (values: TaxonomyValue[]) => void;
+        itemsService: import('../../types').TaxonomyItemsService;
+        eventService?: import('../../types').TaxonomyPickerEventService | undefined;
+        levels?: import('../../types').TaxonomyLevel[] | undefined;
+        placeholder?: string | undefined;
+        disabled?: boolean | undefined;
+        label?: string | undefined;
+        containerClassName?: string | undefined;
+        portalElement?: (HTMLElement | (() => HTMLElement | null) | null) | undefined;
+        ref?: import('react').LegacyRef<HTMLInputElement> | undefined;
+        key?: import('react').Key | null | undefined;
+    }>) => import("react/jsx-runtime").JSX.Element)[];
+};
+export default _default;
+type Story = StoryObj<typeof MetadataTaxonomyPicker>;
+export declare const DefaultClosed: Story;
+export declare const DisabledState: Story;

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

@@ -0,0 +1,105 @@
+export interface TaxonomyNode {
+    id: string;
+    displayName: string;
+    selectable: boolean;
+    hasChildren: boolean;
+    level: number;
+    ancestors?: TaxonomyAncestor[];
+}
+export interface TaxonomySearchResult {
+    id: string;
+    displayName: string;
+    selectable: boolean;
+    hasChildren: boolean;
+    level: number;
+    ancestors: TaxonomyAncestor[];
+}
+/** When `ancestors` is set, the level stack is rebuilt from it; otherwise the target is appended. */
+export interface DrillDownTarget {
+    id: string;
+    displayName: string;
+    ancestors?: TaxonomyAncestor[];
+}
+export interface TaxonomyAncestor {
+    id: string;
+    displayName: string;
+    level: number;
+}
+export interface TaxonomyValue {
+    id: string;
+    displayName: string;
+    level: number;
+    ancestors?: TaxonomyAncestor[];
+}
+export interface TaxonomyLevel {
+    level: number;
+    displayName: string;
+    selectable?: boolean;
+}
+export interface BreadcrumbEntry {
+    id: string;
+    displayName: string;
+}
+export interface FetchParams {
+    limit: number;
+    marker?: string;
+    signal?: AbortSignal;
+}
+export interface FetchResponse<T> {
+    entries: T[];
+    next_marker?: string;
+}
+export interface SearchParams extends FetchParams {
+    parentId?: string | null;
+    levelFilter?: number;
+}
+export interface TaxonomyItemsService {
+    getNodes(parentId: string | null, params: FetchParams): Promise<FetchResponse<TaxonomyNode>>;
+    searchNodes(query: string, params: SearchParams): Promise<FetchResponse<TaxonomySearchResult>>;
+}
+export interface TaxonomyPickerEventService {
+    onNavigate?: (parentId: string | null, path: BreadcrumbEntry[]) => void;
+    onSearch?: (query: string) => void;
+    onOpenChange?: (isOpen: boolean) => void;
+}
+export declare enum TaxonomyPickerMode {
+    SingleLevel = "single-level",
+    MultiLevel = "multi-level"
+}
+export interface MetadataTaxonomyPickerProps {
+    mode: TaxonomyPickerMode;
+    multiSelect: boolean;
+    value: TaxonomyValue[];
+    onValueChange: (values: TaxonomyValue[]) => void;
+    itemsService: TaxonomyItemsService;
+    eventService?: TaxonomyPickerEventService;
+    /**
+     * Taxonomy levels for the level-filter dropdown and search auto-scope.
+     * Pass `[]` (or omit) to hide the filter and skip auto-scoping.
+     */
+    levels?: TaxonomyLevel[];
+    placeholder?: string;
+    disabled?: boolean;
+    /**
+     * Visible field label rendered above the trigger and associated with the
+     * combobox input via `htmlFor` for accessibility. When omitted, no label
+     * element is rendered — the caller is then responsible for providing an
+     * accessible name via `aria-label` / `aria-labelledby` on the picker.
+     */
+    label?: string;
+    /**
+     * CSS class applied to the outermost container element.
+     * Intended for layout adjustments (margin, width, grid placement) only —
+     * do NOT use to override internal Blueprint component styles.
+     */
+    containerClassName?: string;
+    /**
+     * DOM element (or a getter returning one) that the popover should be
+     * portalled into. Use this when the field lives inside a Drawer, Modal,
+     * or Accordion so the popover positions and scrolls correctly relative
+     * to that container.
+     *
+     * When omitted, the popover portals into `document.body` (Radix default).
+     */
+    portalElement?: HTMLElement | (() => HTMLElement | null) | null;
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+    "name": "@box/metadata-taxonomy-picker",
+    "version": "2.18.0",
+    "license": "SEE LICENSE IN LICENSE",
+    "peerDependencies": {
+        "@ariakit/react": "^0.4.21",
+        "@box/blueprint-web": "^15.5.1",
+        "@box/blueprint-web-assets": "^4.122.0",
+        "@tanstack/react-virtual": "^3.10.8",
+        "react": "^18.0.0",
+        "react-dom": "^18.0.0",
+        "react-intl": "^6.4.2"
+    },
+    "devDependencies": {
+        "@ariakit/react": "^0.4.21",
+        "@box/blueprint-web": "^15.5.1",
+        "@box/blueprint-web-assets": "^4.122.0",
+        "@box/eslint-plugin-blueprint": "1.2.5",
+        "@box/storybook-utils": "0.20.9",
+        "@tanstack/react-virtual": "^3.10.8",
+        "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"
+    ]
+}