@servicetitan/anvil2 3.14.0 → 3.15.0

package/dist/src/components/SelectField/types.d.ts

@@ -2,344 +2,268 @@ import { AriaAttributes, CSSProperties, ReactElement, ReactNode } from 'react';
 import { AiMarkWithTooltipOrPopoverProps, DataAttributes, LayoutUtilProps, Size } from '../../types';
 import { OptionContent } from '../../internal/types/optionContent';
 import { AddNewItemProps } from '../../internal/types/addNewItemTypes';
-/**
- * Configuration options for the SelectField cache.
- * @property enabled - Whether caching is enabled. Defaults to true.
- * @property maxSize - Maximum number of cached entries before clearing the cache. Defaults to 15.
- */
+/** Per-search cache for `loadOptions` results. */
 export type SelectFieldCacheOptions = {
+    /** Stays on unless `false`. Defaults to `true`. */
     enabled?: boolean;
+    /** Distinct search keys kept. Exceeding this wipes the map. Defaults to `15`. */
     maxSize?: number;
 };
-/**
- * Imperative handle for the SelectField component.
- * @property clearCache - Clears the options cache.
- * @property invalidate - Clears the cache and triggers a fresh options load from the data source.
- */
+/** Imperative cache control for a mounted {@link SelectField}. */
 export type SelectFieldHandle = {
+    /** Drops cached `loadOptions` results without fetching. */
     clearCache: () => void;
+    /** Drops the cache and fetches options again. */
     invalidate: () => void;
 };
 export type SelectFieldGroupByValue = string | number;
-/**
- * Rich content configuration for a SelectField option row.
- * Controls the avatar, icon, description, and chip display within an option.
- */
+/** Alias of {@link OptionContent}. */
 export type SelectFieldOptionContent = OptionContent;
 export type SelectFieldOption<TID extends number | string = string | number> = {
+    /** Selection key. */
     id: TID;
+    /** Trigger text and default search/display string. */
     label: string;
+    /** Extra searchable text. Not shown in the row. */
     searchText?: string;
+    /** Section key. Omit for an ungrouped option. */
     group?: SelectFieldGroupByValue;
     /**
-     * When true, the option cannot be selected from the menu. If the option is
-     * already in the field `value`, MultiSelectField also treats it as locked:
-     * the chip has no close control, and clear / backspace skip it.
+     * Cannot be chosen from the menu. If it is already in a MultiSelectField
+     * `value`, the chip has no close control and clear/backspace skip it.
      */
     disabled?: boolean;
+    /** Consumer bag. Unused by the field. */
     extra?: Record<string, unknown>;
+    /** Avatar, icon, description, and chips on the option row. */
     content?: SelectFieldOptionContent;
 };
+/** Option that must have `group`. */
 export type SelectFieldGroupedOption<TID extends number | string = string | number> = SelectFieldOption<TID> & {
     group: SelectFieldGroupByValue;
 };
+/** Option that must not have `group`. */
 export type SelectFieldUngroupedOption<TID extends number | string = string | number> = Omit<SelectFieldOption<TID>, "group"> & {
     group?: never;
 };
