@servicetitan/anvil2 3.13.6 → 3.14.0

package/dist/src/internal/functions/getInitial.d.ts

@@ -1,16 +1,6 @@
 /**
- * Extracts initials from a full name string.
- *
- * Features:
- * - Handles single names (returns first two characters)
- * - Handles multiple names (returns first and last name initials)
- * - Automatically capitalizes all initials
- * - Filters out empty strings and whitespace
- * - Handles edge cases like empty names and single characters
- * - Preserves proper capitalization rules
- * - Returns undefined for empty or falsy input
- *
- * @param name - The full name string to extract initials from
- * @returns The initials as a string, or undefined if name is empty
+ * Initials from a space-split name. Multiple words: first and last, both
+ * uppercased. One word: first two characters as title case, or a single
+ * uppercased character. Empty / falsy input is `undefined`.
  */
 export declare function getInitial(name: string): string | undefined;

package/dist/src/internal/functions/getKeyboardFocusableElements.d.ts

@@ -1,36 +1,12 @@
 /**
- * CSS selector matching elements that natively participate in keyboard focus.
- * Use with `querySelectorAll` to enumerate focusables, or with `Element.closest`
- * to test whether a given target is inside one.
- *
- * `[contenteditable]:not([contenteditable="false"])` covers every editable
- * value the attribute accepts — `""` (bare), `"true"`, `"plaintext-only"`,
- * `"inherit"` — and excludes the explicit opt-out `"false"`. All editable
- * variants have an implicit tabindex of 0.
+ * CSS selector for natively keyboard-focusable descendants.
+ * `[contenteditable]:not([contenteditable="false"])` includes `""`, `"true"`,
+ * `"plaintext-only"`, and `"inherit"` — those have implicit tabindex 0.
  */
 export declare const KEYBOARD_FOCUSABLE_SELECTOR = "a[href], button, input, textarea, select, details, [contenteditable]:not([contenteditable=\"false\"]), [tabindex]:not([tabindex=\"-1\"])";
 /**
- * Retrieves all keyboard focusable elements within a given container element.
- *
- * Features:
- * - Finds all elements that can receive keyboard focus
- * - Filters out disabled, hidden, and inert elements
- * - Respects ARIA attributes for accessibility
- * - Checks computed styles for visibility
- * - Supports all standard focusable elements (links, buttons, inputs, etc.)
- * - Handles null and undefined input gracefully
- * - Returns array of focusable HTMLElements
- * - Excludes elements with tabindex="-1"
- *
- * Focusable Elements Detected:
- * - Links with href attributes
- * - Buttons (all types)
- * - Form inputs (text, checkbox, radio, etc.)
- * - Textareas and select elements
- * - Details elements
- * - Elements with positive tabindex values
- *
- * @param element - The container element to search for focusable elements
- * @returns Array of focusable HTMLElements, or empty array if no element provided
+ * Keyboard-focusable descendants of `element`. Drops `disabled`,
+ * `display: none`, and elements whose `aria-hidden` or `inert` attribute is
+ * a non-empty string. Missing `element` is `[]`.
  */
 export declare function getKeyboardFocusableElements(element?: HTMLElement | null): Element[];

package/dist/src/internal/functions/inlineMarkdown.d.ts

@@ -1,20 +1,7 @@
 import { ReactNode } from 'react';
 /**
- * Parses a limited set of inline markdown constructs in a string and returns React nodes.
- * `lastIndex` is reset at the start of each call and saved/restored around recursive calls
- * so a single shared regex instance is safe for nested parsing.
- *
- * Supported constructs (matched in order):
- * - `***text***` → `<strong><em>text</em></strong>`
- * - `**text**` → `<strong>text</strong>`
- * - `*text*` → `<em>text</em>`
- * - `==text==` → `<mark>`
- * - `` `text` `` → `<code>` (no nested markdown inside code)
- *
- * For plain-text stripping (e.g. aria-label), use `stripInlineMarkdown` from
- * `./stripInlineMarkdown` — it has no style dependencies.
- *
- * @param text - The string to parse
- * @returns Array of React nodes representing the parsed content
+ * Turns limited inline markdown into React nodes (`***` / `**` / `*` / `==` / `` ` ``).
+ * The shared global regex needs `lastIndex` reset per call and saved around
+ * nested parses. Code spans are not reparsed.
  */
 export declare const parseInlineMarkdown: (text: string) => ReactNode[];

