@box/metadata-taxonomy-picker 2.18.0

package/dist/types/lib/components/taxonomy-items-list/taxonomy-items-list.d.ts

@@ -0,0 +1,82 @@
+import { TaxonomyMenuItemProps } from '../taxonomy-menu-item';
+export interface TaxonomyItemsListProps {
+    items: TaxonomyMenuItemProps[];
+    multiSelect: boolean;
+    selectedValue: string;
+    estimatedRowHeight?: number;
+    /**
+     * When `true`, each row is measured at runtime via `ResizeObserver` +
+     * `getBoundingClientRect()` so the virtualizer can position rows of
+     * varying height (e.g. search/ancestor rows whose breadcrumb may wrap).
+     *
+     * Browse rows are CSS-locked to a fixed height, so leaving this `false`
+     * (the default) avoids per-row layout reads during scroll.
+     */
+    hasVariableRowHeight?: boolean;
+    /** When `true`, the empty state renders "No results found" instead of "No subnodes". */
+    isSearchMode?: boolean;
+    isFetching: boolean;
+    /**
+     * Initial-load error for the list. When set, the entire list area is replaced
+     * by a full-area `ErrorState` with a retry button. Mutually exclusive with
+     * `items` — the controller clears items when this is set.
+     */
+    error: string | null;
+    /**
+     * Inline "load more" error for the active list. When set, an inline error row
+     * is rendered at the bottom of the existing items (already-loaded items remain
+     * visible) and the scroll-near-bottom auto-trigger is suppressed until the
+     * user retries.
+     */
+    loadMoreError?: string | null;
+    /**
+     * Called when the user activates the retry control on either error surface
+     * (full-area initial load error or the inline load-more error row). The
+     * controller decides which operation to re-run via `lastFailedOp`.
+     */
+    onRetry: () => void;
+    /**
+     * Applied as the `id` of the scroll container (`role="listbox"`), satisfying
+     * the `aria-controls` reference set on the combobox input in the shell.
+     * Must match the `listboxId` threaded down from `MetadataTaxonomyPickerShell`.
+     */
+    listboxId?: string;
+    /** Called when the user Shift+Tabs from the first row to return focus to the main input. */
+    onFocusExit?: () => void;
+    /**
+     * `true` when another page of items is available to be loaded.
+     * Required (alongside no in-flight fetch) for the scroll-near-bottom
+     * handler to fire `onLoadMore`.
+     */
+    hasMore?: boolean;
+    /** `true` while a "load more" page request is in flight (drives the inline ghost rows). */
+    isFetchingMore?: boolean;
+    /** Called when the user has scrolled within `LOAD_MORE_ROOT_MARGIN_PX` of the bottom of the list. */
+    onLoadMore?: () => void;
+}
+/** Imperative handle exposed via `ref` for scroll position save/restore. */
+export interface TaxonomyItemsListRef {
+    getScrollTop: () => number;
+    scrollTo: (top: number) => void;
+}
+/**
+ * Virtualized list of taxonomy rows.
+ *
+ * Renders only the visible window of `TaxonomyMenuItem`s plus an overscan
+ * buffer, so very large datasets stay smooth. The list owns the scroll
+ * container and renders one of three non-list states (loading, error, empty)
+ * when applicable; otherwise it renders the virtualized rows.
+ *
+ * The scroll container carries `role="listbox"` (+ `id={listboxId}`) to
+ * satisfy the ARIA combobox contract — the shell's `aria-controls` points
+ * here. In single-select mode the `Radio.Group` lives inside the listbox
+ * (not around it) so the hierarchy is `listbox > radiogroup > options`.
+ *
+ * Browse rows are CSS-locked to a fixed height; search/ancestor rows can
+ * vary, in which case `hasVariableRowHeight` opts into per-row measurement.
+ *
+ * The component exposes a `TaxonomyItemsListRef` imperative handle for
+ * saving and restoring the scroll position when toggling between browse
+ * and search modes.
+ */
+export declare const TaxonomyItemsList: import('react').ForwardRefExoticComponent<TaxonomyItemsListProps & import('react').RefAttributes<TaxonomyItemsListRef>>;