+/** Sync or async option list. */
 export type SelectFieldOptionsResult<TID extends number | string = string | number> = SelectFieldOption<TID>[] | Promise<SelectFieldOption<TID>[]>;
 export type SelectFieldEagerLoader<TID extends number | string = string | number> = (searchValue: string) => SelectFieldOptionsResult<TID>;
 export type SelectFieldOffsetLazyResult<TID extends number | string = string | number> = {
     options: SelectFieldUngroupedOption<TID>[];
+    /** When true, scrolling to the end loads another batch. */
     hasMore?: boolean;
 };
 export type SelectFieldOffsetLazyLoader<TID extends number | string = string | number> = (searchValue: string, offset: number, limit: number) => SelectFieldOffsetLazyResult<TID> | Promise<SelectFieldOffsetLazyResult<TID>>;
 export type SelectFieldPageLazyResult<TID extends number | string = string | number> = {
     options: SelectFieldUngroupedOption<TID>[];
+    /** When true, scrolling to the end loads another page. */
     hasMore?: boolean;
 };
 export type SelectFieldPageLazyLoader<TID extends number | string = string | number> = (searchValue: string, pageNumber: number, pageSize: number) => SelectFieldPageLazyResult<TID> | Promise<SelectFieldPageLazyResult<TID>>;
 export type SelectFieldGroupLazyResult<TID extends number | string = string | number> = {
     options: SelectFieldGroupedOption<TID>[];
+    /** When true, scrolling to the end loads the next group. */
     hasMore?: boolean;
 };
 export type SelectFieldGroupLazyLoader<TID extends number | string = string | number> = (searchValue: string, previousGroupKey: SelectFieldGroupByValue | null) => SelectFieldGroupLazyResult<TID> | Promise<SelectFieldGroupLazyResult<TID>>;
 export type SelectFieldSearchProps = {
-    /**
-     * The current search value.
-     * Not a preferred usage. You likely don't need to control the searchValue yourself.
-     */
+    /** Controlled search string. Prefer the search argument to `loadOptions`. */
     searchValue?: string;
-    /**
-     * Callback when the search value changes.
-     * Not a preferred usage. Lean on the searchValue in the loadOptions function instead.
-     */
+    /** Fires as the search field changes. Prefer the search argument to `loadOptions`. */
     onSearchChange?: (searchValue: string) => void;
-    /**
-     * The number of milliseconds to debounce the search input.
-     */
+    /** Debounce for `loadOptions` while typing. Defaults to `200`. */
     debounceMs?: number;
 };
 type SelectFieldAddNewOptionProps = {
-    /**
-     * The configuration for the add new option.
-     */
+    /** Extra option row that opens consumer-rendered dialog content. */
     addNewOption?: {
-        /**
-         * The label to display for the add new option.
-         */
+        /** Text for the extra menu row. */
         label: string;
-        /**
-         * The content to display in the add new option dialog.
-         */
+        /** Dialog body for the current search string. */
         renderDialogContent: (searchValue: string) => React.ReactNode;
     };
 };
 export type SelectFieldPinnedOptionsSection<TID extends number | string = string | number> = {
+    /**
+     * Static list, or a loader keyed by the current search. Function results
+     * may be cached per search.
+     */
     options: SelectFieldOption<TID>[] | ((searchValue: string) => SelectFieldOption<TID>[] | Promise<SelectFieldOption<TID>[]>);
+    /** Section heading. */
     label: string;
     /**
-     * Whether to re-call the loader when search value changes.
-     * Only applies when `options` is a function. Defaults to true.
-     * When false, the loader is called once and the result is reused for all search values.
-     *
-     * You may wish to use this, for example, if you are loading a set of "favorites" options that should not be re-loaded when the search value changes.
+     * Re-calls a function `options` when search changes. Defaults to `true`.
+     * `false` loads once and reuses the result for every search.
      */
     searchReactive?: boolean;
     /**
-     * Maximum number of search results to cache per section.
-     * Only applies when `options` is a function and `searchReactive` is true.
-     * Oldest entries are evicted when the limit is reached. Defaults to 15.
+     * Cached searches per function section when `searchReactive` is true.
+     * Oldest entries evict first. Defaults to `15`.
      */
     cacheSize?: number;
 };
 /**
- * There are two ways to configure pinned options.
- * 1. A labeled pinned options object (e.g. "Favorites", "Recent", "AI Suggestions", etc.)
- * 2. An array of labeled pinned options objects (e.g. [{"label": "Favorites", "options": [...]}])
+ * Pinned sections above the loaded list: one section or an array of sections.
  */
 export type SelectFieldPinnedOptions<TID extends number | string = string | number> = SelectFieldPinnedOptionsSection<TID> | SelectFieldPinnedOptionsSection<TID>[];
 type SelectFieldCommonSelectFieldProps<TID extends number | string = string | number> = {
     /**
-     * The id of the select field.
+     * Prefix for the input, trigger, popover, and dialog ids. Defaults to a
+     * generated id.
      */
     id?: string;
     /**
-     * The label of the select field.
+     * Visible {@link FieldLabel} and dialog title.
      */
     label: string;
     /**
-     * The placeholder of the select field.
+     * Shown when nothing is selected. Combobox uses the input placeholder;
+     * `disableSearch` uses a fake placeholder on the trigger.
      */
     placeholder?: string;
     /**
-     * The size of the select field.
+     * Control size. Defaults to `medium`.
      */
     size?: Extract<Size, "small" | "medium" | "large">;
     /**
-     * The value of the select field. Must be controlled state.
+     * Controlled selected option. Pass `null` for no selection.
      */
     value: SelectFieldOption<TID> | null;
     /**
-     * The callback to call when an item is clicked.
-     * @param option - The option that was selected.
+     * Called with the chosen option, or `null` when the user clears.
      */
     onSelectedOptionChange: (option: SelectFieldOption<TID> | null) => void;
     /**
-     * Defines the initial loading behavior of the options. Controls when loadOptions is called.
-     * @default "auto"
-     * @description "auto" default behavior, currently equivalent to "immediate".
-     * @description "immediate" will load the initial options when the component is mounted.
-     * @description "open" will load the initial options if/when the user opens the dropdown.
+     * When `loadOptions` first runs. `"auto"` is `"immediate"` (mount). `"open"`
+     * waits for the first open. Defaults to `"auto"`.
      */
     initialLoad?: "auto" | "immediate" | "open";
-    /**
-     * The options to pin to the top of the list.
-     */
+    /** Favorites, recents, and similar sections. */
     pinned?: SelectFieldPinnedOptions<TID>;
     /**
-     * Whether to disable the clear button.
-     * @default false
+     * Hides the clear control. Also hidden when there is no value or the field
+     * is disabled/read-only. Defaults to `false`.
      */
     disableClearButton?: boolean;
-    /**
-     * Configuration for caching loadOptions results.
-     * Caching is enabled by default. Set `{ enabled: false }` to disable.
-     */
+    /** Per-search `loadOptions` cache. Pass `{ enabled: false }` to disable. */
     cache?: SelectFieldCacheOptions;
     /**
-     * The way to display the menu.
-     * @default "auto"
-     * @description "auto" will display the menu as a popover on mobile and a dialog on desktop.
-     * @description "popover" will always display the menu as a popover.
-     * @description "dialog" will always display the menu as a dialog.
+     * Menu surface. `"auto"` is a dialog on mobile and a popover otherwise.
+     * Defaults to `"auto"`.
      */
     displayMenuAs?: "auto" | "popover" | "dialog";
     /**
-     * Error state for the field. Pass `true` to indicate error styling without a message.
-     * Pass a string, string[], or ReactElement (deprecated) for error messages.
+     * Error styling. `true` is style-only; a string, string[], or React element
+     * (deprecated) also renders a message.
      */
     error?: boolean | string | ReactElement | string[];
     /**
-     * Visually hides the label while keeping it accessible to screen readers.
-     * @default false
+     * Hides the visual label while keeping it available to assistive technology.
+     * Defaults to `false`.
      */
     hideLabel?: boolean;
-    /**
-     * Hint text displayed below the input field.
-     */
+    /** Always shown below the field, including with error or warning. */
     hint?: ReactElement | string;
-    /**
-     * Additional information to display in a tooltip next to the label.
-     */
+    /** Tooltip next to the label. */
     moreInfo?: ReactNode;
     /**
-     * AI mark configuration to display next to the label.
-     * Can be a boolean to show a simple AI mark, or an object with tooltip/popover configuration.
+     * AI mark after the label. `true` is sparkle-only; pass tooltip/popover
+     * config for the richer mark.
      */
     labelAiMark?: AiMarkWithTooltipOrPopoverProps["aiMark"];
-    /**
-     * Description text displayed below the input field.
-     */
+    /** Extra copy after `hint`. */
     description?: ReactElement | string;
     /**
      * @deprecated No longer used. Error messages always use `aria-live="assertive"`.
      */
     errorAriaLive?: AriaAttributes["aria-live"];
-    /**
-     * Warning message(s) to display. Supports a single string or an array of strings.
-     */
+    /** Warning copy with icon. */
     warning?: string | string[];
-    /**
-     * Whether the field is required. Shows a red asterisk (*) next to the label.
-     */
+    /** Shows the required indicator and sets `required` on the combobox input. */
     required?: boolean;
-    /**
-     * Whether the field is disabled.
-     * When disabled, the input is still focusable but menu items cannot be selected.
-     */
+    /** Blocks selection. Combobox uses a native-disabled input; listbox uses `aria-disabled` on the trigger. */
     disabled?: boolean;
-    /**
-     * Whether the field is read-only.
-     * When read-only, the input is still focusable but menu items cannot be selected.
-     */
+    /** Focusable, but menu rows cannot be chosen. */
     readOnly?: boolean;
     /**
-     * When `true`, applies a subdued primary background to the field to draw attention to it.
-     * @default false
+     * Subdued primary field background. Defaults to `false`.
      */
     isHighlighted?: boolean;
-    /**
-     * Content to display before the input field.
-     */
+    /** Chrome before the value in the input or listbox trigger. */
     prefix?: string | ReactElement;
-    /**
-     * Content to display after the input field.
-     */
+    /** Chrome after the value in the input or listbox trigger. */
     suffix?: string | ReactElement;
-    /**
-     * Custom CSS class name for the wrapper element.
-     */
     className?: string;
-    /**
-     * Custom inline styles for the wrapper element.
-     */
     style?: CSSProperties;
     /**
-     * Whether to virtualize the dropdown list using windowed rendering.
-     * Enable this for large option sets to improve performance by only rendering visible items.
-     * @default false
+     * Windowed option rendering for large lists. Defaults to `false`.
      */
     virtualize?: boolean;
     /**
-     * Whether to disable the search input.
-     * When true, the input is replaced with a non-editable select trigger and the ARIA pattern
-     * changes from combobox to listbox.
-     * @default false
+     * Replaces the combobox input with a non-editable listbox trigger. Defaults
+     * to `false`.
      */
     disableSearch?: boolean;
 } & SelectFieldSearchProps & SelectFieldAddNewOptionProps & LayoutUtilProps & AddNewItemProps & DataAttributes;
 type SelectFieldGroupingProps = {
     /**
-     * Function to convert a group value to a display label.
-     * Only used when options have a `group` property.
-     * @param groupValue - The group value from the option's `group` property
-     * @returns The formatted group label
+     * Turns an option `group` value into a section heading. Unused when options
+     * have no `group`.
      */
     groupToString?: (groupValue: SelectFieldGroupByValue) => string;
     /**
-     * Function to compare two group values for sorting.
-     * When provided, options are sorted by group using this comparator,
-     * then by match-sort order within each group.
-     * @param a - First group value to compare
-     * @param b - Second group value to compare
-     * @returns Negative if a < b, positive if a > b, zero if equal
+     * Orders groups. Unused when options have no `group`.
      */
     groupSorter?: (a: SelectFieldGroupByValue, b: SelectFieldGroupByValue) => number;
 };
 type SelectFieldNonGroupingProps = {
-    /**
-     * Incompatible with non-group lazy loading.
-     */
     groupToString?: never;
-    /**
-     * Incompatible with non-group lazy loading.
-     */
     groupSorter?: never;
 };
