fix(headless): register jest-dom matcher types for vitest 4

.changeset/headless-jest-dom-matcher-types.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/package.json

@@ -53,8 +53,9 @@
   "scripts": {
     "build": "rm -rf dist && vite build",
     "dev": "vite build --watch",
-    "lint": "eslint src",
-    "test": "vitest run"
+    "lint": "eslint src && pnpm typecheck",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@floating-ui/react": "catalog:repo"

packages/headless/src/test-utils/jest-dom.d.ts

@@ -1,2 +1,17 @@
-import '@testing-library/jest-dom/vitest';
+import 'vitest';
 import './vitest-axe';
+
+import type { TestingLibraryMatchers } from '@testing-library/jest-dom/matchers';
+
+// `@testing-library/jest-dom/vitest` registers its matcher types via a
+// triple-slash `/// <reference>` to an internal declaration file, which does not
+// reliably apply when re-exported through this package's test setup. Declare the
+// `vitest` module augmentation explicitly so `expect(...).toBeInTheDocument()` and
+// friends are typed. `import 'vitest'` keeps this file a module augmentation
+// rather than an ambient module declaration that would shadow vitest's own types.
+declare module 'vitest' {
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface Assertion<T = any> extends TestingLibraryMatchers<any, T> {}
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface AsymmetricMatchersContaining extends TestingLibraryMatchers<any, any> {}
+}