package/dist/src/internal/functions/isThenable.d.ts

@@ -1,4 +1,4 @@
 /**
- * Returns true when `value` looks like a thenable (Promise or Promise-like).
+ * Detects objects with a callable `then` member.
  */
 export declare function isThenable<T>(value: unknown): value is PromiseLike<T>;

package/dist/src/internal/functions/kebabize.d.ts

@@ -1,16 +1,6 @@
 /**
- * Converts a camelCase or PascalCase string to kebab-case format.
- *
- * Features:
- * - Handles camelCase to kebab-case conversion
- * - Handles PascalCase to kebab-case conversion
- * - Preserves consecutive numbers without separators
- * - Adds hyphens before uppercase letters and numbers
- * - Maintains lowercase letters as-is
- * - Handles edge cases like single characters and empty strings
- * - Preserves existing hyphens in the input string
- *
- * @param str - The string to convert to kebab-case
- * @returns The kebab-case version of the input string
+ * Inserts hyphens before uppercase letters and digits (except consecutive
+ * digits and the first character), then lowercases. Adjacent capitals each
+ * get a hyphen (`HTTP` → `h-t-t-p`).
  */
 export declare function kebabize(str: string): string;

package/dist/src/internal/functions/mapOrder.d.ts

@@ -1 +1,5 @@
+/**
+ * Sorts a copy of `array` by each item's `key` against `order`. Keys missing
+ * from `order` sort first (`indexOf` is `-1`).
+ */
 export declare function mapOrder(array: any[], order: any[], key: string): any[];

package/dist/src/internal/functions/popoverTargetDomProps.d.ts

@@ -1,4 +1,4 @@
-/** React 18 warns on `popoverTarget`; React 19 warns on `popovertarget`. */
+/** React 18 warns on `popoverTarget`; React 19 warns on `popovertarget`. Missing `id` is `{}`. */
 export declare function popoverTargetDomProps(id: string | undefined, version?: string): {
     [x: string]: string;
 };

package/dist/src/internal/functions/portalScopeClassNames.d.ts

@@ -2,19 +2,12 @@ import { CSSProperties } from 'react';
 /**
  * Class names that re-establish the Anvil2 styling scope on a container.
  *
- * Native `popover` / top-layer elements (toasts, popovers, tooltips, surfaces)
- * are promoted to the top layer and live high in the DOM, escaping any ancestor
- * `AnvilProvider`'s `.anvil2` scope. Without the scope, descendants resolve none
- * of the `--a2-*` design tokens (defined on `.anvil2.theme-core`) and miss the
- * scoped component rules, so they render unstyled.
+ * Native `popover` / top-layer elements are promoted out of ancestor
+ * `AnvilProvider` `.anvil2` scope. Without the scope, descendants miss
+ * `--a2-*` tokens and scoped component rules.
  *
- * Spread/append these class names onto such containers so they self-scope and
- * render correctly in any host context (including outside an `AnvilProvider`,
- * e.g. when an Anvil2 component is used from a legacy host).
- *
- * Pair with `usePortalScopeStyle` so custom `ThemeProvider` tokens (e.g. Carto
- * Inter) are re-applied on top of `.theme-core`, which otherwise resets those
- * variables to core defaults (Nunito Sans).
+ * Pair with `usePortalScopeStyle` so custom `ThemeProvider` tokens are
+ * re-applied; `.theme-core` otherwise resets them to core defaults.
  */
 export declare const portalScopeClassNames: string;
 /**
@@ -22,7 +15,7 @@ export declare const portalScopeClassNames: string;
  *
  * `.theme-core` on the same node redefines `--a2-*` to core defaults, which
  * wins over inherited `ThemeProvider` variables. Re-applying `themeStyle`
- * after that reset keeps Carto (and other custom themes) intact.
+ * after that reset keeps custom themes intact.
  *
  * Pass the element's own styles so positioning / UA resets still win.
  */