+/** Page-number scroll loading. */
 export type SelectFieldPropsLazyPage<TID extends number | string = string | number> = SelectFieldCommonSelectFieldProps<TID> & {
-    /**
-     * Lazy loading mode using page-based pagination.
-     * Options will be loaded on demand when the user scrolls to the bottom of the list.
-     * This mode only supports flat options (i.e. cannot be used with grouped options).
-     */
+    /** Scroll pagination by page number. Grouping props are not allowed. */
     lazy: "page";
     lazyOptions?: {
+        /** Options per `loadOptions` call. Defaults to `20`. */
         pageSize?: number;
     };
-    /**
-     * Function to load the options.
-     */
+    /** Called with search, page number, and page size. Return `{ options, hasMore }`. */
     loadOptions: SelectFieldPageLazyLoader<TID>;
 } & SelectFieldNonGroupingProps;
+/** Offset scroll loading. */
 export type SelectFieldPropsLazyOffset<TID extends number | string = string | number> = SelectFieldCommonSelectFieldProps<TID> & {
-    /**
-     * Lazy loading mode using offset-based pagination.
-     * Options will be loaded on demand when the user scrolls to the bottom of the list.
-     * This mode only supports flat options (i.e. cannot be used with grouped options).
-     */
+    /** Scroll pagination by offset. Grouping props are not allowed. */
     lazy: "offset";
     lazyOptions?: {
+        /** Options per `loadOptions` call. Defaults to `20`. */
         limit?: number;
     };
-    /**
-     * Function to load the options.
-     */
+    /** Called with search, offset, and limit. Return `{ options, hasMore }`. */
     loadOptions: SelectFieldOffsetLazyLoader<TID>;
 } & SelectFieldNonGroupingProps;
