@servicetitan/anvil2 2.5.1 → 2.6.1

package/dist/internal/components/Popover/Popover.d.ts

@@ -0,0 +1,267 @@
+import { ReactNode } from 'react';
+import { Placement } from '@floating-ui/react';
+import { PopoverTrigger } from './PopoverTrigger';
+import { DisableCloseOnEscapeOrClickProps } from '../../../types';
+import { OpenCloseTransitionStateEffects } from '../../../internal/hooks';
+/** ARIA role of the beta Popover popup. */
+export type PopoverRole = "dialog" | "listbox" | "tree" | "grid";
+/**
+ * Sub-options for `placement="auto"`. Constrains which sides `autoPlacement()`
+ * may choose from. Ignored when a specific placement is set.
+ */
+export type PopoverAutoPlacementConfig = {
+    /** Limits which sides autoPlacement() considers. Defaults to all sides. */
+    allowedPlacements?: Placement[];
+};
+/**
+ * Sub-options for a specific placement (e.g. `"bottom"`). Overrides the default
+ * opposite-side fallback sequence used by `flip()`. Ignored when `placement="auto"`.
+ */
+export type PopoverFlipPlacementConfig = {
+    /** Explicit fallback sequence for flip(). Overrides the default opposite-side fallback. */
+    fallbackPlacements?: Placement[];
+};
+type PopoverPropsBase = {
+    /** Content to render inside the popover tree. */
+    children?: ReactNode;
+    /** Controlled open state. */
+    open?: boolean;
+    /** Initial open state for uncontrolled mode. @default false */
+    defaultOpen?: boolean;
+    /** Fires when the popover closes for any non-hover reason. */
+    onClose?: () => void;
+    /** Fires when the user clicks outside the popover. Not fired when disableCloseOnClickOutside is set. */
+    onClickOutside?: (e: globalThis.MouseEvent) => void;
+    /** Whether to hide the arrow/caret indicator. @default false */
+    disableCaret?: boolean;
+    /** Whether to remove default padding from the content area. @default false */
+    noPadding?: boolean;
+    /** Whether the popover width should match the trigger element width. @default false */
+    matchReferenceWidth?: boolean;
+    /** Whether the popover should have a fixed width of 40dvw. @default false */
+    fixedWidth?: boolean;
+    /** Fills available viewport height between the trigger and viewport edge. @default false */
+    fillAvailableHeight?: boolean;
+    /** Maximum height of the popover content. */
+    maxHeight?: number | string;
+    /** Constrains the popover to available viewport height. @default false */
+    fitScreen?: boolean;
+    /** Minimum height of the popover content. @default "2.875rem" */
+    minHeight?: number | string;
+} & DisableCloseOnEscapeOrClickProps & OpenCloseTransitionStateEffects;
+/**
+ * Role-specific props for `role="dialog"` (default).
+ *
+ * Only dialog popovers use `FloatingFocusManager` — focus moves into the content
+ * on open. The `modal`, `openOnHover`, and `delay` props are only meaningful
+ * in this context.
+ */
+type DialogRoleProps = {
+    /**
+     * The ARIA role of the popup. Drives `aria-haspopup` on the trigger and
+     * `role` on the content via Floating UI's `useRole`.
+     *
+     * @default "dialog"
+     */
+    role?: "dialog";
+    /** Traps focus until closed (modal) or closes on Tab-out (non-modal). @default false */
+    modal?: boolean;
+    /**
+     * Whether the popover opens on hover instead of click. @default false
+     *
+     * @remarks
+     * Hover-triggered popovers should contain only readable text — no interactive
+     * elements (buttons, links, inputs). The content is intentionally removed from
+     * the tab order so Tab moves cleanly between page elements. Interactive content
+     * inside a hover-triggered popover is unreachable by keyboard users. Use a
+     * click-triggered popover (default) when the content includes interactive elements.
+     */
+    openOnHover?: boolean;
+    /** Delay in ms before opening on hover. @default 100 */
+    delay?: number;
+};
+/**
+ * Role-specific props for combobox popup roles (`listbox`, `tree`, `grid`).
+ *
+ * These roles follow the ARIA combobox pattern — focus stays on the trigger and
+ * the inner component (e.g. `Listbox`) owns the role and keyboard navigation.
+ * `FloatingFocusManager` is disabled. `modal`, `openOnHover`, and `delay` are
+ * not applicable and are excluded at the type level.
+ *
+ * @remarks
+ * Floating UI adds `role="combobox"` to the trigger element for these roles.
+ * The `combobox` ARIA role only accepts names from `aria-label` or
+ * `aria-labelledby` — visible text content is not used. Always provide an
+ * explicit `aria-label` on `Popover.Button` or your custom trigger.
+ *
+ * @example
+ * // ✅ Correct — explicit aria-label required for non-dialog roles
+ * <Popover role="listbox">
+ *   <Popover.Button aria-label="Select an option">Open</Popover.Button>
+ *   <Popover.Content>
+ *     <Listbox>...</Listbox>
+ *   </Popover.Content>
+ * </Popover>
+ */
+type NonDialogRoleProps = {
+    /** The ARIA role of the popup. */
+    role: Exclude<PopoverRole, "dialog">;
+    modal?: never;
+    openOnHover?: never;
+    delay?: never;
+};
+type WithAutoPlacement = {
+    /**
+     * Uses `autoPlacement()` — picks the side with the most space. Pass
+     * a specific placement (e.g. `"bottom"`) to express a preferred side
+     * with `flip()` fallback instead.
+     */
+    placement?: "auto";
+    /** Sub-options for `autoPlacement()`. */
+    placementConfig?: PopoverAutoPlacementConfig;
+};
+type WithSpecificPlacement = {
+    /**
+     * Preferred placement relative to the trigger. Floating UI's `flip()`
+     * middleware will adapt to the opposite side if there is not enough space.
+     * Pass `"auto"` to let Floating UI pick the best side automatically.
+     *
+     * @default "bottom"
+     */
+    placement: Placement;
+    /** Sub-options for `flip()`. */
+    placementConfig?: PopoverFlipPlacementConfig;
+};
+/**
+ * Props for the beta Popover component.
+ *
+ * Two independent discriminated unions are combined:
+ * - **Role**: `role="dialog"` (default) enables `FloatingFocusManager` and accepts `modal`,
+ *   `openOnHover`, and `delay`. Non-dialog roles (`listbox`, `tree`, `grid`) disable
+ *   focus management — the inner component owns focus and keyboard navigation.
+ * - **Placement**: `placement="auto"` uses `autoPlacement()` and accepts
+ *   `placementConfig.allowedPlacements`. Specific placements use `flip()` and accept
+ *   `placementConfig.fallbackPlacements`.
+ *
+ * @extends DisableCloseOnEscapeOrClickProps
+ * @extends OpenCloseTransitionStateEffects
+ */
+export type PopoverProps = (PopoverPropsBase & DialogRoleProps & WithAutoPlacement) | (PopoverPropsBase & DialogRoleProps & WithSpecificPlacement) | (PopoverPropsBase & NonDialogRoleProps & WithAutoPlacement) | (PopoverPropsBase & NonDialogRoleProps & WithSpecificPlacement);
+/**
+ * Beta Popover component for displaying floating content relative to a trigger element.
+ *
+ * Built on three layers:
+ * - HTML Popover API (`popover="manual"`) for top-layer rendering without z-index management
+ * - Floating UI (`@floating-ui/react`) for JavaScript-based positioning
+ * - Floating UI interaction hooks for correct ARIA attributes and keyboard behavior
+ *
+ * Features:
+ * - Correct ARIA linkage: `aria-controls`, `aria-haspopup` with role string, `aria-expanded`
+ * - `FloatingFocusManager` for both modal (focus trapped) and non-modal (Tab-out closes)
+ * - `safePolygon()` hover zone replaces CSS `::before` hover bridge
+ * - `role` prop drives both `aria-haspopup` on trigger and `role` on content
+ * - Controlled and uncontrolled modes via `open` / `defaultOpen`
+ * - Imperative handle exposing `openPopover` and `closePopover`
+ * - Animation lifecycle callbacks via `onOpenAnimationStart` etc.
+ *
+ * @example
+ * <Popover>
+ *   <Popover.Button>Open</Popover.Button>
+ *   <Popover.Content>
+ *     <p>Popover content</p>
+ *     <Popover.Close>Close</Popover.Close>
+ *   </Popover.Content>
+ * </Popover>
+ *
+ * @example
+ * <Popover modal>
+ *   <Popover.Trigger>
+ *     {(props) => <Button {...props}>Open form</Button>}
+ *   </Popover.Trigger>
+ *   <Popover.Content>
+ *     <TextField label="Name" />
+ *     <Popover.Close>Done</Popover.Close>
+ *   </Popover.Content>
+ * </Popover>
+ *
+ * @example
+ * <Popover openOnHover role="dialog">
+ *   <Popover.Button>Hover me</Popover.Button>
+ *   <Popover.Content>Hover content</Popover.Content>
+ * </Popover>
+ */
+export declare const Popover: import('react').ForwardRefExoticComponent<PopoverProps & import('react').RefAttributes<unknown>> & {
+    /**
+     * PopoverTrigger component for creating custom trigger elements.
+     *
+     * Features:
+     * - Render prop pattern for full control over the trigger element
+     * - ARIA attributes and event handlers injected via getReferenceProps
+     *
+     * @example
+     * <Popover.Trigger>
+     *   {(props) => (
+     *     <Button {...props}>
+     *       Click to open popover
+     *     </Button>
+     *   )}
+     * </Popover.Trigger>
+     */
+    Trigger: typeof PopoverTrigger;
+    /**
+     * PopoverContent component for the main popover content area.
+     *
+     * Features:
+     * - HTML Popover API top-layer rendering (popover="manual")
+     * - Floating UI positioning via refs.setFloating and floatingStyles
+     * - FloatingFocusManager for focus trapping (modal) or Tab-out closing (non-modal)
+     * - Arrow/caret indicator with position computed from middlewareData.arrow
+     * - Scroll position reset when the popover opens
+     * - Optional scrollerRef for external scroll access
+     *
+     * @example
+     * <Popover.Content>
+     *   <p>Popover content</p>
+     *   <Popover.Close>Close</Popover.Close>
+     * </Popover.Content>
+     */
+    Content: import('react').ForwardRefExoticComponent<Omit<Omit<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "popover"> & {
+        scrollerRef?: import('react').RefObject<HTMLDivElement>;
+        hideWhileClosed?: boolean;
+    } & import('react').RefAttributes<HTMLDivElement>>;
+    /**
+     * PopoverClose component for closing the popover.
+     *
+     * Features:
+     * - Supports all Button component props and styling
+     * - Closes the popover on click via closePopover
+     * - Automatic tracking ID generation for analytics
+     *
+     * @example
+     * <Popover.Close>Close</Popover.Close>
+     *
+     * @example
+     * <Popover.Close appearance="secondary" size="small">
+     *   Cancel
+     * </Popover.Close>
+     */
+    Close: import('react').ForwardRefExoticComponent<import('./PopoverClose').PopoverCloseProps & import('react').RefAttributes<HTMLButtonElement>>;
+    /**
+     * PopoverButton component for creating button-style triggers.
+     *
+     * Features:
+     * - Button styling and behavior with all Button props
+     * - ARIA attributes and event handlers injected via getReferenceProps
+     * - Automatic tracking ID generation for analytics
+     *
+     * @example
+     * <Popover.Button>Click to open</Popover.Button>
+     *
+     * @example
+     * <Popover.Button appearance="primary" size="large" icon={InfoIcon}>
+     *   Information
+     * </Popover.Button>
+     */
+    Button: import('react').ForwardRefExoticComponent<import('./PopoverButton').PopoverButtonProps & import('react').RefAttributes<HTMLButtonElement>>;
+};
+export {};

