playbook_ui 18.2.0 → 18.3.0.pre.alpha.forwardrefwarnings20879

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

@@ -12,8 +12,10 @@ import DropdownContainer from "./subcomponents/DropdownContainer";
 import DropdownContext from "./context";
 import DropdownOption from "./subcomponents/DropdownOption";
 import DropdownTrigger from "./subcomponents/DropdownTrigger";
+import DropdownFormFields from "./subcomponents/DropdownFormFields";
 import useDropdown from "./hooks/useDropdown";
 import useAsyncOptions, { LoadOptions } from "./hooks/useAsyncOptions";
+import { getCreationOption, matchesOptionExactly } from "./utilities/optionCreation";
 import getQuickPickOptions from "./quickpick";
 
 import {
@@ -99,6 +101,7 @@ type CustomQuickPickDates = {
 type InputChangeReason = "input" | "clear";
 
 type DropdownProps = {
+    allowOptionCreation?: boolean;
     aria?: { [key: string]: string };
     async?: boolean;
     loadOptions?: LoadOptions;
@@ -122,6 +125,9 @@ type DropdownProps = {
     data?: { [key: string]: string };
     defaultValue?: GenericObject;
     error?: string;
+    enableFormSupport?: boolean;
+    enablePillReorder?: boolean;
+    externalDragHandle?: boolean;
     htmlOptions?: { [key: string]: string | number | boolean | (() => void) },
     id?: string;
     isClosed?: boolean;
@@ -134,6 +140,7 @@ type DropdownProps = {
     options?: GenericObject;
     placeholder?: string;
     separators?: boolean;
+    showPillIndex?: boolean;
     variant?: "default" | "subtle" | "quickpick";
     rangeEndsToday?: boolean;
     controlsStartId?: string;
@@ -143,6 +150,8 @@ type DropdownProps = {
       fontColor?: string;
     };
     requiredIndicator?: boolean;
+    required?: boolean;
+    validationMessage?: string;
 };
 
 interface DropdownComponent
@@ -154,6 +163,7 @@ interface DropdownComponent
 
 let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
     const {
+        allowOptionCreation = false,
         aria = {},
         async = false,
         loadOptions,
@@ -163,7 +173,7 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
         onInputChange,
         renderOption,
         value,
-        autocomplete = false,
+        autocomplete: autocompleteProp = false,
         blankSelection = '',
         children,
         className,
@@ -175,7 +185,10 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
         data = {},
         defaultValue = {},
         disabled = false,
-        error,
+        error: errorProp,
+        enableFormSupport = false,
+        enablePillReorder = false,
+        externalDragHandle = false,
         htmlOptions = {},
         id,
         isClosed = true,
@@ -188,15 +201,27 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
         onSelect,
         options,
         placeholder,
+        showPillIndex = false,
         rangeEndsToday = false,
         controlsStartId,
         controlsEndId,
         separators = true,
         variant = "default",
         activeStyle,
-        requiredIndicator = false
+        requiredIndicator = false,
+        required = false,
+        validationMessage = "Please fill out this field."
     } = props;
 
+    const isPillReorderEnabled = Boolean(enablePillReorder && multiSelect);
+
+    const creationEnabled = allowOptionCreation && variant !== "quickpick";
+    const autocomplete = autocompleteProp || creationEnabled;
+
+    const [formInvalid, setFormInvalid] = useState(false);
+    const formError = formInvalid ? validationMessage : "";
+    const error = enableFormSupport ? errorProp || formError : errorProp;
+
     const ariaProps = buildAriaProps(aria);
     const dataProps = buildDataProps(data);
     const htmlProps = buildHtmlProps(htmlOptions);
@@ -365,6 +390,11 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
     ? [selected]
     : [];
 
+    const hasFormSelection = enableFormSupport && selectedArray.some((option) => String(option.id ?? option.value ?? "") !== "");
+    useEffect(() => {
+        if (!enableFormSupport || hasFormSelection || !required) setFormInvalid(false);
+    }, [enableFormSupport, hasFormSelection, required]);
+
     const selectedOptionIds = useMemo(() => (
       multiSelect && getOptionValue
         ? new Set(selectedArray.map((option) => String(getOptionValue(option))))
@@ -415,7 +445,16 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
         return optionsWithBlankSelection.filter((option: GenericObject) => !selectedArray.some((sel) => isSameOption(sel, option)));
     }, [optionsWithBlankSelection, selectedArray, multiSelect, isSameOption, selectedOptionIds, getOptionValue]);
     
-    const filteredOptions = useMemo(() => {
+    const searchIsPending = loading || (asyncEnabled && asyncStatus === "loading");
+    const searchFailed = asyncEnabled && asyncStatus === "error";
+    const canCreateOption = creationEnabled && !disabled && !searchIsPending && !searchFailed;
+    let creationOption: GenericObject | null = null;
+    if (canCreateOption) {
+        const existingOptions = Array.isArray(dropdownOptions) ? dropdownOptions : [];
+        creationOption = getCreationOption(filterItem, [...existingOptions, ...selectedArray]);
+    }
+
+    const matchingOptions = useMemo(() => {
           const selectedLabel =
             !multiSelect &&
             !Array.isArray(selected) &&
@@ -431,9 +470,29 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
           const filterText =
             selectedLabel && filterItem === selectedLabel ? "" : filterItem;
           return availableOptions.filter((opt: GenericObject) =>
-            String(opt.label).toLowerCase().includes(filterText.toLowerCase())
+            String(opt.label).toLowerCase().includes(filterText.toLowerCase()) ||
+            (creationEnabled && matchesOptionExactly(opt, filterText))
           );
-        }, [availableOptions, filterItem, multiSelect, selected, asyncEnabled, autocomplete]);
+        }, [availableOptions, filterItem, multiSelect, selected, asyncEnabled, autocomplete, creationEnabled]);
+
+    const filteredOptions = creationOption ? [...matchingOptions, creationOption] : matchingOptions;
+    const inputShowsSelection = !multiSelect && !Array.isArray(selected) && filterItem === selected?.label;
+    let creationFocusIndex = -1;
+    if (creationEnabled && creationOption) {
+        creationFocusIndex = matchingOptions.length;
+    } else if (creationEnabled) {
+        creationFocusIndex = matchingOptions.findIndex((option: GenericObject) => !option.disabled);
+    }
+
+    useEffect(() => {
+        if (!creationEnabled) return;
+        if (isDropDownClosed || !filterItem.trim() || inputShowsSelection) {
+            setFocusedOptionIndex(-1);
+            return;
+        }
+
+        setFocusedOptionIndex(creationFocusIndex);
+    }, [creationEnabled, isDropDownClosed, filterItem, inputShowsSelection, creationFocusIndex]);
 
     // 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.
@@ -441,18 +500,25 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
         ? noOptionsText || "No results found"
         : "";
 
+    let asyncStatusText = "";
+    if (asyncEnabled) {
+        if (searchIsPending) asyncStatusText = "Loading…";
+        else if (searchFailed) asyncStatusText = "Unable to load options";
+        else if (!creationOption) asyncStatusText = asyncEmptyCopy;
+    }
+
     // 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) {
+        if (!creationEnabled && asyncEnabled && !isDropDownClosed) {
             setFocusedOptionIndex(filteredOptions.length ? 0 : -1);
         }
-    }, [asyncResultOptions]);
+    }, [asyncResultOptions, creationEnabled]);
 
     // For keyboard accessibility: Set focus within dropdown to selected item if it exists
     useEffect(() => {
-        if (!isDropDownClosed) {
+        if (!creationEnabled && !isDropDownClosed) {
             let newIndex = 0;
             if (selected && !Array.isArray(selected) && selected.label) {
                 const selectedIndex = filteredOptions.findIndex((option: GenericObject) => isSameOption(option, selected));
@@ -462,7 +528,7 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
             }
             setFocusedOptionIndex(newIndex);
         }
-    }, [isDropDownClosed]);
+    }, [isDropDownClosed, creationEnabled]);
 
     // Auto-position dropdown above/below based on available space or fixed/absolute when portaled to body / floating root
     useLayoutEffect(() => {
@@ -580,10 +646,12 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
                    }
                } else {
                    setSelected(clickedItem);
-                   // 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 || "" : "");
+                   // Plain uncontrolled autocomplete clears its query after selection.
+                   const keepSelectedLabel = autocomplete && (creationEnabled || asyncEnabled || isControlled);
+                   const nextQuery = keepSelectedLabel
+                     ? (isControlled ? (selected as GenericObject)?.label : clickedItem.label) || ""
+                     : "";
+                   setFilterItem(nextQuery);
                    if (shouldCloseOnClick) {
                        setIsDropDownClosed(true);
                    }
@@ -724,6 +792,27 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
       }
     }, [variant, initialSelected, controlsStartId, controlsEndId]);
 