+/** Group-key scroll loading. */
 export type SelectFieldPropsLazyGroup<TID extends number | string = string | number> = SelectFieldCommonSelectFieldProps<TID> & {
-    /**
-     * Lazy loading mode using incremental group loading.
-     * Groups will be loaded on demand when the user scrolls to the bottom of the list.
-     * This mode supports grouped options.
-     */
+    /** Scroll pagination by group key. */
     lazy: "group";
+    /** Present so this branch matches other lazy variants. */
     lazyOptions?: object;
-    /**
-     * Function to load the options.
-     */
+    /** Called with search and the previous group key (`null` first). Return `{ options, hasMore }`. */
     loadOptions: SelectFieldGroupLazyLoader<TID>;
 } & SelectFieldGroupingProps;
+/** Eager `loadOptions`. */
 export type SelectFieldPropsEager<TID extends number | string = string | number> = SelectFieldCommonSelectFieldProps<TID> & {
-    /**
-     * Whether the options are lazy loaded. If true, the options will be loaded on demand when the user scrolls to the bottom of the list.
-     * @default false
-     */
+    /** Eager fetch on `initialLoad`. No scroll pagination. */
     lazy?: false;
-    /**
-     * Function to load the options.
-     */
+    /** Called with the current search. Return options or a promise of options. */
     loadOptions: SelectFieldEagerLoader<TID>;
 } & SelectFieldGroupingProps;