package/dist/internal/components/Popover/PopoverButton.d.ts

@@ -0,0 +1,24 @@
+import { ButtonProps } from '../../../components/Button';
+import { DataTrackingId } from '../../../types';
+/**
+ * Props for the PopoverButton component.
+ * @extends ButtonProps
+ */
+export type PopoverButtonProps = ButtonProps & DataTrackingId;
+/**
+ * PopoverButton component for creating button-style triggers.
+ *
+ * Features:
+ * - Button styling and behavior with all Button props
+ * - ARIA attributes and event handlers injected via getReferenceProps
+ * - Automatic tracking ID generation for analytics
+ *
+ * @example
+ * <Popover.Button>Click to open</Popover.Button>
+ *
+ * @example
+ * <Popover.Button appearance="primary" size="large" icon={InfoIcon}>
+ *   Information
+ * </Popover.Button>
+ */
+export declare const PopoverButton: import('react').ForwardRefExoticComponent<PopoverButtonProps & import('react').RefAttributes<HTMLButtonElement>>;

package/dist/internal/components/Popover/PopoverClose.d.ts

@@ -0,0 +1,24 @@
+import { ButtonProps } from '../../../components/Button';
+import { DataTrackingId } from '../../../types';
+/**
+ * Props for the PopoverClose component.
+ * @extends ButtonProps
+ */
+export type PopoverCloseProps = ButtonProps & DataTrackingId;
+/**
+ * PopoverClose component for closing the popover.
+ *
+ * Features:
+ * - Supports all Button component props and styling
+ * - Closes the popover on click via closePopover
+ * - Automatic tracking ID generation for analytics
+ *
+ * @example
+ * <Popover.Close>Close</Popover.Close>
+ *
+ * @example
+ * <Popover.Close appearance="secondary" size="small">
+ *   Cancel
+ * </Popover.Close>
+ */
+export declare const PopoverClose: import('react').ForwardRefExoticComponent<PopoverCloseProps & import('react').RefAttributes<HTMLButtonElement>>;