+    const handleFormInvalid = () => {
+        setFormInvalid(true);
+        const focusTarget = inputRef.current || inputWrapperRef.current;
+        focusTarget?.focus();
+    };
+
+    const handleFormReset = () => {
+        const hasDefaultSelection = Object.keys(initialSelected).length > 0;
+        const resetValue = multiSelect || hasDefaultSelection ? initialSelected : null;
+        const resetQuery = autocomplete && !multiSelect
+            ? (initialSelected as GenericObject).label || ""
+            : "";
+
+        setSelected(initialSelected);
+        handleSelectionChange(resetValue);
+        setFilterItem(resetQuery);
+        setFormInvalid(false);
+        setIsDropDownClosed(true);
+        if (asyncEnabled) clearAsync();
+    };
+
     return (
         <div {...ariaProps}
             {...dataProps}
@@ -738,7 +827,9 @@ 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) : "",
+                    asyncStatus: asyncStatusText,
+                    creationEnabled,
+                    creationOption,
                     renderOption,
                     optionKey,
                     isControlled,
@@ -754,6 +845,8 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
                     disabled,
                     error,
                     errorId,
+                    enablePillReorder: isPillReorderEnabled,
+                    externalDragHandle,
                     filterItem,
                     filteredOptions,
                     focusedOptionIndex,