+/** Page, offset, or group lazy {@link SelectFieldProps}. */
 export type SelectFieldPropsLazy<TID extends number | string = string | number> = SelectFieldPropsLazyPage<TID> | SelectFieldPropsLazyOffset<TID> | SelectFieldPropsLazyGroup<TID>;
+/**
+ * Single-select field. Discriminated by `lazy`: omit or `false` for eager
+ * `loadOptions`; `"page"` / `"offset"` / `"group"` for lazy loaders.
+ */
 export type SelectFieldProps<TID extends number | string = string | number> = SelectFieldPropsLazy<TID> | SelectFieldPropsEager<TID>;
 export {};

package/dist/src/components/SelectMenu/SelectMenu.d.ts

@@ -1,28 +1,3 @@
 import { SelectMenuHandle, SelectMenuProps } from './types';
-/**
- * SelectMenu component for selecting a single option from a dropdown triggered by any element.
- *
- * Features:
- * - Attaches to any trigger element via a render prop
- * - Optional search input rendered inside the popover/dialog
- * - Lazy loading with pagination (page, offset, or group modes)
- * - Pinned options support
- * - Grouped options support
- * - Supports both popover and dialog display modes
- * - Adaptive display based on device (mobile uses dialog)
- * - Cache support for loadOptions results
- * - Full accessibility support with ARIA attributes
- * - Controlled selection state
- * - Configurable popover width
- * - Optional "Add new item" affordance below the option list with consumer-owned dialog
- *
- * @example
- * <SelectMenu
- *   trigger={(props) => <Button {...props}>Select a book</Button>}
- *   label="Books"
- *   value={selectedOption}
- *   onSelectedOptionChange={setSelectedOption}
- *   loadOptions={loadOptions}
- * />
- */
+/** Single-select menu opened from a custom trigger. Selection is controlled. */
 export declare const SelectMenu: import('react').ForwardRefExoticComponent<SelectMenuProps & import('react').RefAttributes<SelectMenuHandle>>;