package/dist/types/lib/components/taxonomy-level-filter/index.d.ts

@@ -0,0 +1 @@
+export { TaxonomyLevelFilter, type TaxonomyLevelFilterProps } from './taxonomy-level-filter';

package/dist/types/lib/components/taxonomy-level-filter/messages.d.ts

@@ -0,0 +1,7 @@
+export declare const messages: {
+    allOption: {
+        defaultMessage: string;
+        description: string;
+        id: string;
+    };
+};

package/dist/types/lib/components/taxonomy-level-filter/taxonomy-level-filter.d.ts

@@ -0,0 +1,11 @@
+import { TaxonomyLevel } from '../../types';
+export interface TaxonomyLevelFilterProps {
+    availableLevels: readonly TaxonomyLevel[];
+    levelFilter: number | null;
+    onLevelFilterChange: (level: number | null) => void;
+}
+/**
+ * Dropdown above the search results that scopes search to a single taxonomy
+ * level. "All levels" clears the filter.
+ */
+export declare function TaxonomyLevelFilter({ availableLevels, levelFilter, onLevelFilterChange }: TaxonomyLevelFilterProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/lib/components/taxonomy-menu-item/index.d.ts

@@ -0,0 +1 @@
+export { TaxonomyMenuItem, type TaxonomyMenuItemProps } from './taxonomy-menu-item';

package/dist/types/lib/components/taxonomy-menu-item/messages.d.ts

@@ -0,0 +1,7 @@
+export declare const messages: {
+    drillDownAriaLabel: {
+        defaultMessage: string;
+        description: string;
+        id: string;
+    };
+};

package/dist/types/lib/components/taxonomy-menu-item/taxonomy-menu-item.d.ts

@@ -0,0 +1,20 @@
+import { TaxonomyAncestor } from '../../types';
+export interface TaxonomyMenuItemProps {
+    id: string;
+    displayName: string;
+    isSearchMode?: boolean;
+    selectable: boolean;
+    multiSelect: boolean;
+    isSelected: boolean;
+    showDrillDown: boolean;
+    ancestors?: TaxonomyAncestor[];
+    onSelect: (id: string, closeAfterSelect?: boolean) => void;
+    onDrillDown?: (id: string) => void;
+    /** Called when Shift+Tab is pressed while this is the first row, to return focus to the main input. */
+    onFocusExit?: () => void;
+}
+/**
+ * Row component for browse and search lists.
+ * Keyboard model is documented in useTaxonomyMenuItemKeyboard.
+ */
+export declare const TaxonomyMenuItem: import('react').NamedExoticComponent<TaxonomyMenuItemProps>;

package/dist/types/lib/components/taxonomy-menu-item/use-taxonomy-menu-item-keyboard.d.ts

@@ -0,0 +1,47 @@
+import { KeyboardEvent } from 'react';
+export interface UseTaxonomyMenuItemKeyboardOptions {
+    id: string;
+    multiSelect: boolean;
+    onSelect: (id: string, closeAfterSelect?: boolean) => void;
+    /** Called when focus exits the top of the list (e.g. Shift+Tab on the first row). */
+    onFocusExit?: () => void;
+    rowRef: React.RefObject<HTMLButtonElement>;
+    selectionControlRef: React.RefObject<HTMLButtonElement>;
+    drillDownRef: React.RefObject<HTMLButtonElement>;
+}
+export interface UseTaxonomyMenuItemKeyboardResult {
+    /** Redirect focus to the row when the radio receives it without our code asking. */
+    handleSelectionControlFocus: () => void;
+    /** Bubble-phase handler on the CompositeItem row div. */
+    handleRowKeyDown: (event: KeyboardEvent<HTMLButtonElement>) => void;
+    /**
+     * Capture-phase handler on the CompositeItem row div. Intercepts all arrow
+     * keys originating from the selection control before Radix's RadioGroup
+     * navigation (merged via Slot/asChild into the radio button's own onKeyDown)
+     * can process them.
+     */
+    handleRowKeyDownCapture: (event: KeyboardEvent<HTMLButtonElement>) => void;
+    /** Bubble-phase handler on the checkbox / radio button. */
+    handleSelectionControlKeyDown: (event: KeyboardEvent<HTMLButtonElement>) => void;
+    /** Bubble-phase handler on the drill-down IconButton. */
+    handleDrillDownKeyDown: (event: KeyboardEvent<HTMLButtonElement>) => void;
+}
+/**
+ * Encapsulates all keyboard (and radio-focus-redirect) logic for a single
+ * TaxonomyMenuItem row.
+ *
+ * Keyboard model (requires an ancestor CompositeProvider + Composite):
+ * - Tab / Shift+Tab anywhere in the row  → next / previous row.
+ *   At a list boundary Tab exits the popup naturally.
+ * - ArrowUp / ArrowDown anywhere in the row → next / previous row.
+ * - ArrowLeft from row → selection control.
+ * - ArrowRight from row → drill-down.
+ * - ArrowLeft from selection control → row.
+ * - ArrowRight from selection control → drill-down.
+ * - ArrowLeft from drill-down → selection control (or row if none).
+ * - Enter on radio → select (Radix blocks the native Enter event on buttons).
+ * - Enter / Space on drill-down → drill-down action.
+ * - Arrow keys from the selection control are intercepted in the capture phase
+ *   so Radix's RovingFocusGroup never navigates between radios.
+ */
+export declare function useTaxonomyMenuItemKeyboard({ id, multiSelect, onSelect, onFocusExit, rowRef, selectionControlRef, drillDownRef, }: UseTaxonomyMenuItemKeyboardOptions): UseTaxonomyMenuItemKeyboardResult;

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

@@ -0,0 +1,49 @@
+/** Single-line browse rows — matches `--bp-size-090` (36px) in taxonomy-menu-item styles. */
+export declare const ESTIMATED_BROWSE_ROW_HEIGHT = 36;
+/**
+ * Two-line search/ancestor rows — display name + breadcrumb line.
+ * ~20px body-default-bold + ~16px xsmall breadcrumb + 2 × 4px vertical padding ≈ 44px.
+ */
+export declare const ESTIMATED_SEARCH_ROW_HEIGHT = 44;
+/**
+ * How many off-screen rows the virtualizer renders above and below the
+ * viewport. Higher values reduce the chance of fast scroll outrunning
+ * the renderer at the cost of slightly more DOM work; rows are memoized,
+ * so the trade-off favors a generous cushion.
+ */
+export declare const OVERSCAN_COUNT = 20;
+/** Skeleton rows shown during initial load. Sized to fill the stable 21rem popover area. */
+export declare const SKELETON_ROW_COUNT = 9;
+/** Height (px) of each skeleton row Ghost placeholder. */
+export declare const SKELETON_ROW_HEIGHT = 16;
+/** Number of ghost rows shown at the bottom of the list while a "load more" page is in flight. */
+export declare const LOAD_MORE_GHOST_ROW_COUNT = 3;
+/** Height (px) of each ghost row shown during "load more". */
+export declare const LOAD_MORE_GHOST_ROW_HEIGHT = 16;
+/** Total height (px) of the inline "load more" ghost block: padding(12×2) + 3×16 + 2×gap(20) = 112. */
+export declare const LOAD_MORE_GHOST_BLOCK_HEIGHT = 112;
+/** Distance (px) from the bottom of the list at which the next page is pre-fetched. */
+export declare const LOAD_MORE_ROOT_MARGIN_PX = 200;
+/** Minimum time the load-more loading slot stays visible before yielding to the inline error row. */
+export declare const LOAD_MORE_ERROR_MIN_VISIBLE_MS = 400;
+/** Separator string rendered between breadcrumb segments. */
+export declare const BREADCRUMB_SEPARATOR = " / ";
+/** Maximum number of lines the breadcrumb trail may occupy before collapsing to `first / icon / last`. */
+export declare const BREADCRUMB_MAX_LINES = 2;
+/**
+ * Sub-pixel tolerance for breadcrumb overflow detection.
+ * Browsers can report ~1px diffs even when content visually fits.
+ */
+export declare const BREADCRUMB_OVERFLOW_THRESHOLD_PX = 2;
+/** Unicode ellipsis character used when trimming overflowed breadcrumb segments. */
+export declare const BREADCRUMB_ELLIPSIS_CHAR = "\u2026";
+/** Default page size for taxonomy node fetch requests. */
+export declare const DEFAULT_PAGE_LIMIT = 100;
+/** Stale-after threshold for cached levels; older entries are evicted on read. */
+export declare const CACHE_TTL_MS: number;
+/** Cache key used for the root level (parentId === null). */
+export declare const ROOT_CACHE_KEY = "__root__";
+/** Sentinel `Crumb.id` for the synthetic root entry; mapped back to `null` parentId by the shell. */
+export declare const BREADCRUMB_ROOT_ID = "__breadcrumb_root__";
+/** Debounce time for search input changes. */
+export declare const SEARCH_DEBOUNCE_MS = 500;

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

@@ -0,0 +1,17 @@
+export declare const messages: {
+    initialLoadErrorFallback: {
+        defaultMessage: string;
+        description: string;
+        id: string;
+    };
+    searchErrorFallback: {
+        defaultMessage: string;
+        description: string;
+        id: string;
+    };
+    loadMoreErrorFallback: {
+        defaultMessage: string;
+        description: string;
+        id: string;
+    };
+};

package/dist/types/lib/hooks/use-taxonomy-picker-controller.d.ts

@@ -0,0 +1,22 @@
+import { PickerState } from '../state/reducer';
+import { DrillDownTarget, TaxonomyItemsService, TaxonomyLevel, TaxonomyPickerEventService } from '../types';
+/** Forces a fixed search scope, bypassing the level-filter and drill-down scoping. */
+export interface SearchScopeOverride {
+    parentId: string | null;
+    levelFilter: number | null;
+}
+export declare function useTaxonomyPickerController(itemsService: TaxonomyItemsService, levels?: readonly TaxonomyLevel[], eventService?: TaxonomyPickerEventService): {
+    state: PickerState;
+    isOpen: boolean;
+    handleOpenChange: (open: boolean) => void;
+    handleInputValueChange: (inputValue: string) => void;
+    actions: {
+        drillDown: (target: DrillDownTarget) => void;
+        navigateBack: (targetParentId: string | null) => void;
+        loadMore: () => Promise<void>;
+        searchLoadMore: () => Promise<void>;
+        setLevelFilter: (level: number | null) => void;
+        retry: () => void;
+        setSearchScopeOverride: (next: SearchScopeOverride | undefined) => void;
+    };
+};

package/dist/types/lib/metadata-taxonomy-picker.d.ts

@@ -0,0 +1,8 @@
+import { MetadataTaxonomyPickerProps } from './types';
+export type { MetadataTaxonomyPickerProps } from './types';
+/**
+ * Forwards the ref to the picker's trigger input so consumers can manage
+ * focus or other imperative interactions on the input element directly.
+ */
+export declare const MetadataTaxonomyPicker: import('react').ForwardRefExoticComponent<MetadataTaxonomyPickerProps & import('react').RefAttributes<HTMLInputElement>>;
+export default MetadataTaxonomyPicker;

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

@@ -0,0 +1,180 @@
+import { BreadcrumbEntry, TaxonomyLevel, TaxonomyNode, TaxonomySearchResult } from '../types';
+export declare enum FailedOp {
+    Browse = "browse",
+    BrowseMore = "browse-more",
+    Search = "search",
+    SearchMore = "search-more"
+}
+export declare enum PickerActionType {
+    /** Initial fetch for the current level started — shows the skeleton. */
+    FetchStart = "FETCH_START",
+    /** Initial fetch succeeded; carries `forParentId` so stale responses can be dropped. */
+    FetchSuccess = "FETCH_SUCCESS",
+    /** Initial fetch failed; sets `lastFailedOp = 'browse'` so retry knows what to re-run. */
+    FetchError = "FETCH_ERROR",
+    /** User navigated deeper into a node — atomically transitions to a new level. */
+    DrillDown = "DRILL_DOWN",
+    /** User navigated back to a level whose snapshot is still cached — no skeleton. */
+    NavigateBack = "NAVIGATE_BACK",
+    /** User navigated back to a level whose cache was evicted — re-fetch with skeleton. */
+    NavigateBackRefetch = "NAVIGATE_BACK_REFETCH",
+    /** Hard reset to `initialState` (e.g. popover closed). */
+    Reset = "RESET",
+    /** "Load more" page fetch for the current browse list started. */
+    LoadMoreStart = "LOAD_MORE_START",
+    /** "Load more" page appended to `items`; advances `itemsNextMarker`. */
+    LoadMoreSuccess = "LOAD_MORE_SUCCESS",
+    /**
+     * "Load more" page failed; sets `loadMoreError` so the inline error row is shown,
+     * and `lastFailedOp = 'browse-more'` so retry knows what to re-run from the
+     * current marker.
+     */
+    LoadMoreError = "LOAD_MORE_ERROR",
+    /** Search input changed — updates the raw `searchInputValue` on every keystroke. */
+    SearchInputChange = "SEARCH_INPUT_CHANGE",
+    /** Debounced search committed — promotes `searchInputValue` to `searchQuery` and fires the request. */
+    SearchFetchStart = "SEARCH_FETCH_START",
+    /** Search results arrived; carries `forQuery` so stale responses can be dropped. */
+    SearchFetchSuccess = "SEARCH_FETCH_SUCCESS",
+    /** Search request failed; sets `lastFailedOp = 'search'`. */
+    SearchFetchError = "SEARCH_FETCH_ERROR",
+    /** Search input cleared — wipes the search slice and returns to the browse view. */
+    SearchClear = "SEARCH_CLEAR",
+    /** "Load more" page fetch for the current search results started. */
+    SearchLoadMoreStart = "SEARCH_LOAD_MORE_START",
+    /** "Load more" page appended to `searchResults`; advances `searchNextMarker`. */
+    SearchLoadMoreSuccess = "SEARCH_LOAD_MORE_SUCCESS",
+    /**
+     * "Load more" page for search failed; sets `searchLoadMoreError` so the inline
+     * error row is shown and `lastFailedOp = 'search-more'` so retry re-runs the
+     * load-more from the current marker against the active query.
+     */
+    SearchLoadMoreError = "SEARCH_LOAD_MORE_ERROR",
+    /** User picked a level filter for the global (root-level) search. */
+    SetLevelFilter = "SET_LEVEL_FILTER"
+}
+export type PickerAction = {
+    type: PickerActionType.FetchStart;
+} | {
+    type: PickerActionType.FetchSuccess;
+    entries: TaxonomyNode[];
+    nextMarker: string | undefined;
+    forParentId: string | null;
+} | {
+    type: PickerActionType.FetchError;
+    error: string;
+    forParentId: string | null;
+} | {
+    type: PickerActionType.DrillDown;
+    targetParentId: string;
+    levelStack: BreadcrumbEntry[];
+} | {
+    type: PickerActionType.NavigateBack;
+    targetParentId: string | null;
+    levelStack: BreadcrumbEntry[];
+    cached: {
+        items: TaxonomyNode[];
+        nextMarker: string | undefined;
+    };
+} | {
+    type: PickerActionType.NavigateBackRefetch;
+    targetParentId: string | null;
+    levelStack: BreadcrumbEntry[];
+} | {
+    type: PickerActionType.Reset;
+} | {
+    type: PickerActionType.LoadMoreStart;
+} | {
+    type: PickerActionType.LoadMoreSuccess;
+    entries: TaxonomyNode[];
+    nextMarker: string | undefined;
+} | {
+    type: PickerActionType.LoadMoreError;
+    error: string;
+} | {
+    type: PickerActionType.SearchInputChange;
+    value: string;
+    availableLevels: readonly TaxonomyLevel[];
+} | {
+    type: PickerActionType.SearchFetchStart;
+    query: string;
+} | {
+    type: PickerActionType.SearchFetchSuccess;
+    results: TaxonomySearchResult[];
+    nextMarker: string | undefined;
+    forQuery: string;
+} | {
+    type: PickerActionType.SearchFetchError;
+    error: string;
+} | {
+    type: PickerActionType.SearchClear;
+} | {
+    type: PickerActionType.SearchLoadMoreStart;
+} | {
+    type: PickerActionType.SearchLoadMoreSuccess;
+    entries: TaxonomySearchResult[];
+    nextMarker: string | undefined;
+    forQuery: string;
+} | {
+    type: PickerActionType.SearchLoadMoreError;
+    error: string;
+    forQuery: string;
+} | {
+    type: PickerActionType.SetLevelFilter;
+    level: number | null;
+};
+export interface PickerState {
+    /** Breadcrumb trail of ancestors leading to `currentParentId`; empty at root. */
+    levelStack: BreadcrumbEntry[];
+    /** Parent node currently being browsed; `null` is the root level. */
+    currentParentId: string | null;
+    /** Children of `currentParentId` rendered in the browse list. */
+    items: TaxonomyNode[];
+    /** Pagination cursor for the next `items` page; `undefined` when no more pages. */
+    itemsNextMarker: string | undefined;
+    /** Initial fetch for the current level is in flight — drives the skeleton. */
+    isFetching: boolean;
+    /** "Load more" page for the current level is in flight — drives the inline spinner. */
+    isFetchingMore: boolean;
+    /** Initial fetch error for the current level; mutually exclusive with `items`. */
+    initialLoadError: string | null;
+    /**
+     * "Load more" page error for the current level. When set, an inline error row
+     * is rendered at the bottom of the existing list (already-loaded items remain
+     * visible). Cleared when a retry begins or the level changes.
+     */
+    loadMoreError: string | null;
+    /** Raw search input value — updated on every keystroke (pre-debounce). */
+    searchInputValue: string;
+    /** Debounced/committed query the active search request was fired against; used to race-guard `SearchFetchSuccess`. */
+    searchQuery: string;
+    /** Results for the active `searchQuery`. */
+    searchResults: TaxonomySearchResult[];
+    /** Pagination cursor for the next `searchResults` page. */
+    searchNextMarker: string | undefined;
+    /** Initial search fetch is in flight. */
+    isFetchingSearch: boolean;
+    /** "Load more" page for search results is in flight. */
+    isFetchingSearchMore: boolean;
+    /** Initial search request error; mutually exclusive with `searchResults`. */
+    searchError: string | null;
+    /**
+     * "Load more" page error for the active search query. When set, an inline
+     * error row is rendered at the bottom of the search results list. Cleared
+     * when a retry begins or the search query changes / clears.
+     */
+    searchLoadMoreError: string | null;
+    /** Optional level filter applied to the global (root-level) search; `null` means "all levels". */
+    levelFilter: number | null;
+    /** Levels available in the current taxonomy (drives the level-filter dropdown and single-level scoping). */
+    availableLevels: TaxonomyLevel[];
+    /**
+     * Which operation failed most recently, so `retry()` knows which one to re-run
+     * without having to infer it from other state. Cleared on success or when a
+     * new operation begins. Covers all four failure cases: initial browse, browse
+     * load-more, initial search, and search load-more.
+     */
+    lastFailedOp: FailedOp | null;
+}
+export declare const initialState: PickerState;
+export declare function pickerReducer(state: PickerState, action: PickerAction): PickerState;

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

@@ -0,0 +1,4 @@
+import { BreadcrumbEntry } from '../types';
+import { PickerState } from './reducer';
+/** Atomic move to a new level: empties items, shows skeleton, wipes search slice. */
+export declare const transitionToLevel: (state: PickerState, targetParentId: string | null, levelStack: BreadcrumbEntry[]) => PickerState;

package/dist/types/lib/stories/metadata-taxonomy-picker.stories.d.ts

@@ -0,0 +1,136 @@
+import { StoryObj } from '@storybook/react-vite';
+import { MetadataTaxonomyPicker } from '../../index';
+import { MetadataTaxonomyPickerProps, TaxonomyPickerMode, TaxonomyValue } from '../types';
+declare const _default: {
+    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)[];
+    parameters: {
+        docs: {
+            description: {
+                component: string;
+            };
+            page: () => import("react/jsx-runtime").JSX.Element;
+        };
+        modernizedComponents: boolean;
+    };
+};
+export default _default;
+type Story = StoryObj<typeof MetadataTaxonomyPicker>;
+/** The popover shows the initial data when the initial fetch is successful. */
+export declare const InitialData: Story;
+/**
+ * The popover shows a skeleton loading state while the initial fetch is in progress.
+ */
+export declare const LoadingState: Story;
+/**
+ * The popover shows an empty state when there is no data after loading completes.
+ */
+export declare const EmptyState: Story;
+/** 1 000 items rendered in a virtualized list — validates performance at scale. */
+export declare const LargeDataset: Story;
+/** 1 000 items in multi-select mode — checkboxes with large dataset. */
+export declare const LargeDatasetMultiSelect: Story;
+/** Error state — the fetch fails and a retry button is shown. */
+export declare const ErrorState: Story;
+/**
+ * Disabled state — the trigger cannot be interacted with.
+ */
+export declare const Disabled: Story;
+/**
+ * No selection — only the placeholder text is visible inside the trigger.
+ */
+export declare const NoSelection: Story;
+/**
+ * A single chip is shown inside the trigger when one value is selected.
+ */
+export declare const SingleChip: Story;
+/**
+ * Multiple chips are shown when several values are selected.
+ */
+export declare const MultipleChips: Story;
+/**
+ * When many values are selected the chips wrap across multiple lines inside the trigger.
+ */
+export declare const OverflowChips: Story;
+/** Click a row's chevron (or press Right Arrow on a focused row) to drill in. */
+export declare const DrillDownNavigation: Story;
+/**
+ * Eight-level hierarchy (Region → Block) with four siblings per level. Drill all
+ * the way down to see the Blueprint Breadcrumb collapse the older ancestors into
+ * the folder-tree dropdown while keeping the last few levels and the current
+ * page visible.
+ */
+export declare const DeepDrillDownNavigation: Story;
+/**
+ * Six-level hierarchy with intentionally long display names, rendered in a
+ * narrow popover. Forces the folder-tree truncation to engage early so the
+ * breadcrumb dropdown trigger is visible even mid-way through the trail.
+ */
+export declare const DeepDrillDownNavigationWithLongLabels: Story;
+/**
+ * Picker with real search filtering: typing a substring shows all matching
+ * nodes with their ancestor breadcrumbs. Try `region`, `country`, `state`, or
+ * `01` to see results across all levels. Use the level filter dropdown to
+ * restrict results to a specific level.
+ */
+export declare const WithSearch: Story;
+/**
+ * Disabled state with selected values — chips are visible but not interactive (no dismiss button).
+ */
+export declare const DisabledWithChips: Story;
+/**
+ * Cursor-paginated browse list (450 items, page size 100). Scroll near the bottom
+ * to auto-fetch the next page: ghost rows appear while the request is in flight
+ * and new rows append below the already-loaded ones, preserving scroll position.
+ */
+export declare const Pagination: Story;
+/**
+ * Pagination + drill-down: scroll through several pages at the root, drill into
+ * a node, then navigate back. All pages loaded before drilling down are restored
+ * from cache, so the user lands back at the same scroll-loaded state without
+ * having to re-scroll or re-fetch.
+ */
+export declare const PaginationWithDrillDownCacheRestore: Story;
+/** Multi-level × multi-select: drill down at every level, pick many values across levels. */
+export declare const MultiLevelMultiSelect: Story;
+/** Multi-level × single-select: drill down, pick one value; popover closes on selection. */
+export declare const MultiLevelSingleSelect: Story;
+/**
+ * Single-level × multi-select with non-selectable parents. Drill through
+ * Country → State (no radios) to reach selectable Cities; search is locked
+ * to the City level regardless of browse position.
+ */
+export declare const SingleLevelMultiSelectWithNonSelectableParents: Story;
+/** Single-level × single-select with non-selectable parents — closes on City pick. */
+export declare const SingleLevelSingleSelectWithNonSelectableParents: Story;
+/**
+ * Browse load-more error: the first page loads successfully, but the next page
+ * (triggered by scrolling to the bottom) fails. Already-loaded items stay
+ * visible and an inline "Loading failed" row with a Reload action appears at
+ * the bottom of the list. Clicking Reload re-attempts from the current marker.
+ */
+export declare const LoadMoreError: Story;
+/**
+ * Search error: the initial search request fails, replacing the result area
+ * with the full-area error and retry button. Clicking retry re-runs the last
+ * committed query.
+ */
+export declare const SearchErrorState: Story;
+export declare const PortalElementInScrollableContainer: Story;
+export declare const ForwardedRefFocus: Story;

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