package/dist/internal/components/Popover/PopoverContent.d.ts

@@ -0,0 +1,34 @@
+import { ComponentPropsWithoutRef, HTMLAttributes, RefObject } from 'react';
+/**
+ * Props for the PopoverContent component.
+ * @extends ComponentPropsWithoutRef<"div">
+ */
+export type PopoverContentProps = Omit<ComponentPropsWithoutRef<"div">, "popover"> & {
+    /** Reference to the scrollable content area. */
+    scrollerRef?: RefObject<HTMLDivElement>;
+    /** Whether to unmount children from the DOM while the popover is closed. Useful for performance when the content is expensive to render. */
+    hideWhileClosed?: boolean;
+};
+/**
+ * PopoverContent component for the main popover content area.
+ *
+ * Features:
+ * - HTML Popover API top-layer rendering (popover="manual")
+ * - Floating UI positioning via refs.setFloating and floatingStyles
+ * - FloatingFocusManager for focus trapping (modal) or Tab-out closing (non-modal)
+ * - Arrow/caret indicator with position computed from middlewareData.arrow
+ * - Scroll position reset when the popover opens
+ * - Optional scrollerRef for external scroll access
+ *
+ * @example
+ * <Popover.Content>
+ *   <p>Popover content</p>
+ *   <Popover.Close>Close</Popover.Close>
+ * </Popover.Content>
+ */
+export declare const PopoverContent: import('react').ForwardRefExoticComponent<Omit<Omit<import('react').DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "popover"> & {
+    /** Reference to the scrollable content area. */
+    scrollerRef?: RefObject<HTMLDivElement>;
+    /** Whether to unmount children from the DOM while the popover is closed. Useful for performance when the content is expensive to render. */
+    hideWhileClosed?: boolean;
+} & import('react').RefAttributes<HTMLDivElement>>;

