@servicetitan/dte-unlayer 0.141.0 → 0.143.0

package/src/display-conditions/useLookupOptions.ts

@@ -1,43 +1,61 @@
-import { useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import { generateId } from './constants';
 import {
     emitLookupOptionsRequest,
-    isSearchableLookupSource,
     LookupOption,
     onLookupOptionsResponse,
 } from './lookupOptionsController';
 
 /**
- * - `idle`     -> no lookup source (or searchable source): use free-text input.
- * - `loading`  -> request in flight: show a disabled/loading value control.
- * - `ready`    -> host returned options: render the dropdown.
- * - `fallback` -> empty/error/timeout: fall back to free-text so the user is never blocked.
+ * - `idle`       -> no lookup source: use free-text input.
+ * - `loading`    -> initial request in flight: show a disabled/loading value control.
+ * - `static`     -> host returned a full list: render a locally-filtered dropdown.
+ * - `searchable` -> host wants per-query search: render an async dropdown driven by `loadOptions`.
+ * - `fallback`   -> empty/error/timeout: fall back to free-text so the user is never blocked.
  */
-export type LookupOptionsStatus = 'idle' | 'loading' | 'ready' | 'fallback';
+export type LookupOptionsStatus = 'idle' | 'loading' | 'static' | 'searchable' | 'fallback';
 
 /** Time to wait for the host before falling back to free-text input. */
 const LOOKUP_OPTIONS_TIMEOUT_MS = 10_000;
 
 interface UseLookupOptionsResult {
     status: LookupOptionsStatus;
+    /** Full option list for `static` sources; empty for `searchable`/`idle`/`fallback`. */
     options: LookupOption[];
+    /**
+     * Per-query resolver for `searchable` sources. Emits a request with the typed
+     * `query` and resolves with the host's fresh list (or `[]` on timeout). Wire
+     * this into an async dropdown (e.g. Anvil2 `SelectField`'s `loadOptions`).
+     */
+    loadOptions: (query: string) => Promise<LookupOption[]>;
+    /**
+     * Resolve the option(s) for already-stored keys (exact match, not a text
+     * search). Used on open to turn a saved searchable value back into its
+     * human-readable label. Resolves with `[]` on timeout.
+     */
+    resolveOptions: (keys: string[]) => Promise<LookupOption[]>;
 }
 
 /**
  * Requests host-resolved dropdown options for a field's `fieldLookupSource`.
  *
- * Re-runs whenever `sourceKey` changes, ignores stale responses whose requestId
- * does not match the latest request, and cleans up its listener/timeout on
- * unmount or source change.
+ * Fires a single query-less request whenever `sourceKey` changes. The host's
+ * response decides the mode: a full list (`static`, filtered locally) or a
+ * searchable source (`searchable`, driven by `loadOptions` per keystroke).
+ * Stale responses (mismatched requestId) are ignored and the listener/timeout
+ * are cleaned up on unmount or source change.
  */
 export const useLookupOptions = (sourceKey: string | undefined): UseLookupOptionsResult => {
     const [status, setStatus] = useState<LookupOptionsStatus>('idle');
     const [options, setOptions] = useState<LookupOption[]>([]);
     const latestRequestIdRef = useRef<string | null>(null);
+    const sourceKeyRef = useRef<string | undefined>(sourceKey);
 
     useEffect(() => {
-        // No source, or a searchable source we intentionally skip for now.
-        if (!sourceKey || isSearchableLookupSource(sourceKey)) {
+        sourceKeyRef.current = sourceKey;
+        const normalizedSourceKey = sourceKey?.trim();
+
+        if (!normalizedSourceKey) {
             latestRequestIdRef.current = null;
             setStatus('idle');
             setOptions([]);
@@ -63,16 +81,21 @@ export const useLookupOptions = (sourceKey: string | undefined): UseLookupOption
                 return;
             }
             clearTimeout(timeoutId);
+            if (response.searchable) {
+                setOptions([]);
+                setStatus('searchable');
+                return;
+            }
             if (response.options.length > 0) {
                 setOptions(response.options);
-                setStatus('ready');
+                setStatus('static');
             } else {
                 setOptions([]);
                 setStatus('fallback');
             }
         });
 
-        emitLookupOptionsRequest({ requestId, sourceKey });
+        emitLookupOptionsRequest({ requestId, sourceKey: normalizedSourceKey });
 
         return () => {
             clearTimeout(timeoutId);
@@ -80,5 +103,45 @@ export const useLookupOptions = (sourceKey: string | undefined): UseLookupOption
         };
     }, [sourceKey]);
 
-    return { status, options };
+    const requestOptions = useCallback((payload: { query?: string; keys?: string[] }) => {
+        const normalizedSourceKey = sourceKeyRef.current?.trim();
+        if (!normalizedSourceKey) {
+            return Promise.resolve<LookupOption[]>([]);
+        }
+
+        return new Promise<LookupOption[]>(resolve => {
+            const requestId = generateId();
+            let settled = false;
+
+            const finish = (result: LookupOption[]) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearTimeout(timeoutId);
+                unsubscribe();
+                resolve(result);
+            };
+
+            const timeoutId = setTimeout(() => finish([]), LOOKUP_OPTIONS_TIMEOUT_MS);
+
+            const unsubscribe = onLookupOptionsResponse(response => {
+                if (response.requestId !== requestId) {
+                    return;
+                }
+                finish(response.options);
+            });
+
+            emitLookupOptionsRequest({ requestId, sourceKey: normalizedSourceKey, ...payload });
+        });
+    }, []);
+
+    const loadOptions = useCallback((query: string) => requestOptions({ query }), [requestOptions]);
+
+    const resolveOptions = useCallback(
+        (keys: string[]) => requestOptions({ keys }),
+        [requestOptions],
+    );
+
+    return { status, options, loadOptions, resolveOptions };
 };