@persona/design-system 0.1.5-pre.4

package/dist/ComboboxBase-D2wypeXf.d.cts

@@ -0,0 +1,320 @@
+import { r as ButtonProps } from "./Button-C_3p5Xfi.cjs";
+import { c as ParagraphProps, u as SpanProps } from "./Text-CrGiWG2E.cjs";
+import { n as InputSizes } from "./input-Bm_anD8X.cjs";
+import { a as InputProps } from "./Input-XppkvfUf.cjs";
+import { o as StickerProps } from "./Sticker-S6QWjlEJ.cjs";
+import * as _$react from "react";
+import { CSSProperties } from "react";
+import * as _$styled_components0 from "styled-components";
+import * as _$react_jsx_runtime0 from "react/jsx-runtime.js";
+import { Spacing } from "@persona/design-tokens";
+import { Virtualizer } from "@tanstack/react-virtual";
+
+//#region components/Combobox/ComboboxBase.d.ts
+/**
+ * In the future, we may extend this to include other style properties
+ * like fontWeight, fontStyle, etc. if needed.
+ */
+type LabelStyle = Pick<CSSProperties, 'fontFamily'>;
+interface ComboboxOption<T = string> {
+  label: string;
+  /**
+   * Description of the option that will be displayed below the label. Will not be rendered when labelStickerVariant is provided.
+   */
+  description?: string;
+  value: T;
+  /**
+   * Sticker variant to render the label within.
+   */
+  labelStickerVariant?: StickerProps['variant'];
+  /**
+   * Optional style properties to apply to the option label currently limited to fontFamily.
+   * This should only be used as a one-off for font dropdowns and most comboboxes should use the default fontFamily.
+   */
+  PLEASE_DO_NOT_USE_labelFontStyle?: LabelStyle;
+}
+interface ComboboxOptionGroup<T = string> {
+  readonly label: string;
+  readonly options: ComboboxOptionsOrGroups<T>;
+  /**
+   * When `true`, the group renders as a single navigation row with a
+   * trailing chevron. Clicking it descends into a submenu whose
+   * contents are this group's `options`; the group itself never
+   * commits a value via `onChange`. The `label` becomes the
+   * breadcrumb crumb shown alongside any leaf inside in search mode.
+   *
+   * When omitted (or `false`), the group renders inline as a section
+   * header above its options — the legacy `MenuHeading` behavior.
+   *
+   * Today only single-select Combobox honors the nested-navigation
+   * UX. Multi-select degrades gracefully: it strips the `nested`
+   * flag from every group at the top of the component (treating the
+   * tree as inline section headers + leaves), so every leaf stays
+   * reachable with checkboxes — just without the chevron / Back-row
+   * navigation. Nested-nav for multi-select can be added once we
+   * have customer demand without changing this API.
+   */
+  readonly nested?: boolean;
+}
+declare function isOptionGroup<T>(item: ComboboxOption<T> | ComboboxOptionGroup<T>): item is ComboboxOptionGroup<T>;
+/** True when a group renders as a navigation row rather than a section header. */
+declare function isNestedGroup<T>(item: ComboboxOption<T> | ComboboxOptionGroup<T>): item is ComboboxOptionGroup<T> & {
+  nested: true;
+};
+type ComboboxOptionsOrGroups<T = string> = readonly (ComboboxOption<T> | ComboboxOptionGroup<T>)[];
+/**
+ * Flatten the visible leaves at the current navigation level. Inline
+ * (non-nested) groups are walked through transparently — their leaves
+ * surface at this level. Nested groups are skipped along with their
+ * contents — those leaves live behind a navigation step in single-
+ * select. Multi-select doesn't reach this code with nested groups
+ * intact (it inlines them at the component boundary), so the skip
+ * here is the single-select-only contract.
+ */
+declare function flattenOptions<T>(items: ComboboxOptionsOrGroups<T>): ComboboxOption<T>[];
+/**
+ * Recurse through the entire option tree looking for any nested
+ * group. Used to gate nested-mode behavior so trees that don't opt
+ * in (the overwhelmingly common case) skip the extra book-keeping
+ * entirely. Single-select uses this to switch between its nested-nav
+ * render path and the legacy renderer; multi-select uses it to
+ * short-circuit its `nested → inline` transform when there's nothing
+ * to convert.
+ */
+declare function containsNestedGroup<T>(items: readonly (ComboboxOption<T> | ComboboxOptionGroup<T>)[]): boolean;
+/**
+ * Walk the option tree by following `path` step-by-step. Each entry
+ * in `path` is the `label` of a nested group at that level; we
+ * descend into its `options` at each step. Returns the items visible
+ * at the resolved level (a mix of leaves, inline groups, and further
+ * nested groups).
+ *
+ * - Empty `path` returns the original top-level items unchanged.
+ * - If any step doesn't resolve to a known nested group (e.g. stale
+ *   state after the registry changes), returns an empty list so the
+ *   consumer can fall back to the root view.
+ */
+declare function getOptionsAtPath<T>(options: ComboboxOptionsOrGroups<T>, path: readonly string[]): ComboboxOptionsOrGroups<T>;
+/**
+ * One leaf hit returned by `flattenLeafOptions`. Carries the leaf's
+ * `option` alongside the labels of every nested-group ancestor
+ * (top-down). Used as the search-results data shape so each hit can
+ * render with a breadcrumb (e.g. "Business Account" for a custom
+ * field that lives under that parent record type's submenu).
+ */
+interface LeafOptionEntry<T = string> {
+  option: ComboboxOption<T>;
+  breadcrumb: readonly string[];
+}
+/**
+ * Recursively walk the tree and return every leaf option, each paired
+ * with the labels of its nested-group ancestors. Used by single-select
+ * Combobox to populate the search-results view: the search query
+ * bypasses the active navigation path and matches against every leaf
+ * in the tree, with the breadcrumb surfacing parent context in each
+ * hit.
+ *
+ * Inline (non-nested) groups are walked through transparently — their
+ * `label` isn't a breadcrumb crumb because they don't correspond to a
+ * navigation step. Only nested groups contribute a crumb.
+ */
+declare function flattenLeafOptions<T>(options: ComboboxOptionsOrGroups<T>, breadcrumb?: readonly string[]): LeafOptionEntry<T>[];
+/**
+ * Discriminated tagged item for single-select's downshift items list
+ * in nested-navigation mode. Leaves are selectable and commit via
+ * `onChange`; groups are navigable and descend into a submenu instead.
+ */
+type NavigableItem<T> = {
+  readonly kind: 'leaf';
+  readonly option: ComboboxOption<T>;
+} | {
+  readonly kind: 'group';
+  readonly group: ComboboxOptionGroup<T>;
+};
+/**
+ * Build the flat list of navigable items at the current navigation
+ * level, in document order. Inline (non-nested) groups are walked
+ * through transparently; their leaves and any nested subgroups
+ * contribute at this level. Nested groups become a `kind: 'group'`
+ * entry that the renderer turns into a navigation row.
+ */
+declare function getNavigableItemsAtLevel<T>(items: ComboboxOptionsOrGroups<T>): NavigableItem<T>[];
+/**
+ * A hook which provides the caller with dynamically filtered options
+ *
+ * @param options - The options to filter (can be flat or grouped)
+ * @param inputValue - The input value to filter the options by
+ * @returns The subset of the options that match the input value according to the fuse.js library
+ */
+declare function useFilteredOptions<T = string>(options: ComboboxOptionsOrGroups<T>, inputValue: string): ComboboxOption<T>[];
+type VirtualRow<T> = {
+  kind: 'group-header';
+  label: string;
+} | {
+  kind: 'option';
+  option: ComboboxOption<T>;
+  index: number;
+};
+declare function buildVirtualRows<T>(options: ComboboxOptionsOrGroups<T>, filteredOptions: ComboboxOption<T>[], indexRealToIndexVirtual: Map<number, number>): VirtualRow<T>[];
+interface RenderOptionsWithGroupsParams<T> {
+  options: ComboboxOptionsOrGroups<T>;
+  filteredOptions: ComboboxOption<T>[];
+  virtualizer?: Virtualizer<HTMLDivElement, Element>;
+  virtualRows?: VirtualRow<T>[];
+  renderOption: (option: ComboboxOption<T>, flatIndex: number) => React.ReactNode;
+}
+/**
+ * Renders options with support for groups, handling filtering and proper indexing
+ *
+ * @param params - Object containing options, filteredOptions, and renderOption
+ * @param params.options - The original options array (can include groups)
+ * @param params.filteredOptions - The flat filtered options to display
+ * @param params.virtualizer - Optional virtualizer for large lists
+ * @param params.virtualRows - Pre-built flat rows list (required when virtualizer is provided)
+ * @param params.renderOption - Callback to render each individual option with its flat index
+ * @returns React nodes with properly grouped and filtered options
+ */
+declare function renderOptionsWithGroups<T>({
+  options,
+  filteredOptions,
+  renderOption,
+  virtualizer,
+  virtualRows
+}: RenderOptionsWithGroupsParams<T>): React.ReactNode;
+interface ComboboxBaseProps<T = string> {
+  /**
+   * Size of the combobox input
+   */
+  size?: InputSizes;
+  /**
+   * Array of options to display in the dropdown
+   * Can be flat options, grouped options, or a mix of both
+   */
+  options: ComboboxOptionsOrGroups<T>;
+  /**
+   * If true, the options are currently being loaded
+   */
+  isOptionsLoading?: boolean;
+  /**
+   * Callback when input value changes (for filtering)
+   * In single this is the main input, in multi this is the search input
+   * In both cases this corresponds to the input the user can type into to filter the options
+   */
+  onInputChange?: (value: string) => void;
+  /**
+   * Callback when dropdown open state changes
+   */
+  onOpenChange?: (isOpen: boolean) => void;
+  /**
+   * Custom empty state message when no options match filter
+   */
+  emptyStateMessage?: string;
+  /**
+   * Whether the combobox is disabled
+   */
+  disabled?: boolean;
+  /**
+   * ID of the label for the combobox input
+   */
+  labelId?: string;
+  /**
+   * Aria label for accessibility when no visible label is provided
+   */
+  'aria-label'?: string;
+  /**
+   * Placeholder text when no option is selected
+   */
+  placeholder?: string;
+  /**
+   * Whether the combobox has a warning state
+   */
+  hasWarning?: boolean;
+  /**
+   * Whether the combobox has an error state
+   */
+  hasError?: boolean;
+  /**
+   * ID for the combobox input
+   */
+  id?: string;
+  /**
+   * Whether to render the dropdown in a portal (breaks out of overflow containers)
+   */
+  portal?: boolean;
+  /**
+   * Reference to the container element for portal rendering.
+   * When provided, the dropdown will use this element's dimensions for positioning.
+   */
+  portalContainerRef?: React.RefObject<HTMLElement>;
+  /**
+   * Optional external trigger (e.g. an "Add" button or icon-only menu opener).
+   * When provided, the Combobox clones it with downshift's toggle props and
+   * renders it in place of the default input + caret; the search input moves
+   * inside the dropdown.
+   */
+  trigger?: React.ReactElement;
+  /**
+   * Render the searchable option list inline without a trigger or floating
+   * dropdown. Use when another component already owns the containing popover.
+   *
+   * When `true`, the in-panel search uses bordered `Input` chrome and the
+   * embedder owns all surrounding spacing; when `false`, the floating-dropdown
+   * borderless search strip is preserved.
+   */
+  embedded?: boolean;
+}
+declare const MAX_DROPDOWN_HEIGHT = "300px";
+declare const Container: _$styled_components0.StyledComponent<"div", any, {}, never>;
+declare const InputContainer: _$styled_components0.StyledComponent<"div", any, {}, never>;
+interface ComboboxInputProps {
+  $isOpen?: boolean;
+  hasError?: boolean;
+  hasWarning?: boolean;
+  $selectedItemStyle?: LabelStyle;
+}
+declare const ComboboxInput: _$styled_components0.StyledComponent<_$react.ForwardRefExoticComponent<InputProps & _$react.RefAttributes<HTMLInputElement>>, any, ComboboxInputProps, never>;
+declare const CaretButton: _$styled_components0.StyledComponent<_$react.ForwardRefExoticComponent<Omit<ButtonProps, "ref"> & _$react.RefAttributes<HTMLButtonElement>>, any, {
+  width: "icon";
+}, "width">;
+interface DropdownContainerProps {
+  $isOpen?: boolean;
+  $portal?: boolean;
+  $embedded?: boolean;
+  $top?: number;
+  $left?: number;
+  $width?: number;
+  /** Minimum dropdown width (decouples from a narrow trigger). */
+  $minWidth?: string;
+}
+declare const DropdownContainer: _$styled_components0.StyledComponent<_$react.ComponentType<any>, any, DropdownContainerProps, never>;
+declare const ScrollableMenuList: _$styled_components0.StyledComponent<"div", any, {
+  padding?: Spacing;
+}, never>;
+declare const SearchInputContainer: _$styled_components0.StyledComponent<"div", any, {
+  $embedded?: boolean;
+}, never>;
+declare const SearchInput: _$styled_components0.StyledComponent<_$react.ForwardRefExoticComponent<InputProps & _$react.RefAttributes<HTMLInputElement>>, any, {
+  $embedded?: boolean;
+}, never>;
+declare const EmptyState: _$styled_components0.StyledComponent<_$react.FC<_$react.PropsWithChildren<SpanProps>>, any, ParagraphProps, never>;
+declare const LoadingContainer: _$styled_components0.StyledComponent<"div", any, {}, never>;
+declare const OptionLabel: _$styled_components0.StyledComponent<"div", any, {
+  $labelStyle?: LabelStyle;
+}, never>;
+declare const Description: _$styled_components0.StyledComponent<"p", any, {}, never>;
+declare function useDropdownPosition(portalContainerRef: React.RefObject<HTMLElement>, isOpen: boolean, portal?: boolean): {
+  top: number;
+  left: number;
+  width: number;
+};
+interface DropdownPortalWrapperProps {
+  children: React.ReactNode;
+  portal?: boolean;
+}
+declare function DropdownPortalWrapper({
+  children,
+  portal
+}: DropdownPortalWrapperProps): _$react_jsx_runtime0.JSX.Element;
+//#endregion
+export { renderOptionsWithGroups as A, containsNestedGroup as C, getOptionsAtPath as D, getNavigableItemsAtLevel as E, useFilteredOptions as M, isNestedGroup as O, buildVirtualRows as S, flattenOptions as T, NavigableItem as _, ComboboxOptionGroup as a, SearchInput as b, Description as c, DropdownPortalWrapperProps as d, EmptyState as f, MAX_DROPDOWN_HEIGHT as g, LoadingContainer as h, ComboboxOption as i, useDropdownPosition as j, isOptionGroup as k, DropdownContainer as l, LeafOptionEntry as m, ComboboxBaseProps as n, ComboboxOptionsOrGroups as o, InputContainer as p, ComboboxInput as r, Container as s, CaretButton as t, DropdownPortalWrapper as u, OptionLabel as v, flattenLeafOptions as w, SearchInputContainer as x, ScrollableMenuList as y };
+//# sourceMappingURL=ComboboxBase-D2wypeXf.d.cts.map

