feat(combo-box): allow custom value (#2232)

Closes #1726

Author: metonym

COMPONENT_INDEX.md

@@ -1971,6 +1971,18 @@
           "constant": false,
           "reactive": true
         },
+        {
+          "name": "allowCustomValue",
+          "kind": "let",
+          "description": "Set to `true` to allow custom values that are not in the items list.\nBy default, user-entered text is cleared when the combobox loses focus without selecting an item.\nWhen enabled, custom text is preserved.",
+          "type": "boolean",
+          "value": "false",
+          "isFunction": false,
+          "isFunctionDeclaration": false,
+          "isRequired": false,
+          "constant": false,
+          "reactive": false
+        },
         {
           "name": "shouldFilterItem",
           "kind": "let",

docs/src/COMPONENT_API.json

@@ -91,6 +91,12 @@ For async (e.g., server-side) filtering, bind to `value` and update `items` when
 
 <FileSource src="/framed/ComboBox/AsyncComboBox" />
 
+## Allow custom value
+
+Set `allowCustomValue` to `true` to let users enter custom text that isn't in the predefined list. By default, user-entered text is cleared when the combobox loses focus without selecting an item. When `allowCustomValue` is enabled, custom text is preserved.
+
+<FileSource src="/framed/ComboBox/AllowCustomValue" />
+
 ## Top direction
 
 Set `direction` to `"top"` to make the dropdown menu appear above the input.

docs/src/pages/components/ComboBox.svx

@@ -0,0 +1,33 @@
+<script>
+  import { ComboBox } from "carbon-components-svelte";
+
+  let selectedId = undefined;
+  let value = "";
+</script>
+
+<ComboBox
+  allowCustomValue
+  titleText="Favorite fruit"
+  placeholder="Select or enter a fruit"
+  helperText="You can select from the list or type your own"
+  bind:selectedId
+  bind:value
+  items={[
+    { id: "0", text: "Apple" },
+    { id: "1", text: "Banana" },
+    { id: "2", text: "Orange" },
+    { id: "3", text: "Strawberry" },
+  ]}
+  shouldFilterItem={(item, value) => {
+    if (!value) return true;
+    return item.text.toLowerCase().includes(value.toLowerCase());
+  }}
+  on:select={(e) => {
+    console.log("Selected item:", e.detail);
+  }}
+/>
+
+<div style:margin-top="var(--cds-layout-01)">
+  <div><strong>Selected ID:</strong> {selectedId ?? "none"}</div>
+  <div><strong>Current value:</strong> {value || "empty"}</div>
+</div>

docs/src/pages/framed/ComboBox/AllowCustomValue.svelte

@@ -73,6 +73,13 @@
   /** Set to `true` to open the combobox menu dropdown */
   export let open = false;
 
+  /**
+   * Set to `true` to allow custom values that are not in the items list.
+   * By default, user-entered text is cleared when the combobox loses focus without selecting an item.
+   * When enabled, custom text is preserved.
+   */
+  export let allowCustomValue = false;
+
   /**
    * Determine if an item should be filtered given the current combobox value
    * @type {(item: ComboBoxItem, value: string) => boolean}
@@ -177,8 +184,8 @@
       filteredItems = [];
       if (!selectedItem) {
         selectedId = undefined;
-        // Only reset value if the input is not focused
-        if (!ref.contains(document.activeElement)) {
+        // Only reset value if the input is not focused and allowCustomValue is false
+        if (!ref.contains(document.activeElement) && !allowCustomValue) {
           value = "";
         }
         highlightedIndex = -1;

src/ComboBox/ComboBox.svelte

@@ -27,6 +27,7 @@
   ) => item.text.toLowerCase().includes(value.toLowerCase());
   export let translateWithIdSelection: ComponentProps<ComboBox>["translateWithIdSelection"] =
     undefined;
+  export let allowCustomValue = false;
 </script>
 
 <ComboBox
@@ -47,6 +48,7 @@
   {warnText}
   {shouldFilterItem}
   {translateWithIdSelection}
+  {allowCustomValue}
   on:select={(e) => {
     console.log("select", e.detail);
   }}

tests/ComboBox/ComboBox.test.svelte

@@ -421,4 +421,53 @@ describe("ComboBox", () => {
     const dropdown = screen.queryAllByRole("listbox")[1];
     expect(dropdown).toBeUndefined();
   });
+
+  it("should preserve custom value when allowCustomValue is true and user clicks away", async () => {
+    render(ComboBox, { props: { allowCustomValue: true } });
+
+    const input = getInput();
+    await user.click(input);
+    await user.type(input, "Custom Value");
+    await user.click(document.body);
+    expect(input).toHaveValue("Custom Value");
+  });
+
+  it("should preserve custom value when allowCustomValue is true and menu closes", async () => {
+    render(ComboBox, { props: { allowCustomValue: true } });
+
+    const input = getInput();
+    await user.click(input);
+    await user.type(input, "My Custom Text");
+    await user.keyboard("{Tab}");
+    expect(input).toHaveValue("My Custom Text");
+  });
+
+  it("should clear custom value when allowCustomValue is false (default behavior)", async () => {
+    render(ComboBox);
+
+    const input = getInput();
+    await user.click(input);
+    await user.type(input, "Custom Value");
+    await user.click(document.body);
+    expect(input).toHaveValue("");
+  });
+
+  it("should preserve custom value when allowCustomValue is true and Enter is pressed", async () => {
+    render(ComboBox, { props: { allowCustomValue: true } });
+
+    const input = getInput();
+    await user.click(input);
+    await user.type(input, "New Custom Entry");
+    await user.keyboard("{Enter}");
+    expect(input).toHaveValue("New Custom Entry");
+  });
+
+  it("should still allow selecting items from list when allowCustomValue is true", async () => {
+    render(ComboBox, { props: { allowCustomValue: true } });
+
+    const input = getInput();
+    await user.click(input);
+    await user.click(screen.getByText("Email"));
+    expect(input).toHaveValue("Email");
+  });
 });

tests/ComboBox/ComboBox.test.ts

@@ -114,6 +114,14 @@ type $Props = {
    */
   open?: boolean;
 
+  /**
+   * Set to `true` to allow custom values that are not in the items list.
+   * By default, user-entered text is cleared when the combobox loses focus without selecting an item.
+   * When enabled, custom text is preserved.
+   * @default false
+   */
+  allowCustomValue?: boolean;
+
   /**
    * Determine if an item should be filtered given the current combobox value
    * @default () => true