package/dist/src/components/SelectMenu/SelectMenuSync.d.ts

@@ -2,40 +2,16 @@ import { MatchSorterOptions } from 'match-sorter';
 import { SelectMenuProps, SelectMenuOption, SelectMenuGroupByValue } from './types';
 import { SyncFilterFn } from '../../internal/functions/syncFilterUtils';
 export type SelectMenuSyncProps = Omit<SelectMenuProps, "loadOptions" | "lazy" | "debounceMs" | "cache" | "initialLoad"> & {
-    /**
-     * The options to display in the select menu.
-     */
+    /** In-memory options. Search filters this list instead of calling `loadOptions`. */
     options: SelectMenuOption[];
     /**
-     * Controls how options are filtered and sorted when the user types a search value.
-     * Can be a function that returns options in the desired display order,
-     * or a MatchSorterOptions object to customize the default match-sorter behavior.
-     *
-     * By default, options are filtered by `label` and `searchText` using match-sorter.
+     * Filter and sort as the user types. A function returns the display order;
+     * a match-sorter options object customizes the default. Defaults to
+     * match-sorter on `label` and `searchText`.
      */
     filter?: SyncFilterFn | MatchSorterOptions<SelectMenuOption>;
-    /**
-     * Custom comparator function to sort groups.
-     */
+    /** Orders groups when options include a `group`. */
     groupSorter?: (a: SelectMenuGroupByValue, b: SelectMenuGroupByValue) => number;
 };
-/**
- * SelectMenuSync is a simplified version of SelectMenu for client-side option sets.
- *
- * Features:
- * - Accepts `options` instead of `loadOptions` and `lazy`
- * - Performs client-side filtering of the options
- * - Optionally accepts a custom filter function or MatchSorterOptions
- * - Supports grouping with optional group sorting via `groupSorter`
- * - Supports all other props of SelectMenu
- *
- * @example
- * <SelectMenuSync
- *   trigger={(props) => <Button {...props}>Pick a book</Button>}
- *   label="Books"
- *   options={bookOptions}
- *   value={selectedOption}
- *   onSelectedOptionChange={setSelectedOption}
- * />
- */
+/** {@link SelectMenu} for a client-side `options` list. */
 export declare const SelectMenuSync: (props: SelectMenuSyncProps) => import("react/jsx-runtime").JSX.Element;

package/dist/src/components/SelectMenu/internal/useMenuInteraction.d.ts

@@ -7,6 +7,7 @@ export type UseMenuInteractionConfig = {
     onItemActivate: (item: SelectItem) => void;
     selectedItemIds: Set<string | number>;
     displayAs: "popover" | "dialog";
+    /** When false, activating a row leaves the menu open (multi-select). */
     closeOnActivate: boolean;
     disabled?: boolean;
     /**
@@ -71,6 +72,7 @@ type ItemReturnProps = {
 } & Record<string, unknown>;
 export type GetMenuPropsFn = (opts?: MenuPropsArg) => MenuReturnProps;
 export type GetItemPropsFn = (opts: ItemPropsArg) => ItemReturnProps;
+/** Keyboard, highlight, and trigger/menu prop bags. */
 export declare const useMenuInteraction: ({ items, sectionsMeta: _sectionsMeta, onItemActivate, selectedItemIds, displayAs: _displayAs, closeOnActivate, disabled, closeOnDisabled, id, triggerRef, label, isOpen, setIsOpen, onImplicitClose, onExplicitClose, }: UseMenuInteractionConfig) => {
     isOpen: boolean;
     openMenu: () => void;