@servicetitan/anvil2 1.49.3 → 1.49.5

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

@@ -0,0 +1,102 @@
+import { SelectFieldOption, SelectFieldPropsLazyPage, SelectFieldPropsLazyOffset, SelectFieldPropsLazyGroup, SelectFieldPropsEager } from '../../../beta/components/SelectField/types';
+export declare const DEFAULT_PAGE_SIZE = 20;
+/**
+ * Configuration for caching search results in useSelectFieldLoading.
+ * When enabled, the full accumulated state (options, pagination cursor, hasMore)
+ * is cached per search value, allowing instant restoration when returning to
+ * a previous search.
+ */
+export type CacheConfig = {
+    /**
+     * Whether caching is enabled. Defaults to true.
+     */
+    enabled?: boolean;
+    /**
+     * Maximum number of search values to cache before clearing.
+     * Defaults to 15.
+     */
+    maxSize?: number;
+};
+type UseSelectFieldLoadingConfigLazyPage = Pick<SelectFieldPropsLazyPage, "lazy" | "loadOptions"> & {
+    pageSize: number;
+    cache?: CacheConfig;
+};
+type UseSelectFieldLoadingConfigLazyOffset = Pick<SelectFieldPropsLazyOffset, "lazy" | "loadOptions"> & {
+    limit: number;
+    cache?: CacheConfig;
+};
+type UseSelectFieldLoadingConfigLazyGroup = Pick<SelectFieldPropsLazyGroup, "lazy" | "loadOptions"> & {
+    cache?: CacheConfig;
+};
+type UseSelectFieldLoadingConfigEager = Pick<SelectFieldPropsEager, "lazy" | "loadOptions"> & {
+    cache?: CacheConfig;
+};
+export type UseSelectFieldLoadingConfig = UseSelectFieldLoadingConfigLazyPage | UseSelectFieldLoadingConfigLazyOffset | UseSelectFieldLoadingConfigLazyGroup | UseSelectFieldLoadingConfigEager;
+export type UseSelectFieldLoadingReturn = {
+    /**
+     * Current loaded options array
+     */
+    options: SelectFieldOption[];
+    /**
+     * Boolean indicating initial load in progress
+     */
+    loading: boolean;
+    /**
+     * Boolean indicating load more in progress
+     */
+    loadingMore: boolean;
+    /**
+     * Boolean indicating if more options are available
+     */
+    hasMore: boolean;
+    /**
+     * Function to load options. When initial is true, replaces options and sets loading state.
+     * When initial is false or undefined, appends options and sets loadingMore state.
+     * @param searchValue - The search value to load options for
+     * @param options - Optional configuration
+     * @param options.initial - Whether this is an initial load (replaces options) or continuation (appends options)
+     */
+    loadOptions: (searchValue: string, options?: {
+        initial?: boolean;
+    }) => Promise<void>;
+    /**
+     * Function to load more options (for pagination). Appends to existing options.
+     * @param searchValue - The search value to load more options for
+     */
+    loadMore: (searchValue: string) => Promise<void>;
+    /**
+     * Function to reset all state to initial values
+     */
+    reset: () => void;
+    /**
+     * Function to clear the search results cache
+     */
+    clearCache: () => void;
+};
+/**
+ * Custom hook for managing SelectField option loading state and logic.
+ *
+ * Features:
+ * - Manages option loading state (loading, loadingMore, hasMore)
+ * - Supports eager loading and three lazy loading modes (page, offset, group)
+ * - Handles pagination state tracking for lazy loading
+ * - Provides methods to load options (initial or continuation) and load more
+ * - Automatically manages option replacement vs appending based on load type
+ * - Tracks pagination state (page, offset, group) for lazy loading modes
+ * - Provides reset functionality to clear all state
+ *
+ * @param config - Configuration object containing lazy mode, loadOptions function, and pagination settings
+ * @returns Object containing options, loading states, and load functions
+ *
+ * @example
+ * const { options, loading, loadingMore, hasMore, loadOptions, loadMore } = useSelectFieldLoading({
+ *   lazy: "page",
+ *   loadOptions: async (searchValue, page, pageSize) => {
+ *     const result = await fetchOptions(searchValue, page, pageSize);
+ *     return { options: result.items, hasMore: result.hasMore };
+ *   },
+ *   pageSize: 10
+ * });
+ */
+export declare function useSelectFieldLoading(config: UseSelectFieldLoadingConfig): UseSelectFieldLoadingReturn;
+export {};