package/dist/ComboboxBase-INya0Csa.d.mts

@@ -0,0 +1,320 @@
+import { r as ButtonProps } from "./Button-DqDLGURJ.mjs";
+import { c as ParagraphProps, u as SpanProps } from "./Text-CnXedFut.mjs";
+import { n as InputSizes } from "./input-BCmP106-.mjs";
+import { a as InputProps } from "./Input-Cv5qieRg.mjs";
+import { o as StickerProps } from "./Sticker-Bd7KkekO.mjs";
+import { Spacing } from "@persona/design-tokens";
+import * as _$styled_components0 from "styled-components";
+import * as _$react_jsx_runtime0 from "react/jsx-runtime";
+import * as _$react from "react";
+import { CSSProperties } from "react";
+import { Virtualizer } from "@tanstack/react-virtual";
+
+//#region components/Combobox/ComboboxBase.d.ts
+/**
+ * In the future, we may extend this to include other style properties
+ * like fontWeight, fontStyle, etc. if needed.
+ */
+type LabelStyle = Pick<CSSProperties, 'fontFamily'>;
+interface ComboboxOption<T = string> {
+  label: string;
+  /**
+   * Description of the option that will be displayed below the label. Will not be rendered when labelStickerVariant is provided.
+   */
+  description?: string;
+  value: T;
+  /**
+   * Sticker variant to render the label within.
+   */
+  labelStickerVariant?: StickerProps['variant'];
+  /**
+   * Optional style properties to apply to the option label currently limited to fontFamily.
+   * This should only be used as a one-off for font dropdowns and most comboboxes should use the default fontFamily.
+   */
+  PLEASE_DO_NOT_USE_labelFontStyle?: LabelStyle;
+}
+interface ComboboxOptionGroup<T = string> {
+  readonly label: string;
+  readonly options: ComboboxOptionsOrGroups<T>;
+  /**
+   * When `true`, the group renders as a single navigation row with a
+   * trailing chevron. Clicking it descends into a submenu whose
+   * contents are this group's `options`; the group itself never
+   * commits a value via `onChange`. The `label` becomes the
+   * breadcrumb crumb shown alongside any leaf inside in search mode.
+   *
+   * When omitted (or `false`), the group renders inline as a section
+   * header above its options — the legacy `MenuHeading` behavior.
+   *
+   * Today only single-select Combobox honors the nested-navigation
+   * UX. Multi-select degrades gracefully: it strips the `nested`
+   * flag from every group at the top of the component (treating the
+   * tree as inline section headers + leaves), so every leaf stays
+   * reachable with checkboxes — just without the chevron / Back-row
+   * navigation. Nested-nav for multi-select can be added once we
+   * have customer demand without changing this API.
+   */
+  readonly nested?: boolean;
+}
+declare function isOptionGroup<T>(item: ComboboxOption<T> | ComboboxOptionGroup<T>): item is ComboboxOptionGroup<T>;
+/** True when a group renders as a navigation row rather than a section header. */
+declare function isNestedGroup<T>(item: ComboboxOption<T> | ComboboxOptionGroup<T>): item is ComboboxOptionGroup<T> & {
+  nested: true;
+};
+type ComboboxOptionsOrGroups<T = string> = readonly (ComboboxOption<T> | ComboboxOptionGroup<T>)[];
+/**
+ * Flatten the visible leaves at the current navigation level. Inline
+ * (non-nested) groups are walked through transparently — their leaves
+ * surface at this level. Nested groups are skipped along with their
+ * contents — those leaves live behind a navigation step in single-
+ * select. Multi-select doesn't reach this code with nested groups
+ * intact (it inlines them at the component boundary), so the skip
+ * here is the single-select-only contract.
+ */
+declare function flattenOptions<T>(items: ComboboxOptionsOrGroups<T>): ComboboxOption<T>[];
+/**
+ * Recurse through the entire option tree looking for any nested
+ * group. Used to gate nested-mode behavior so trees that don't opt
+ * in (the overwhelmingly common case) skip the extra book-keeping
+ * entirely. Single-select uses this to switch between its nested-nav
+ * render path and the legacy renderer; multi-select uses it to
+ * short-circuit its `nested → inline` transform when there's nothing
+ * to convert.
+ */
+declare function containsNestedGroup<T>(items: readonly (ComboboxOption<T> | ComboboxOptionGroup<T>)[]): boolean;
+/**
+ * Walk the option tree by following `path` step-by-step. Each entry
+ * in `path` is the `label` of a nested group at that level; we
+ * descend into its `options` at each step. Returns the items visible
+ * at the resolved level (a mix of leaves, inline groups, and further
+ * nested groups).
+ *
+ * - Empty `path` returns the original top-level items unchanged.
+ * - If any step doesn't resolve to a known nested group (e.g. stale
+ *   state after the registry changes), returns an empty list so the
+ *   consumer can fall back to the root view.
+ */
+declare function getOptionsAtPath<T>(options: ComboboxOptionsOrGroups<T>, path: readonly string[]): ComboboxOptionsOrGroups<T>;
+/**
+ * One leaf hit returned by `flattenLeafOptions`. Carries the leaf's
+ * `option` alongside the labels of every nested-group ancestor
+ * (top-down). Used as the search-results data shape so each hit can
+ * render with a breadcrumb (e.g. "Business Account" for a custom
+ * field that lives under that parent record type's submenu).
+ */
+interface LeafOptionEntry<T = string> {
+  option: ComboboxOption<T>;
+  breadcrumb: readonly string[];
+}
+/**
+ * Recursively walk the tree and return every leaf option, each paired
+ * with the labels of its nested-group ancestors. Used by single-select
+ * Combobox to populate the search-results view: the search query
+ * bypasses the active navigation path and matches against every leaf
+ * in the tree, with the breadcrumb surfacing parent context in each
+ * hit.
+ *
+ * Inline (non-nested) groups are walked through transparently — their
+ * `label` isn't a breadcrumb crumb because they don't correspond to a
+ * navigation step. Only nested groups contribute a crumb.
+ */
+declare function flattenLeafOptions<T>(options: ComboboxOptionsOrGroups<T>, breadcrumb?: readonly string[]): LeafOptionEntry<T>[];
+/**
+ * Discriminated tagged item for single-select's downshift items list
+ * in nested-navigation mode. Leaves are selectable and commit via
+ * `onChange`; groups are navigable and descend into a submenu instead.
+ */
+type NavigableItem<T> = {
+  readonly kind: 'leaf';
+  readonly option: ComboboxOption<T>;
+} | {
+  readonly kind: 'group';
+  readonly group: ComboboxOptionGroup<T>;
+};
+/**
+ * Build the flat list of navigable items at the current navigation
+ * level, in document order. Inline (non-nested) groups are walked
+ * through transparently; their leaves and any nested subgroups
+ * contribute at this level. Nested groups become a `kind: 'group'`
+ * entry that the renderer turns into a navigation row.
+ */
+declare function getNavigableItemsAtLevel<T>(items: ComboboxOptionsOrGroups<T>): NavigableItem<T>[];
+/**
+ * A hook which provides the caller with dynamically filtered options
+ *
+ * @param options - The options to filter (can be flat or grouped)
+ * @param inputValue - The input value to filter the options by
+ * @returns The subset of the options that match the input value according to the fuse.js library
+ */
+declare function useFilteredOptions<T = string>(options: ComboboxOptionsOrGroups<T>, inputValue: string): ComboboxOption<T>[];
+type VirtualRow<T> = {
+  kind: 'group-header';
+  label: string;
+} | {
+  kind: 'option';
+  option: ComboboxOption<T>;
+  index: number;
+};
+declare function buildVirtualRows<T>(options: ComboboxOptionsOrGroups<T>, filteredOptions: ComboboxOption<T>[], indexRealToIndexVirtual: Map<number, number>): VirtualRow<T>[];
+interface RenderOptionsWithGroupsParams<T> {
+  options: ComboboxOptionsOrGroups<T>;
+  filteredOptions: ComboboxOption<T>[];
+  virtualizer?: Virtualizer<HTMLDivElement, Element>;
+  virtualRows?: VirtualRow<T>[];
+  renderOption: (option: ComboboxOption<T>, flatIndex: number) => React.ReactNode;
+}
+/**
+ * Renders options with support for groups, handling filtering and proper indexing
+ *
+ * @param params - Object containing options, filteredOptions, and renderOption
+ * @param params.options - The original options array (can include groups)
+ * @param params.filteredOptions - The flat filtered options to display
+ * @param params.virtualizer - Optional virtualizer for large lists
+ * @param params.virtualRows - Pre-built flat rows list (required when virtualizer is provided)
+ * @param params.renderOption - Callback to render each individual option with its flat index
+ * @returns React nodes with properly grouped and filtered options
+ */
+declare function renderOptionsWithGroups<T>({
+  options,
+  filteredOptions,
+  renderOption,
+  virtualizer,
+  virtualRows
+}: RenderOptionsWithGroupsParams<T>): React.ReactNode;
+interface ComboboxBaseProps<T = string> {
+  /**
+   * Size of the combobox input
+   */
+  size?: InputSizes;
+  /**
+   * Array of options to display in the dropdown
+   * Can be flat options, grouped options, or a mix of both
+   */
+  options: ComboboxOptionsOrGroups<T>;
+  /**
+   * If true, the options are currently being loaded
+   */
+  isOptionsLoading?: boolean;
+  /**
+   * Callback when input value changes (for filtering)
+   * In single this is the main input, in multi this is the search input
+   * In both cases this corresponds to the input the user can type into to filter the options
+   */
+  onInputChange?: (value: string) => void;
+  /**
+   * Callback when dropdown open state changes
+   */
+  onOpenChange?: (isOpen: boolean) => void;
+  /**
+   * Custom empty state message when no options match filter
+   */
+  emptyStateMessage?: string;
+  /**
+   * Whether the combobox is disabled
+   */
+  disabled?: boolean;
+  /**
+   * ID of the label for the combobox input
+   */
+  labelId?: string;
+  /**
+   * Aria label for accessibility when no visible label is provided
+   */
+  'aria-label'?: string;
+  /**
+   * Placeholder text when no option is selected
+   */
+  placeholder?: string;
+  /**
+   * Whether the combobox has a warning state
+   */
+  hasWarning?: boolean;
+  /**
+   * Whether the combobox has an error state
+   */
+  hasError?: boolean;
+  /**
+   * ID for the combobox input
+   */
+  id?: string;
+  /**
+   * Whether to render the dropdown in a portal (breaks out of overflow containers)
+   */
+  portal?: boolean;
+  /**
+   * Reference to the container element for portal rendering.
+   * When provided, the dropdown will use this element's dimensions for positioning.
+   */
+  portalContainerRef?: React.RefObject<HTMLElement>;
+  /**
+   * Optional external trigger (e.g. an "Add" button or icon-only menu opener).
+   * When provided, the Combobox clones it with downshift's toggle props and
+   * renders it in place of the default input + caret; the search input moves
+   * inside the dropdown.
+   */
+  trigger?: React.ReactElement;
+  /**
+   * Render the searchable option list inline without a trigger or floating
+   * dropdown. Use when another component already owns the containing popover.
+   *
+   * When `true`, the in-panel search uses bordered `Input` chrome and the
+   * embedder owns all surrounding spacing; when `false`, the floating-dropdown
+   * borderless search strip is preserved.
+   */
+  embedded?: boolean;
+}
+declare const MAX_DROPDOWN_HEIGHT = "300px";
+declare const Container: _$styled_components0.StyledComponent<"div", any, {}, never>;
+declare const InputContainer: _$styled_components0.StyledComponent<"div", any, {}, never>;
+interface ComboboxInputProps {
+  $isOpen?: boolean;
+  hasError?: boolean;
+  hasWarning?: boolean;
+  $selectedItemStyle?: LabelStyle;
+}
+declare const ComboboxInput: _$styled_components0.StyledComponent<_$react.ForwardRefExoticComponent<InputProps & _$react.RefAttributes<HTMLInputElement>>, any, ComboboxInputProps, never>;
+declare const CaretButton: _$styled_components0.StyledComponent<_$react.ForwardRefExoticComponent<Omit<ButtonProps, "ref"> & _$react.RefAttributes<HTMLButtonElement>>, any, {
+  width: "icon";
+}, "width">;
+interface DropdownContainerProps {
+  $isOpen?: boolean;
+  $portal?: boolean;
+  $embedded?: boolean;
+  $top?: number;
+  $left?: number;
+  $width?: number;
+  /** Minimum dropdown width (decouples from a narrow trigger). */
+  $minWidth?: string;
+}
+declare const DropdownContainer: _$styled_components0.StyledComponent<_$react.ComponentType<any>, any, DropdownContainerProps, never>;
+declare const ScrollableMenuList: _$styled_components0.StyledComponent<"div", any, {
+  padding?: Spacing;
+}, never>;
+declare const SearchInputContainer: _$styled_components0.StyledComponent<"div", any, {
+  $embedded?: boolean;
+}, never>;
+declare const SearchInput: _$styled_components0.StyledComponent<_$react.ForwardRefExoticComponent<InputProps & _$react.RefAttributes<HTMLInputElement>>, any, {
+  $embedded?: boolean;
+}, never>;
+declare const EmptyState: _$styled_components0.StyledComponent<_$react.FC<_$react.PropsWithChildren<SpanProps>>, any, ParagraphProps, never>;
+declare const LoadingContainer: _$styled_components0.StyledComponent<"div", any, {}, never>;
+declare const OptionLabel: _$styled_components0.StyledComponent<"div", any, {
+  $labelStyle?: LabelStyle;
+}, never>;
+declare const Description: _$styled_components0.StyledComponent<"p", any, {}, never>;
+declare function useDropdownPosition(portalContainerRef: React.RefObject<HTMLElement>, isOpen: boolean, portal?: boolean): {
+  top: number;
+  left: number;
+  width: number;
+};
+interface DropdownPortalWrapperProps {
+  children: React.ReactNode;
+  portal?: boolean;
+}
+declare function DropdownPortalWrapper({
+  children,
+  portal
+}: DropdownPortalWrapperProps): _$react_jsx_runtime0.JSX.Element;
+//#endregion
+export { renderOptionsWithGroups as A, containsNestedGroup as C, getOptionsAtPath as D, getNavigableItemsAtLevel as E, useFilteredOptions as M, isNestedGroup as O, buildVirtualRows as S, flattenOptions as T, NavigableItem as _, ComboboxOptionGroup as a, SearchInput as b, Description as c, DropdownPortalWrapperProps as d, EmptyState as f, MAX_DROPDOWN_HEIGHT as g, LoadingContainer as h, ComboboxOption as i, useDropdownPosition as j, isOptionGroup as k, DropdownContainer as l, LeafOptionEntry as m, ComboboxBaseProps as n, ComboboxOptionsOrGroups as o, InputContainer as p, ComboboxInput as r, Container as s, CaretButton as t, DropdownPortalWrapper as u, OptionLabel as v, flattenLeafOptions as w, SearchInputContainer as x, ScrollableMenuList as y };
+//# sourceMappingURL=ComboboxBase-INya0Csa.d.mts.map