@@ -782,9 +875,22 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
                     setIsDropDownClosed,
                     setIsInputFocused,
                     setSelected,
+                    showPillIndex,
                     toggleDropdown
                 }}
             >
+                {enableFormSupport && (
+                    <DropdownFormFields
+                        disabled={disabled}
+                        multiSelect={multiSelect}
+                        name={name}
+                        onInvalid={handleFormInvalid}
+                        onReset={handleFormReset}
+                        required={required}
+                        selected={selectedArray}
+                        validationMessage={validationMessage}
+                    />
+                )}
                 {label && (
                   <label
                       data-dropdown="pb-dropdown-label"

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

@@ -0,0 +1,51 @@
+<%
+  options = [
+    { label: 'Year', value: 'year', id: 'year' },
+    { label: 'Territory', value: 'territory', id: 'territory' },
+    { label: 'Branch', value: 'branch', id: 'branch' },
+    { label: 'Product', value: 'product', id: 'product' },
+  ]
+%>
+
+<%= pb_rails("body", props: { text: "Select services, then drag the pills to reorder them.", margin_bottom: "xs" }) %>
+
+<%= pb_rails("dropdown", props: {
+  id: "dropdown-draggable-pills-example",
+  default_value: [options[0], options[1], options[2]],
+  enable_pill_reorder: true,
+  show_pill_index: true,
+  multi_select: true,
+  label: "Services",
+  name: :services,
+  options: options,
+  placeholder: "Add services...",
+}) %>
+
+<%= pb_rails("body", props: {
+  id: "dropdown-draggable-order",
+  color: "lighter",
+  margin_top: "xs",
+  text: "Current order: Year -> Territory -> Branch",
+}) %>
+
+<script>
+  (() => {
+    const dropdownId = "dropdown-draggable-pills-example";
+    const orderElement = document.getElementById("dropdown-draggable-order");
+
+    const updateOrderText = (detail) => {
+      if (!orderElement || !Array.isArray(detail)) return;
+      orderElement.textContent = `Current order: ${detail.map((item) => item.label).join(" -> ")}`;
+    };
+
+    document.addEventListener("pb:dropdown:reordered", (event) => {
+      if (event.target.id !== dropdownId) return;
+      updateOrderText(event.detail);
+    });
+
+    document.addEventListener("pb:dropdown:selected", (event) => {
+      if (event.target.id !== dropdownId) return;
+      updateOrderText(event.detail);
+    });
+  })();
+</script>

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

@@ -0,0 +1,62 @@
+import React, { useState } from 'react'
+import { Body, Button, Dropdown, Flex } from 'playbook-ui'
+
+const options = [
+  { label: 'Year', value: 'year', id: 'year' },
+  { label: 'Territory', value: 'territory', id: 'territory' },
+  { label: 'Branch', value: 'branch', id: 'branch' },
+  { label: 'Product', value: 'product', id: 'product' },
+]
+
+const DropdownDraggablePills = (props) => {
+  const [value, setValue] = useState([
+    options[0],
+    options[1],
+    options[2],
+  ])
+
+  const currentOrder = value.map((item) => item.label).join(' -> ')
+
+  const handleReset = () => {
+    setValue([options[0], options[1], options[2]])
+  }
+
+  return (
+    <Flex
+        align="stretch"
+        gap="sm"
+        orientation="column"
+    >
+      <Flex
+          align="center"
+          justify="between"
+      >
+        <Body text="Select services, then drag the pills to reorder them." />
+        <Button
+            onClick={handleReset}
+            text="Reset"
+            variant="secondary"
+        />
+      </Flex>
+
+      <Dropdown
+          enablePillReorder
+          label="Services"
+          multiSelect
+          onChange={({ target }) => setValue(target.value || [])}
+          options={options}
+          placeholder="Add services..."
+          showPillIndex
+          value={value}
+          {...props}
+      />
+
+      <Body
+          color="lighter"
+          text={`Current order: ${currentOrder}`}
+      />
+    </Flex>
+  )
+}
+
+export default DropdownDraggablePills

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

@@ -0,0 +1,9 @@
+Use `enable_pill_reorder: true` with `show_pill_index: true` to let users drag selected multi-select pills into a new order. By default, each pill shows a grip icon and can be dragged from anywhere on the pill. Set `external_drag_handle: true` to use an external grip handle instead (drag only from the handle).
+
+While dragging, pills stay in place, a ghost follows the pointer, and a blue line marks where the pill will land. Order is committed on drop.
+
+The `pb:dropdown:reordered` custom event receives the reordered value array. Submitted form values (hidden inputs) preserve the new order. `pb:dropdown:selected` also fires with the updated order.
+
+Keyboard reorder: focus a pill, then press ArrowLeft or ArrowRight to move it one position.
+
+Works with Multi-Select and Multi-Select + Autocomplete Dropdown variants only, and is disabled by default.

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

@@ -0,0 +1,9 @@
+Use `enablePillReorder` to let users drag selected multi-select pills into a new order. Pair with `showPillIndex` to display numbered prefixes that update automatically after reorder or removal.
+
+By default, each pill shows a grip icon and can be dragged from anywhere on the pill. Set `externalDragHandle` to `true` to use an external grip handle instead (drag only from the handle).
+
+While dragging, pills stay in place, a ghost follows the pointer, and a blue line marks where the pill will land. Order is committed on drop. The `onChange` callback receives the reordered value array.
+
+Keyboard reorder: focus a pill, then press ArrowLeft or ArrowRight to move it one position.
+
+Works with Multi-Select and Multi-Select + Autocomplete.  Dropdown variants only, and is disabled by default.

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

@@ -0,0 +1,50 @@
+import React, { useState } from 'react'
+import Dropdown from '../_dropdown'
+import Button from '../../pb_button/_button'
+import Body from '../../pb_body/_body'
+
+const DropdownForm = () => {
+  const [submittedTags, setSubmittedTags] = useState(null)
+  const options = [
+    { id: 'product', label: 'Product', value: 'product' },
+    { id: 'support', label: 'Support', value: 'support' },
+  ]
+
+  const handleSubmit = (event) => {
+    event.preventDefault()
+    setSubmittedTags(new FormData(event.currentTarget).getAll('tags[]'))
+  }
+
+  return (
+    <form onReset={() => setSubmittedTags(null)}
+        onSubmit={handleSubmit}
+    >
+      <Dropdown
+          enableFormSupport
+          label="Tags"
+          marginBottom="md"
+          multiSelect
+          name="tags[]"
+          options={options}
+          required
+          requiredIndicator
+          validationMessage="Select at least one tag."
+      />
+      <Button htmlType="submit"
+          text="Submit"
+      />
+      <Button htmlType="reset"
+          marginLeft="xs"
+          text="Reset"
+          variant="secondary"
+      />
+      {submittedTags && (
+        <Body marginTop="sm"
+            text={`Submitted tags: ${submittedTags.join(', ')}`}
+        />
+      )}
+    </form>
+  )
+}
+
+export default DropdownForm

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

@@ -0,0 +1,9 @@
+Set `enableFormSupport` to opt into React native form submission, required validation, and reset handling. The prop defaults to `false`. Passing `name` or `required` alone does not enable native form behavior. Option creation is a separate feature controlled by `allowOptionCreation`.
+
+With `enableFormSupport` enabled and `name` provided, Dropdown renders named hidden inputs. Each selected option submits its `id`, falling back to `value`. For `multiSelect`, each selection gets a separate input and the name ends in `[]`; an existing `[]` suffix is preserved. Disabled Dropdowns do not submit values. An empty selection submits an empty string.
+
+The example below requires at least one tag. Submit an empty selection to see validation, select tags and submit to see the values from `FormData`, or use Reset to restore the default selection.
+
+Use `required` for native form constraint validation, `validationMessage` for the inline required message, and `requiredIndicator` for the visual asterisk. Invalid submissions focus the trigger or autocomplete input. Typing a query does not satisfy required validation; select an option first. The unnamed validation input never submits query text.
+
+Native form reset restores `defaultValue`, clears the query and validation message, and closes the menu. A controlled Dropdown reports that reset through its normal selection callbacks; the parent must update `value`. Canceling the reset event preserves the selection. In a controlled form library, pass `value`, `name`, and `onChange`; Dropdown sends `{ target: { name, value } }`, with an option object or array as `value`. The forwarded ref exposes `clearSelected`, rather than a native input ref.

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

@@ -0,0 +1,16 @@
+<%= pb_rails("dropdown", props: {
+  allow_option_creation: true,
+  label: "Grid Alignment Group",
+  margin_bottom: "md",
+  name: "grid_alignment_group",
+  options: [{ id: "existing", label: "Existing group", value: "existing" }],
+}) %>
+
+<%= pb_rails("dropdown", props: {
+  allow_option_creation: true,
+  label: "Home IDs",
+  multi_select: true,
+  name: "home_ids[]",
+  options: [{ id: "existing", label: "Existing group", value: "existing" }],
+  placeholder: "Type a home ID and press Enter",
+}) %>

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

@@ -0,0 +1,27 @@
+import React from 'react'
+import Dropdown from '../_dropdown'
+
+const DropdownOptionCreation = () => {
+  const options = [{ id: 'existing', label: 'Existing tag', value: 'existing' }]
+
+  return (
+    <>
+      <Dropdown
+          allowOptionCreation
+          label="Grid Alignment Group"
+          marginBottom="md"
+          name="gridAlignmentGroup"
+          options={options}
+      />
+      <Dropdown
+          allowOptionCreation
+          label="Tags"
+          multiSelect
+          name="tags[]"
+          options={options}
+      />
+    </>
+  )
+}
+
+export default DropdownOptionCreation

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

@@ -0,0 +1,9 @@
+Enable `allow_option_creation: true` to select text that is not already an option. This also enables autocomplete on the default trigger. With custom subcomponents, provide an autocomplete trigger or a searchable container. Creation supports single and multiple selections, including async search, and is ignored for the quickpick variant.
+
+Type a new value and click the `Create "…"` row, or use the arrow keys and Enter. A non-empty search focuses the Create row when it is available; arrow keys can choose another option. Creation trims surrounding whitespace, rejects blank text, and suppresses case-insensitive matches against existing or selected labels, values, and IDs. An exact ID or value match keeps the existing option visible and selectable even when its label does not contain the query. The selected object is `{ id: text, label: text, value: text, __isNew__: true }`. The Create label is presentation only.
+
+Created selections emit the normal `pb:dropdown:selected` event with the option object, or an array for `multi_select: true`. Rails retains its existing native form support. Multi-select fields submit individual selected values in selection order, and the field name receives a `[]` suffix only if it does not already have one. While selections exist, the empty base input is disabled so it does not add a blank array entry. Clearing the selection restores the base input for required validation; disabled Dropdowns stay excluded from submission.
+
+For async usage, combine `allow_option_creation: true` with `async: true` and handle the existing `pb:dropdown:search` event using its `setResults` and `setError` callbacks. Creation is hidden during pending searches and errors, then offered when settled results have no exact match. Creation can be offered below `search_term_minimum_length`, when no remote search runs.
+
+Creation does not persist a server record or append to application-owned options; persist selections through your normal form submission or selection handler.

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

@@ -0,0 +1,9 @@
+Enable `allowOptionCreation` to select text that is not already an option. This also enables autocomplete on the default trigger. Creation supports single and multiple selections, including async search, and is ignored for the quickpick variant.
+
+Type a new value and click the `Create "…"` row, or use the arrow keys and Enter. Creation trims surrounding whitespace, rejects blank text, and suppresses case-insensitive matches against existing or selected labels, values, and IDs. An exact ID or value match keeps the existing option visible and selectable even when its label does not contain the query. The selected object is `{ id: text, label: text, value: text, __isNew__: true }`. The Create label is presentation only.
+
+Created selections use the normal `onSelect(optionOrArray)` and `onChange({ target: { name, value } })` callbacks. Multiple selections produce an array of option objects. Native form submission additionally requires `enableFormSupport`; option creation alone does not enable it. Creation does not persist a server record or append to application-owned options; persist selections through your normal form submission or selection handler.
+
+For async usage, combine `allowOptionCreation` with `async` and your existing `loadOptions`; both Promise and callback loaders are supported. Creation is hidden during pending searches and errors, then offered when settled results have no exact match. Applications that manage fetching themselves must pass `loading` while the request is pending.
+
+A non-empty search focuses the Create row when it is available; arrow keys can choose another option. Closing the menu or clearing the query removes automatic option focus. Enter selects a highlighted option, including when the query is blank. Enter with a closed menu, or a blank query and no highlighted option, remains available for normal form submission and does not change the selection.

data/app/pb_kits/playbook/pb_dropdown/docs/_playground.json

@@ -5,6 +5,7 @@
     "options": "Options.data"
   },
   "defaults": {
+    "allowOptionCreation": false,
     "async": false,
     "autocomplete": false,
     "blankSelection": "",
@@ -12,13 +13,18 @@
     "closeOnClick": "any",
     "constrainHeight": false,
     "disabled": false,
+    "enablePillReorder": false,
+    "externalDragHandle": false,
     "multiSelect": false,
     "separators": true,
+    "showPillIndex": false,
     "variant": "default",
     "rangeEndsToday": false,
     "controlsStartId": "",
     "controlsEndId": "",
     "requiredIndicator": false,
+    "required": false,
+    "validationMessage": "",
     "dark": false,
     "label": "Select a Country",
     "options": [
@@ -124,7 +130,11 @@
         "closeOnClick",
         "constrainHeight",
         "isClosed",
-        "requiredIndicator"
+        "enableFormSupport",
+        "requiredIndicator",
+        "required",
+        "validationMessage",
+        "allowOptionCreation"
       ]
     },
     {
@@ -141,6 +151,9 @@
       "props": [
         "separators",
         "formPillProps",
+        "enablePillReorder",
+        "externalDragHandle",
+        "showPillIndex",
         "activeStyle",
         "dark",
         "disabled"
@@ -155,6 +168,15 @@
     }
   ],
   "presets": [
+    {
+      "name": "Create tags",
+      "props": {
+        "allowOptionCreation": true,
+        "multiSelect": true,
+        "name": "tags[]",
+        "label": "Tags"
+      }
+    },
     {
       "name": "Async search",
       "structureMode": "async",
@@ -339,6 +361,15 @@
     "formPillProps": {
       "requires": "multiSelect"
     },
+    "enablePillReorder": {
+      "requires": "multiSelect"
+    },
+    "externalDragHandle": {
+      "requires": "enablePillReorder"
+    },
+    "showPillIndex": {
+      "requires": "multiSelect"
+    },
     "rangeEndsToday": {
       "requires": {
         "variant": "quickpick"
@@ -389,7 +420,7 @@
       "when": {
         "multiSelect": true
       },
-      "message": "Multi-select returns arrays of selected options. Use formPillProps to adjust the selected-pill appearance and clearable to let users reset the selection.",
+      "message": "Multi-select returns arrays of selected options. Use formPillProps to adjust the selected-pill appearance and clearable to let users reset the selection. Opt into enablePillReorder to drag pills into a new priority order.",
       "type": "info"
     },
     "autocomplete_info": {