package/dist/src/internal/functions/safePopover.d.ts

@@ -1,2 +1,4 @@
+/** Calls `showPopover()`; any throw is `console.warn`ed and swallowed. */
 export declare const safeShowPopover: (element?: HTMLElement) => void;
+/** Calls `hidePopover()`; any throw is `console.warn`ed and swallowed. */
 export declare const safeHidePopover: (element?: HTMLElement) => void;

package/dist/src/internal/functions/sizeToToken.d.ts

@@ -1,2 +1,3 @@
 import { GapSize } from '../../types';
+/** Maps a {@link GapSize} to `core.primitive.Size*` `.value`. `"half"` is title-cased. */
 export declare const sizeToToken: (value?: GapSize) => string | undefined;

package/dist/src/internal/functions/stripInlineMarkdown.d.ts

@@ -1,8 +1,6 @@
 /**
- * Strips inline markdown syntax from a string, returning plain text.
- * Intended for accessibility contexts (e.g. `aria-label`) where only plain text is appropriate.
- *
- * @param str - The string to strip
- * @returns The string with all inline markdown syntax removed
+ * Drops inline markdown markers and returns the inner text (for `aria-label`).
+ * Shared global regex: reset `lastIndex` per call and save it around nested
+ * strips. Code spans are not reparsed.
  */
 export declare const stripInlineMarkdown: (str: string) => string;

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

@@ -1,10 +1,12 @@
 import { MatchSorterOptions } from 'match-sorter';
 import { SelectFieldOption, SelectFieldGroupByValue } from '../../components/SelectField/types';
 export type SyncFilterFn<TID extends string | number = string | number, T extends SelectFieldOption<TID> = SelectFieldOption<TID>> = (options: T[], searchValue: string) => T[];
+/** Filters by label and search text, preserving input order for equal matches. */
 export declare const defaultSyncFilter: <TID extends string | number, T extends SelectFieldOption<TID> = SelectFieldOption<TID>>(options: T[], searchValue: string) => T[];
+/** Normalizes a filter function or match-sorter options into a sync filter. */
 export declare const toSyncFilterFn: <TID extends string | number, T extends SelectFieldOption<TID> = SelectFieldOption<TID>>(filter: SyncFilterFn<TID, T> | MatchSorterOptions<T>) => SyncFilterFn<TID, T>;
 /**
- * Sorts options by group using the provided comparator while maintaining
- * the original order within each group (stable sort).
+ * Orders groups with the comparator, keeps options stable within each group,
+ * and places ungrouped options last.
  */
 export declare const sortByGroup: <TID extends string | number, T extends SelectFieldOption<TID> = SelectFieldOption<TID>>(options: T[], groupSorter: (a: SelectFieldGroupByValue, b: SelectFieldGroupByValue) => number) => T[];

package/dist/src/internal/functions/warnOnce.d.ts

@@ -1,5 +1,4 @@
 /**
- * Logs a console.warn in development only, and only once per unique message.
- * Tree-shaken in production builds via the `process.env.NODE_ENV` guard.
+ * `console.warn` in development, once per unique message. No-op in production.
  */
 export declare function warnOnce(message: string): void;

package/dist/src/internal/hooks/useBulkActionRunner.d.ts

