playbook_ui 18.1.0 → 18.2.0.pre.alpha.PLAY3330requiredtypeaheadvalidationbug20501

data/app/pb_kits/playbook/pb_dropdown/_dropdown.tsx

@@ -1,4 +1,4 @@
-import React, { useState, useRef, useEffect, useLayoutEffect, forwardRef, useImperativeHandle, useMemo, useContext } from "react";
+import React, { useState, useRef, useEffect, useLayoutEffect, forwardRef, useImperativeHandle, useMemo, useContext, useCallback } from "react";
 import classnames from "classnames";
 import { buildAriaProps, buildCss, buildDataProps, buildHtmlProps } from "../utilities/props";
 import { globalProps } from "../utilities/globalProps";
@@ -13,12 +13,14 @@ import DropdownContext from "./context";
 import DropdownOption from "./subcomponents/DropdownOption";
 import DropdownTrigger from "./subcomponents/DropdownTrigger";
 import useDropdown from "./hooks/useDropdown";
+import useAsyncOptions, { LoadOptions } from "./hooks/useAsyncOptions";
 import getQuickPickOptions from "./quickpick";
 
 import {
     separateChildComponents,
     prepareSubcomponents,
     handleClickOutside,
+    setQuickPickDateOnPicker,
 } from "./utilities";
 
 import { DialogContext } from "../pb_dialog/_dialog_context";
@@ -81,9 +83,12 @@ function serializeDropdownFilterResetDefault(
     return undefined;
 }
 