package/dist/internal/components/Popover/PopoverTrigger.d.ts

@@ -0,0 +1,46 @@
+import { AriaAttributes, ReactElement, MouseEvent, KeyboardEvent, FocusEvent } from 'react';
+/** Props passed to the PopoverTrigger render function. */
+type PopoverTriggerChildrenProps = {
+    ref: (node: Element | null) => void;
+    id: string;
+    "aria-controls"?: string;
+    "aria-haspopup"?: AriaAttributes["aria-haspopup"];
+    "aria-expanded"?: boolean;
+    "data-state": "open" | "closed";
+    onClick?: (e: MouseEvent) => void;
+    onKeyDown?: (e: KeyboardEvent) => void;
+    onMouseEnter?: (e: MouseEvent) => void;
+    onMouseLeave?: (e: MouseEvent) => void;
+    onFocus?: (e: FocusEvent) => void;
+    onBlur?: (e: FocusEvent) => void;
+};
+/**
+ * Props for the PopoverTrigger component.
+ */
+export type PopoverTriggerProps = {
+    /**
+     * Render function that receives trigger props and returns a React element.
+     */
+    children: (props: PopoverTriggerChildrenProps) => ReactElement;
+};
+/**
+ * PopoverTrigger component for creating custom trigger elements.
+ *
+ * Features:
+ * - Render prop pattern for full control over the trigger element
+ * - ARIA attributes and event handlers injected via getReferenceProps
+ *
+ * @example
+ * <Popover.Trigger>
+ *   {(props) => (
+ *     <Button {...props}>
+ *       Click to open popover
+ *     </Button>
+ *   )}
+ * </Popover.Trigger>
+ */
+export declare function PopoverTrigger(props: PopoverTriggerProps): ReactElement<any, string | import('react').JSXElementConstructor<any>>;
+export declare namespace PopoverTrigger {
+    var displayName: string;
+}
+export {};