package/dist/ComboboxBase.d.cts

@@ -0,0 +1,2 @@
+import { A as renderOptionsWithGroups, C as containsNestedGroup, D as getOptionsAtPath, E as getNavigableItemsAtLevel, M as useFilteredOptions, O as isNestedGroup, S as buildVirtualRows, T as flattenOptions, _ as NavigableItem, a as ComboboxOptionGroup, b as SearchInput, c as Description, d as DropdownPortalWrapperProps, f as EmptyState, g as MAX_DROPDOWN_HEIGHT, h as LoadingContainer, i as ComboboxOption, j as useDropdownPosition, k as isOptionGroup, l as DropdownContainer, m as LeafOptionEntry, n as ComboboxBaseProps, o as ComboboxOptionsOrGroups, p as InputContainer, r as ComboboxInput, s as Container, t as CaretButton, u as DropdownPortalWrapper, v as OptionLabel, w as flattenLeafOptions, x as SearchInputContainer, y as ScrollableMenuList } from "./ComboboxBase-D2wypeXf.cjs";
+export { CaretButton, ComboboxBaseProps, ComboboxInput, ComboboxOption, ComboboxOptionGroup, ComboboxOptionsOrGroups, Container, Description, DropdownContainer, DropdownPortalWrapper, DropdownPortalWrapperProps, EmptyState, InputContainer, LeafOptionEntry, LoadingContainer, MAX_DROPDOWN_HEIGHT, NavigableItem, OptionLabel, ScrollableMenuList, SearchInput, SearchInputContainer, buildVirtualRows, containsNestedGroup, flattenLeafOptions, flattenOptions, getNavigableItemsAtLevel, getOptionsAtPath, isNestedGroup, isOptionGroup, renderOptionsWithGroups, useDropdownPosition, useFilteredOptions };