@@ -1,41 +1,18 @@
 type BulkComputeResult<T> = T[] | Promise<T[]>;
 export type UseBulkActionRunnerOptions<T> = {
-    /** Sets the draft (or commits when confirmation is off). */
     setDraft: (next: T[]) => void;
 };
 export type UseBulkActionRunnerResult<T> = {
-    /**
-     * True while a bulk-action promise is in flight. While true, callers should
-     * disable option rows, override the bulk row's checkState to "loading", and
-     * disable Apply.
-     */
     pending: boolean;
-    /**
-     * Run a bulk action. If `compute` returns an array synchronously, the draft
-     * is updated immediately. If it returns a promise, the runner enters the
-     * pending state until resolve/reject. Stale resolutions (those that finish
-     * after another draft mutation or another bulk run, or after `reset()`) are
-     * silently discarded.
-     */
     runBulk: (compute: (current: T[]) => BulkComputeResult<T>, current: T[]) => void;
-    /**
-     * Wrap an external draft mutation so that any in-flight bulk promise's
-     * eventual resolution is discarded. Use this in place of the raw setDraft
-     * whenever the user mutates the draft outside of a bulk action (option
-     * click, etc.) so that a slow Select-All-fetching promise can't clobber a
-     * subsequent click.
-     */
     setDraftAndBump: (next: T[]) => void;
-    /**
-     * Discard any in-flight bulk resolution. Call when the menu closes so that
-     * a promise resolving after close can't apply to the next menu instance.
-     */
     reset: () => void;
 };
 /**
- * Runs Select-All / Select-Filtered-style "bulk action" computations against
- * the controlled or draft selection, with support for both synchronous and
- * asynchronous results, and stale-result discard via a monotonic generation.
+ * Applies Select-All / Select-Filtered computes through `setDraft`, discarding
+ * stale async results with a generation counter. Synchronous arrays apply
+ * immediately. `setDraftAndBump` and `reset` also advance the generation;
+ * `reset` clears `pending` but does not revert the last `setDraft`.
  */
 export declare function useBulkActionRunner<T>({ setDraft, }: UseBulkActionRunnerOptions<T>): UseBulkActionRunnerResult<T>;
 export {};

package/dist/src/internal/hooks/useCommitSelectionIfChanged.d.ts