package/dist/internal/components/Popover/index.d.ts

@@ -0,0 +1,6 @@
+export * from './Popover';
+export { type PopoverButtonProps } from './PopoverButton';
+export { type PopoverCloseProps } from './PopoverClose';
+export { type PopoverContentProps } from './PopoverContent';
+export { type PopoverTriggerProps } from './PopoverTrigger';
+export { Popover as default } from './Popover';

package/dist/internal/components/Popover/internal/PopoverContext.d.ts

@@ -0,0 +1,45 @@
+import { CSSProperties, RefObject, HTMLProps } from 'react';
+import { FloatingContext, MiddlewareData, Placement } from '@floating-ui/react';
+import { PopoverRole } from '../Popover';
+export type PopoverContextProps = {
+    /** Context object from useFloating; required by FloatingFocusManager and interaction hooks. */
+    floatingContext: FloatingContext;
+    /** Callback refs from useFloating; setReference for the trigger, setFloating for the content. */
+    refs: {
+        setReference: (node: Element | null) => void;
+        setFloating: (node: HTMLElement | null) => void;
+    };
+    /** Inline positioning styles from useFloating; applied to the content element. */
+    floatingStyles: CSSProperties;
+    /** Middleware output from useFloating; used for arrow positioning via middlewareData.arrow. */
+    middlewareData: MiddlewareData;
+    /** Merged prop getter for the trigger; spreads ARIA attributes and event handlers. */
+    getReferenceProps: (userProps?: HTMLProps<Element>) => Record<string, unknown>;
+    /** Merged prop getter for the content; spreads ARIA attributes and event handlers. */
+    getFloatingProps: (userProps?: HTMLProps<HTMLElement>) => Record<string, unknown>;
+    /** Auto-generated id for the trigger element; used as the default aria-labelledby on content. */
+    triggerId: string;
+    /** Current open/closed state. */
+    openState: boolean;
+    /** Opens the popover. */
+    openPopover: () => void;
+    /** Closes the popover. Fires onClose unless opened via hover. */
+    closePopover: () => void;
+    /** Whether the open state is externally controlled. */
+    controlled: boolean;
+    /** Resolved placement after flip/shift middleware; may differ from the placement prop. */
+    actualPlacement: Placement;
+    /** Ref attached to the arrow span element inside PopoverContent. */
+    arrowRef: RefObject<HTMLSpanElement>;
+    /** Whether the popover traps focus (modal) or closes on Tab-out (non-modal). Only applies when role is "dialog". */
+    modal?: boolean;
+    /** Whether the popover opens on hover/focus instead of click. Only applies when role is "dialog". */
+    openOnHover: boolean;
+    /** Whether to remove default padding from the content area. */
+    noPadding?: boolean;
+    /** Whether to hide the arrow/caret indicator. */
+    disableCaret?: boolean;
+    /** The ARIA role of the popup. Drives FloatingFocusManager and ARIA attribute behavior. */
+    role: PopoverRole;
+};
+export declare const PopoverContext: import('react').Context<PopoverContextProps | null>;