package/dist/ComboboxBase.d.mts

@@ -0,0 +1,2 @@
+import { A as renderOptionsWithGroups, C as containsNestedGroup, D as getOptionsAtPath, E as getNavigableItemsAtLevel, M as useFilteredOptions, O as isNestedGroup, S as buildVirtualRows, T as flattenOptions, _ as NavigableItem, a as ComboboxOptionGroup, b as SearchInput, c as Description, d as DropdownPortalWrapperProps, f as EmptyState, g as MAX_DROPDOWN_HEIGHT, h as LoadingContainer, i as ComboboxOption, j as useDropdownPosition, k as isOptionGroup, l as DropdownContainer, m as LeafOptionEntry, n as ComboboxBaseProps, o as ComboboxOptionsOrGroups, p as InputContainer, r as ComboboxInput, s as Container, t as CaretButton, u as DropdownPortalWrapper, v as OptionLabel, w as flattenLeafOptions, x as SearchInputContainer, y as ScrollableMenuList } from "./ComboboxBase-INya0Csa.mjs";
+export { CaretButton, ComboboxBaseProps, ComboboxInput, ComboboxOption, ComboboxOptionGroup, ComboboxOptionsOrGroups, Container, Description, DropdownContainer, DropdownPortalWrapper, DropdownPortalWrapperProps, EmptyState, InputContainer, LeafOptionEntry, LoadingContainer, MAX_DROPDOWN_HEIGHT, NavigableItem, OptionLabel, ScrollableMenuList, SearchInput, SearchInputContainer, buildVirtualRows, containsNestedGroup, flattenLeafOptions, flattenOptions, getNavigableItemsAtLevel, getOptionsAtPath, isNestedGroup, isOptionGroup, renderOptionsWithGroups, useDropdownPosition, useFilteredOptions };