@butternutbox/pawprint-native 1.6.3 → 2.0.0

package/src/components/molecules/SelectField/SelectField.test.tsx

@@ -1,777 +1,329 @@
 import React from "react"
-import { View } from "react-native"
-import { screen, fireEvent, act, waitFor } from "@testing-library/react"
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest"
-import { MEASURED_TRIGGER } from "../../../__mocks__/react-native"
+import { screen, fireEvent, waitFor } from "@testing-library/react"
+import { describe, it, expect, vi } from "vitest"
 import { renderWithTheme } from "../../../test-utils"
 import { SelectField } from "./SelectField"
+import type { SelectFieldOptionData } from "./SelectField"
+
+const COUNTRIES: SelectFieldOptionData[] = [
+  { value: "uk", label: "United Kingdom" },
+  { value: "us", label: "United States" },
+  { value: "ca", label: "Canada" },
+  { value: "au", label: "Australia" }
+]
+
+const renderField = (
+  props: Partial<React.ComponentProps<typeof SelectField>> = {}
+) => {
+  renderWithTheme(
+    <SelectField
+      label="Country"
+      placeholder="Select a country"
+      options={COUNTRIES}
+      {...props}
+    />
+  )
+
+  return screen.getByRole("combobox") as HTMLInputElement
+}
 
 describe("SelectField", () => {
-  describe("when using simple props API", () => {
-    it("renders label when provided", () => {
-      renderWithTheme(
-        <SelectField label="Country" placeholder="Select a country">
-          <SelectField.Item value="uk">United Kingdom</SelectField.Item>
-        </SelectField>
-      )
+  describe("field chrome", () => {
+    it("renders the label, description and optional text", () => {
+      renderField({ description: "Pick one", optionalText: "(optional)" })
 
       expect(screen.getByText("Country")).toBeInTheDocument()
-    })
-
-    it("renders description when provided", () => {
-      renderWithTheme(
-        <SelectField
-          label="Country"
-          placeholder="Select a country"
-          description="Choose your country"
-        >
-          <SelectField.Item value="uk">United Kingdom</SelectField.Item>
-        </SelectField>
-      )
-
-      expect(screen.getByText("Choose your country")).toBeInTheDocument()
-    })
-
-    it("renders error message when error prop and state='error' are provided", () => {
-      renderWithTheme(
-        <SelectField
-          label="Country"
-          placeholder="Select a country"
-          state="error"
-          error="Country is required"
-        >
-          <SelectField.Item value="uk">United Kingdom</SelectField.Item>
-        </SelectField>
-      )
-
-      expect(screen.getByText("Country is required")).toBeInTheDocument()
-    })
-
-    it("does not render error message when error prop is provided without state='error'", () => {
-      renderWithTheme(
-        <SelectField
-          label="Country"
-          placeholder="Select a country"
-          error="Country is required"
-        >
-          <SelectField.Item value="uk">United Kingdom</SelectField.Item>
-        </SelectField>
-      )
-
-      expect(screen.queryByText("Country is required")).not.toBeInTheDocument()
-    })
-
-    it("shows (optional) when optionalText is provided", () => {
-      renderWithTheme(
-        <SelectField
-          label="Country"
-          placeholder="Select a country"
-          optionalText="(optional)"
-        >
-          <SelectField.Item value="uk">United Kingdom</SelectField.Item>
-        </SelectField>
-      )
-
+      expect(screen.getByText("Pick one")).toBeInTheDocument()
       expect(screen.getByText("(optional)")).toBeInTheDocument()
     })
 
-    it("renders the component structure", () => {
-      renderWithTheme(
-        <SelectField label="Country" placeholder="Select a country">
-          <SelectField.Item value="uk">United Kingdom</SelectField.Item>
-        </SelectField>
-      )
+    it("renders the error message whenever error is set", () => {
+      renderField({ error: "Please choose a country" })
 
-      expect(screen.getByText("Country")).toBeInTheDocument()
+      expect(screen.getByText("Please choose a country")).toBeInTheDocument()
     })
-  })
-
-  describe("when using controlled mode", () => {
-    it("renders with controlled value", () => {
-      const onValueChange = vi.fn()
 
-      renderWithTheme(
-        <SelectField
-          label="Country"
-          value="uk"
-          onValueChange={onValueChange}
-          placeholder="Select a country"
-        >
-          <SelectField.Item value="uk">United Kingdom</SelectField.Item>
-          <SelectField.Item value="us">United States</SelectField.Item>
-        </SelectField>
-      )
+    it("is not editable when disabled", () => {
+      const input = renderField({ disabled: true })
 
-      expect(screen.getByText("Country")).toBeInTheDocument()
+      expect(input).toBeDisabled()
     })
   })
 
-  describe("when disabled", () => {
-    it("renders disabled state", () => {
-      renderWithTheme(
-        <SelectField label="Country" placeholder="Select a country" disabled>
-          <SelectField.Item value="uk">United Kingdom</SelectField.Item>
-        </SelectField>
-      )
+  describe("opening and closing", () => {
+    it("shows every option on focus", () => {
+      const input = renderField()
+      fireEvent.focus(input)
 
-      expect(screen.getByText("Country")).toBeInTheDocument()
+      COUNTRIES.forEach((option) => {
+        expect(screen.getByText(option.label)).toBeInTheDocument()
+      })
     })
-  })
 
-  describe("validation states", () => {
-    it("shows error state with error message", () => {
-      renderWithTheme(
-        <SelectField
-          label="Country"
-          placeholder="Select a country"
-          state="error"
-          error="Country is required"
-        >
-          <SelectField.Item value="uk">United Kingdom</SelectField.Item>
-        </SelectField>
-      )
+    it("stays closed until the field is focused", () => {
+      renderField()
 
-      expect(screen.getByText("Country is required")).toBeInTheDocument()
+      expect(screen.queryByText("United Kingdom")).not.toBeInTheDocument()
     })
 
-    it("renders success state", () => {
-      renderWithTheme(
-        <SelectField
-          label="Country"
-          placeholder="Select a country"
-          state="success"
-        >
-          <SelectField.Item value="uk">United Kingdom</SelectField.Item>
-        </SelectField>
-      )
-
-      expect(screen.getByText("Country")).toBeInTheDocument()
-    })
-  })
+    it("closes on blur", async () => {
+      const input = renderField()
+      fireEvent.focus(input)
+      fireEvent.blur(input)
 
-  describe("when using compound component API", () => {
-    it("renders compound components", () => {
-      renderWithTheme(
-        <SelectField.Root>
-          <SelectField.Label>Country</SelectField.Label>
-          <SelectField.Trigger>
-            <SelectField.Value placeholder="Select a country" />
-          </SelectField.Trigger>
-          <SelectField.Content>
-            <SelectField.Item value="uk">United Kingdom</SelectField.Item>
-          </SelectField.Content>
-          <SelectField.Description>Choose your country</SelectField.Description>
-        </SelectField.Root>
+      await waitFor(() =>
+        expect(screen.queryByText("United Kingdom")).not.toBeInTheDocument()
       )
-
-      expect(screen.getByText("Country")).toBeInTheDocument()
-      expect(screen.getByText("Choose your country")).toBeInTheDocument()
     })
 
-    it("renders error in compound mode", () => {
-      renderWithTheme(
-        <SelectField.Root>
-          <SelectField.Label state="error">Country</SelectField.Label>
-          <SelectField.Trigger state="error">
-            <SelectField.Value placeholder="Select a country" />
-          </SelectField.Trigger>
-          <SelectField.Content>
-            <SelectField.Item value="uk">United Kingdom</SelectField.Item>
-          </SelectField.Content>
-          <SelectField.Error>Country is required</SelectField.Error>
-        </SelectField.Root>
-      )
-
-      expect(screen.getByText("Country is required")).toBeInTheDocument()
-    })
-  })
+    it("does not open when disabled", () => {
+      const input = renderField({ disabled: true })
+      fireEvent.focus(input)
 
-  describe("when using with ref", () => {
-    it("forwards ref to root element", () => {
-      const ref = React.createRef<View>()
-      renderWithTheme(<SelectField ref={ref} label="Test" />)
-      expect(ref.current).toBeTruthy()
+      expect(screen.queryByText("United Kingdom")).not.toBeInTheDocument()
     })
   })
 
-  describe("uncontrolled mode with defaultValue", () => {
-    it("renders with defaultValue without crashing and shows items when opened", () => {
+  describe("portal", () => {
+    it("renders the dropdown outside the field's own subtree", () => {
       renderWithTheme(
         <SelectField
           label="Country"
           placeholder="Select a country"
-          defaultValue="uk"
-        >
-          <SelectField.Item value="uk">United Kingdom</SelectField.Item>
-          <SelectField.Item value="us">United States</SelectField.Item>
-        </SelectField>
+          options={COUNTRIES}
+        />
       )
 
-      fireEvent.click(screen.getAllByRole("button")[0])
-      expect(screen.getByText("United Kingdom")).toBeInTheDocument()
-    })
-  })
-
-  describe("when searchable", () => {
-    const openDropdown = () => {
-      fireEvent.click(screen.getAllByRole("button")[0])
-    }
-
-    const openDropdownWithContent = () => {
-      vi.useFakeTimers()
-      fireEvent.click(screen.getAllByRole("button")[0])
-      act(() => vi.advanceTimersByTime(500))
-      vi.useRealTimers()
-    }
+      const input = screen.getByRole("combobox") as HTMLInputElement
+      fireEvent.focus(input)
 
-    it("shows search input in the trigger when dropdown is opened", () => {
-      renderWithTheme(
-        <SelectField label="Country" placeholder="Select a country" searchable>
-          <SelectField.Item value="uk">United Kingdom</SelectField.Item>
-          <SelectField.Item value="us">United States</SelectField.Item>
-        </SelectField>
-      )
+      const row = screen.getByText("Canada")
+      const fieldRoot = input.closest("div")
 
-      expect(screen.queryByPlaceholderText("Search...")).not.toBeInTheDocument()
-      openDropdown()
-      expect(screen.getByPlaceholderText("Search...")).toBeInTheDocument()
+      expect(row).toBeInTheDocument()
+      expect(fieldRoot?.contains(row)).toBe(false)
     })
 
-    it("does not show search input when not searchable", () => {
-      renderWithTheme(
-        <SelectField label="Country" placeholder="Select a country">
-          <SelectField.Item value="uk">United Kingdom</SelectField.Item>
-          <SelectField.Item value="us">United States</SelectField.Item>
-        </SelectField>
-      )
-
-      openDropdown()
-      expect(screen.queryByPlaceholderText("Search...")).not.toBeInTheDocument()
-    })
+    it("removes the dropdown from the host when it closes", async () => {
+      const input = renderField()
+      fireEvent.focus(input)
+      expect(screen.getByText("Canada")).toBeInTheDocument()
 
-    it("renders with a custom searchPlaceholder", () => {
-      renderWithTheme(
-        <SelectField
-          label="Country"
-          placeholder="Select a country"
-          searchable
-          searchPlaceholder="Find a country..."
-        >
-          <SelectField.Item value="uk">United Kingdom</SelectField.Item>
-        </SelectField>
+      fireEvent.blur(input)
+      await waitFor(() =>
+        expect(screen.queryByText("Canada")).not.toBeInTheDocument()
       )
-
-      openDropdown()
-      expect(
-        screen.getByPlaceholderText("Find a country...")
-      ).toBeInTheDocument()
     })
+  })
 
-    it("filters items based on the search query", () => {
-      renderWithTheme(
-        <SelectField label="Country" placeholder="Select a country" searchable>
-          <SelectField.Item value="uk">United Kingdom</SelectField.Item>
-          <SelectField.Item value="us">United States</SelectField.Item>
-          <SelectField.Item value="ca">Canada</SelectField.Item>
-        </SelectField>
-      )
-
-      openDropdownWithContent()
-      fireEvent.change(screen.getByPlaceholderText("Search..."), {
-        target: { value: "united" }
-      })
+  describe("filtering", () => {
+    it("matches on a substring, case-insensitively", () => {
+      const input = renderField()
+      fireEvent.focus(input)
+      fireEvent.change(input, { target: { value: " united" } })
 
       expect(screen.getByText("United Kingdom")).toBeInTheDocument()
       expect(screen.getByText("United States")).toBeInTheDocument()
       expect(screen.queryByText("Canada")).not.toBeInTheDocument()
     })
 
-    it("is case-insensitive when filtering", () => {
-      renderWithTheme(
-        <SelectField label="Country" placeholder="Select a country" searchable>
-          <SelectField.Item value="uk">United Kingdom</SelectField.Item>
-          <SelectField.Item value="ca">Canada</SelectField.Item>
-        </SelectField>
-      )
-
-      openDropdownWithContent()
-      fireEvent.change(screen.getByPlaceholderText("Search..."), {
-        target: { value: "CANADA" }
+    it("orders starts-with matches ahead of contains matches", () => {
+      const input = renderField({
+        options: [
+          { value: "scan", label: "Canine scan" },
+          { value: "ca", label: "Canada" },
+          { value: "af", label: "Africa" }
+        ]
       })
+      fireEvent.focus(input)
+      fireEvent.change(input, { target: { value: "ca" } })
 
-      expect(screen.getByText("Canada")).toBeInTheDocument()
-      expect(screen.queryByText("United Kingdom")).not.toBeInTheDocument()
-    })
+      const rendered = screen
+        .getAllByRole("button")
+        .map((row) => row.textContent)
+        .filter((text) => text && text.length > 0)
 
-    it("shows default 'No results found' when search matches no items", () => {
-      renderWithTheme(
-        <SelectField label="Country" placeholder="Select a country" searchable>
-          <SelectField.Item value="uk">United Kingdom</SelectField.Item>
-          <SelectField.Item value="us">United States</SelectField.Item>
-        </SelectField>
+      expect(rendered.indexOf("Canine scan")).toBeLessThan(
+        rendered.indexOf("Africa")
       )
-
-      openDropdownWithContent()
-      fireEvent.change(screen.getByPlaceholderText("Search..."), {
-        target: { value: "xyz" }
-      })
-
-      expect(screen.getByText("No results found")).toBeInTheDocument()
-    })
-
-    it("shows custom noResultsText when provided", () => {
-      renderWithTheme(
-        <SelectField
-          label="Country"
-          placeholder="Select a country"
-          searchable
-          noResultsText="No countries match your search"
-        >
-          <SelectField.Item value="uk">United Kingdom</SelectField.Item>
-        </SelectField>
+      expect(rendered.indexOf("Canada")).toBeLessThan(
+        rendered.indexOf("Africa")
       )
-
-      openDropdownWithContent()
-      fireEvent.change(screen.getByPlaceholderText("Search..."), {
-        target: { value: "xyz" }
-      })
-
-      expect(
-        screen.getByText("No countries match your search")
-      ).toBeInTheDocument()
     })
 
-    it("shows all items when search query is cleared", () => {
-      renderWithTheme(
-        <SelectField label="Country" placeholder="Select a country" searchable>
-          <SelectField.Item value="uk">United Kingdom</SelectField.Item>
-          <SelectField.Item value="ca">Canada</SelectField.Item>
-        </SelectField>
-      )
-
-      openDropdownWithContent()
-      const input = screen.getByPlaceholderText("Search...")
-      fireEvent.change(input, { target: { value: "canada" } })
-      expect(screen.queryByText("United Kingdom")).not.toBeInTheDocument()
+    it("shows the no-results row when nothing matches", () => {
+      const input = renderField({ noResultsText: "No countries found" })
+      fireEvent.focus(input)
+      fireEvent.change(input, { target: { value: "zzzz" } })
 
-      fireEvent.change(input, { target: { value: "" } })
-      expect(screen.getByText("United Kingdom")).toBeInTheDocument()
-      expect(screen.getByText("Canada")).toBeInTheDocument()
-    })
-
-    it("closes the dropdown and clears the search when closed", () => {
-      renderWithTheme(
-        <SelectField label="Country" placeholder="Select a country" searchable>
-          <SelectField.Item value="uk">United Kingdom</SelectField.Item>
-          <SelectField.Item value="ca">Canada</SelectField.Item>
-        </SelectField>
-      )
-
-      openDropdownWithContent()
-      fireEvent.change(screen.getByPlaceholderText("Search..."), {
-        target: { value: "canada" }
-      })
-      expect(screen.queryByText("United Kingdom")).not.toBeInTheDocument()
-
-      fireEvent.click(screen.getByTestId("select-overlay"))
-      expect(screen.queryByPlaceholderText("Search...")).not.toBeInTheDocument()
+      expect(screen.getByText("No countries found")).toBeInTheDocument()
+      expect(screen.queryByText("Canada")).not.toBeInTheDocument()
     })
 
-    it("re-focuses the search input when it blurs while the dropdown is open", () => {
-      renderWithTheme(
-        <SelectField label="Country" placeholder="Select a country" searchable>
-          <SelectField.Item value="uk">United Kingdom</SelectField.Item>
-        </SelectField>
-      )
+    it("resets the filter on refocus so the full list shows again", () => {
+      const input = renderField()
+      fireEvent.focus(input)
+      fireEvent.change(input, { target: { value: "united" } })
+      fireEvent.blur(input)
+      fireEvent.focus(input)
 
-      openDropdownWithContent()
-      const input = screen.getByPlaceholderText("Search...")
-      vi.useFakeTimers()
-      input.blur()
-      expect(input).not.toHaveFocus()
-
-      act(() => vi.advanceTimersByTime(50))
-      vi.useRealTimers()
-      expect(input).toHaveFocus()
+      expect(screen.getByText("Canada")).toBeInTheDocument()
     })
   })
 
-  describe("when searchable with an async query", () => {
-    type Result = { value: string; label: string }
-
-    const openAndType = (query: string) => {
-      fireEvent.click(screen.getAllByRole("button")[0])
-      const input = screen.getByPlaceholderText("Search...")
-      fireEvent.change(input, { target: { value: query } })
-    }
-
-    it("shows children as the default list before the user types", async () => {
-      const onSearchQuery = vi.fn(async (): Promise<Result[]> => [])
-
-      renderWithTheme(
-        <SelectField
-          label="Breed"
-          placeholder="Select a breed"
-          searchable
-          debounceMs={0}
-          onSearchQuery={onSearchQuery}
-        >
-          <SelectField.Item value="popular">Most popular</SelectField.Item>
-        </SelectField>
-      )
-
-      fireEvent.click(screen.getAllByRole("button")[0])
-
-      expect(await screen.findByText("Most popular")).toBeInTheDocument()
-      expect(onSearchQuery).not.toHaveBeenCalled()
-    })
-
-    it("does not open an empty dropdown in query mode before the user types", () => {
-      const onSearchQuery = vi.fn(async (): Promise<Result[]> => [])
-
-      renderWithTheme(
-        <SelectField
-          label="Breed"
-          placeholder="Select a breed"
-          searchable
-          debounceMs={0}
-          onSearchQuery={onSearchQuery}
-        />
-      )
-
-      vi.useFakeTimers()
-      fireEvent.click(screen.getAllByRole("button")[0])
-      act(() => vi.advanceTimersByTime(500))
-      vi.useRealTimers()
-
-      // Trigger is open (search input shown) but no content container is
-      // rendered: an empty dropdown crashes the real Select.Content on web.
-      expect(screen.getByPlaceholderText("Search...")).toBeInTheDocument()
-      expect(screen.queryByTestId("select-overlay")).not.toBeInTheDocument()
-      expect(onSearchQuery).not.toHaveBeenCalled()
-    })
-
-    it("calls onSearchQuery with the typed query and renders the results", async () => {
-      const onSearchQuery = vi.fn(
-        async (): Promise<Result[]> => [
-          { value: "labrador", label: "Labrador Retriever" }
-        ]
-      )
-
-      renderWithTheme(
-        <SelectField
-          label="Breed"
-          placeholder="Select a breed"
-          searchable
-          debounceMs={0}
-          onSearchQuery={onSearchQuery}
-        />
-      )
-
-      openAndType("lab")
+  describe("selecting", () => {
+    it("sets the input text to the option label and emits its value", () => {
+      const onValueChange = vi.fn()
+      const input = renderField({ onValueChange })
+      fireEvent.focus(input)
+      fireEvent.click(screen.getByText("Canada"))
 
-      expect(await screen.findByText("Labrador Retriever")).toBeInTheDocument()
-      expect(onSearchQuery).toHaveBeenCalledWith("lab")
+      expect(onValueChange).toHaveBeenCalledWith("ca")
+      expect(input).toHaveValue("Canada")
     })
 
-    it("shows a loading spinner while the query is in flight", async () => {
-      let resolveQuery: (results: Result[]) => void = () => {}
-      const onSearchQuery = vi.fn(
-        () =>
-          new Promise<Result[]>((resolve) => {
-            resolveQuery = resolve
-          })
-      )
-
-      renderWithTheme(
-        <SelectField
-          label="Breed"
-          placeholder="Select a breed"
-          searchable
-          debounceMs={0}
-          onSearchQuery={onSearchQuery}
-        />
-      )
-
-      openAndType("lab")
-
-      expect(await screen.findByRole("progressbar")).toBeInTheDocument()
+    it("closes the dropdown after selecting", () => {
+      const input = renderField()
+      fireEvent.focus(input)
+      fireEvent.click(screen.getByText("Canada"))
+      fireEvent.blur(input)
 
-      await waitFor(() => expect(onSearchQuery).toHaveBeenCalled())
-      act(() => resolveQuery([{ value: "labrador", label: "Labrador" }]))
-
-      expect(await screen.findByText("Labrador")).toBeInTheDocument()
-      expect(screen.queryByRole("progressbar")).not.toBeInTheDocument()
+      expect(screen.queryByText("Australia")).not.toBeInTheDocument()
     })
 
-    it("shows errorText when the query rejects", async () => {
-      const onSearchQuery = vi.fn(async (): Promise<Result[]> => {
-        throw new Error("boom")
+    it("does not emit for a disabled option", () => {
+      const onValueChange = vi.fn()
+      const input = renderField({
+        onValueChange,
+        options: [{ value: "uk", label: "United Kingdom", disabled: true }]
       })
+      fireEvent.focus(input)
+      fireEvent.click(screen.getByText("United Kingdom"))
 
-      renderWithTheme(
-        <SelectField
-          label="Breed"
-          placeholder="Select a breed"
-          searchable
-          debounceMs={0}
-          errorText="Couldn't load breeds"
-          onSearchQuery={onSearchQuery}
-        />
-      )
-
-      openAndType("lab")
-
-      expect(
-        await screen.findByText("Couldn't load breeds")
-      ).toBeInTheDocument()
+      expect(onValueChange).not.toHaveBeenCalled()
     })
 
-    it("shows noResultsText when the query resolves empty", async () => {
-      const onSearchQuery = vi.fn(async (): Promise<Result[]> => [])
+    it("marks the committed option as selected", () => {
+      const input = renderField({ defaultValue: "ca" })
+      fireEvent.focus(input)
 
-      renderWithTheme(
-        <SelectField
-          label="Breed"
-          placeholder="Select a breed"
-          searchable
-          debounceMs={0}
-          noResultsText="No breeds found"
-          onSearchQuery={onSearchQuery}
-        />
-      )
+      const selected = screen
+        .getAllByRole("button")
+        .find((row) => row.textContent === "Canada")
 
-      openAndType("xyz")
-
-      expect(await screen.findByText("No breeds found")).toBeInTheDocument()
+      expect(selected).toHaveAttribute("aria-selected", "true")
     })
+  })
 
-    it("renders results instead of locally filtering children in query mode", async () => {
-      const onSearchQuery = vi.fn(
-        async (): Promise<Result[]> => [
-          { value: "labrador", label: "Labrador Retriever" }
-        ]
-      )
-
-      renderWithTheme(
-        <SelectField
-          label="Breed"
-          placeholder="Select a breed"
-          searchable
-          debounceMs={0}
-          onSearchQuery={onSearchQuery}
-        >
-          <SelectField.Item value="uk">United Kingdom</SelectField.Item>
-        </SelectField>
-      )
-
-      openAndType("lab")
-
-      expect(await screen.findByText("Labrador Retriever")).toBeInTheDocument()
-      expect(screen.queryByText("United Kingdom")).not.toBeInTheDocument()
-    })
-
-    it("debounces the query, firing once after the last keystroke", () => {
-      const onSearchQuery = vi.fn(
-        async (): Promise<Result[]> => [
-          { value: "labrador", label: "Labrador Retriever" }
-        ]
-      )
-
-      renderWithTheme(
-        <SelectField
-          label="Breed"
-          placeholder="Select a breed"
-          searchable
-          debounceMs={300}
-          onSearchQuery={onSearchQuery}
-        />
-      )
-
-      vi.useFakeTimers()
-      fireEvent.click(screen.getAllByRole("button")[0])
-      const input = screen.getByPlaceholderText("Search...")
-
-      fireEvent.change(input, { target: { value: "l" } })
-      act(() => vi.advanceTimersByTime(200))
-      fireEvent.change(input, { target: { value: "la" } })
-      act(() => vi.advanceTimersByTime(200))
-      fireEvent.change(input, { target: { value: "lab" } })
-
-      // Each keystroke restarted the timer, so nothing has fired yet even
-      // though 400ms of typing has elapsed.
-      expect(onSearchQuery).not.toHaveBeenCalled()
+  describe("selection vs blur", () => {
+    it("selects even when the row press also blurs the field", async () => {
+      const onValueChange = vi.fn()
+      const input = renderField({ onValueChange })
+      fireEvent.focus(input)
 
-      act(() => vi.advanceTimersByTime(300))
-      vi.useRealTimers()
+      const row = screen.getByText("Canada")
+      fireEvent.blur(input)
+      fireEvent.click(row)
 
-      expect(onSearchQuery).toHaveBeenCalledTimes(1)
-      expect(onSearchQuery).toHaveBeenCalledWith("lab")
+      await waitFor(() => expect(input).toHaveValue("Canada"))
+      expect(onValueChange).toHaveBeenLastCalledWith("ca")
     })
 
-    it("ignores a stale response superseded by a later keystroke", async () => {
-      const resolvers: Array<(results: Result[]) => void> = []
-      const onSearchQuery = vi.fn(
-        () =>
-          new Promise<Result[]>((resolve) => {
-            resolvers.push(resolve)
-          })
-      )
-
-      renderWithTheme(
-        <SelectField
-          label="Breed"
-          placeholder="Select a breed"
-          searchable
-          debounceMs={0}
-          onSearchQuery={onSearchQuery}
-        />
-      )
-
-      fireEvent.click(screen.getAllByRole("button")[0])
-      const input = screen.getByPlaceholderText("Search...")
-
-      fireEvent.change(input, { target: { value: "lab" } })
-      await waitFor(() => expect(resolvers).toHaveLength(1))
-
-      fireEvent.change(input, { target: { value: "labr" } })
-      await waitFor(() => expect(resolvers).toHaveLength(2))
-
-      // The newer query lands first, then the superseded one resolves late.
-      await act(async () => {
-        resolvers[1]([{ value: "labrador", label: "Labrador Retriever" }])
-      })
-      expect(screen.getByText("Labrador Retriever")).toBeInTheDocument()
+    it("does not overwrite the selection with a blur commit", async () => {
+      const onValueChange = vi.fn()
+      const input = renderField({ onValueChange })
+      fireEvent.focus(input)
+      fireEvent.change(input, { target: { value: "can" } })
 
-      await act(async () => {
-        resolvers[0]([{ value: "stale", label: "Stale Result" }])
-      })
+      const row = screen.getByText("Canada")
+      fireEvent.blur(input)
+      fireEvent.click(row)
 
-      expect(screen.queryByText("Stale Result")).not.toBeInTheDocument()
-      expect(screen.getByText("Labrador Retriever")).toBeInTheDocument()
+      await waitFor(() => expect(input).toHaveValue("Canada"))
+      expect(onValueChange).not.toHaveBeenCalledWith(null)
     })
   })
 
-  describe("with items", () => {
-    const openDropdown = () => fireEvent.click(screen.getAllByRole("button")[0])
-
-    it("renders items with leadingIcon", () => {
-      renderWithTheme(
-        <SelectField label="Country" placeholder="Select a country">
-          <SelectField.Item
-            value="uk"
-            leadingIcon={<div data-testid="icon">🇬🇧</div>}
-          >
-            United Kingdom
-          </SelectField.Item>
-        </SelectField>
-      )
-
-      openDropdown()
-      expect(screen.getByTestId("icon")).toBeInTheDocument()
-    })
-
-    it("renders items with hintText", () => {
-      renderWithTheme(
-        <SelectField label="Country" placeholder="Select a country">
-          <SelectField.Item value="uk" hintText="Europe">
-            United Kingdom
-          </SelectField.Item>
-        </SelectField>
-      )
+  describe("free text", () => {
+    it("keeps the typed text and emits null when nothing matches", async () => {
+      const onValueChange = vi.fn()
+      const input = renderField({ onValueChange, defaultValue: "ca" })
+      fireEvent.focus(input)
+      fireEvent.change(input, { target: { value: "xyz" } })
+      fireEvent.blur(input)
 
-      openDropdown()
-      expect(screen.getByText("Europe")).toBeInTheDocument()
+      expect(input).toHaveValue("xyz")
+      await waitFor(() => expect(onValueChange).toHaveBeenLastCalledWith(null))
     })
 
-    it("renders disabled items", () => {
-      renderWithTheme(
-        <SelectField label="Country" placeholder="Select a country">
-          <SelectField.Item value="uk" disabled>
-            United Kingdom
-          </SelectField.Item>
-        </SelectField>
-      )
+    it("commits an exactly typed label without selecting from the list", async () => {
+      const onValueChange = vi.fn()
+      const input = renderField({ onValueChange })
+      fireEvent.focus(input)
+      fireEvent.change(input, { target: { value: "canada" } })
+      fireEvent.blur(input)
 
-      openDropdown()
-      const item = screen.getByText("United Kingdom")
-      expect(item).toBeInTheDocument()
+      await waitFor(() => expect(onValueChange).toHaveBeenLastCalledWith("ca"))
     })
   })
-  describe("when the field moves while the dropdown is open", () => {
-    const restingPageY = MEASURED_TRIGGER.pageY
 
-    beforeEach(() => {
-      vi.useFakeTimers()
-    })
+  describe("clearing", () => {
+    it("is hidden while the field is empty", () => {
+      renderField()
 
-    afterEach(() => {
-      MEASURED_TRIGGER.pageY = restingPageY
-      vi.useRealTimers()
+      expect(screen.queryByLabelText("Clear selection")).not.toBeInTheDocument()
     })
 
-    const renderSearchable = () =>
-      renderWithTheme(
-        <SelectField label="Breed" placeholder="Select a breed" searchable>
-          <SelectField.Item value="lab">Labrador</SelectField.Item>
-          <SelectField.Item value="pug">Pug</SelectField.Item>
-        </SelectField>
-      )
-
-    const triggerPositionOf = (container: HTMLElement) =>
-      container
-        .querySelector("[data-trigger-position]")
-        ?.getAttribute("data-trigger-position")
-
-    const advanceFrames = (count: number) =>
-      act(() => vi.advanceTimersByTime(count * 16))
-
-    it("anchors the dropdown to the field once it has opened", () => {
-      const { container } = renderSearchable()
+    it("appears once there is text and empties the field", () => {
+      const onValueChange = vi.fn()
+      const input = renderField({ onValueChange, defaultValue: "ca" })
 
-      fireEvent.click(screen.getAllByRole("button")[0])
-      advanceFrames(3)
+      fireEvent.click(screen.getByLabelText("Clear selection"))
 
-      expect(triggerPositionOf(container)).toBe(
-        JSON.stringify(MEASURED_TRIGGER)
-      )
+      expect(input).toHaveValue("")
+      expect(onValueChange).toHaveBeenCalledWith(null)
     })
 
-    it("follows the field to where it comes to rest", () => {
-      const { container } = renderSearchable()
+    it("shows the full list again after clearing", () => {
+      const input = renderField({ defaultValue: "ca" })
+      fireEvent.focus(input)
+      fireEvent.click(screen.getByLabelText("Clear selection"))
 
-      fireEvent.click(screen.getAllByRole("button")[0])
-      advanceFrames(3)
-      MEASURED_TRIGGER.pageY = 380
-      advanceFrames(3)
-
-      expect(triggerPositionOf(container)).toBe(
-        JSON.stringify({ ...MEASURED_TRIGGER, pageY: 380 })
-      )
+      expect(screen.getByText("Australia")).toBeInTheDocument()
     })
+  })
 
-    it("holds the dropdown in place while the field is still moving", () => {
-      const { container } = renderSearchable()
+  describe("controlled mode", () => {
+    it("shows the label for the controlled value", () => {
+      const input = renderField({ value: "au" })
 
-      fireEvent.click(screen.getAllByRole("button")[0])
-      advanceFrames(3)
+      expect(input).toHaveValue("Australia")
+    })
 
-      for (const pageY of [650, 600, 550]) {
-        MEASURED_TRIGGER.pageY = pageY
-        advanceFrames(1)
-      }
+    it("does not change its own value when controlled", () => {
+      const input = renderField({ value: "au", onValueChange: vi.fn() })
+      fireEvent.focus(input)
+      fireEvent.click(screen.getByText("Canada"))
+      fireEvent.blur(input)
 
-      expect(triggerPositionOf(container)).toBe(
-        JSON.stringify({ ...MEASURED_TRIGGER, pageY: restingPageY })
-      )
+      expect(input).toHaveValue("Australia")
     })
+  })
+
+  describe("regression", () => {
+    it("keeps focus on the input while the filtered list changes", () => {
+      const input = renderField()
+      fireEvent.focus(input)
+      input.focus()
 
-    it("does not track the field while the dropdown is closed", () => {
-      const { container } = renderSearchable()
+      fireEvent.change(input, { target: { value: "u" } })
+      expect(document.activeElement).toBe(input)
 
-      advanceFrames(3)
+      fireEvent.change(input, { target: { value: "un" } })
+      expect(document.activeElement).toBe(input)
 
-      expect(triggerPositionOf(container)).toBeUndefined()
+      fireEvent.change(input, { target: { value: "zzz" } })
+      expect(document.activeElement).toBe(input)
     })
   })
 })