package/dist/internal/components/Popover/internal/usePopoverContext.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns the PopoverContext for use within Popover compound components.
+ * @returns The current PopoverContextProps value.
+ * @throws Error if called outside a Popover component.
+ */
+export declare function usePopoverContext(): import('./PopoverContext').PopoverContextProps;

package/dist/internal/components/SelectOption.d.ts

@@ -0,0 +1,13 @@
+import { SelectItem, GetItemPropsFn } from '../types/selectFieldInternalTypes';
+import { CheckState } from '../../types';
+export type SelectOptionProps = {
+    item: SelectItem;
+    index: number;
+    highlighted: boolean;
+    disabled: boolean;
+    getItemProps: GetItemPropsFn;
+    selectionType: "single" | "multiple";
+    checked: CheckState;
+    isListScrolled?: boolean;
+};
+export declare const SelectOption: ({ item, index, highlighted, disabled, getItemProps, selectionType, checked, isListScrolled, }: SelectOptionProps) => import("react/jsx-runtime").JSX.Element;

package/dist/internal/components/SelectOptions.d.ts

@@ -0,0 +1,23 @@
+import { SelectFieldOption } from '../../beta/components/SelectField/types';
+import { CSSProperties } from 'react';
+import { OptionsPanelHandle } from './OptionsPanel';
+import { GetItemPropsFn, GetMenuPropsFn, SectionMeta, SelectItem } from '../types/selectFieldInternalTypes';
+export type SelectOptionsProps = {
+    isOpen: boolean;
+    items: SelectItem[];
+    getMenuProps: GetMenuPropsFn;
+    getItemProps: GetItemPropsFn;
+    highlightedIndex: number;
+    selectedOption: SelectFieldOption | null;
+    hasMore: boolean;
+    onLoadMore: () => void;
+    loading: boolean;
+    loadingMore: boolean;
+    disableAutoLoadMore?: boolean;
+    disabled?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    sectionsMeta?: SectionMeta[];
+    virtualize?: boolean;
+};
+export declare const SelectOptions: import('react').ForwardRefExoticComponent<SelectOptionsProps & import('react').RefAttributes<OptionsPanelHandle>>;

package/dist/internal/components/VirtualizedOptionsPanel.d.ts

@@ -0,0 +1,2 @@
+import { OptionsPanelProps, OptionsPanelHandle } from './OptionsPanel';
+export declare const VirtualizedOptionsPanel: import('react').ForwardRefExoticComponent<OptionsPanelProps & import('react').RefAttributes<OptionsPanelHandle>>;

package/dist/internal/functions/buildSelectItems.d.ts