@@ -0,0 +1,10 @@
+import { TaxonomyMenuItemProps } from '../../components/taxonomy-menu-item';
+interface BuildOptions extends Partial<TaxonomyMenuItemProps> {
+    onSelect: TaxonomyMenuItemProps['onSelect'];
+    onDrillDown: TaxonomyMenuItemProps['onDrillDown'];
+}
+/** Browse-mode items: single-line rows, no ancestors, drill-down enabled. */
+export declare function buildBrowseItems(count: number, options: BuildOptions): TaxonomyMenuItemProps[];
+/** Search-mode items: rows with ancestor breadcrumbs of varying depth. */
+export declare function buildSearchItems(count: number, options: BuildOptions): TaxonomyMenuItemProps[];
+export {};

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

@@ -0,0 +1,35 @@
+import { TaxonomyItemsService, TaxonomyLevel, TaxonomyNode, TaxonomySearchResult } from '../../types';
+declare const ROOT_KEY = "__root__";
+export interface MockServiceConfig {
+    /** Flat fixture; ignored when `nodesByParent` is set. */
+    nodes?: TaxonomyNode[];
+    /** Children indexed by parent id; use `ROOT_KEY` for the root level. */
+    nodesByParent?: Record<string, TaxonomyNode[]>;
+    /**
+     * Pre-defined search results returned verbatim regardless of the query.
+     * Ignored when `filterSearchByQuery` is `true`.
+     */
+    searchResults?: TaxonomySearchResult[];
+    /**
+     * When `true` and `nodesByParent` is provided, `searchNodes` performs a
+     * real case-insensitive substring match against every node's display name
+     * and returns results with full ancestor chains — useful for interactive
+     * search stories.
+     */
+    filterSearchByQuery?: boolean;
+    /** Optional fixture levels; accepted for parity with the picker's `levels` prop. */
+    levels?: TaxonomyLevel[];
+    delay?: number;
+    /** Override the response delay for `searchNodes` only. Defaults to `delay`. */
+    searchDelay?: number;
+    shouldError?: boolean;
+    errorMessage?: string;
+    /**
+     * When set, `getNodes` / `searchNodes` honor `params.limit` + `params.marker`
+     * for true cursor pagination over the fixture. When unset, the full fixture
+     * is returned in one page (legacy behavior used by non-pagination stories).
+     */
+    paginate?: boolean;
+}
+export declare function createMockItemsService(config?: MockServiceConfig): TaxonomyItemsService;
+export { ROOT_KEY };