@@ -1,19 +1,12 @@
 /**
- * Returns a stable commit function that invokes `onChange` only when `next`
- * is a different set of `id`s than the latest `selected` value.
+ * Invokes `onChange` only when `next` is a different id set than the latest
+ * `selected` value (not the closed-over one).
  *
- * Downshift can re-invoke a click handler captured on an earlier render.
- * That stale handler still sees the pre-click selection, so it reports an
- * add of ids the parent already holds. Consumers that write a new array from
- * that callback (MobX `observer`, `setState(next.map(...))`) re-render, and
- * the stale handler fires again.
- *
- * Comparing against the latest selection — not the closed-over one — breaks
- * that loop without treating the stale add as a toggle/deselect.
- *
- * @param selected The current selected options
- * @param onChange Called when the id set actually changes
- * @returns A stable function that commits `next` only when ids differ
+ * Downshift can re-invoke a click handler from an earlier render. That handler
+ * still sees the pre-click selection, so it reports an add of ids the parent
+ * already holds. Consumers that write a new array from that callback re-render,
+ * and the stale handler fires again. Comparing against the latest selection
+ * breaks that loop without treating the stale add as a deselect.
  */
 export declare function useCommitSelectionIfChanged<T extends {
     id: string | number;

package/dist/src/internal/hooks/useConfirmationDraft.d.ts

@@ -13,9 +13,9 @@ export type UseConfirmationDraftResult<T> = {
     isDirty: boolean;
 };
 /**
- * Holds a draft copy of a controlled value while a menu is open, so that
- * selections can be confirmed (`apply`) or discarded (`cancel`). When
- * `enabled` is false, `setDraft` passes through directly to `onCommit` and
- * `displayValue` always reflects the controlled `value`.
+ * Holds a draft of a controlled value while confirmation is on. `setDraft`
+ * commits immediately when `enabled` is false. Opening, or a `value` change
+ * while open, copies `value` into the draft. Closing does not reset it —
+ * `cancel` does.
  */
 export declare function useConfirmationDraft<T>({ value, onCommit, isOpen, enabled, isEqual, }: UseConfirmationDraftOptions<T>): UseConfirmationDraftResult<T>;

package/dist/src/internal/hooks/useContainerQuery/useContainerQuery.d.ts

@@ -1,45 +1,14 @@
 import { RefObject } from 'react';
-/**
- * Return type for the useContainerQuery hook
- */
 export type ContainerQueryReturnProps = {
-    /**
-     * The breakpoint name
-     */
     name: "xs" | "sm" | "md" | "lg" | "xl" | "xxl";
-    /**
-     * Minimum width for this breakpoint
-     */
     min: number | undefined;
-    /**
-     * Maximum width for this breakpoint
-     */
     max: number | undefined;
-    /**
-     * Current container width
-     */
     containerWidth: number;
-    /**
-     * Current container height
-     */
     containerHeight: number;
 };
 /**
- * Custom hook for detecting current breakpoint based on container dimensions.
- *
- * Features:
- * - Detects current breakpoint based on container width instead of viewport width
- * - Supports all standard breakpoints (xs, sm, md, lg, xl, xxl)
- * - Provides container dimensions information
- * - Uses hammer-token breakpoint values for consistency
- * - Listens for container resize events using ResizeObserver
- * - Supports optional disable functionality
- * - Uses container element dimensions for accurate measurements
- *
- * @param containerRef - React ref to the container element to observe
- * @param props - Optional configuration object
- * @param props.disable - Whether to disable the hook
- * @returns Current breakpoint information or undefined if disabled
+ * Observes a container and returns its active Anvil2 breakpoint and dimensions.
+ * Returns `undefined` while disabled or before measurement.
  */
 export declare const useContainerQuery: (containerRef: RefObject<HTMLElement>, props?: {
     disable?: boolean;

package/dist/src/internal/hooks/useDebouncedCallback/useDebouncedCallback.d.ts

@@ -1,28 +1,6 @@
 /**
- * Custom hook for creating a debounced version of a callback function.
- *
- * Features:
- * - Delays callback execution until after a specified delay period
- * - Cancels previous pending calls when a new one is made
- * - Maintains stable function reference (only changes when delay changes)
- * - Always uses the latest callback via ref (avoids stale closures)
- * - Properly cleans up timeouts on unmount and delay changes
- * - Supports async callbacks
- * - Type-safe with generics
- *
- * @param callback - The function to debounce
- * @param delay - Delay in milliseconds before executing the callback
- * @returns Debounced version of the callback with the same signature
- *
- * @example
- * const debouncedSearch = useDebouncedCallback(
- *   (searchTerm: string) => {
- *     performSearch(searchTerm);
- *   },
- *   300
- * );
- *
- * // Later in event handler:
- * debouncedSearch(inputValue);
+ * Returns a debounced function with a stable identity that always calls the
+ * latest `callback`. Pending calls cancel on a new invoke, delay change, or
+ * unmount. Defaults to 300ms.
  */
 export declare function useDebouncedCallback<T extends (...args: any[]) => any>(callback: T, delay?: number): T;

package/dist/src/internal/hooks/useDialogScrollLock/useDialogScrollLock.d.ts

@@ -1,40 +1,15 @@
-/**
- * Props for the useDialogScrollLock hook
- * @property {boolean} open - Whether the dialog is open
- * @property {string} id - Unique identifier for the dialog
- * @property {boolean} [enableScrollChaining] - Whether to enable scroll chaining
- * @property {React.RefObject<HTMLElement>} elementRef - Reference to the dialog element
- */
 export interface UseDialogScrollLockProps {
-    /**
-     * Whether the dialog is open
-     */
+    /** When true, this id counts as open on the host. */
     open: boolean;
-    /**
-     * Unique identifier for the dialog
-     */
+    /** Distinguishes this dialog from others on the same shadow host. */
     id: string;
-    /**
-     * Whether to enable scroll chaining
-     */
+    /** Skips host scroll locking when enabled. */
     enableScrollChaining?: boolean;
-    /**
-     * Reference to the dialog element
-     */
+    /** Element used to locate the enclosing shadow root. */
     elementRef: React.RefObject<HTMLElement>;
 }
 /**
- * Custom hook for managing dialog scroll lock in shadow DOM environments.
- *
- * Features:
- * - Manages scroll lock state for dialogs in shadow DOM
- * - Tracks multiple open dialogs with unique IDs
- * - Prevents scroll chaining when dialogs are open
- * - Automatically cleans up scroll lock on unmount
- * - Supports enabling/disabling scroll chaining
- * - Uses data attributes to track dialog state
- *
- * @param props - Configuration object containing dialog state and element reference
- * @returns void
+ * Records open dialog ids on a shared shadow host so page-scroll CSS remains
+ * active until the last dialog closes. No-op outside a shadow root.
  */
 export declare const useDialogScrollLock: ({ open, id, enableScrollChaining, elementRef, }: UseDialogScrollLockProps) => void;

package/dist/src/internal/hooks/useDialogTransitionStates/useDialogTransitionStates.d.ts

@@ -1,32 +1,7 @@
 import { RefObject } from 'react';
 import { OpenCloseTransitionStateEffects } from '../useOpenCloseTransitionStates';
 /**
- * Effects configuration for dialog transition states
- * @property {() => void} [onOpenAnimationStart] - Callback when opening animation starts
- * @property {() => void} [onCloseAnimationStart] - Callback when closing animation starts
- * @property {() => void} [onOpenAnimationComplete] - Callback when opening animation completes
- * @property {() => void} [onCloseAnimationComplete] - Callback when closing animation completes
- */
-/**
- * Custom hook for managing dialog transition states and animations.
- *
- * Features:
- * - Manages dialog open/close transition states
- * - Handles animation timing based on CSS animation duration
- * - Provides callbacks for animation lifecycle events
- * - Supports controlled dialog state management
- * - Automatically handles showModal() and close() calls
- * - Provides utility flags for open/closed states
- *
- * @param ref - The ref to the dialog element
- * @param openProp - The open prop controlling dialog visibility
- * @param options - Additional, optional options including callbacks for animation start, complete, and initialization
- * @returns Object containing dialog state, control functions, and utility flags
- */
-/**
- * Effects configuration for dialog transition states
- * @param openProp - The open prop controlling dialog visibility
- * @param options - The effects configuration
- * @returns The dialog transition state
+ * Coordinates a dialog's modal lifecycle with its CSS opening and closing
+ * animations.
  */
 export declare const useDialogTransitionStates: (ref: RefObject<HTMLDialogElement>, openProp: boolean | undefined, options?: OpenCloseTransitionStateEffects) => import('..').OpenCloseTransitionState;

package/dist/src/internal/hooks/useDownshiftEnvironment/useDownshiftEnvironment.d.ts

@@ -1,10 +1,10 @@
-/**
- * Return type for the useDownshiftEnvironment hook
- * @property {React.RefObject<HTMLDivElement>} ref - Ref to attach to the wrapper element
- * @property {object | undefined} environment - Environment configuration for downshift
- */
 export interface UseDownshiftEnvironmentReturn {
+    /** Attach to the wrapper so `getRootNode()` can see a shadow host. */
     ref: React.RefObject<HTMLDivElement>;
+    /**
+     * Set when the wrapper's `getRootNode()` is a shadow root; otherwise
+     * Downshift uses its `document` default.
+     */
     environment: {
         document: Document;
         addEventListener: typeof document.addEventListener;
@@ -13,24 +13,8 @@ export interface UseDownshiftEnvironmentReturn {
     } | undefined;
 }
 /**
- * Hook to handle downshift environment configuration for shadow DOM support
- *
- * Features:
- * - Fixes shadow DOM compatibility issues with downshift
- * - Provides proper document and event listener references
- * - Returns ref for wrapper element and environment configuration
- *
- * @returns Object containing ref and environment configuration
- *
- * @example
- * const { ref, environment } = useDownshiftEnvironment();
- *
- * return (
- *   <div ref={ref}>
- *     <Combobox environment={environment}>
- *       combobox content
- *     </Combobox>
- *   </div>
- * );
+ * Supplies Downshift's `environment` so listboxes inside shadow DOM still
+ * receive document-level events. First render is always `environment:
+ * undefined` because the wrapper ref is empty.
  */
 export declare const useDownshiftEnvironment: () => UseDownshiftEnvironmentReturn;

package/dist/src/internal/hooks/useFocusWithin/useFocusWithin.d.ts

@@ -11,19 +11,8 @@ export interface UseFocusWithinReturnValue<T extends HTMLElement = HTMLElement>
     };
 }
 /**
- * Custom hook for tracking focus state within a DOM element.
- *
- * @param options Configuration options for the hook
- * @param options.onFocus Optional callback when focus enters the element
- * @param options.onBlur Optional callback when focus leaves the element
- * @returns Object containing props for the element
- *
- * @example
- * const { props } = useFocusWithin({
- *   onFocus: () => console.log('Focus entered'),
- *   onBlur: () => console.log('Focus left')
- * });
- *
- * return <div {...props}>Content</div>;
+ * Returns `onFocus`/`onBlur` props that fire when focus enters or leaves the
+ * host, not when it moves among descendants. `otherRelatedElements` are also
+ * treated as inside for leave detection.
  */
 export declare function useFocusWithin<T extends HTMLElement>({ onBlur, onFocus, otherRelatedElements, }?: UseFocusWithinOptions): UseFocusWithinReturnValue<T>;

package/dist/src/internal/hooks/useGroupedOptions.d.ts

@@ -1,40 +1,22 @@
 import { SelectFieldGroupByValue, SelectFieldOption } from '../../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))
- * @property options - The options belonging to this group
- */
+/** A group label and its options, normalized for section rendering. */
 export type NormalizedGroupSection<TID extends string | number> = {
     label: string;
     options: SelectFieldOption<TID>[];
 };
 type UseGroupedOptionsResult<TID extends string | number> = {
-    /** Options that have a group property, converted to downshift items */
     groupedItems: SelectItem<TID>[];
-    /** Options that don't have a group property, converted to downshift items */
     ungroupedItems: SelectItem<TID>[];
-    /** Metadata about each group section for rendering */
     groupSections: NormalizedGroupSection<TID>[];
 };
 /**
- * Hook that processes options and groups them by their `group` property.
- *
- * Groups are ordered by insertion order (first occurrence of a group value
- * defines its position in the list).
- *
- * @param options - The options to process
- * @param groupToString - Optional function to convert group values to display labels
- * @returns Grouped items, ungrouped items, and group section metadata
+ * Partitions options into Downshift items and group sections, preserving
+ * first-seen group order.
  */
 export declare function useGroupedOptions<TID extends string | number>(options: SelectFieldOption<TID>[], groupToString?: (groupValue: SelectFieldGroupByValue) => string): UseGroupedOptionsResult<TID>;
 /**
- * Sorts group sections using the provided comparator function.
- * The group value is extracted from the first option in each section.
- *
- * @param sections - The group sections to sort
- * @param groupSorter - Comparator function for group values
- * @returns A new array of sorted sections
+ * Returns group sections sorted by each section's first option group value.
  */
 export declare function sortGroupSections<TID extends string | number>(sections: NormalizedGroupSection<TID>[], groupSorter: (a: SelectFieldGroupByValue, b: SelectFieldGroupByValue) => number): NormalizedGroupSection<TID>[];
 export {};