@@ -0,0 +1,22 @@
+import { SelectFieldOption } from '../../beta/components/SelectField/types';
+import { SectionMeta, SelectItem } from '../types/selectFieldInternalTypes';
+import { NormalizedPinnedSection } from '../hooks/usePinnedOptions';
+import { NormalizedGroupSection } from '../hooks/useGroupedOptions';
+export declare function toSelectItem(option: SelectFieldOption): SelectItem;
+type BuildSelectItemsParams = {
+    prefixItems?: SelectItem[];
+    pinnedSections: NormalizedPinnedSection[];
+    groupSections: NormalizedGroupSection[];
+    ungroupedItems: SelectItem[];
+};
+/**
+ * Assembles the flat items array and sectionsMeta.
+ * Order: prefixItems → pinned sections → group sections → ungrouped items.
+ * Multi-select hooks pass bulk action items (select-all / select-filtered) as prefixItems;
+ * single-select hooks omit it.
+ */
+export declare function buildSelectItems({ prefixItems, pinnedSections, groupSections, ungroupedItems, }: BuildSelectItemsParams): {
+    items: SelectItem[];
+    sectionsMeta: SectionMeta[];
+};
+export {};

package/dist/internal/functions/syncFilterUtils.d.ts

@@ -0,0 +1,10 @@
+import { MatchSorterOptions } from 'match-sorter';
+import { SelectFieldOption, SelectFieldGroupByValue } from '../../beta/components/SelectField/types';
+export type SyncFilterFn<T extends SelectFieldOption = SelectFieldOption> = (options: T[], searchValue: string) => T[];
+export declare const defaultSyncFilter: SyncFilterFn;
+export declare const toSyncFilterFn: <T extends SelectFieldOption = SelectFieldOption>(filter: SyncFilterFn<T> | MatchSorterOptions<T>) => SyncFilterFn<T>;
+/**
+ * Sorts options by group using the provided comparator while maintaining
+ * the original order within each group (stable sort).
+ */
+export declare const sortByGroup: <T extends SelectFieldOption = SelectFieldOption>(options: T[], groupSorter: (a: SelectFieldGroupByValue, b: SelectFieldGroupByValue) => number) => T[];

package/dist/{beta/components/SelectField/internal → internal/hooks}/useGroupedOptions.d.ts

@@ -1,4 +1,5 @@
-import { SelectFieldDownshiftItem, SelectFieldGroupByValue, SelectFieldOption } from '../types';
+import { SelectFieldGroupByValue, SelectFieldOption } from '../../beta/components/SelectField/types';
+import { SelectItem } from '../types/selectFieldInternalTypes';
 /**
  * Normalized group section structure used internally.
  * @property label - The group label (derived from groupToString or String(groupValue))
@@ -10,9 +11,9 @@ export type NormalizedGroupSection = {
 };
 type UseGroupedOptionsResult = {
     /** Options that have a group property, converted to downshift items */
-    groupedItems: SelectFieldDownshiftItem[];
+    groupedItems: SelectItem[];
     /** Options that don't have a group property, converted to downshift items */
-    ungroupedItems: SelectFieldDownshiftItem[];
+    ungroupedItems: SelectItem[];
     /** Metadata about each group section for rendering */
     groupSections: NormalizedGroupSection[];
 };

package/dist/{beta/components/SelectField/internal/useFieldListSections.d.ts → internal/hooks/useOptionsSections.d.ts}

