@etus/ui 0.1.0

package/src/components/forms/Autocomplete/Autocomplete.test.tsx

@@ -0,0 +1,2351 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion, @typescript-eslint/require-await -- Test file: non-null assertions are safe with known test data */
+import type { AutocompleteOption } from "./Autocomplete.types"
+
+// Autocomplete/Autocomplete.test.tsx
+import { act, render, screen, waitFor, within } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { axe, toHaveNoViolations } from "jest-axe"
+import * as React from "react"
+import { describe, expect, it, vi } from "vitest"
+
+import { Autocomplete } from "./Autocomplete"
+
+expect.extend(toHaveNoViolations)
+
+// Default test options
+const defaultOptions: AutocompleteOption[] = [
+  { value: "apple", label: "Apple" },
+  { value: "banana", label: "Banana" },
+  { value: "orange", label: "Orange" },
+]
+
+// ============================================
+// RENDERING TESTS
+// ============================================
+describe("Autocomplete", () => {
+  describe("Rendering", () => {
+    it("renders correctly", () => {
+      render(<Autocomplete aria-label="Test autocomplete" options={defaultOptions} />)
+      expect(screen.getByRole("combobox")).toBeInTheDocument()
+    })
+
+    it("renders with custom className", () => {
+      render(
+        <Autocomplete
+          aria-label="Test autocomplete"
+          className="custom-class"
+          options={defaultOptions}
+        />
+      )
+      expect(screen.getByRole("combobox").closest('[data-slot="autocomplete"]')).toHaveClass(
+        "custom-class"
+      )
+    })
+
+    it("renders with placeholder", () => {
+      render(
+        <Autocomplete
+          aria-label="Test autocomplete"
+          options={defaultOptions}
+          placeholder="Type to search..."
+        />
+      )
+      expect(screen.getByPlaceholderText("Type to search...")).toBeInTheDocument()
+    })
+
+    it("renders with default value", () => {
+      render(
+        <Autocomplete
+          aria-label="Test autocomplete"
+          defaultValue="apple"
+          options={defaultOptions}
+        />
+      )
+      expect(screen.getByRole("combobox")).toHaveValue("Apple")
+    })
+
+    it("renders with controlled value", () => {
+      render(
+        <Autocomplete
+          aria-label="Test autocomplete"
+          options={defaultOptions}
+          value="banana"
+          onChange={() => {}}
+        />
+      )
+      expect(screen.getByRole("combobox")).toHaveValue("Banana")
+    })
+
+    it("has data-slot attribute", () => {
+      render(<Autocomplete aria-label="Test autocomplete" options={defaultOptions} />)
+      expect(
+        screen.getByRole("combobox").closest('[data-slot="autocomplete"]')
+      ).toBeInTheDocument()
+    })
+
+    it("passes through data-* attributes", () => {
+      render(
+        <Autocomplete
+          aria-label="Test autocomplete"
+          data-custom="value"
+          options={defaultOptions}
+        />
+      )
+      expect(
+        screen.getByRole("combobox").closest('[data-slot="autocomplete"]')
+      ).toHaveAttribute("data-custom", "value")
+    })
+  })
+
+  // ============================================
+  // INPUT TYPING TESTS
+  // ============================================
+  describe("Input Typing", () => {
+    it("updates input value when typing", async () => {
+      const user = userEvent.setup()
+      render(<Autocomplete aria-label="Test autocomplete" options={defaultOptions} />)
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "app")
+
+      expect(input).toHaveValue("app")
+    })
+
+    it("opens dropdown when typing meets minChars", async () => {
+      const user = userEvent.setup()
+      render(
+        <Autocomplete aria-label="Test autocomplete" minChars={2} options={defaultOptions} />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "a")
+
+      // Should not open with just 1 char when minChars is 2
+      expect(screen.queryByRole("listbox")).not.toBeInTheDocument()
+
+      await user.type(input, "p")
+
+      // Should open after 2 chars
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+    })
+
+    it("does not open dropdown when below minChars", async () => {
+      const user = userEvent.setup()
+      render(
+        <Autocomplete aria-label="Test autocomplete" minChars={3} options={defaultOptions} />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "ap")
+
+      expect(screen.queryByRole("listbox")).not.toBeInTheDocument()
+    })
+  })
+
+  // ============================================
+  // LOADING STATE TESTS
+  // ============================================
+  describe("Loading State", () => {
+    it("shows loading spinner when loading is true", async () => {
+      const user = userEvent.setup()
+      render(
+        <Autocomplete aria-label="Test autocomplete" loading={true} options={[]} />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "test")
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      // Should show loading message
+      expect(screen.getByText("Loading...")).toBeInTheDocument()
+    })
+
+    it("uses custom loading message", async () => {
+      const user = userEvent.setup()
+      render(
+        <Autocomplete
+          aria-label="Test autocomplete"
+          loading={true}
+          loadingMessage="Fetching results..."
+          options={[]}
+        />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "test")
+
+      await waitFor(() => {
+        expect(screen.getByText("Fetching results...")).toBeInTheDocument()
+      })
+    })
+
+    it("has data-loading attribute when loading", () => {
+      render(
+        <Autocomplete aria-label="Test autocomplete" loading={true} options={defaultOptions} />
+      )
+      expect(
+        screen.getByRole("combobox").closest('[data-slot="autocomplete"]')
+      ).toHaveAttribute("data-loading")
+    })
+
+    it("shows spinner in input when loading", () => {
+      render(
+        <Autocomplete aria-label="Test autocomplete" loading={true} options={defaultOptions} />
+      )
+      expect(screen.getByRole("combobox").closest('[data-slot="autocomplete"]')?.querySelector('[data-slot="autocomplete-spinner"]')).toBeInTheDocument()
+    })
+  })
+
+  // ============================================
+  // DEBOUNCE TESTS
+  // ============================================
+  describe("Debounce", () => {
+    it("debounces onInputChange calls", () => {
+      vi.useFakeTimers()
+      const handleInputChange = vi.fn()
+      render(
+        <Autocomplete
+          aria-label="Test autocomplete"
+          debounceMs={300}
+          options={defaultOptions}
+          onInputChange={handleInputChange}
+        />
+      )
+
+      const input = screen.getByRole("combobox")
+
+      // Type characters using fireEvent for fake timers compatibility
+      act(() => {
+        input.focus()
+        // Simulate typing
+        ;["a", "ap", "app"].forEach((val) => {
+          Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, "value")?.set?.call(input, val)
+          input.dispatchEvent(new Event("input", { bubbles: true }))
+        })
+      })
+
+      // Should not have been called yet (still debouncing)
+      expect(handleInputChange).not.toHaveBeenCalled()
+
+      // Fast-forward past debounce time
+      act(() => {
+        vi.advanceTimersByTime(300)
+      })
+
+      // Should have been called with final value
+      expect(handleInputChange).toHaveBeenCalledWith("app")
+
+      vi.useRealTimers()
+    })
+
+    it("respects custom debounceMs", () => {
+      vi.useFakeTimers()
+      const handleInputChange = vi.fn()
+      render(
+        <Autocomplete
+          aria-label="Test autocomplete"
+          debounceMs={500}
+          options={defaultOptions}
+          onInputChange={handleInputChange}
+        />
+      )
+
+      const input = screen.getByRole("combobox")
+
+      act(() => {
+        input.focus()
+        Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, "value")?.set?.call(input, "test")
+        input.dispatchEvent(new Event("input", { bubbles: true }))
+      })
+
+      // Not called after 300ms
+      act(() => {
+        vi.advanceTimersByTime(300)
+      })
+      expect(handleInputChange).not.toHaveBeenCalled()
+
+      // Called after 500ms total
+      act(() => {
+        vi.advanceTimersByTime(200)
+      })
+      expect(handleInputChange).toHaveBeenCalledWith("test")
+
+      vi.useRealTimers()
+    })
+  })
+
+  // ============================================
+  // MIN CHARS TESTS
+  // ============================================
+  describe("MinChars", () => {
+    it("uses default minChars of 1", async () => {
+      const user = userEvent.setup()
+      render(<Autocomplete aria-label="Test autocomplete" options={defaultOptions} />)
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "a")
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+    })
+
+    it("respects custom minChars", async () => {
+      const user = userEvent.setup()
+      render(
+        <Autocomplete aria-label="Test autocomplete" minChars={3} options={defaultOptions} />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "ap")
+
+      expect(screen.queryByRole("listbox")).not.toBeInTheDocument()
+
+      await user.type(input, "p")
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+    })
+
+    it("hides dropdown when input length drops below minChars", async () => {
+      const user = userEvent.setup()
+      render(
+        <Autocomplete aria-label="Test autocomplete" minChars={2} options={defaultOptions} />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "ap")
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      await user.clear(input)
+      await user.type(input, "a")
+
+      await waitFor(() => {
+        expect(screen.queryByRole("listbox")).not.toBeInTheDocument()
+      })
+    })
+  })
+
+  // ============================================
+  // SELECTION TESTS
+  // ============================================
+  describe("Selection", () => {
+    it("selects option when clicked", async () => {
+      const user = userEvent.setup()
+      const handleChange = vi.fn()
+      render(
+        <Autocomplete
+          aria-label="Test autocomplete"
+          options={defaultOptions}
+          onChange={handleChange}
+        />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "a")
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      await user.click(screen.getByText("Apple"))
+
+      expect(handleChange).toHaveBeenCalledWith("apple")
+    })
+
+    it("updates input value after selection", async () => {
+      const user = userEvent.setup()
+      render(<Autocomplete aria-label="Test autocomplete" options={defaultOptions} />)
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "a")
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      await user.click(screen.getByText("Apple"))
+
+      expect(input).toHaveValue("Apple")
+    })
+
+    it("closes dropdown after selection", async () => {
+      const user = userEvent.setup()
+      render(<Autocomplete aria-label="Test autocomplete" options={defaultOptions} />)
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "a")
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      await user.click(screen.getByText("Apple"))
+
+      await waitFor(() => {
+        expect(screen.queryByRole("listbox")).not.toBeInTheDocument()
+      })
+    })
+
+    it("shows check icon on selected item", async () => {
+      const user = userEvent.setup()
+      render(
+        <Autocomplete
+          aria-label="Test autocomplete"
+          defaultValue="apple"
+          options={defaultOptions}
+        />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.clear(input)
+      await user.type(input, "a")
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      const selectedItem = document.querySelector(
+        '[data-slot="autocomplete-item"][data-selected="true"]'
+      )
+      expect(selectedItem).toBeInTheDocument()
+      expect(selectedItem?.querySelector("svg")).toHaveClass("opacity-100")
+    })
+  })
+
+  // ============================================
+  // KEYBOARD NAVIGATION TESTS
+  // ============================================
+  describe("Keyboard Navigation", () => {
+    it("navigates options with arrow keys", async () => {
+      const user = userEvent.setup()
+      render(<Autocomplete aria-label="Test autocomplete" options={defaultOptions} />)
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "a")
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      await user.keyboard("{ArrowDown}")
+
+      await waitFor(() => {
+        const highlighted = document.querySelector('[data-highlighted="true"]')
+        expect(highlighted).toBeInTheDocument()
+      })
+    })
+
+    it("selects option with Enter key", async () => {
+      const user = userEvent.setup()
+      const handleChange = vi.fn()
+      render(
+        <Autocomplete
+          aria-label="Test autocomplete"
+          options={defaultOptions}
+          onChange={handleChange}
+        />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "a")
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      await user.keyboard("{ArrowDown}{Enter}")
+
+      expect(handleChange).toHaveBeenCalled()
+    })
+
+    it("closes dropdown with Escape key", async () => {
+      const user = userEvent.setup()
+      render(<Autocomplete aria-label="Test autocomplete" options={defaultOptions} />)
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "a")
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      await user.keyboard("{Escape}")
+
+      await waitFor(() => {
+        expect(screen.queryByRole("listbox")).not.toBeInTheDocument()
+      })
+    })
+
+    it("navigates up with ArrowUp key", async () => {
+      const user = userEvent.setup()
+      render(<Autocomplete aria-label="Test autocomplete" options={defaultOptions} />)
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "a")
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      // Go down twice, then up once
+      await user.keyboard("{ArrowDown}{ArrowDown}{ArrowUp}")
+
+      await waitFor(() => {
+        const highlighted = document.querySelector('[data-highlighted="true"]')
+        expect(highlighted).toBeInTheDocument()
+      })
+    })
+  })
+
+  // ============================================
+  // STATES TESTS
+  // ============================================
+  describe("States", () => {
+    it("handles disabled state", () => {
+      render(
+        <Autocomplete disabled aria-label="Test autocomplete" options={defaultOptions} />
+      )
+      expect(screen.getByRole("combobox")).toBeDisabled()
+    })
+
+    it("applies disabled styling", () => {
+      render(
+        <Autocomplete disabled aria-label="Test autocomplete" options={defaultOptions} />
+      )
+      expect(screen.getByRole("combobox")).toHaveClass("disabled:opacity-50")
+    })
+
+    it("has data-disabled attribute when disabled", () => {
+      render(
+        <Autocomplete disabled aria-label="Test autocomplete" options={defaultOptions} />
+      )
+      expect(
+        screen.getByRole("combobox").closest('[data-slot="autocomplete"]')
+      ).toHaveAttribute("data-disabled")
+    })
+
+    it("shows empty message when no results", async () => {
+      const user = userEvent.setup()
+      render(
+        <Autocomplete
+          aria-label="Test autocomplete"
+          emptyMessage="No items found"
+          loading={false}
+          options={[]}
+        />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "xyz")
+
+      await waitFor(() => {
+        expect(screen.getByText("No items found")).toBeInTheDocument()
+      })
+    })
+  })
+
+  // ============================================
+  // SIZE VARIANT TESTS
+  // ============================================
+  describe("Size Variants", () => {
+    it("applies default size (md)", () => {
+      render(<Autocomplete aria-label="Test autocomplete" options={defaultOptions} />)
+      expect(screen.getByRole("combobox")).toHaveClass("h-[var(--autocomplete-input-height-md)]")
+    })
+
+    it("applies sm size", () => {
+      render(
+        <Autocomplete aria-label="Test autocomplete" options={defaultOptions} size="sm" />
+      )
+      expect(screen.getByRole("combobox")).toHaveClass("h-[var(--autocomplete-input-height-sm)]")
+    })
+
+    it("applies lg size", () => {
+      render(
+        <Autocomplete aria-label="Test autocomplete" options={defaultOptions} size="lg" />
+      )
+      expect(screen.getByRole("combobox")).toHaveClass("h-[var(--autocomplete-input-height-lg)]")
+    })
+
+    it("has data-size attribute", () => {
+      render(
+        <Autocomplete aria-label="Test autocomplete" options={defaultOptions} size="sm" />
+      )
+      expect(
+        screen.getByRole("combobox").closest('[data-slot="autocomplete"]')
+      ).toHaveAttribute("data-size", "sm")
+    })
+  })
+
+  // ============================================
+  // VISUAL VARIANT TESTS
+  // ============================================
+  describe("Visual Variants", () => {
+    it("applies default variant", () => {
+      render(<Autocomplete aria-label="Test autocomplete" options={defaultOptions} />)
+      expect(screen.getByRole("combobox")).toHaveClass("border-input")
+    })
+
+    it("applies filled variant", () => {
+      render(
+        <Autocomplete
+          aria-label="Test autocomplete"
+          options={defaultOptions}
+          variant="filled"
+        />
+      )
+      expect(screen.getByRole("combobox")).toHaveClass("bg-muted")
+    })
+
+    it("applies flushed variant", () => {
+      render(
+        <Autocomplete
+          aria-label="Test autocomplete"
+          options={defaultOptions}
+          variant="flushed"
+        />
+      )
+      expect(screen.getByRole("combobox")).toHaveClass("rounded-none")
+    })
+
+    it("has data-variant attribute", () => {
+      render(
+        <Autocomplete
+          aria-label="Test autocomplete"
+          options={defaultOptions}
+          variant="filled"
+        />
+      )
+      expect(
+        screen.getByRole("combobox").closest('[data-slot="autocomplete"]')
+      ).toHaveAttribute("data-variant", "filled")
+    })
+  })
+
+  // ============================================
+  // ACCESSIBILITY TESTS
+  // ============================================
+  describe("Accessibility", () => {
+    it("has no accessibility violations", async () => {
+      const { container } = render(
+        <Autocomplete aria-label="Test autocomplete" options={defaultOptions} />
+      )
+      const results = await axe(container)
+      expect(results).toHaveNoViolations()
+    })
+
+    it("has no violations when disabled", async () => {
+      const { container } = render(
+        <Autocomplete disabled aria-label="Test autocomplete" options={defaultOptions} />
+      )
+      const results = await axe(container)
+      expect(results).toHaveNoViolations()
+    })
+
+    it("has no violations when loading", async () => {
+      const { container } = render(
+        <Autocomplete loading aria-label="Test autocomplete" options={defaultOptions} />
+      )
+      const results = await axe(container)
+      expect(results).toHaveNoViolations()
+    })
+
+    it("input has combobox role", () => {
+      render(<Autocomplete aria-label="Test autocomplete" options={defaultOptions} />)
+      expect(screen.getByRole("combobox")).toBeInTheDocument()
+    })
+
+    it("has aria-expanded attribute", () => {
+      render(<Autocomplete aria-label="Test autocomplete" options={defaultOptions} />)
+      expect(screen.getByRole("combobox")).toHaveAttribute("aria-expanded", "false")
+    })
+
+    it("aria-expanded updates when opened", async () => {
+      const user = userEvent.setup()
+      render(<Autocomplete aria-label="Test autocomplete" options={defaultOptions} />)
+
+      const input = screen.getByRole("combobox")
+      expect(input).toHaveAttribute("aria-expanded", "false")
+
+      await user.type(input, "a")
+
+      await waitFor(() => {
+        expect(input).toHaveAttribute("aria-expanded", "true")
+      })
+    })
+
+    it("has aria-haspopup attribute", () => {
+      render(<Autocomplete aria-label="Test autocomplete" options={defaultOptions} />)
+      expect(screen.getByRole("combobox")).toHaveAttribute("aria-haspopup", "listbox")
+    })
+
+    it("has aria-autocomplete attribute", () => {
+      render(<Autocomplete aria-label="Test autocomplete" options={defaultOptions} />)
+      expect(screen.getByRole("combobox")).toHaveAttribute("aria-autocomplete", "list")
+    })
+
+    it("options have role option", async () => {
+      const user = userEvent.setup()
+      render(<Autocomplete aria-label="Test autocomplete" options={defaultOptions} />)
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "a")
+
+      await waitFor(() => {
+        const options = screen.getAllByRole("option")
+        expect(options.length).toBe(3)
+      })
+    })
+  })
+
+  // ============================================
+  // DATA ATTRIBUTE TESTS
+  // ============================================
+  describe("Data Attributes", () => {
+    it("has data-slot on wrapper", () => {
+      render(<Autocomplete aria-label="Test autocomplete" options={defaultOptions} />)
+      expect(
+        screen.getByRole("combobox").closest('[data-slot="autocomplete"]')
+      ).toBeInTheDocument()
+    })
+
+    it("has data-slot on input", () => {
+      render(<Autocomplete aria-label="Test autocomplete" options={defaultOptions} />)
+      expect(screen.getByRole("combobox")).toHaveAttribute(
+        "data-slot",
+        "autocomplete-input"
+      )
+    })
+
+    it("has data-slot on list when opened", async () => {
+      const user = userEvent.setup()
+      render(<Autocomplete aria-label="Test autocomplete" options={defaultOptions} />)
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "a")
+
+      await waitFor(() => {
+        expect(document.querySelector('[data-slot="autocomplete-list"]')).toBeInTheDocument()
+      })
+    })
+
+    it("has data-slot on items", async () => {
+      const user = userEvent.setup()
+      render(<Autocomplete aria-label="Test autocomplete" options={defaultOptions} />)
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "a")
+
+      await waitFor(() => {
+        const items = document.querySelectorAll('[data-slot="autocomplete-item"]')
+        expect(items.length).toBe(3)
+      })
+    })
+
+    it("preserves custom data attributes", () => {
+      render(
+        <Autocomplete
+          aria-label="Test autocomplete"
+          data-field="search"
+          data-form="settings"
+          options={defaultOptions}
+        />
+      )
+      const wrapper = screen.getByRole("combobox").closest('[data-slot="autocomplete"]')
+      expect(wrapper).toHaveAttribute("data-field", "search")
+      expect(wrapper).toHaveAttribute("data-form", "settings")
+    })
+  })
+
+  // ============================================
+  // DISABLED OPTIONS TESTS
+  // ============================================
+  describe("Disabled Options", () => {
+    it("renders disabled option correctly", async () => {
+      const user = userEvent.setup()
+      const options: AutocompleteOption[] = [
+        { value: "enabled", label: "Enabled" },
+        { value: "disabled", label: "Disabled", disabled: true },
+      ]
+      render(<Autocomplete aria-label="Test autocomplete" options={options} />)
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "e")
+
+      await waitFor(() => {
+        const disabledItem = document.querySelector(
+          '[data-slot="autocomplete-item"][data-disabled="true"]'
+        )
+        expect(disabledItem).toBeInTheDocument()
+        expect(disabledItem).toHaveTextContent("Disabled")
+      })
+    })
+
+    it("does not select disabled option when clicked", async () => {
+      const user = userEvent.setup()
+      const handleChange = vi.fn()
+      const options: AutocompleteOption[] = [
+        { value: "enabled", label: "Enabled" },
+        { value: "disabled", label: "Disabled", disabled: true },
+      ]
+      render(
+        <Autocomplete
+          aria-label="Test autocomplete"
+          options={options}
+          onChange={handleChange}
+        />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "e")
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      await user.click(screen.getByText("Disabled"))
+
+      expect(handleChange).not.toHaveBeenCalled()
+    })
+  })
+
+  // ============================================
+  // EDGE CASES TESTS
+  // ============================================
+  describe("Edge Cases", () => {
+    it("handles empty options array", async () => {
+      const user = userEvent.setup()
+      render(<Autocomplete aria-label="Empty autocomplete" options={[]} />)
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "test")
+
+      await waitFor(() => {
+        expect(screen.getByText("No results found.")).toBeInTheDocument()
+      })
+    })
+
+    it("handles rapid typing correctly", () => {
+      vi.useFakeTimers()
+      const handleInputChange = vi.fn()
+      render(
+        <Autocomplete
+          aria-label="Test autocomplete"
+          debounceMs={300}
+          options={defaultOptions}
+          onInputChange={handleInputChange}
+        />
+      )
+
+      const input = screen.getByRole("combobox")
+
+      // Rapid typing using native events
+      act(() => {
+        input.focus()
+        const values = ["a", "ab", "abc", "abcd", "abcde", "abcdef"]
+        for (const val of values) {
+          Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, "value")?.set?.call(input, val)
+          input.dispatchEvent(new Event("input", { bubbles: true }))
+        }
+      })
+
+      // Fast-forward past debounce
+      act(() => {
+        vi.advanceTimersByTime(300)
+      })
+
+      // Should only be called once with final value
+      expect(handleInputChange).toHaveBeenCalledTimes(1)
+      expect(handleInputChange).toHaveBeenCalledWith("abcdef")
+
+      vi.useRealTimers()
+    })
+
+    it("handles special characters in values", async () => {
+      const user = userEvent.setup()
+      const handleChange = vi.fn()
+      const options: AutocompleteOption[] = [
+        { value: "special-chars_123", label: "Special Chars" },
+      ]
+      render(
+        <Autocomplete
+          aria-label="Test autocomplete"
+          options={options}
+          onChange={handleChange}
+        />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "s")
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      await user.click(screen.getByText("Special Chars"))
+
+      expect(handleChange).toHaveBeenCalledWith("special-chars_123")
+    })
+
+    it("handles many options", async () => {
+      const user = userEvent.setup()
+      const manyOptions: AutocompleteOption[] = Array.from({ length: 100 }, (_, i) => ({
+        value: `option-${String(i + 1)}`,
+        label: `Option ${String(i + 1)}`,
+      }))
+      render(<Autocomplete aria-label="Test autocomplete" options={manyOptions} />)
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "o")
+
+      await waitFor(() => {
+        const items = document.querySelectorAll('[data-slot="autocomplete-item"]')
+        expect(items.length).toBe(100)
+      })
+    })
+
+    it("closes dropdown when clicking outside", async () => {
+      const user = userEvent.setup()
+      render(
+        <div>
+          <button>Outside</button>
+          <Autocomplete aria-label="Test autocomplete" options={defaultOptions} />
+        </div>
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "a")
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      await user.click(screen.getByText("Outside"))
+
+      await waitFor(() => {
+        expect(screen.queryByRole("listbox")).not.toBeInTheDocument()
+      })
+    })
+  })
+
+  // ============================================
+  // TYPE SAFETY TESTS
+  // ============================================
+  describe("Type Safety", () => {
+    it("accepts valid size prop values", () => {
+      const sizes = ["sm", "md", "lg"] as const
+      sizes.forEach((size) => {
+        const { unmount } = render(
+          <Autocomplete aria-label="Test autocomplete" options={defaultOptions} size={size} />
+        )
+        expect(screen.getByRole("combobox")).toBeInTheDocument()
+        unmount()
+      })
+    })
+
+    it("accepts valid variant prop values", () => {
+      const variants = ["default", "filled", "flushed"] as const
+      variants.forEach((variant) => {
+        const { unmount } = render(
+          <Autocomplete
+            aria-label="Test autocomplete"
+            options={defaultOptions}
+            variant={variant}
+          />
+        )
+        expect(screen.getByRole("combobox")).toBeInTheDocument()
+        unmount()
+      })
+    })
+  })
+
+  // ============================================
+  // SHOW CLEAR TESTS
+  // ============================================
+  describe("showClear", () => {
+    describe("Rendering", () => {
+      it("does not render clear button by default", () => {
+        render(
+          <Autocomplete
+            aria-label="Test autocomplete"
+            defaultValue="apple"
+            options={defaultOptions}
+          />
+        )
+        expect(
+          document.querySelector('[data-slot="autocomplete-clear"]')
+        ).not.toBeInTheDocument()
+      })
+
+      it("renders clear button when showClear is true and has value", () => {
+        render(
+          <Autocomplete
+            showClear
+            aria-label="Test autocomplete"
+            defaultValue="apple"
+            options={defaultOptions}
+          />
+        )
+        expect(
+          document.querySelector('[data-slot="autocomplete-clear"]')
+        ).toBeInTheDocument()
+      })
+
+      it("does not render clear button when showClear is true but no value", () => {
+        render(
+          <Autocomplete
+            showClear
+            aria-label="Test autocomplete"
+            options={defaultOptions}
+          />
+        )
+        expect(
+          document.querySelector('[data-slot="autocomplete-clear"]')
+        ).not.toBeInTheDocument()
+      })
+
+      it("does not render clear button when disabled", () => {
+        render(
+          <Autocomplete
+            disabled
+            showClear
+            aria-label="Test autocomplete"
+            defaultValue="apple"
+            options={defaultOptions}
+          />
+        )
+        expect(
+          document.querySelector('[data-slot="autocomplete-clear"]')
+        ).not.toBeInTheDocument()
+      })
+
+      it("hides clear button during loading state", () => {
+        render(
+          <Autocomplete
+            loading
+            showClear
+            aria-label="Test autocomplete"
+            defaultValue="apple"
+            options={defaultOptions}
+          />
+        )
+        expect(
+          document.querySelector('[data-slot="autocomplete-clear"]')
+        ).not.toBeInTheDocument()
+      })
+    })
+
+    describe("Interactions", () => {
+      it("clears value when clear button is clicked", async () => {
+        const user = userEvent.setup()
+        render(
+          <Autocomplete
+            showClear
+            aria-label="Test autocomplete"
+            defaultValue="apple"
+            options={defaultOptions}
+          />
+        )
+
+        const input = screen.getByRole("combobox")
+        expect(input).toHaveValue("Apple")
+
+        const clearButton = document.querySelector('[data-slot="autocomplete-clear"]')
+        expect(clearButton).toBeInTheDocument()
+
+        await user.click(clearButton!)
+
+        expect(input).toHaveValue("")
+      })
+
+      it("calls onChange with undefined when cleared", async () => {
+        const user = userEvent.setup()
+        const handleChange = vi.fn()
+        render(
+          <Autocomplete
+            showClear
+            aria-label="Test autocomplete"
+            defaultValue="apple"
+            options={defaultOptions}
+            onChange={handleChange}
+          />
+        )
+
+        const clearButton = document.querySelector('[data-slot="autocomplete-clear"]')
+        await user.click(clearButton!)
+
+        expect(handleChange).toHaveBeenCalledWith(undefined)
+      })
+
+      it("calls onClear callback when cleared", async () => {
+        const user = userEvent.setup()
+        const handleClear = vi.fn()
+        render(
+          <Autocomplete
+            showClear
+            aria-label="Test autocomplete"
+            defaultValue="apple"
+            options={defaultOptions}
+            onClear={handleClear}
+          />
+        )
+
+        const clearButton = document.querySelector('[data-slot="autocomplete-clear"]')
+        await user.click(clearButton!)
+
+        expect(handleClear).toHaveBeenCalledTimes(1)
+      })
+
+      it("focuses input after clearing", async () => {
+        const user = userEvent.setup()
+        render(
+          <Autocomplete
+            showClear
+            aria-label="Test autocomplete"
+            defaultValue="apple"
+            options={defaultOptions}
+          />
+        )
+
+        const input = screen.getByRole("combobox")
+        const clearButton = document.querySelector('[data-slot="autocomplete-clear"]')
+        await user.click(clearButton!)
+
+        expect(document.activeElement).toBe(input)
+      })
+
+      it("hides clear button after clearing", async () => {
+        const user = userEvent.setup()
+        render(
+          <Autocomplete
+            showClear
+            aria-label="Test autocomplete"
+            defaultValue="apple"
+            options={defaultOptions}
+          />
+        )
+
+        const clearButton = document.querySelector('[data-slot="autocomplete-clear"]')
+        await user.click(clearButton!)
+
+        expect(
+          document.querySelector('[data-slot="autocomplete-clear"]')
+        ).not.toBeInTheDocument()
+      })
+    })
+
+    describe("Accessibility", () => {
+      it("clear button has aria-label", () => {
+        render(
+          <Autocomplete
+            showClear
+            aria-label="Test autocomplete"
+            defaultValue="apple"
+            options={defaultOptions}
+          />
+        )
+
+        const clearButton = document.querySelector('[data-slot="autocomplete-clear"]')
+        expect(clearButton).toHaveAttribute("aria-label", "Clear")
+      })
+
+      it("clear button is focusable with keyboard", async () => {
+        const user = userEvent.setup()
+        render(
+          <Autocomplete
+            showClear
+            aria-label="Test autocomplete"
+            defaultValue="apple"
+            options={defaultOptions}
+          />
+        )
+
+        const input = screen.getByRole("combobox")
+        await user.click(input)
+        await user.tab()
+
+        const clearButton = document.querySelector('[data-slot="autocomplete-clear"]')
+        expect(document.activeElement).toBe(clearButton)
+      })
+
+      it("clear button responds to Enter key", async () => {
+        const user = userEvent.setup()
+        const handleClear = vi.fn()
+        render(
+          <Autocomplete
+            showClear
+            aria-label="Test autocomplete"
+            defaultValue="apple"
+            options={defaultOptions}
+            onClear={handleClear}
+          />
+        )
+
+        const clearButton = document.querySelector('[data-slot="autocomplete-clear"]')!
+        ;(clearButton as HTMLElement).focus()
+        await user.keyboard("{Enter}")
+
+        expect(handleClear).toHaveBeenCalledTimes(1)
+      })
+
+      it("clear button responds to Space key", async () => {
+        const user = userEvent.setup()
+        const handleClear = vi.fn()
+        render(
+          <Autocomplete
+            showClear
+            aria-label="Test autocomplete"
+            defaultValue="apple"
+            options={defaultOptions}
+            onClear={handleClear}
+          />
+        )
+
+        const clearButton = document.querySelector('[data-slot="autocomplete-clear"]')!
+        ;(clearButton as HTMLElement).focus()
+        await user.keyboard(" ")
+
+        expect(handleClear).toHaveBeenCalledTimes(1)
+      })
+
+      it("has no accessibility violations with showClear", async () => {
+        const { container } = render(
+          <Autocomplete
+            showClear
+            aria-label="Test autocomplete"
+            defaultValue="apple"
+            options={defaultOptions}
+          />
+        )
+        const results = await axe(container)
+        expect(results).toHaveNoViolations()
+      })
+    })
+
+    describe("Data Attributes", () => {
+      it("clear button has data-slot attribute", () => {
+        render(
+          <Autocomplete
+            showClear
+            aria-label="Test autocomplete"
+            defaultValue="apple"
+            options={defaultOptions}
+          />
+        )
+
+        expect(
+          document.querySelector('[data-slot="autocomplete-clear"]')
+        ).toBeInTheDocument()
+      })
+    })
+  })
+
+  // ============================================
+  // AUTO HIGHLIGHT TESTS
+  // ============================================
+  describe("autoHighlight", () => {
+    it("does not highlight any option by default when autoHighlight is false", async () => {
+      const user = userEvent.setup()
+      render(<Autocomplete aria-label="Test autocomplete" options={defaultOptions} />)
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "a")
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      // No item should be highlighted initially
+      expect(document.querySelector('[data-highlighted="true"]')).not.toBeInTheDocument()
+    })
+
+    it("highlights first enabled option when dropdown opens and autoHighlight is true", async () => {
+      const user = userEvent.setup()
+      render(
+        <Autocomplete autoHighlight aria-label="Test autocomplete" options={defaultOptions} />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "a")
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      // First option should be highlighted
+      await waitFor(() => {
+        const highlighted = document.querySelector('[data-highlighted="true"]')
+        expect(highlighted).toBeInTheDocument()
+        expect(highlighted).toHaveTextContent("Apple")
+      })
+    })
+
+    it("skips disabled options when auto-highlighting", async () => {
+      const user = userEvent.setup()
+      const options: AutocompleteOption[] = [
+        { value: "disabled1", label: "Disabled First", disabled: true },
+        { value: "enabled", label: "Enabled Option" },
+        { value: "disabled2", label: "Disabled Second", disabled: true },
+      ]
+      render(
+        <Autocomplete autoHighlight aria-label="Test autocomplete" options={options} />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "e")
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      // First enabled option should be highlighted
+      await waitFor(() => {
+        const highlighted = document.querySelector('[data-highlighted="true"]')
+        expect(highlighted).toBeInTheDocument()
+        expect(highlighted).toHaveTextContent("Enabled Option")
+      })
+    })
+
+    it("Enter key selects auto-highlighted option", async () => {
+      const user = userEvent.setup()
+      const handleChange = vi.fn()
+      render(
+        <Autocomplete
+          autoHighlight
+          aria-label="Test autocomplete"
+          options={defaultOptions}
+          onChange={handleChange}
+        />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "a")
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+        expect(document.querySelector('[data-highlighted="true"]')).toBeInTheDocument()
+      })
+
+      await user.keyboard("{Enter}")
+
+      expect(handleChange).toHaveBeenCalledWith("apple")
+    })
+
+    it("handles empty options array gracefully", async () => {
+      const user = userEvent.setup()
+      render(
+        <Autocomplete autoHighlight aria-label="Test autocomplete" options={[]} />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "test")
+
+      await waitFor(() => {
+        expect(screen.getByText("No results found.")).toBeInTheDocument()
+      })
+
+      // No crash, no highlighted element
+      expect(document.querySelector('[data-highlighted="true"]')).not.toBeInTheDocument()
+    })
+
+    it("handles all disabled options gracefully", async () => {
+      const user = userEvent.setup()
+      const options: AutocompleteOption[] = [
+        { value: "disabled1", label: "Disabled First", disabled: true },
+        { value: "disabled2", label: "Disabled Second", disabled: true },
+      ]
+      render(
+        <Autocomplete autoHighlight aria-label="Test autocomplete" options={options} />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "d")
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      // No item should be highlighted since all are disabled
+      expect(document.querySelector('[data-highlighted="true"]')).not.toBeInTheDocument()
+    })
+
+    it("arrow keys move from auto-highlighted option", async () => {
+      const user = userEvent.setup()
+      render(
+        <Autocomplete autoHighlight aria-label="Test autocomplete" options={defaultOptions} />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "a")
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+        expect(document.querySelector('[data-highlighted="true"]')).toHaveTextContent("Apple")
+      })
+
+      await user.keyboard("{ArrowDown}")
+
+      await waitFor(() => {
+        const highlighted = document.querySelector('[data-highlighted="true"]')
+        expect(highlighted).toHaveTextContent("Banana")
+      })
+    })
+  })
+
+  // ============================================
+  // COMPLETE ON FOCUS TESTS
+  // ============================================
+  describe("completeOnFocus", () => {
+    it("does not show dropdown on focus by default", async () => {
+      const user = userEvent.setup()
+      render(<Autocomplete aria-label="Test autocomplete" options={defaultOptions} />)
+
+      const input = screen.getByRole("combobox")
+      await user.click(input)
+
+      // Dropdown should not open on focus when completeOnFocus is false
+      expect(screen.queryByRole("listbox")).not.toBeInTheDocument()
+    })
+
+    it("shows all suggestions on focus when completeOnFocus is true", async () => {
+      const user = userEvent.setup()
+      render(
+        <Autocomplete completeOnFocus aria-label="Test autocomplete" options={defaultOptions} />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.click(input)
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      // All options should be visible
+      expect(screen.getAllByRole("option")).toHaveLength(3)
+    })
+
+    it("ignores minChars when completeOnFocus is true and input is focused", async () => {
+      const user = userEvent.setup()
+      render(
+        <Autocomplete
+          completeOnFocus
+          aria-label="Test autocomplete"
+          minChars={3}
+          options={defaultOptions}
+        />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.click(input)
+
+      // Dropdown should open even though minChars is 3 and input is empty
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+    })
+
+    it("triggers onInputChange with empty string on focus", async () => {
+      const user = userEvent.setup()
+      const handleInputChange = vi.fn()
+      render(
+        <Autocomplete
+          completeOnFocus
+          aria-label="Test autocomplete"
+          options={defaultOptions}
+          onInputChange={handleInputChange}
+        />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.click(input)
+
+      await waitFor(() => {
+        expect(handleInputChange).toHaveBeenCalledWith("")
+      })
+    })
+
+    it("works with autoHighlight", async () => {
+      const user = userEvent.setup()
+      render(
+        <Autocomplete
+          autoHighlight
+          completeOnFocus
+          aria-label="Test autocomplete"
+          options={defaultOptions}
+        />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.click(input)
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+        const highlighted = document.querySelector('[data-highlighted="true"]')
+        expect(highlighted).toBeInTheDocument()
+        expect(highlighted).toHaveTextContent("Apple")
+      })
+    })
+
+    it("closes dropdown when clicking outside after completeOnFocus opens it", async () => {
+      const user = userEvent.setup()
+      render(
+        <div>
+          <button>Outside</button>
+          <Autocomplete completeOnFocus aria-label="Test autocomplete" options={defaultOptions} />
+        </div>
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.click(input)
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      await user.click(screen.getByText("Outside"))
+
+      await waitFor(() => {
+        expect(screen.queryByRole("listbox")).not.toBeInTheDocument()
+      })
+    })
+
+    it("allows selection after completeOnFocus opens dropdown", async () => {
+      const user = userEvent.setup()
+      const handleChange = vi.fn()
+      render(
+        <Autocomplete
+          completeOnFocus
+          aria-label="Test autocomplete"
+          options={defaultOptions}
+          onChange={handleChange}
+        />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.click(input)
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      await user.click(screen.getByText("Banana"))
+
+      expect(handleChange).toHaveBeenCalledWith("banana")
+      expect(input).toHaveValue("Banana")
+    })
+  })
+
+  describe("forceSelection", () => {
+    it("allows any input when forceSelection is false (default)", async () => {
+      const user = userEvent.setup()
+      render(
+        <div>
+          <Autocomplete aria-label="Test autocomplete" options={defaultOptions} />
+          <button type="button">Outside</button>
+        </div>
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "xyz")
+      await user.click(screen.getByText("Outside"))
+
+      // Input should keep custom value
+      expect(input).toHaveValue("xyz")
+    })
+
+    it("reverts to empty on blur when no match and no prior selection", async () => {
+      const user = userEvent.setup()
+      const handleChange = vi.fn()
+      render(
+        <div>
+          <Autocomplete
+            forceSelection
+            aria-label="Test autocomplete"
+            options={defaultOptions}
+            onChange={handleChange}
+          />
+          <button type="button">Outside</button>
+        </div>
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "xyz")
+      await user.click(screen.getByText("Outside"))
+
+      // Input should be cleared
+      expect(input).toHaveValue("")
+      // onChange should be called with undefined to clear value
+      expect(handleChange).toHaveBeenCalledWith(undefined)
+    })
+
+    it("reverts to last valid selection on blur when no match", async () => {
+      const user = userEvent.setup()
+      const handleChange = vi.fn()
+      render(
+        <div>
+          <Autocomplete
+            forceSelection
+            aria-label="Test autocomplete"
+            defaultValue="apple"
+            options={defaultOptions}
+            onChange={handleChange}
+          />
+          <button type="button">Outside</button>
+        </div>
+      )
+
+      const input = screen.getByRole("combobox")
+      expect(input).toHaveValue("Apple")
+
+      // Clear and type something that doesn't match
+      await user.clear(input)
+      await user.type(input, "xyz")
+      await user.click(screen.getByText("Outside"))
+
+      // Should revert to last valid selection
+      expect(input).toHaveValue("Apple")
+      // onChange should NOT be called since we reverted to same value
+    })
+
+    it("keeps value when input text exactly matches an option label", async () => {
+      const user = userEvent.setup()
+      const handleChange = vi.fn()
+      render(
+        <div>
+          <Autocomplete
+            forceSelection
+            aria-label="Test autocomplete"
+            options={defaultOptions}
+            onChange={handleChange}
+          />
+          <button type="button">Outside</button>
+        </div>
+      )
+
+      const input = screen.getByRole("combobox")
+      // Type exactly matching label (case-insensitive)
+      await user.type(input, "Apple")
+      await user.click(screen.getByText("Outside"))
+
+      // Value should be kept and selection made
+      expect(input).toHaveValue("Apple")
+      expect(handleChange).toHaveBeenCalledWith("apple")
+    })
+
+    it("handles case-insensitive matching", async () => {
+      const user = userEvent.setup()
+      const handleChange = vi.fn()
+      render(
+        <div>
+          <Autocomplete
+            forceSelection
+            aria-label="Test autocomplete"
+            options={defaultOptions}
+            onChange={handleChange}
+          />
+          <button type="button">Outside</button>
+        </div>
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "BANANA")
+      await user.click(screen.getByText("Outside"))
+
+      // Should match "Banana" case-insensitively
+      expect(input).toHaveValue("Banana")
+      expect(handleChange).toHaveBeenCalledWith("banana")
+    })
+
+    it("sets aria-invalid when input doesn't match any option", async () => {
+      const user = userEvent.setup()
+      render(
+        <Autocomplete forceSelection aria-label="Test autocomplete" options={defaultOptions} />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "xyz")
+
+      // Should have aria-invalid while typing non-matching text
+      expect(input).toHaveAttribute("aria-invalid", "true")
+    })
+
+    it("removes aria-invalid when input matches an option", async () => {
+      const user = userEvent.setup()
+      render(
+        <Autocomplete forceSelection aria-label="Test autocomplete" options={defaultOptions} />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "Apple")
+
+      // Should not have aria-invalid when text matches
+      expect(input).not.toHaveAttribute("aria-invalid", "true")
+    })
+
+    it("removes aria-invalid when input is empty", async () => {
+      const user = userEvent.setup()
+      render(
+        <Autocomplete forceSelection aria-label="Test autocomplete" options={defaultOptions} />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "xyz")
+      expect(input).toHaveAttribute("aria-invalid", "true")
+
+      await user.clear(input)
+      expect(input).not.toHaveAttribute("aria-invalid", "true")
+    })
+
+    it("validates on Tab key (blur)", async () => {
+      const user = userEvent.setup()
+      const handleChange = vi.fn()
+      render(
+        <div>
+          <Autocomplete
+            forceSelection
+            aria-label="Test autocomplete"
+            defaultValue="apple"
+            options={defaultOptions}
+            onChange={handleChange}
+          />
+          <button type="button">Next Field</button>
+        </div>
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.clear(input)
+      await user.type(input, "xyz")
+      await user.tab()
+
+      // Should revert to last valid selection
+      expect(input).toHaveValue("Apple")
+    })
+
+    it("accepts partial match when user selects from dropdown", async () => {
+      const user = userEvent.setup()
+      const handleChange = vi.fn()
+      render(
+        <Autocomplete
+          forceSelection
+          aria-label="Test autocomplete"
+          options={defaultOptions}
+          onChange={handleChange}
+        />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "app")
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      await user.click(screen.getByText("Apple"))
+
+      expect(input).toHaveValue("Apple")
+      expect(handleChange).toHaveBeenCalledWith("apple")
+    })
+
+    it("works with controlled value", async () => {
+      const user = userEvent.setup()
+      const handleChange = vi.fn()
+
+      function ControlledAutocomplete() {
+        const [value, setValue] = React.useState<string | undefined>("apple")
+        return (
+          <div>
+            <Autocomplete
+              forceSelection
+              aria-label="Test autocomplete"
+              options={defaultOptions}
+              value={value}
+              onChange={(newValue) => {
+                setValue(newValue as string | undefined)
+                handleChange(newValue)
+              }}
+            />
+            <button type="button">Outside</button>
+          </div>
+        )
+      }
+
+      render(<ControlledAutocomplete />)
+
+      const input = screen.getByRole("combobox")
+      expect(input).toHaveValue("Apple")
+
+      await user.clear(input)
+      await user.type(input, "xyz")
+      await user.click(screen.getByText("Outside"))
+
+      // Should revert to controlled value
+      expect(input).toHaveValue("Apple")
+    })
+  })
+
+  describe("multiple", () => {
+    // Rendering
+    it("does not render tags when multiple is false (default)", async () => {
+      render(<Autocomplete aria-label="Test autocomplete" defaultValue="apple" options={defaultOptions} />)
+
+      // Should not have tags
+      expect(screen.queryByRole("list")).not.toBeInTheDocument()
+      expect(screen.queryByTestId("autocomplete-tags")).not.toBeInTheDocument()
+    })
+
+    it("renders selected values as tags when multiple is true", async () => {
+      render(
+        <Autocomplete
+          multiple
+          aria-label="Test autocomplete"
+          defaultValue={["apple", "banana"]}
+          options={defaultOptions}
+        />
+      )
+
+      // Should have tags with data-slot
+      const tags = document.querySelectorAll('[data-slot="autocomplete-tag"]')
+      expect(tags).toHaveLength(2)
+      expect(tags[0]).toHaveTextContent("Apple")
+      expect(tags[1]).toHaveTextContent("Banana")
+    })
+
+    it("renders tag remove buttons", async () => {
+      render(
+        <Autocomplete
+          multiple
+          aria-label="Test autocomplete"
+          defaultValue={["apple"]}
+          options={defaultOptions}
+        />
+      )
+
+      const removeButton = document.querySelector('[data-slot="autocomplete-tag-remove"]')
+      expect(removeButton).toBeInTheDocument()
+      expect(removeButton).toHaveAttribute("aria-label", "Remove Apple")
+    })
+
+    // Selection
+    it("allows selecting multiple values", async () => {
+      const user = userEvent.setup()
+      const handleChange = vi.fn()
+      render(
+        <Autocomplete
+          completeOnFocus
+          multiple
+          aria-label="Test autocomplete"
+          options={defaultOptions}
+          onChange={handleChange}
+        />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.click(input)
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      // Select first item
+      await user.click(screen.getByText("Apple"))
+      expect(handleChange).toHaveBeenLastCalledWith(["apple"])
+
+      // Select second item
+      await user.click(screen.getByText("Banana"))
+      expect(handleChange).toHaveBeenLastCalledWith(["apple", "banana"])
+    })
+
+    it("does not close dropdown after selection in multiple mode", async () => {
+      const user = userEvent.setup()
+      render(
+        <Autocomplete
+          completeOnFocus
+          multiple
+          aria-label="Test autocomplete"
+          options={defaultOptions}
+        />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.click(input)
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      await user.click(screen.getByText("Apple"))
+
+      // Dropdown should still be open
+      expect(screen.getByRole("listbox")).toBeInTheDocument()
+    })
+
+    it("toggles selection on click", async () => {
+      const user = userEvent.setup()
+      const handleChange = vi.fn()
+      render(
+        <Autocomplete
+          completeOnFocus
+          multiple
+          aria-label="Test autocomplete"
+          defaultValue={["apple"]}
+          options={defaultOptions}
+          onChange={handleChange}
+        />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.click(input)
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      // Click on already selected item to deselect (use within to target dropdown option, not tag)
+      const listbox = screen.getByRole("listbox")
+      await user.click(within(listbox).getByText("Apple"))
+      expect(handleChange).toHaveBeenLastCalledWith([])
+    })
+
+    it("calls onChange with array of values", async () => {
+      const user = userEvent.setup()
+      const handleChange = vi.fn()
+      render(
+        <Autocomplete
+          completeOnFocus
+          multiple
+          aria-label="Test autocomplete"
+          options={defaultOptions}
+          onChange={handleChange}
+        />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.click(input)
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      await user.click(screen.getByText("Apple"))
+
+      // onChange should be called with an array
+      expect(handleChange).toHaveBeenCalledWith(["apple"])
+      expect(Array.isArray(handleChange.mock.calls[0]?.[0])).toBe(true)
+    })
+
+    // Tag Removal
+    it("removes tag when remove button is clicked", async () => {
+      const user = userEvent.setup()
+      const handleChange = vi.fn()
+      render(
+        <Autocomplete
+          multiple
+          aria-label="Test autocomplete"
+          defaultValue={["apple", "banana"]}
+          options={defaultOptions}
+          onChange={handleChange}
+        />
+      )
+
+      // Click remove button on first tag
+      const removeButton = document.querySelector('[data-slot="autocomplete-tag-remove"]')!
+      await user.click(removeButton as HTMLElement)
+
+      expect(handleChange).toHaveBeenCalledWith(["banana"])
+    })
+
+    it("removes last tag with Backspace when input is empty", async () => {
+      const user = userEvent.setup()
+      const handleChange = vi.fn()
+      render(
+        <Autocomplete
+          multiple
+          aria-label="Test autocomplete"
+          defaultValue={["apple", "banana"]}
+          options={defaultOptions}
+          onChange={handleChange}
+        />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.click(input)
+      await user.keyboard("{Backspace}")
+
+      expect(handleChange).toHaveBeenCalledWith(["apple"])
+    })
+
+    it("does not remove tag with Backspace when input has text", async () => {
+      const user = userEvent.setup()
+      const handleChange = vi.fn()
+      render(
+        <Autocomplete
+          multiple
+          aria-label="Test autocomplete"
+          defaultValue={["apple"]}
+          options={defaultOptions}
+          onChange={handleChange}
+        />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "test")
+      await user.keyboard("{Backspace}")
+
+      // Should only remove one character from input, not the tag
+      expect(handleChange).not.toHaveBeenCalled()
+      expect(input).toHaveValue("tes")
+    })
+
+    // Integration
+    it("works with showClear to clear all selections", async () => {
+      const user = userEvent.setup()
+      const handleChange = vi.fn()
+      render(
+        <Autocomplete
+          multiple
+          showClear
+          aria-label="Test autocomplete"
+          defaultValue={["apple", "banana"]}
+          options={defaultOptions}
+          onChange={handleChange}
+        />
+      )
+
+      const clearButton = document.querySelector('[data-slot="autocomplete-clear"]')!
+      await user.click(clearButton as HTMLElement)
+
+      expect(handleChange).toHaveBeenCalledWith([])
+    })
+
+    it("shows check marks for selected items in dropdown", async () => {
+      const user = userEvent.setup()
+      render(
+        <Autocomplete
+          completeOnFocus
+          multiple
+          aria-label="Test autocomplete"
+          defaultValue={["apple"]}
+          options={defaultOptions}
+        />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.click(input)
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      // Check that selected item has data-selected (use within to target dropdown option, not tag)
+      const listbox = screen.getByRole("listbox")
+      const appleOption = within(listbox).getByText("Apple").closest('[role="option"]')
+      expect(appleOption).toHaveAttribute("data-selected", "true")
+    })
+
+    it("clears input after selection in multiple mode", async () => {
+      const user = userEvent.setup()
+      render(<Autocomplete multiple aria-label="Test autocomplete" options={defaultOptions} />)
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "app")
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      await user.click(screen.getByText("Apple"))
+
+      // Input should be cleared after selection
+      expect(input).toHaveValue("")
+    })
+
+    it("works with controlled value as array", async () => {
+      const user = userEvent.setup()
+      const handleChange = vi.fn()
+
+      function ControlledMultiple() {
+        const [value, setValue] = React.useState<string[]>(["apple"])
+        return (
+          <Autocomplete
+            completeOnFocus
+            multiple
+            aria-label="Test autocomplete"
+            options={defaultOptions}
+            value={value}
+            onChange={(newValue) => {
+              setValue(newValue as string[])
+              handleChange(newValue)
+            }}
+          />
+        )
+      }
+
+      render(<ControlledMultiple />)
+
+      // Should have one tag initially
+      let tags = document.querySelectorAll('[data-slot="autocomplete-tag"]')
+      expect(tags).toHaveLength(1)
+
+      const input = screen.getByRole("combobox")
+      await user.click(input)
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      await user.click(screen.getByText("Banana"))
+
+      // Should have two tags now
+      tags = document.querySelectorAll('[data-slot="autocomplete-tag"]')
+      expect(tags).toHaveLength(2)
+    })
+
+    it("handles keyboard selection in multiple mode", async () => {
+      const user = userEvent.setup()
+      const handleChange = vi.fn()
+      render(
+        <Autocomplete
+          autoHighlight
+          completeOnFocus
+          multiple
+          aria-label="Test autocomplete"
+          options={defaultOptions}
+          onChange={handleChange}
+        />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.click(input)
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      // First item should be highlighted due to autoHighlight
+      await user.keyboard("{Enter}")
+
+      expect(handleChange).toHaveBeenCalledWith(["apple"])
+      // Dropdown should still be open
+      expect(screen.getByRole("listbox")).toBeInTheDocument()
+    })
+  })
+
+  // ============================================
+  // DROPDOWN BUTTON TESTS
+  // ============================================
+  describe("dropdown", () => {
+    it("does not render dropdown button by default", () => {
+      render(<Autocomplete aria-label="Test autocomplete" options={defaultOptions} />)
+      expect(document.querySelector('[data-slot="autocomplete-dropdown"]')).not.toBeInTheDocument()
+    })
+
+    it("renders dropdown button when dropdown is true", () => {
+      render(
+        <Autocomplete dropdown aria-label="Test autocomplete" options={defaultOptions} />
+      )
+      expect(document.querySelector('[data-slot="autocomplete-dropdown"]')).toBeInTheDocument()
+    })
+
+    it("dropdown button has accessible name", () => {
+      render(
+        <Autocomplete dropdown aria-label="Test autocomplete" options={defaultOptions} />
+      )
+      const dropdownButton = document.querySelector('[data-slot="autocomplete-dropdown"]')
+      expect(dropdownButton).toHaveAttribute("aria-label", "Toggle dropdown")
+    })
+
+    it("opens dropdown when button is clicked", async () => {
+      const user = userEvent.setup()
+      render(
+        <Autocomplete dropdown aria-label="Test autocomplete" options={defaultOptions} />
+      )
+
+      expect(screen.queryByRole("listbox")).not.toBeInTheDocument()
+
+      const dropdownButton = document.querySelector('[data-slot="autocomplete-dropdown"]')!
+      await user.click(dropdownButton as HTMLElement)
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+    })
+
+    it("closes dropdown when button is clicked while open", async () => {
+      const user = userEvent.setup()
+      render(
+        <Autocomplete dropdown aria-label="Test autocomplete" options={defaultOptions} />
+      )
+
+      const dropdownButton = document.querySelector('[data-slot="autocomplete-dropdown"]')!
+
+      // Open dropdown
+      await user.click(dropdownButton as HTMLElement)
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      // Close dropdown
+      await user.click(dropdownButton as HTMLElement)
+      await waitFor(() => {
+        expect(screen.queryByRole("listbox")).not.toBeInTheDocument()
+      })
+    })
+
+    it("clears input in 'blank' mode (default)", async () => {
+      const user = userEvent.setup()
+      render(
+        <Autocomplete dropdown aria-label="Test autocomplete" options={defaultOptions} />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "App")
+
+      expect(input).toHaveValue("App")
+
+      const dropdownButton = document.querySelector('[data-slot="autocomplete-dropdown"]')!
+      await user.click(dropdownButton as HTMLElement)
+
+      // Input should be cleared in blank mode
+      expect(input).toHaveValue("")
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      // All options should be visible
+      expect(screen.getAllByRole("option")).toHaveLength(3)
+    })
+
+    it("keeps query in 'current' mode", async () => {
+      const user = userEvent.setup()
+      render(
+        <Autocomplete
+          dropdown
+          aria-label="Test autocomplete"
+          dropdownMode="current"
+          options={defaultOptions}
+        />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "App")
+
+      expect(input).toHaveValue("App")
+
+      const dropdownButton = document.querySelector('[data-slot="autocomplete-dropdown"]')!
+      await user.click(dropdownButton as HTMLElement)
+
+      // Input should be kept in current mode
+      expect(input).toHaveValue("App")
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+    })
+
+    it("Alt+ArrowDown opens dropdown", async () => {
+      const user = userEvent.setup()
+      render(
+        <Autocomplete dropdown aria-label="Test autocomplete" options={defaultOptions} />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.click(input)
+
+      expect(screen.queryByRole("listbox")).not.toBeInTheDocument()
+
+      await user.keyboard("{Alt>}{ArrowDown}{/Alt}")
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+    })
+
+    it("does not show dropdown button when disabled", () => {
+      render(
+        <Autocomplete disabled dropdown aria-label="Test autocomplete" options={defaultOptions} />
+      )
+      // Dropdown button should be disabled
+      const dropdownButton = document.querySelector('[data-slot="autocomplete-dropdown"]')
+      expect(dropdownButton).toBeDisabled()
+    })
+
+    it("triggers onOpenChange when dropdown button is clicked", async () => {
+      const user = userEvent.setup()
+      const handleOpenChange = vi.fn()
+      render(
+        <Autocomplete
+          dropdown
+          aria-label="Test autocomplete"
+          options={defaultOptions}
+          onOpenChange={handleOpenChange}
+        />
+      )
+
+      const dropdownButton = document.querySelector('[data-slot="autocomplete-dropdown"]')!
+      await user.click(dropdownButton as HTMLElement)
+
+      expect(handleOpenChange).toHaveBeenCalledWith(true)
+    })
+
+    it("renders ChevronDown icon in dropdown button", () => {
+      render(
+        <Autocomplete dropdown aria-label="Test autocomplete" options={defaultOptions} />
+      )
+      const dropdownButton = document.querySelector('[data-slot="autocomplete-dropdown"]')
+      const icon = dropdownButton?.querySelector(".lucide-chevron-down")
+      expect(icon).toBeInTheDocument()
+    })
+
+    it("positions dropdown button after clear button when both present", async () => {
+      const user = userEvent.setup()
+      render(
+        <Autocomplete
+          dropdown
+          showClear
+          aria-label="Test autocomplete"
+          options={defaultOptions}
+        />
+      )
+
+      const input = screen.getByRole("combobox")
+      await user.type(input, "App")
+
+      // Both buttons should be present
+      expect(document.querySelector('[data-slot="autocomplete-clear"]')).toBeInTheDocument()
+      expect(document.querySelector('[data-slot="autocomplete-dropdown"]')).toBeInTheDocument()
+    })
+
+    it("works with completeOnFocus", async () => {
+      const user = userEvent.setup()
+      render(
+        <Autocomplete
+          completeOnFocus
+          dropdown
+          aria-label="Test autocomplete"
+          options={defaultOptions}
+        />
+      )
+
+      const dropdownButton = document.querySelector('[data-slot="autocomplete-dropdown"]')!
+      await user.click(dropdownButton as HTMLElement)
+
+      await waitFor(() => {
+        expect(screen.getByRole("listbox")).toBeInTheDocument()
+      })
+
+      // All options should be visible
+      expect(screen.getAllByRole("option")).toHaveLength(3)
+    })
+  })
+})