+// Async results are server records, so identify them by value like Typeahead rather than by label.
+const asyncOptionValue = (option: GenericObject) => option.value ?? option.id ?? option.label;
+
 type CustomQuickPickDate = {
     label: string;
-    value: string[] | { timePeriod: string; amount: number };
+    value: Array<Date | string> | { timePeriod: string; amount: number };
 };
 
 type CustomQuickPickDates = {
@@ -91,8 +96,18 @@ type CustomQuickPickDates = {
     dates: CustomQuickPickDate[];
 };
 
+type InputChangeReason = "input" | "clear";
+
 type DropdownProps = {
     aria?: { [key: string]: string };
+    async?: boolean;
+    loadOptions?: LoadOptions;
+    defaultOptions?: boolean | GenericObject[];
+    cacheOptions?: boolean;
+    loading?: boolean;
+    onInputChange?: (input: string, detail: { reason: InputChangeReason }) => void;
+    value?: GenericObject | GenericObject[] | null;
+    renderOption?: (option: GenericObject) => React.ReactNode;
     autocomplete?: boolean;
     blankSelection?: string;
     children?: React.ReactChild[] | React.ReactChild | React.ReactElement[];
@@ -113,6 +128,7 @@ type DropdownProps = {
     label?: string;
     multiSelect?: boolean;
     name?: string;
+    noOptionsText?: string;
     onChange?: (event: { target: { name?: string; value: any } }) => void;
     onSelect?: (arg: GenericObject) => null;
     options?: GenericObject;
@@ -139,6 +155,14 @@ interface DropdownComponent
 let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
     const {
         aria = {},
+        async = false,
+        loadOptions,
+        defaultOptions = false,
+        cacheOptions = false,
+        loading = false,
+        onInputChange,
+        renderOption,
+        value,
         autocomplete = false,
         blankSelection = '',
         children,
@@ -159,6 +183,7 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
         multiSelect = false,
         formPillProps,
         name,
+        noOptionsText,
         onChange,
         onSelect,
         options,
@@ -188,15 +213,27 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
         [classes],
     );
 
+    const asyncEnabled = async && variant !== "quickpick";
+    const getOptionValue = asyncEnabled ? asyncOptionValue : undefined;
+    const { options: loadedOptions, status: asyncStatus, search: searchAsync, cancel: cancelAsync, resume: resumeAsync, clear: clearAsync } = useAsyncOptions(asyncEnabled && !!loadOptions && !disabled, loadOptions, defaultOptions, cacheOptions);
+
     // ------------- Quick Pick ---------------------------------
     // Use QuickPick options when variant is "quickpick"
     const dropdownOptions = variant === "quickpick" 
         ? getQuickPickOptions(rangeEndsToday, customQuickPickDates) 
-        : (options || []);
+        : (asyncEnabled && loadOptions ? loadedOptions : options || []);
     // ----------------------------------------------------------
 
     const [isDropDownClosed, setIsDropDownClosed, toggleDropdown] = useDropdown(disabled ? true : isClosed);
 
+    const previouslyClosed = useRef(isDropDownClosed);
+    const queryRef = useRef("");
+    useLayoutEffect(() => {
+      if (asyncEnabled && (disabled || (!previouslyClosed.current && isDropDownClosed))) cancelAsync();
+      if (asyncEnabled && !disabled && previouslyClosed.current && !isDropDownClosed) resumeAsync(queryRef.current);
+      previouslyClosed.current = isDropDownClosed;
+    }, [asyncEnabled, isDropDownClosed, disabled, cancelAsync, resumeAsync]);
+
     // Use a suffix for the trigger ID to avoid conflict with the outer div's id
     const sanitizeForId = (str: string) =>
       str.toLowerCase().replace(/\s+/g, "_").replace(/[^a-z0-9_]/g, "");
@@ -225,16 +262,53 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
       return defaultValue || {};
     }, [multiSelect, defaultValue, variant, dropdownOptions]);
 
-    const [selected, setSelected] = useState<GenericObject | GenericObject[]>(
+    const [internalSelected, setInternalSelected] = useState<GenericObject | GenericObject[]>(
       initialSelected
     );
 
+    const optionKey = (option: GenericObject) => String(
+      getOptionValue ? getOptionValue(option) : option.id ?? option.value ?? option.label
+    );
+
+    const isControlled = value !== undefined;
+    const selected = isControlled ? (value ?? (multiSelect ? [] : {})) : internalSelected;
+    const setSelected: React.Dispatch<React.SetStateAction<GenericObject | GenericObject[]>> = (next) => {
+      if (!isControlled) setInternalSelected(next);
+    };
+    const isSameOption = useCallback((left: GenericObject, right: GenericObject, legacyKey = "label") => {
+      if (!getOptionValue) return left?.[legacyKey] === right?.[legacyKey];
+      if (!left || !right || !Object.keys(left).length || !Object.keys(right).length) return false;
+      return String(getOptionValue(left)) === String(getOptionValue(right));
+    }, [getOptionValue]);
+
     // Autocomplete displays the selection in the input; seed from defaultValue
     const [filterItem, setFilterItem] = useState(() => {
       if (!autocomplete || multiSelect) return "";
-      if (Array.isArray(initialSelected)) return "";
-      return (initialSelected as GenericObject)?.label || "";
+      if (Array.isArray(selected)) return "";
+      return (selected as GenericObject)?.label || "";
     });
+    queryRef.current = filterItem;
+
+    const preserveQueryOnControlledClear = useRef(false);
+
+    // Form adapters may recreate equivalent option objects on every render.
+    // Synchronize the query only when selection identity or display text changes.
+    const controlledSelectionKey = isControlled ? JSON.stringify(
+      (Array.isArray(value) ? value : value && Object.keys(value).length ? [value] : [])
+        .map((option) => [
+          String(getOptionValue ? getOptionValue(option) : option.id ?? option.value ?? option.label),
+          option.label,
+        ])
+    ) : undefined;
+    const controlledLabel = !multiSelect && value && !Array.isArray(value) ? value?.label || "" : "";
+
+    useEffect(() => {
+      if (isControlled && autocomplete) {
+        // Accepting a selection clear must not erase the character that started a new search.
+        if (controlledLabel || !preserveQueryOnControlledClear.current) setFilterItem(controlledLabel);
+        preserveQueryOnControlledClear.current = false;
+      }
+    }, [isControlled, controlledSelectionKey, controlledLabel, autocomplete, multiSelect]);
 
     const filterResetDefaultSerialized = useMemo(
         () => serializeDropdownFilterResetDefault(variant, multiSelect, defaultValue, dropdownOptions),
@@ -291,6 +365,12 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
     ? [selected]
     : [];
 
+    const selectedOptionIds = useMemo(() => (
+      multiSelect && getOptionValue
+        ? new Set(selectedArray.map((option) => String(getOptionValue(option))))
+        : null
+    ), [multiSelect, getOptionValue, selectedArray]);
+
     const { trigger, container, otherChildren } =
         separateChildComponents(children);
 
@@ -321,33 +401,61 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
         setIsDropDownClosed(disabled ? true : isClosed)
     }, [disabled, isClosed])
 
-    const blankSelectionOption: GenericObject = blankSelection ? [{ label: blankSelection, value: "" }] : [];
+    // blankSelection is a clear action, not a search result, so it cannot stand in for an empty async list.
+    const blankSelectionOption: GenericObject = blankSelection && (!asyncEnabled || dropdownOptions.length > 0)
+        ? [{ label: blankSelection, value: "" }]
+        : [];
     const optionsWithBlankSelection = blankSelectionOption.concat(dropdownOptions);
 
     const availableOptions = useMemo(()=> {
         if (!multiSelect) return optionsWithBlankSelection;
-        return optionsWithBlankSelection.filter((option: GenericObject) => !selectedArray.some((sel) => sel.label === option.label));
-    }, [optionsWithBlankSelection, selectedArray, multiSelect]);
+        if (selectedOptionIds) {
+          return optionsWithBlankSelection.filter((option: GenericObject) => !selectedOptionIds.has(String(getOptionValue(option))));
+        }
+        return optionsWithBlankSelection.filter((option: GenericObject) => !selectedArray.some((sel) => isSameOption(sel, option)));
+    }, [optionsWithBlankSelection, selectedArray, multiSelect, isSameOption, selectedOptionIds, getOptionValue]);
     
     const filteredOptions = useMemo(() => {
-          // When the input shows the selected label, do not filter the list down to that one option
           const selectedLabel =
             !multiSelect &&
             !Array.isArray(selected) &&
             (selected as GenericObject)?.label;
+          // Async searches stay unfiltered until the input is showing the selected label.
+          // Reopening then shows only results that match that text.
+          if (asyncEnabled) {
+            if (!(autocomplete && selectedLabel && filterItem === selectedLabel)) return availableOptions;
+            const query = String(selectedLabel).toLowerCase();
+            return availableOptions.filter((opt: GenericObject) => String(opt.label).toLowerCase().includes(query));
+          }
+          // When the input shows the selected label, do not filter the list down to that one option
           const filterText =
             selectedLabel && filterItem === selectedLabel ? "" : filterItem;
           return availableOptions.filter((opt: GenericObject) =>
             String(opt.label).toLowerCase().includes(filterText.toLowerCase())
           );
-        }, [availableOptions, filterItem, multiSelect, selected]);
+        }, [availableOptions, filterItem, multiSelect, selected, asyncEnabled, autocomplete]);
+
+    // Empty copy follows the settled search. Hiding already-selected rows must not turn a
+    // successful result list into "No results found", including the last pick while the menu stays open.
+    const asyncEmptyCopy = asyncEnabled && (asyncStatus === "empty" || (asyncStatus === "idle" && dropdownOptions.length === 0))
+        ? noOptionsText || "No results found"
+        : "";
+
+    // A keystroke clears the highlight. Focus the first result once the next list arrives,
+    // including options the application loads itself.
+    const asyncResultOptions = loadOptions ? loadedOptions : options;
+    useEffect(() => {
+        if (asyncEnabled && !isDropDownClosed) {
+            setFocusedOptionIndex(filteredOptions.length ? 0 : -1);
+        }
+    }, [asyncResultOptions]);
 
     // For keyboard accessibility: Set focus within dropdown to selected item if it exists
     useEffect(() => {
         if (!isDropDownClosed) {
             let newIndex = 0;
             if (selected && !Array.isArray(selected) && selected.label) {
-                const selectedIndex = filteredOptions.findIndex((option: GenericObject) => option.label === selected.label);
+                const selectedIndex = filteredOptions.findIndex((option: GenericObject) => isSameOption(option, selected));
                 if (selectedIndex >= 0) {
                     newIndex = selectedIndex;
                 }
@@ -412,38 +520,70 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
     ]);
 
 
-    const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const handleSelectionChange = (value: any) => {
+        onSelect && onSelect(value);
+        onChange && onChange({ target: { name, value } });
+    };
+
+    const handleChange = (e: React.ChangeEvent<HTMLInputElement>, replaceSelection = false) => {
         if (disabled) return;
+        if (asyncEnabled) {
+          searchAsync(e.target.value);
+          setFocusedOptionIndex(-1);
+        }
+        if ((replaceSelection || ((asyncEnabled || onInputChange) && !e.target.value)) && autocomplete && !multiSelect && selectedArray.length) {
+          preserveQueryOnControlledClear.current = isControlled && !!e.target.value;
+          setSelected({});
+          handleSelectionChange(null);
+        }
         setFilterItem(e.target.value);
+        onInputChange?.(e.target.value, { reason: "input" });
         setIsDropDownClosed(false);
     };
 
-    const handleSelectionChange = (value: any) => {
-        onSelect && onSelect(value);
-        onChange && onChange({ target: { name, value } });
-    };
 
       const handleOptionClick = (clickedItem: GenericObject) => {
                 if (disabled) return;
+                preserveQueryOnControlledClear.current = false;
+                // Single autocomplete keeps the search results so reopening can match the selected label.
+                // Other selections still drop back to the initial list.
+                if (asyncEnabled) {
+                  if (!multiSelect && autocomplete) cancelAsync();
+                  else clearAsync();
+                }
                 const shouldCloseOnClick = closeOnClick === "any" || closeOnClick === "inside";
                 
                 if (multiSelect) {
+                  if (isControlled || getOptionValue) {
+                    const exists = selectedOptionIds
+                      ? selectedOptionIds.has(String(getOptionValue(clickedItem)))
+                      : selectedArray.some((option) => isSameOption(option, clickedItem, "value"));
+                    const next = exists
+                      ? selectedArray.filter((option) => !isSameOption(option, clickedItem, "value"))
+                      : [...selectedArray, clickedItem];
+                    setSelected(next);
+                    handleSelectionChange(next);
+                  } else {
                     setSelected((prev) => {
                        const list = prev as GenericObject[];
-                       const exists = list.find((option) => option.value === clickedItem.value);
+                       const exists = list.find((option) => isSameOption(option, clickedItem, "value"));
                        const next = exists
-                       ? list.filter((option) => option.value !== clickedItem.value)
+                       ? list.filter((option) => !isSameOption(option, clickedItem, "value"))
                            : [...list, clickedItem];
                    handleSelectionChange(next);
                        return next;
                    });
+                  }
                    setFilterItem("");
                    if (shouldCloseOnClick) {
                        setIsDropDownClosed(true);
                    }
                } else {
                    setSelected(clickedItem);
-                   setFilterItem("");
+                   // Async autocomplete shows the selection in the input, as controlled mode and Rails do
+                   setFilterItem(isControlled && autocomplete
+                     ? (selected as GenericObject)?.label || ""
+                     : asyncEnabled && autocomplete ? clickedItem.label || "" : "");
                    if (shouldCloseOnClick) {
                        setIsDropDownClosed(true);
                    }
@@ -455,12 +595,12 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
                        
                        if (controlsStartId) {
                            const startPicker = (document.querySelector(`#${controlsStartId}`) as HTMLElement & { _flatpickr?: any })?._flatpickr;
-                           startPicker?.setDate(start, true);
+                           setQuickPickDateOnPicker(startPicker, start, "start");
                        }
                        
                        if (controlsEndId) {
                            const endPicker = (document.querySelector(`#${controlsEndId}`) as HTMLElement & { _flatpickr?: any })?._flatpickr;
-                           endPicker?.setDate(end, true);
+                           setQuickPickDateOnPicker(endPicker, end, "end");
                        }
                    }
             }
@@ -474,6 +614,10 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
 
     const handleBackspace = () => {
       if (disabled) return;
+      preserveQueryOnControlledClear.current = false;
+      if (asyncEnabled) clearAsync();
+      onInputChange?.("", { reason: "clear" });
+      if ((onInputChange || asyncEnabled) && multiSelect) setFilterItem("");
       if (multiSelect) {
         setSelected([]);
         handleSelectionChange([]);
@@ -481,7 +625,7 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
         setSelected({});
         handleSelectionChange(null);
         setFocusedOptionIndex(-1);
-        setFilterItem("");
+        setFilterItem(isControlled && autocomplete && !multiSelect ? (selected as GenericObject)?.label || "" : "");
         
         // Clear linked DatePickers as well if this is a quickpick variant with controls
         if (variant === "quickpick") {
@@ -511,6 +655,9 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
     // Create an internal ref object that holds the imperative handle methods
     const imperativeRef = useRef({
       clearSelected: () => {
+          preserveQueryOnControlledClear.current = false;
+          if (asyncEnabled) clearAsync();
+          onInputChange?.("", { reason: "clear" });
         if (multiSelect) {
           setSelected([]);
           handleSelectionChange([]);
@@ -518,7 +665,7 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
           setSelected({});
           handleSelectionChange(null);
         }
-        setFilterItem("");
+        setFilterItem(isControlled && autocomplete && !multiSelect ? (selected as GenericObject)?.label || "" : "");
         setIsDropDownClosed(true);
       },
     });
@@ -528,6 +675,9 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
     useEffect(() => {
       imperativeRef.current = {
         clearSelected: () => {
+          preserveQueryOnControlledClear.current = false;
+          if (asyncEnabled) clearAsync();
+          onInputChange?.("", { reason: "clear" });
           if (multiSelect) {
             setSelected([]);
             handleSelectionChange([]);
@@ -535,11 +685,11 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
             setSelected({});
             handleSelectionChange(null);
           }
-          setFilterItem("");
+          setFilterItem(isControlled && autocomplete && !multiSelect ? (selected as GenericObject)?.label || "" : "");
           setIsDropDownClosed(true);
         },
       };
-    }, [multiSelect, handleSelectionChange, setSelected, setFilterItem, setIsDropDownClosed]);
+    }, [multiSelect, handleSelectionChange, setSelected, setFilterItem, setIsDropDownClosed, asyncEnabled, clearAsync, onInputChange]);
 
     useImperativeHandle(ref, () => imperativeRef.current);
 
@@ -562,12 +712,12 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
           setTimeout(() => {
             if (controlsStartId) {
               const startPicker = (document.querySelector(`#${controlsStartId}`) as HTMLElement & { _flatpickr?: any })?._flatpickr;
-              startPicker?.setDate(start, true);
+              setQuickPickDateOnPicker(startPicker, start, "start");
             }
             
             if (controlsEndId) {
               const endPicker = (document.querySelector(`#${controlsEndId}`) as HTMLElement & { _flatpickr?: any })?._flatpickr;
-              endPicker?.setDate(end, true);
+              setQuickPickDateOnPicker(endPicker, end, "end");
             }
           }, 0);
         }
@@ -579,6 +729,7 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
             {...dataProps}
             {...htmlProps}
             {...(filterResetDefaultSerialized ? { "data-default-value": filterResetDefaultSerialized } : {})}
+            aria-busy={asyncEnabled ? (loading || asyncStatus === "loading") : undefined}
             className={classes}
             id={id}
             ref={outerDivRef}
@@ -586,6 +737,15 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
         >
             <DropdownContext.Provider
                 value={{
+                    asyncEnabled,
+                    asyncStatus: asyncEnabled ? (loading || asyncStatus === "loading" ? "Loading…" : asyncStatus === "error" ? "Unable to load options" : asyncEmptyCopy) : "",
+                    renderOption,
+                    optionKey,
+                    isControlled,
+                    onInputChange,
+                    isSameOption,
+                    selectedOptionIds,
+                    getOptionValue,
                     activeStyle,
                     autocomplete,
                     blankSelection,
@@ -613,6 +773,7 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
                     portalHost,
                     selectId,
                     multiSelect,
+                    noOptionsText,
                     onSelect,
                     optionsWithBlankSelection,
                     selected,
@@ -682,7 +843,7 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
                             <DropdownContainer constrainHeight={constrainHeight}>
                                 {optionsWithBlankSelection &&
                                     optionsWithBlankSelection?.map((option: GenericObject) => (
-                                        <DropdownOption key={option.id}
+                                        <DropdownOption key={optionKey(option)}
                                             option={option}
                                         />
                                     ))}

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_async_custom_content.html.erb

@@ -0,0 +1,58 @@
+<%= pb_rails("dropdown", props: {
+  id: "async-rich-user-dropdown",
+  label: "User",
+  name: "async_rich_user",
+  placeholder: "Try Emily or Michael",
+  autocomplete: true,
+  async: true,
+  active_style: { background_color: "bg_light", font_color: "text_lt_default" },
+  options: [],
+}) %>
+
+<template id="async-user-option-template">
+  <%= pb_rails("flex", props: { orientation: "column", align: "start" }) do %>
+    <%= pb_rails("body", props: { text: "Name", data: { async_user_name: true } }) %>
+    <%= pb_rails("detail", props: { text: "Title and Department", data: { async_user_detail: true } }) %>
+  <% end %>
+</template>
+
+<script>
+  (() => {
+    const dropdown = document.getElementById("async-rich-user-dropdown");
+    const template = document.getElementById("async-user-option-template");
+    if (!dropdown || !template || dropdown.dataset.asyncExampleBound) return;
+    dropdown.dataset.asyncExampleBound = "true";
+
+    dropdown.addEventListener("pb:dropdown:search", (event) => {
+      const { searchingFor, setResults, setError } = event.detail;
+      const params = new URLSearchParams({
+        q: searchingFor,
+        limit: "10",
+        select: "firstName,lastName,company",
+      });
+
+      fetch(`https://dummyjson.com/users/search?${params}`, { credentials: "omit" })
+        .then((response) => {
+          if (!response.ok) throw new Error("User search failed");
+          return response.json();
+        })
+        .then(({ users }) => {
+          setResults(users.map((user) => {
+            const option = {
+              id: user.id,
+              label: `${user.firstName} ${user.lastName}`,
+              value: user.id,
+              title: user.company?.title || "",
+              department: user.company?.department || "",
+            };
+            const content = template.content.cloneNode(true);
+            content.querySelector("[data-async-user-name]").textContent = option.label;
+            content.querySelector("[data-async-user-detail]").textContent =
+              [option.title, option.department].filter(Boolean).join(" · ");
+            return { option, content };
+          }));
+        })
+        .catch(() => setError());
+    });
+  })();
+</script>

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_async_custom_content.md

@@ -0,0 +1,10 @@
+For custom Rails result rows, pass `{ option, content }` entries to the async search event's `setResults` callback. `active_style: { background_color: "bg_light", font_color: "text_lt_default" }` is recommended so the selected row uses a light background and default text color. Plain option objects and rich entries can appear in the same result array.
+
+- `option` is the ordinary serializable Dropdown option object: `id`, `label`, `value`, and any custom data. `disabled: true` prevents selection.
+- `content` is an `Element` or `DocumentFragment`, usually cloned from a Rails-rendered `<template>`. Dropdown clones it into its standard option wrapper; it does not consume or move your original nodes. Populate API text with `textContent`. HTML strings are not a rich-content input.
+
+The explicit `option.label` is used in the selected input, even when the row contains additional text. Content is not serialized into option data or the existing `pb:dropdown:selected` payload. Nested content supports click selection and keyboard navigation, including when the menu is portaled.
+
+Provide display content only: do not include another Dropdown option wrapper, interactive controls, or named form inputs in suggestions. Keep submitted fields outside the result content and update them from selection data. Cloning preserves markup and data attributes but does not copy JavaScript event listeners attached to the original nodes.
+
+The example searches [DummyJSON’s public sample users API](https://dummyjson.com/docs/users) without credentials or an API key. Try `Emily` or `Michael`. It renders Rails Body and Detail kits for the name, job title, and department, retaining title and department in the selected option data. The same pattern works with a User kit or other custom display content.

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_async_initial_options.jsx

@@ -0,0 +1,45 @@
+import React from 'react'
+import Dropdown from '../_dropdown'
+
+let searchTimer
+let searchController
+
+const loadUsers = (term) => new Promise((resolve, reject) => {
+  clearTimeout(searchTimer)
+  searchController?.abort()
+  const controller = searchController = new AbortController()
+  searchTimer = setTimeout(() => {
+    const params = new URLSearchParams({ q: term, limit: '10', select: 'firstName,lastName' })
+    fetch(`https://dummyjson.com/users/search?${params}`, { signal: controller.signal, credentials: 'omit' })
+      .then((response) => {
+        if (!response.ok) throw new Error('Search failed')
+        return response.json()
+      })
+      .then(({ users }) => resolve(users.map((user) => ({
+        ...user,
+        label: `${user.firstName} ${user.lastName}`,
+        value: user.id,
+      }))))
+      .catch((error) => {
+        if (error.name !== 'AbortError') reject(error)
+      })
+  }, 250)
+})
+
+const DropdownAsyncInitialOptions = () => (
+  <Dropdown
+      activeStyle={{
+        backgroundColor: "bg_light",
+        fontColor: "text_lt_default",
+      }}
+      async
+      autocomplete
+      cacheOptions
+      defaultOptions
+      label="User"
+      loadOptions={loadUsers}
+      placeholder="Try Emily or Michael"
+  />
+)
+
+export default DropdownAsyncInitialOptions

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_async_initial_options.md

@@ -0,0 +1,9 @@
+Initial results and caching apply only to `async` Dropdowns with `loadOptions`. `activeStyle={{ backgroundColor: "bg_light", fontColor: "text_lt_default" }}` is recommended so the selected row uses a light background and default text color.
+
+- `defaultOptions={true}` calls `loadOptions("")` when enabled without opening the menu.
+- `defaultOptions={options}` supplies an initial result list without making a request. Use `options` without `loadOptions` for externally managed results.
+- `cacheOptions` reuses successful results for exact query strings, including empty results. Each Dropdown keeps at most 100 queries, evicting the oldest stored query. Errors are not cached, and caches are not shared between Dropdowns.
+
+Both props default to `false`. When a search scope changes, use React's `key` to remount the scoped Dropdown, or manage results externally. Changing an inline loader function alone does not invalidate cached results.
+
+Clearing removes displayed results and invalidates pending work, but retains cached results for subsequent searches. Emptying the query does not automatically restore the initial list.

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_async_loading.jsx

@@ -0,0 +1,43 @@
+import React from 'react'
+import Dropdown from '../_dropdown'
+
+let searchTimer
+let searchController
+
+const loadUsers = (term) => new Promise((resolve, reject) => {
+  clearTimeout(searchTimer)
+  searchController?.abort()
+  const controller = searchController = new AbortController()
+  searchTimer = setTimeout(() => {
+    const params = new URLSearchParams({ q: term, limit: '10', select: 'firstName,lastName' })
+    fetch(`https://dummyjson.com/users/search?${params}`, { signal: controller.signal, credentials: 'omit' })
+      .then((response) => {
+        if (!response.ok) throw new Error('Search failed')
+        return response.json()
+      })
+      .then(({ users }) => resolve(users.map((user) => ({
+        ...user,
+        label: `${user.firstName} ${user.lastName}`,
+        value: user.id,
+      }))))
+      .catch((error) => {
+        if (error.name !== 'AbortError') reject(error)
+      })
+  }, 250)
+})
+
+const DropdownAsyncLoading = () => (
+  <Dropdown
+      activeStyle={{
+        backgroundColor: "bg_light",
+        fontColor: "text_lt_default",
+      }}
+      async
+      autocomplete
+      label="User"
+      loadOptions={loadUsers}
+      placeholder="Try Emily or Michael"
+  />
+)
+
+export default DropdownAsyncLoading

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_async_loading.md

@@ -0,0 +1,9 @@
+Use `async` with `autocomplete` or `Dropdown.Container searchbar` to search remote options. `activeStyle={{ backgroundColor: "bg_light", fontColor: "text_lt_default" }}` is recommended so the selected row uses a light background and default text color. This example queries DummyJSON's public sample users API; the consuming application owns the request and result mapping.
+
+`loadOptions(term, callback)` may call `callback(options)` or return a promise resolving to options. Map results to the existing Dropdown shape: `id`, `label`, and `value`, plus any custom fields. Remote matches are displayed without additional local label filtering. When a search returns nothing, earlier results whose labels contain the query stay visible, including text typed after a space. After a single-select autocomplete selection, opening the menu again shows only results whose labels contain the selected label now in the input. With `multiSelect`, each pick becomes a Form Pill, the query clears, and that row stays hidden. See Async Multi Select. Results are matched by `value`, falling back to `id` and then `label`, so results with the same label stay distinct.
+
+Dropdown calls the loader for nonempty queries. This example waits 250ms after the last keystroke and aborts the previous request, the same pause Rails uses and the external search example uses. Keep debounce and minimum query length in the application's loader or input handler, as Nitro's existing Typeahead adapters do. No request runs on mount unless `defaultOptions={true}` is supplied.
+
+Loading, empty, and error states are built in. Opening the Dropdown before any results are available shows the empty message. Thrown errors, rejected promises, invalid results, and requests exceeding 15 seconds show the error state. Callback loaders should invoke their callback once when complete.
+
+New searches, clearing, dismissal, disabling, and unmounting invalidate pending results. Dismissing an unfinished search restores the previous results. A search that already settled as an error or with no results keeps that message when the menu closes, and opening it again does not start another search. Stale responses cannot replace the current results. Application code owns network cancellation. Async mode does not apply to Quick Pick.