@@ -1,7 +1,6 @@
-import { SelectFieldDownshiftItem } from '../types';
-import { SectionMeta } from './types';
+import { SectionMeta, SelectItem } from '../types/selectFieldInternalTypes';
 export type SectionItem = {
-    item: SelectFieldDownshiftItem;
+    item: SelectItem;
     index: number;
 };
 export type PinnedSection = {
@@ -22,8 +21,8 @@ export type FlatSection = {
 export type Section = PinnedSection | GroupSection | FlatSection;
 export type VirtualRow = {
     type: "item";
-    item: SelectFieldDownshiftItem;
-    downshiftIndex: number;
+    item: SelectItem;
+    index: number;
 } | {
     type: "header";
     label: string;
@@ -36,15 +35,15 @@ export type VirtualRow = {
 };
 /**
  * Computes grouped sections from a flat items array and section metadata.
- * @param items - The flat downshift items array
+ * @param items - The flat items array
  * @param sectionsMeta - Section metadata describing pinned/group ranges
  * @returns Grouped sections for rendering
  */
-export declare const useFieldListSections: (items: SelectFieldDownshiftItem[], sectionsMeta: SectionMeta[]) => Section[];
+export declare const useOptionsSections: (items: SelectItem[], sectionsMeta: SectionMeta[]) => Section[];
 /**
  * Flattens grouped sections into a linear list of virtual rows for virtualization,
  * and builds a mapping from downshift item index to virtual row index.
- * @param sections - The grouped sections from useFieldListSections
+ * @param sections - The grouped sections from useOptionsSections
  * @param hasMore - Whether there are more items to load
  * @returns The flat virtual row list and a downshift-to-virtual index mapping
  */

package/dist/{beta/components/SelectField/internal → internal/hooks}/usePinnedOptions.d.ts

@@ -1,4 +1,4 @@
-import { SelectFieldOption, SelectFieldPinnedOptions } from '../types';
+import { SelectFieldOption, SelectFieldPinnedOptions } from '../../beta/components/SelectField/types';
 /**
  * Normalized pinned section structure used internally.
  * @property label - Section label (e.g., "Recent", "Favorites")

package/dist/{beta/components/SelectField/internal → internal/hooks}/useProcessedOptions.d.ts

@@ -1,4 +1,4 @@
-import { SelectFieldGroupByValue, SelectFieldOption, SelectFieldPinnedOptions } from '../types';
+import { SelectFieldGroupByValue, SelectFieldOption, SelectFieldPinnedOptions } from '../../beta/components/SelectField/types';
 type UseProcessedOptionsParams = {
     options: SelectFieldOption[];
     pinned?: SelectFieldPinnedOptions;
@@ -13,7 +13,7 @@ type UseProcessedOptionsParams = {
  */
 export declare const useProcessedOptions: ({ options, pinned, searchValue, groupToString, groupSorter, }: UseProcessedOptionsParams) => {
     pinnedSections: import('./usePinnedOptions').NormalizedPinnedSection[];
-    ungroupedItems: import('..').SelectFieldDownshiftItem[];
+    ungroupedItems: import('../types/selectFieldInternalTypes').SelectItem[];
     groupSections: import('./useGroupedOptions').NormalizedGroupSection[];
 };
 export {};

package/dist/internal/hooks/useSelectOrchestration.d.ts

@@ -0,0 +1,38 @@
+import { ForwardedRef } from 'react';
+export type UseSelectOrchestrationConfig = {
+    lazy: false | "page" | "offset" | "group" | undefined;
+    loadOptions: any;
+    cache?: {
+        enabled?: boolean;
+        maxSize?: number;
+    };
+    lazyOptions?: {
+        pageSize?: number;
+        limit?: number;
+    };
+    initialLoad?: "auto" | "immediate" | "open";
+    displayMenuAs?: "auto" | "popover" | "dialog";
+    ref: ForwardedRef<{
+        clearCache: () => void;
+        invalidate: () => void;
+    }>;
+};
+/**
+ * Shared orchestration hook used by Select components
+ * Centralizes adaptive view resolution, loading config construction, option loading lifecycle,
+ * and imperative handle setup (clearCache/invalidate).
+ */
+export declare function useSelectOrchestration(config: UseSelectOrchestrationConfig): {
+    displayAs: "popover" | "dialog";
+    initialLoad: "open" | "immediate";
+    initialLoadPerformed: boolean;
+    setInitialLoadPerformed: import('react').Dispatch<import('react').SetStateAction<boolean>>;
+    options: import('../../beta').SelectFieldOption[];
+    loading: boolean;
+    loadingMore: boolean;
+    hasMore: boolean;
+    loadOptions: (searchValue: string, options?: {
+        initial?: boolean;
+    }) => Promise<void>;
+    loadMore: (searchValue: string) => Promise<void>;
+};