From a4341cafa9a0b8de4c093509d9800b3722a3912c Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Tue, 5 May 2026 10:46:22 -0400
Subject: [PATCH 1/7] feat(headless): add package foundation with Dialog
 primitive
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Introduces the @clerk/headless package — a zero-style React component
library providing accessible headless UI primitives. This first PR
establishes the core infrastructure and patterns:

- Package scaffold: Vite build, Vitest browser tests (Chromium), TypeScript config
- Core utils: renderElement (polymorphic rendering with render prop support),
  mergeProps (event handler chaining, style/className merging)
- Hooks: useControllableState, useTransitionStatus, useAnimationsFinished, useTransition
- First primitive: Dialog (modal with focus trapping, scroll lock, portal support)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 pnpm-lock.yaml | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 7f5f20af86a..bffe58b405a 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -21501,6 +21501,19 @@ snapshots:
     optionalDependencies:
       typescript: 5.8.3
 
+  '@vue/language-core@2.2.0(typescript@5.8.3)':
+    dependencies:
+      '@volar/language-core': 2.4.27
+      '@vue/compiler-dom': 3.5.33
+      '@vue/compiler-vue2': 2.7.16
+      '@vue/shared': 3.5.33
+      alien-signals: 0.4.14
+      minimatch: 9.0.9
+      muggle-string: 0.4.1
+      path-browserify: 1.0.1
+    optionalDependencies:
+      typescript: 5.8.3
+
   '@vue/language-core@3.1.4(typescript@5.8.3)':
     dependencies:
       '@volar/language-core': 2.4.23

From e1672499a61d8ec5543561005bc920dd714b1c32 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Tue, 5 May 2026 10:46:22 -0400
Subject: [PATCH 2/7] feat(headless): add package foundation with Dialog
 primitive
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Introduces the @clerk/headless package — a zero-style React component
library providing accessible headless UI primitives. This first PR
establishes the core infrastructure and patterns:

- Package scaffold: Vite build, Vitest browser tests (Chromium), TypeScript config
- Core utils: renderElement (polymorphic rendering with render prop support),
  mergeProps (event handler chaining, style/className merging)
- Hooks: useControllableState, useTransitionStatus, useAnimationsFinished, useTransition
- First primitive: Dialog (modal with focus trapping, scroll lock, portal support)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 pnpm-lock.yaml | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index bffe58b405a..930ca130a23 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -21514,6 +21514,19 @@ snapshots:
     optionalDependencies:
       typescript: 5.8.3
 
+  '@vue/language-core@2.2.0(typescript@5.8.3)':
+    dependencies:
+      '@volar/language-core': 2.4.27
+      '@vue/compiler-dom': 3.5.33
+      '@vue/compiler-vue2': 2.7.16
+      '@vue/shared': 3.5.33
+      alien-signals: 0.4.14
+      minimatch: 9.0.9
+      muggle-string: 0.4.1
+      path-browserify: 1.0.1
+    optionalDependencies:
+      typescript: 5.8.3
+
   '@vue/language-core@3.1.4(typescript@5.8.3)':
     dependencies:
       '@volar/language-core': 2.4.23

From ed793733846dbce193645f76222c9e8ab2320e0d Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Tue, 5 May 2026 10:46:22 -0400
Subject: [PATCH 3/7] feat(headless): add package foundation with Dialog
 primitive
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Introduces the @clerk/headless package — a zero-style React component
library providing accessible headless UI primitives. This first PR
establishes the core infrastructure and patterns:

- Package scaffold: Vite build, Vitest browser tests (Chromium), TypeScript config
- Core utils: renderElement (polymorphic rendering with render prop support),
  mergeProps (event handler chaining, style/className merging)
- Hooks: useControllableState, useTransitionStatus, useAnimationsFinished, useTransition
- First primitive: Dialog (modal with focus trapping, scroll lock, portal support)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 pnpm-lock.yaml | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 930ca130a23..2c3e4114bf9 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -21527,6 +21527,19 @@ snapshots:
     optionalDependencies:
       typescript: 5.8.3
 
+  '@vue/language-core@2.2.0(typescript@5.8.3)':
+    dependencies:
+      '@volar/language-core': 2.4.27
+      '@vue/compiler-dom': 3.5.33
+      '@vue/compiler-vue2': 2.7.16
+      '@vue/shared': 3.5.33
+      alien-signals: 0.4.14
+      minimatch: 9.0.9
+      muggle-string: 0.4.1
+      path-browserify: 1.0.1
+    optionalDependencies:
+      typescript: 5.8.3
+
   '@vue/language-core@3.1.4(typescript@5.8.3)':
     dependencies:
       '@volar/language-core': 2.4.23

From dcfd8fe54b68a4a20bb3254b621dd720fd0f7932 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Tue, 5 May 2026 11:38:36 -0400
Subject: [PATCH 4/7] feat(headless): add cssVars utility and Tooltip primitive

---
 packages/headless/package.json                |   4 +
 .../headless/src/primitives/tooltip/README.md | 115 ++++++
 .../headless/src/primitives/tooltip/index.ts  |  10 +
 .../src/primitives/tooltip/tooltip.test.tsx   | 309 ++++++++++++++++
 .../src/primitives/tooltip/tooltip.tsx        | 333 ++++++++++++++++++
 packages/headless/src/utils/css-vars.test.ts  | 269 ++++++++++++++
 packages/headless/src/utils/css-vars.ts       |  76 ++++
 packages/headless/src/utils/index.ts          |   1 +
 packages/headless/vite.config.ts              |   1 +
 9 files changed, 1118 insertions(+)
 create mode 100644 packages/headless/src/primitives/tooltip/README.md
 create mode 100644 packages/headless/src/primitives/tooltip/index.ts
 create mode 100644 packages/headless/src/primitives/tooltip/tooltip.test.tsx
 create mode 100644 packages/headless/src/primitives/tooltip/tooltip.tsx
 create mode 100644 packages/headless/src/utils/css-vars.test.ts
 create mode 100644 packages/headless/src/utils/css-vars.ts

diff --git a/packages/headless/package.json b/packages/headless/package.json
index 8a255213ca1..6745f1917b9 100644
--- a/packages/headless/package.json
+++ b/packages/headless/package.json
@@ -13,6 +13,10 @@
       "import": "./dist/primitives/tabs/index.js",
       "types": "./dist/primitives/tabs/index.d.ts"
     },
+    "./tooltip": {
+      "import": "./dist/primitives/tooltip/index.js",
+      "types": "./dist/primitives/tooltip/index.d.ts"
+    },
     "./dialog": {
       "import": "./dist/primitives/dialog/index.js",
       "types": "./dist/primitives/dialog/index.d.ts"
diff --git a/packages/headless/src/primitives/tooltip/README.md b/packages/headless/src/primitives/tooltip/README.md
new file mode 100644
index 00000000000..41cca266d07
--- /dev/null
+++ b/packages/headless/src/primitives/tooltip/README.md
@@ -0,0 +1,115 @@
+# Tooltip
+
+A floating label that appears on hover or focus. Non-interactive, used for supplementary descriptions. No focus trapping — tooltips never receive focus.
+
+## When to Use
+
+- Describing icon buttons, truncated text, or any element that benefits from a short label.
+- When the content is display-only (no interactive elements inside).
+- Prefer Tooltip over Popover when the content is a simple text label that should appear on hover/focus and disappear immediately.
+
+## Usage
+
+```tsx
+import { Tooltip } from '@/primitives/tooltip';
+
+<Tooltip>
+  <Tooltip.Trigger>
+    <IconButton aria-label='Settings' />
+  </Tooltip.Trigger>
+  <Tooltip.Positioner>
+    <Tooltip.Popup>
+      Settings
+      <Tooltip.Arrow />
+    </Tooltip.Popup>
+  </Tooltip.Positioner>
+</Tooltip>;
+```
+
+### Controlled
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Tooltip
+  open={open}
+  onOpenChange={setOpen}
+>
+  {/* ... */}
+</Tooltip>;
+```
+
+### Custom Delay
+
+```tsx
+<Tooltip
+  delay={500}
+  closeDelay={100}
+>
+  {/* Opens after 500ms hover, closes 100ms after leaving */}
+</Tooltip>
+```
+
+## Parts
+
+| Part                 | Default Element | Description                                      |
+| -------------------- | --------------- | ------------------------------------------------ |
+| `Tooltip`            | —               | Root context provider                            |
+| `Tooltip.Trigger`    | `<button>`      | Element that triggers the tooltip on hover/focus |
+| `Tooltip.Portal`     | —               | Portals children (accepts `root` prop)           |
+| `Tooltip.Positioner` | `<div>`         | Floating positioned container                    |
+| `Tooltip.Popup`      | `<div>`         | The visible tooltip content                      |
+| `Tooltip.Arrow`      | `<svg>`         | Optional arrow pointing at the trigger           |
+
+## Props
+
+### `Tooltip` (root)
+
+| Prop           | Type                      | Default | Description                          |
+| -------------- | ------------------------- | ------- | ------------------------------------ |
+| `open`         | `boolean`                 | —       | Controlled open state                |
+| `defaultOpen`  | `boolean`                 | `false` | Initial open state (uncontrolled)    |
+| `onOpenChange` | `(open: boolean) => void` | —       | Called when open state changes       |
+| `placement`    | `Placement`               | `"top"` | Floating UI placement                |
+| `sideOffset`   | `number`                  | `4`     | Gap between trigger and tooltip (px) |
+| `delay`        | `number`                  | `200`   | Hover open delay (ms)                |
+| `closeDelay`   | `number`                  | `0`     | Hover close delay (ms)               |
+
+### `Tooltip.Trigger`, `Tooltip.Positioner`, `Tooltip.Popup`
+
+No additional props beyond standard HTML attributes and the `render` prop.
+
+### `Tooltip.Arrow`
+
+Accepts all `FloatingArrow` props. `ref` and `context` are injected automatically.
+
+## Open/Close Behavior
+
+- **Hover**: Opens after `delay` ms, closes after `closeDelay` ms.
+- **Focus**: Opens on keyboard focus (`:focus-visible`), closes on blur.
+- **Dismiss**: Closes on Escape key.
+- **No click handling** — tooltips are triggered by hover and focus only.
+
+## Data Attributes
+
+| Attribute                         | Applies To        | Description                              |
+| --------------------------------- | ----------------- | ---------------------------------------- |
+| `data-cl-slot`                    | All parts         | Part identifier (e.g. `"tooltip-popup"`) |
+| `data-cl-open` / `data-cl-closed` | Trigger           | Open state                               |
+| `data-cl-side`                    | Positioner, Arrow | Resolved placement side                  |
+
+## Positioning
+
+Middleware stack: `offset` -> `flip` -> `shift` -> `arrow` -> CSS vars. Repositions automatically on scroll/resize via `autoUpdate`.
+
+## Important Notes
+
+- **No `FloatingFocusManager`** — tooltips do not receive or trap focus. This is correct per ARIA guidelines.
+- **Nested tooltips are supported** via `FloatingTree`.
+- **`Tooltip.Trigger` wraps its child** — if your trigger is already a button, the `render` prop can forward props to it instead of wrapping.
+- **For tooltip clusters** (e.g. toolbar buttons), consider adding `FloatingDelayGroup` support for instant switching between tooltips.
+
+## ARIA
+
+- Popup: `role="tooltip"`
+- Trigger: `aria-describedby` (pointing to the tooltip)
diff --git a/packages/headless/src/primitives/tooltip/index.ts b/packages/headless/src/primitives/tooltip/index.ts
new file mode 100644
index 00000000000..3c1ebcf36e6
--- /dev/null
+++ b/packages/headless/src/primitives/tooltip/index.ts
@@ -0,0 +1,10 @@
+export type {
+  TooltipArrowProps,
+  TooltipGroupProps,
+  TooltipPopupProps,
+  TooltipPortalProps,
+  TooltipPositionerProps,
+  TooltipProps,
+  TooltipTriggerProps,
+} from './tooltip';
+export { Tooltip } from './tooltip';
diff --git a/packages/headless/src/primitives/tooltip/tooltip.test.tsx b/packages/headless/src/primitives/tooltip/tooltip.test.tsx
new file mode 100644
index 00000000000..bbc344768b5
--- /dev/null
+++ b/packages/headless/src/primitives/tooltip/tooltip.test.tsx
@@ -0,0 +1,309 @@
+import { act, cleanup, render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { axe } from '../../test-utils/axe';
+import { Tooltip } from './tooltip';
+
+afterEach(() => cleanup());
+
+function renderTooltip(props: Partial<React.ComponentProps<typeof Tooltip>> = {}) {
+  return render(
+    <Tooltip
+      delay={0}
+      {...props}
+    >
+      <Tooltip.Trigger>Hover me</Tooltip.Trigger>
+      <Tooltip.Positioner>
+        <Tooltip.Popup>Tooltip content</Tooltip.Popup>
+      </Tooltip.Positioner>
+    </Tooltip>,
+  );
+}
+
+describe('Tooltip', () => {
+  describe('slot attributes', () => {
+    it('renders trigger with data-cl-slot', () => {
+      renderTooltip();
+      const trigger = screen.getByRole('button', { name: 'Hover me' });
+      expect(trigger).toHaveAttribute('data-cl-slot', 'tooltip-trigger');
+    });
+
+    it('renders all parts with correct slot attributes when open', () => {
+      renderTooltip({ defaultOpen: true });
+
+      expect(document.querySelector('[data-cl-slot="tooltip-positioner"]')).toBeInTheDocument();
+      expect(document.querySelector('[data-cl-slot="tooltip-popup"]')).toBeInTheDocument();
+    });
+  });
+
+  describe('open/close', () => {
+    it('opens on hover', async () => {
+      const user = userEvent.setup();
+      renderTooltip();
+
+      const trigger = screen.getByRole('button', { name: 'Hover me' });
+      await user.hover(trigger);
+
+      expect(document.querySelector('[data-cl-slot="tooltip-popup"]')).toBeInTheDocument();
+    });
+
+    it('closes on unhover', async () => {
+      const user = userEvent.setup();
+      renderTooltip();
+
+      const trigger = screen.getByRole('button', { name: 'Hover me' });
+      await user.hover(trigger);
+
+      expect(document.querySelector('[data-cl-slot="tooltip-popup"]')).toBeInTheDocument();
+
+      await user.unhover(trigger);
+
+      const triggerEl = screen.getByRole('button', { name: 'Hover me' });
+      expect(triggerEl).toHaveAttribute('data-cl-closed', '');
+    });
+
+    it('opens on focus', async () => {
+      const user = userEvent.setup();
+      renderTooltip();
+
+      const trigger = screen.getByRole('button', { name: 'Hover me' });
+      await act(async () => {
+        trigger.focus();
+      });
+
+      expect(document.querySelector('[data-cl-slot="tooltip-popup"]')).toBeInTheDocument();
+    });
+
+    it('closes on Escape', async () => {
+      const user = userEvent.setup();
+      renderTooltip({ defaultOpen: true });
+
+      await user.keyboard('{Escape}');
+
+      const trigger = screen.getByRole('button', { name: 'Hover me' });
+      expect(trigger).toHaveAttribute('data-cl-closed', '');
+    });
+
+    it('calls onOpenChange when toggled', async () => {
+      const onOpenChange = vi.fn();
+      const user = userEvent.setup();
+      renderTooltip({ onOpenChange });
+
+      const trigger = screen.getByRole('button', { name: 'Hover me' });
+      await user.hover(trigger);
+
+      expect(onOpenChange).toHaveBeenCalledWith(true);
+    });
+  });
+
+  describe('controlled open', () => {
+    it('respects controlled open prop', () => {
+      renderTooltip({ open: true });
+
+      expect(document.querySelector('[data-cl-slot="tooltip-positioner"]')).toBeInTheDocument();
+    });
+
+    it('does not open when controlled open is false', async () => {
+      const user = userEvent.setup();
+      renderTooltip({ open: false });
+
+      await user.hover(screen.getByRole('button', { name: 'Hover me' }));
+
+      expect(document.querySelector('[data-cl-slot="tooltip-positioner"]')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('ARIA attributes', () => {
+    it('trigger has tooltip role association', async () => {
+      const user = userEvent.setup();
+      renderTooltip();
+
+      const trigger = screen.getByRole('button', { name: 'Hover me' });
+      await user.hover(trigger);
+
+      // aria-describedby must reference the tooltip positioner's id
+      const positioner = document.querySelector('[data-cl-slot="tooltip-positioner"]');
+      expect(positioner).toBeInTheDocument();
+      const positionerId = positioner!.getAttribute('id');
+      expect(positionerId).toBeTruthy();
+      expect(trigger.getAttribute('aria-describedby')).toBe(positionerId);
+    });
+
+    it('tooltip content has role=tooltip', async () => {
+      const user = userEvent.setup();
+      renderTooltip();
+
+      await user.hover(screen.getByRole('button', { name: 'Hover me' }));
+
+      expect(screen.getByRole('tooltip')).toBeInTheDocument();
+    });
+
+    it('focus stays on trigger when tooltip is open', async () => {
+      const user = userEvent.setup();
+      renderTooltip();
+
+      const trigger = screen.getByRole('button', { name: 'Hover me' });
+      await user.hover(trigger);
+
+      expect(document.querySelector('[data-cl-slot="tooltip-popup"]')).toBeInTheDocument();
+      // Tooltip must not steal focus — active element should not be inside the tooltip
+      const popup = document.querySelector('[data-cl-slot="tooltip-popup"]');
+      expect(popup).not.toContainElement(document.activeElement as HTMLElement);
+    });
+  });
+
+  describe('animation lifecycle', () => {
+    it('positioner is not rendered when closed', () => {
+      renderTooltip();
+      expect(document.querySelector('[data-cl-slot="tooltip-positioner"]')).not.toBeInTheDocument();
+    });
+
+    it('applies data-cl-open on popup when open', async () => {
+      const user = userEvent.setup();
+      renderTooltip();
+
+      await user.hover(screen.getByRole('button', { name: 'Hover me' }));
+
+      const popup = document.querySelector('[data-cl-slot="tooltip-popup"]');
+      expect(popup).toHaveAttribute('data-cl-open', '');
+    });
+
+    it('positioner has data-cl-side', async () => {
+      const user = userEvent.setup();
+      renderTooltip();
+
+      await user.hover(screen.getByRole('button', { name: 'Hover me' }));
+
+      const positioner = document.querySelector('[data-cl-slot="tooltip-positioner"]');
+      expect(positioner).toHaveAttribute('data-cl-side');
+    });
+  });
+
+  describe('placement', () => {
+    it('accepts custom placement', () => {
+      renderTooltip({ defaultOpen: true, placement: 'bottom-end' });
+
+      const positioner = document.querySelector('[data-cl-slot="tooltip-positioner"]');
+      expect(positioner).toHaveAttribute('data-cl-side', 'bottom');
+    });
+
+    it('defaults to top placement', () => {
+      renderTooltip({ defaultOpen: true });
+
+      const positioner = document.querySelector('[data-cl-slot="tooltip-positioner"]');
+      expect(positioner).toHaveAttribute('data-cl-side', 'top');
+    });
+  });
+
+  describe('trigger state attributes', () => {
+    it('trigger has data-cl-open when tooltip is visible', async () => {
+      const user = userEvent.setup();
+      renderTooltip();
+
+      const trigger = screen.getByRole('button', { name: 'Hover me' });
+      await user.hover(trigger);
+
+      expect(trigger).toHaveAttribute('data-cl-open', '');
+    });
+
+    it('trigger has data-cl-closed when tooltip is hidden', () => {
+      renderTooltip();
+
+      const trigger = screen.getByRole('button', { name: 'Hover me' });
+      expect(trigger).toHaveAttribute('data-cl-closed', '');
+    });
+  });
+
+  describe('content rendering', () => {
+    it('renders children content when open', async () => {
+      const user = userEvent.setup();
+      renderTooltip();
+
+      await user.hover(screen.getByRole('button', { name: 'Hover me' }));
+
+      expect(screen.getByText('Tooltip content')).toBeInTheDocument();
+    });
+
+    it('does not render content when closed', () => {
+      renderTooltip();
+      expect(screen.queryByText('Tooltip content')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('accessibility (axe)', () => {
+    it('has no violations when closed', async () => {
+      const { container } = renderTooltip();
+      expect(await axe(container)).toHaveNoViolations();
+    });
+
+    it('has no violations when open', async () => {
+      renderTooltip({ defaultOpen: true });
+      expect(await axe(document.body, { rules: { region: { enabled: false } } })).toHaveNoViolations();
+    });
+  });
+
+  describe('Tooltip.Group', () => {
+    function renderTooltipGroup() {
+      return render(
+        <Tooltip.Group delay={{ open: 0, close: 0 }}>
+          <Tooltip delay={0}>
+            <Tooltip.Trigger>Button A</Tooltip.Trigger>
+            <Tooltip.Positioner>
+              <Tooltip.Popup>Tooltip A</Tooltip.Popup>
+            </Tooltip.Positioner>
+          </Tooltip>
+          <Tooltip delay={0}>
+            <Tooltip.Trigger>Button B</Tooltip.Trigger>
+            <Tooltip.Positioner>
+              <Tooltip.Popup>Tooltip B</Tooltip.Popup>
+            </Tooltip.Positioner>
+          </Tooltip>
+        </Tooltip.Group>,
+      );
+    }
+
+    it('renders grouped tooltips', async () => {
+      renderTooltipGroup();
+
+      expect(screen.getByRole('button', { name: 'Button A' })).toBeInTheDocument();
+      expect(screen.getByRole('button', { name: 'Button B' })).toBeInTheDocument();
+    });
+
+    it('opens tooltip within a group on hover', async () => {
+      const user = userEvent.setup();
+      renderTooltipGroup();
+
+      const triggerA = screen.getByRole('button', { name: 'Button A' });
+      await user.hover(triggerA);
+
+      await waitFor(() => {
+        expect(screen.getByText('Tooltip A')).toBeInTheDocument();
+      });
+    });
+
+    it('switches between grouped tooltips without full delay', async () => {
+      const user = userEvent.setup();
+      renderTooltipGroup();
+
+      const triggerA = screen.getByRole('button', { name: 'Button A' });
+      const triggerB = screen.getByRole('button', { name: 'Button B' });
+
+      // Open first tooltip (wait for it to appear)
+      await user.hover(triggerA);
+      await waitFor(() => {
+        expect(screen.getByText('Tooltip A')).toBeInTheDocument();
+      });
+
+      // Move to second tooltip — group instant phase should show it quickly
+      await user.unhover(triggerA);
+      await user.hover(triggerB);
+
+      await waitFor(() => {
+        expect(screen.getByText('Tooltip B')).toBeInTheDocument();
+      });
+
+      // First tooltip should no longer be visible
+      expect(screen.queryByText('Tooltip A')).not.toBeInTheDocument();
+    });
+  });
+});
diff --git a/packages/headless/src/primitives/tooltip/tooltip.tsx b/packages/headless/src/primitives/tooltip/tooltip.tsx
new file mode 100644
index 00000000000..c3af6ad2961
--- /dev/null
+++ b/packages/headless/src/primitives/tooltip/tooltip.tsx
@@ -0,0 +1,333 @@
+'use client';
+
+import {
+  arrow,
+  autoUpdate,
+  type ExtendedRefs,
+  FloatingArrow,
+  type FloatingContext,
+  FloatingDelayGroup,
+  FloatingNode,
+  FloatingPortal,
+  FloatingTree,
+  flip,
+  offset,
+  type Placement,
+  type ReferenceType,
+  shift,
+  type UseInteractionsReturn,
+  useDelayGroup,
+  useDismiss,
+  useFloating,
+  useFloatingNodeId,
+  useFloatingParentNodeId,
+  useFocus,
+  useHover,
+  useInteractions,
+  useRole,
+} from '@floating-ui/react';
+import { type CSSProperties, createContext, type ReactNode, useContext, useMemo, useRef } from 'react';
+import { useControllableState } from '../../hooks/use-controllable-state';
+import { type TransitionProps, useTransition } from '../../hooks/use-transition';
+import { cssVars } from '../../utils/css-vars';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+
+// ---------------------------------------------------------------------------
+// Context
+// ---------------------------------------------------------------------------
+
+interface TooltipContextValue {
+  open: boolean;
+  floatingContext: FloatingContext;
+  refs: ExtendedRefs<ReferenceType>;
+  floatingStyles: CSSProperties;
+  placement: Placement;
+  getReferenceProps: UseInteractionsReturn['getReferenceProps'];
+  getFloatingProps: UseInteractionsReturn['getFloatingProps'];
+  popupRef: React.RefObject<HTMLDivElement | null>;
+  arrowRef: React.MutableRefObject<SVGSVGElement | null>;
+  mounted: boolean;
+  transitionProps: TransitionProps;
+}
+
+const TooltipContext = createContext<TooltipContextValue | null>(null);
+
+function useTooltipContext() {
+  const ctx = useContext(TooltipContext);
+  if (!ctx) {
+    throw new Error('Tooltip compound components must be used within <Tooltip>');
+  }
+  return ctx;
+}
+
+// ---------------------------------------------------------------------------
+// Tooltip (root)
+// ---------------------------------------------------------------------------
+
+export interface TooltipProps {
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  placement?: Placement;
+  sideOffset?: number;
+  /** Delay in ms before the tooltip opens on hover. Default: 200 */
+  delay?: number;
+  /** Delay in ms before the tooltip closes on hover out. Default: 0 */
+  closeDelay?: number;
+  children: ReactNode;
+}
+
+function TooltipInner(props: TooltipProps) {
+  const nodeId = useFloatingNodeId();
+
+  const { placement: placementProp = 'top', sideOffset = 4, delay = 200, closeDelay = 0, children } = props;
+
+  const [open, setOpen] = useControllableState(props.open, props.defaultOpen ?? false, props.onOpenChange);
+
+  const arrowRef = useRef<SVGSVGElement | null>(null);
+  const popupRef = useRef<HTMLDivElement | null>(null);
+
+  const {
+    refs,
+    floatingStyles,
+    context: floatingContext,
+    placement,
+  } = useFloating({
+    nodeId,
+    open,
+    onOpenChange: setOpen,
+    placement: placementProp,
+    middleware: [
+      offset(sideOffset),
+      flip({
+        crossAxis: placementProp.includes('-'),
+        fallbackAxisSideDirection: 'start',
+        padding: 5,
+      }),
+      shift({ padding: 5 }),
+      arrow({ element: arrowRef }),
+      cssVars({ sideOffset }),
+    ],
+    whileElementsMounted: autoUpdate,
+  });
+
+  const { mounted, transitionProps } = useTransition({
+    open,
+    ref: popupRef,
+  });
+
+  // Integrate with FloatingDelayGroup when inside a Tooltip.Group.
+  // Safe to call unconditionally — no-op without a parent provider.
+  useDelayGroup(floatingContext, { id: nodeId });
+
+  const hover = useHover(floatingContext, {
+    move: false,
+    delay: { open: delay, close: closeDelay },
+  });
+  const focus = useFocus(floatingContext);
+  const dismiss = useDismiss(floatingContext);
+  const role = useRole(floatingContext, { role: 'tooltip' });
+
+  const { getReferenceProps, getFloatingProps } = useInteractions([hover, focus, dismiss, role]);
+
+  const contextValue = useMemo<TooltipContextValue>(
+    () => ({
+      open,
+      floatingContext,
+      refs,
+      floatingStyles,
+      placement,
+      getReferenceProps,
+      getFloatingProps,
+      popupRef,
+      arrowRef,
+      mounted,
+      transitionProps,
+    }),
+    [
+      open,
+      floatingContext,
+      refs,
+      floatingStyles,
+      placement,
+      getReferenceProps,
+      getFloatingProps,
+      mounted,
+      transitionProps,
+    ],
+  );
+
+  return (
+    <FloatingNode id={nodeId}>
+      <TooltipContext.Provider value={contextValue}>{children}</TooltipContext.Provider>
+    </FloatingNode>
+  );
+}
+
+function TooltipRoot(props: TooltipProps) {
+  const parentId = useFloatingParentNodeId();
+
+  if (parentId === null) {
+    return (
+      <FloatingTree>
+        <TooltipInner {...props} />
+      </FloatingTree>
+    );
+  }
+
+  return <TooltipInner {...props} />;
+}
+
+// ---------------------------------------------------------------------------
+// Tooltip.Trigger
+// ---------------------------------------------------------------------------
+
+export interface TooltipTriggerProps extends ComponentProps<'button'> {}
+
+function TooltipTrigger(props: TooltipTriggerProps) {
+  const { render, ...otherProps } = props;
+  const { open, refs, getReferenceProps } = useTooltipContext();
+
+  const state = { open };
+
+  const defaultProps = {
+    type: 'button' as const,
+    'data-cl-slot': 'tooltip-trigger',
+    ref: refs.setReference,
+    ...(getReferenceProps() as React.ComponentPropsWithRef<'button'>),
+  };
+
+  return renderElement({
+    defaultTagName: 'button',
+    render,
+    state,
+    stateAttributesMapping: {
+      open: (v: boolean): Record<string, string> | null => (v ? { 'data-cl-open': '' } : { 'data-cl-closed': '' }),
+    },
+    props: mergeProps<'button'>(defaultProps, otherProps),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Tooltip.Portal
+// ---------------------------------------------------------------------------
+
+export interface TooltipPortalProps {
+  children: ReactNode;
+  root?: HTMLElement | null | React.RefObject<HTMLElement | null>;
+}
+
+function TooltipPortal(props: TooltipPortalProps) {
+  const { mounted } = useTooltipContext();
+  if (!mounted) return null;
+  return <FloatingPortal root={props.root}>{props.children}</FloatingPortal>;
+}
+
+// ---------------------------------------------------------------------------
+// Tooltip.Positioner
+// ---------------------------------------------------------------------------
+
+export interface TooltipPositionerProps extends ComponentProps<'div'> {}
+
+function TooltipPositioner(props: TooltipPositionerProps) {
+  const { render, ...otherProps } = props;
+  const { mounted, refs, floatingStyles, placement, getFloatingProps } = useTooltipContext();
+
+  const side = placement.split('-')[0];
+
+  const defaultProps = {
+    'data-cl-slot': 'tooltip-positioner',
+    'data-cl-side': side,
+    ref: refs.setFloating,
+    style: floatingStyles,
+    ...(getFloatingProps() as React.ComponentPropsWithRef<'div'>),
+  };
+
+  return renderElement({
+    defaultTagName: 'div',
+    render,
+    enabled: mounted,
+    props: mergeProps<'div'>(defaultProps, otherProps),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Tooltip.Popup
+// ---------------------------------------------------------------------------
+
+export interface TooltipPopupProps extends ComponentProps<'div'> {}
+
+function TooltipPopup(props: TooltipPopupProps) {
+  const { render, ...otherProps } = props;
+  const { popupRef, transitionProps } = useTooltipContext();
+
+  const defaultProps = {
+    'data-cl-slot': 'tooltip-popup',
+    ref: popupRef,
+    ...transitionProps,
+  };
+
+  return renderElement({
+    defaultTagName: 'div',
+    render,
+    props: mergeProps<'div'>(defaultProps, otherProps),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Tooltip.Arrow
+// ---------------------------------------------------------------------------
+
+export interface TooltipArrowProps extends React.ComponentPropsWithRef<typeof FloatingArrow> {}
+
+function TooltipArrowComponent(props: TooltipArrowProps) {
+  const { floatingContext, arrowRef, placement } = useTooltipContext();
+  const side = placement.split('-')[0];
+
+  return (
+    <FloatingArrow
+      data-cl-slot='tooltip-arrow'
+      data-cl-side={side}
+      {...props}
+      ref={arrowRef}
+      context={floatingContext}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Tooltip.Group
+// ---------------------------------------------------------------------------
+
+export interface TooltipGroupProps {
+  /** Shared delay config for grouped tooltips. Default: { open: 200, close: 100 } */
+  delay?: number | { open?: number; close?: number };
+  /** Time in ms before the group resets to non-instant phase. Default: 300 */
+  timeoutMs?: number;
+  children: ReactNode;
+}
+
+function TooltipGroupRoot(props: TooltipGroupProps) {
+  const { delay = { open: 200, close: 100 }, timeoutMs = 300, children } = props;
+  return (
+    <FloatingDelayGroup
+      delay={delay}
+      timeoutMs={timeoutMs}
+    >
+      {children}
+    </FloatingDelayGroup>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Compound export
+// ---------------------------------------------------------------------------
+
+export const Tooltip = Object.assign(TooltipRoot, {
+  Trigger: TooltipTrigger,
+  Portal: TooltipPortal,
+  Positioner: TooltipPositioner,
+  Popup: TooltipPopup,
+  Arrow: TooltipArrowComponent,
+  Group: TooltipGroupRoot,
+});
diff --git a/packages/headless/src/utils/css-vars.test.ts b/packages/headless/src/utils/css-vars.test.ts
new file mode 100644
index 00000000000..f15d2e247b0
--- /dev/null
+++ b/packages/headless/src/utils/css-vars.test.ts
@@ -0,0 +1,269 @@
+import type { MiddlewareState } from '@floating-ui/react';
+import { describe, expect, it, vi } from 'vitest';
+import { cssVars } from './css-vars';
+
+// Build a minimal MiddlewareState mock for testing the middleware fn
+function createMockState(
+  overrides: {
+    placement?: string;
+    referenceWidth?: number;
+    referenceHeight?: number;
+    floatingWidth?: number;
+    floatingHeight?: number;
+    arrowX?: number;
+    arrowY?: number;
+    arrowElWidth?: number;
+    arrowElHeight?: number;
+    overflow?: { top: number; right: number; bottom: number; left: number };
+  } = {},
+): MiddlewareState {
+  const {
+    placement = 'bottom',
+    referenceWidth = 100,
+    referenceHeight = 40,
+    floatingWidth = 200,
+    floatingHeight = 150,
+    arrowX,
+    arrowY,
+    arrowElWidth = 0,
+    arrowElHeight = 0,
+    overflow = { top: 0, right: 0, bottom: 0, left: 0 },
+  } = overrides;
+
+  const style = {
+    setProperty: vi.fn(),
+  };
+
+  // Mock arrow element inside floating
+  const arrowEl = arrowElWidth || arrowElHeight ? { clientWidth: arrowElWidth, clientHeight: arrowElHeight } : null;
+
+  const floating = {
+    style,
+    querySelector: vi.fn(() => arrowEl),
+  } as unknown as HTMLElement;
+
+  return {
+    placement,
+    elements: {
+      floating,
+      reference: document.createElement('div'),
+    },
+    rects: {
+      reference: { width: referenceWidth, height: referenceHeight, x: 0, y: 0 },
+      floating: { width: floatingWidth, height: floatingHeight, x: 0, y: 0 },
+    },
+    middlewareData: {
+      arrow: arrowX != null || arrowY != null ? { x: arrowX ?? 0, y: arrowY ?? 0, centerOffset: 0 } : {},
+    },
+    platform: {
+      getElementRects: vi.fn(),
+      getDimensions: vi.fn(),
+      getClippingRect: vi.fn(async () => ({
+        width: 1024,
+        height: 768,
+        x: 0,
+        y: 0,
+      })),
+      convertOffsetParentRelativeRectToViewportRelativeRect: vi.fn(async ({ rect }: { rect: unknown }) => rect),
+    },
+    x: 0,
+    y: 0,
+    initialPlacement: placement,
+    strategy: 'absolute',
+  } as unknown as MiddlewareState;
+}
+
+// Helper to extract setProperty calls into a map
+function getVars(state: MiddlewareState): Map<string, string> {
+  const style = (state.elements.floating as HTMLElement).style;
+  const calls = (style.setProperty as ReturnType<typeof vi.fn>).mock.calls as [string, string][];
+  return new Map(calls.map(([name, value]) => [name, value]));
+}
+
+describe('cssVars middleware', () => {
+  it("has name 'cssVars'", () => {
+    const mw = cssVars();
+    expect(mw.name).toBe('cssVars');
+  });
+
+  describe('--cl-anchor-width and --cl-anchor-height', () => {
+    it('sets anchor dimensions from reference rects', async () => {
+      const mw = cssVars();
+      const state = createMockState({
+        referenceWidth: 120,
+        referenceHeight: 36,
+      });
+      await mw.fn(state);
+
+      const vars = getVars(state);
+      expect(vars.get('--cl-anchor-width')).toBe('120px');
+      expect(vars.get('--cl-anchor-height')).toBe('36px');
+    });
+
+    it('handles zero-size reference', async () => {
+      const mw = cssVars();
+      const state = createMockState({
+        referenceWidth: 0,
+        referenceHeight: 0,
+      });
+      await mw.fn(state);
+
+      const vars = getVars(state);
+      expect(vars.get('--cl-anchor-width')).toBe('0px');
+      expect(vars.get('--cl-anchor-height')).toBe('0px');
+    });
+  });
+
+  describe('--cl-available-width and --cl-available-height', () => {
+    it('sets available dimensions as CSS vars', async () => {
+      const mw = cssVars();
+      const state = createMockState({
+        floatingWidth: 200,
+        floatingHeight: 150,
+      });
+      await mw.fn(state);
+
+      const vars = getVars(state);
+      // Values are set (exact numbers depend on detectOverflow's padding)
+      expect(vars.has('--cl-available-width')).toBe(true);
+      expect(vars.has('--cl-available-height')).toBe(true);
+      expect(vars.get('--cl-available-width')).toMatch(/^\d+px$/);
+      expect(vars.get('--cl-available-height')).toMatch(/^\d+px$/);
+    });
+  });
+
+  describe('--cl-transform-origin', () => {
+    it('centers on anchor when no arrow (bottom)', async () => {
+      const mw = cssVars({ sideOffset: 8 });
+      // Reference: x=0, width=100 → center at 50. Floating: x=0.
+      // transformX = 0 + 100/2 - 0 = 50
+      const state = createMockState({
+        placement: 'bottom',
+        referenceWidth: 100,
+      });
+      await mw.fn(state);
+
+      const vars = getVars(state);
+      expect(vars.get('--cl-transform-origin')).toBe('50px -8px');
+    });
+
+    it('centers on anchor when no arrow (top)', async () => {
+      const mw = cssVars({ sideOffset: 4 });
+      const state = createMockState({
+        placement: 'top',
+        referenceWidth: 100,
+      });
+      await mw.fn(state);
+
+      const vars = getVars(state);
+      expect(vars.get('--cl-transform-origin')).toBe('50px calc(100% + 4px)');
+    });
+
+    it('centers on anchor when no arrow (left)', async () => {
+      const mw = cssVars({ sideOffset: 6 });
+      const state = createMockState({
+        placement: 'left',
+        referenceHeight: 40,
+      });
+      await mw.fn(state);
+
+      const vars = getVars(state);
+      // transformY = 0 + 40/2 - 0 = 20
+      expect(vars.get('--cl-transform-origin')).toBe('calc(100% + 6px) 20px');
+    });
+
+    it('centers on anchor when no arrow (right)', async () => {
+      const mw = cssVars({ sideOffset: 6 });
+      const state = createMockState({
+        placement: 'right',
+        referenceHeight: 40,
+      });
+      await mw.fn(state);
+
+      const vars = getVars(state);
+      expect(vars.get('--cl-transform-origin')).toBe('-6px 20px');
+    });
+
+    it('handles alignment variants (e.g. bottom-start)', async () => {
+      const mw = cssVars({ sideOffset: 4 });
+      const state = createMockState({
+        placement: 'bottom-start',
+        referenceWidth: 100,
+      });
+      await mw.fn(state);
+
+      const vars = getVars(state);
+      // Side is still "bottom", centers on anchor
+      expect(vars.get('--cl-transform-origin')).toBe('50px -4px');
+    });
+
+    it('uses arrow position when arrow is present', async () => {
+      const mw = cssVars({ sideOffset: 4 });
+      const state = createMockState({
+        placement: 'bottom',
+        arrowX: 50,
+        arrowElWidth: 12,
+      });
+      await mw.fn(state);
+
+      const vars = getVars(state);
+      // transformX = arrowX + arrowWidth/2 = 50 + 6 = 56
+      expect(vars.get('--cl-transform-origin')).toBe('56px -4px');
+    });
+
+    it('uses arrow Y position on left/right placement', async () => {
+      const mw = cssVars({ sideOffset: 4 });
+      const state = createMockState({
+        placement: 'right',
+        arrowY: 30,
+        arrowElHeight: 10,
+      });
+      await mw.fn(state);
+
+      const vars = getVars(state);
+      // transformY = arrowY + arrowHeight/2 = 30 + 5 = 35
+      expect(vars.get('--cl-transform-origin')).toBe('-4px 35px');
+    });
+
+    it('defaults sideOffset to 0 when not provided', async () => {
+      const mw = cssVars();
+      const state = createMockState({
+        placement: 'bottom',
+        referenceWidth: 100,
+      });
+      await mw.fn(state);
+
+      const vars = getVars(state);
+      expect(vars.get('--cl-transform-origin')).toBe('50px 0px');
+    });
+  });
+
+  describe('return value', () => {
+    it('returns empty object (no position changes)', async () => {
+      const mw = cssVars();
+      const state = createMockState();
+      const result = await mw.fn(state);
+      expect(result).toEqual({});
+    });
+  });
+
+  describe('all five CSS vars are set', () => {
+    it('sets exactly 5 CSS custom properties', async () => {
+      const mw = cssVars({ sideOffset: 4 });
+      const state = createMockState({ placement: 'bottom' });
+      await mw.fn(state);
+
+      const style = state.elements.floating.style;
+      const calls = (style.setProperty as ReturnType<typeof vi.fn>).mock.calls as [string, string][];
+      const varNames = calls.map(([name]) => name);
+
+      expect(varNames).toEqual([
+        '--cl-anchor-width',
+        '--cl-anchor-height',
+        '--cl-available-width',
+        '--cl-available-height',
+        '--cl-transform-origin',
+      ]);
+    });
+  });
+});
diff --git a/packages/headless/src/utils/css-vars.ts b/packages/headless/src/utils/css-vars.ts
new file mode 100644
index 00000000000..1ea73a26801
--- /dev/null
+++ b/packages/headless/src/utils/css-vars.ts
@@ -0,0 +1,76 @@
+import { detectOverflow, type Middleware } from '@floating-ui/react';
+
+/**
+ * Positioning middleware that sets CSS custom properties on the floating element:
+ *
+ * - `--cl-anchor-width`      – reference element width (px)
+ * - `--cl-anchor-height`     – reference element height (px)
+ * - `--cl-available-width`   – available width between anchor and viewport edge (px)
+ * - `--cl-available-height`  – available height between anchor and viewport edge (px)
+ * - `--cl-transform-origin`  – CSS transform-origin pointing back toward the anchor
+ *
+ * Place **after** `arrow()` so arrow position data is available for transform-origin.
+ */
+export function cssVars(opts?: { sideOffset?: number }): Middleware {
+  return {
+    name: 'cssVars',
+    async fn(state) {
+      const { elements, rects, middlewareData, placement } = state;
+      const style = elements.floating.style;
+      const sideOffset = opts?.sideOffset ?? 0;
+
+      // Anchor dimensions
+      style.setProperty('--cl-anchor-width', `${rects.reference.width}px`);
+      style.setProperty('--cl-anchor-height', `${rects.reference.height}px`);
+
+      // Available space
+      const overflow = await detectOverflow(state, { padding: 5 });
+      const side = placement.split('-')[0] as 'top' | 'bottom' | 'left' | 'right';
+
+      const availableHeight =
+        side === 'top'
+          ? rects.floating.height - overflow.top
+          : side === 'bottom'
+            ? rects.floating.height - overflow.bottom
+            : rects.floating.height - Math.max(overflow.top, 0) - Math.max(overflow.bottom, 0);
+
+      const availableWidth =
+        side === 'left'
+          ? rects.floating.width - overflow.left
+          : side === 'right'
+            ? rects.floating.width - overflow.right
+            : rects.floating.width - Math.max(overflow.left, 0) - Math.max(overflow.right, 0);
+
+      style.setProperty('--cl-available-width', `${availableWidth}px`);
+      style.setProperty('--cl-available-height', `${availableHeight}px`);
+
+      // Transform origin — points back toward the anchor
+      const arrowEl = elements.floating.querySelector("[data-cl-slot$='-arrow']") as HTMLElement | null;
+
+      let transformX: number;
+      let transformY: number;
+
+      if (arrowEl) {
+        const arrowX = middlewareData.arrow?.x ?? 0;
+        const arrowY = middlewareData.arrow?.y ?? 0;
+        transformX = arrowX + arrowEl.clientWidth / 2;
+        transformY = arrowY + arrowEl.clientHeight / 2;
+      } else {
+        // No arrow — use the anchor's center relative to the floating element
+        transformX = rects.reference.x + rects.reference.width / 2 - state.x;
+        transformY = rects.reference.y + rects.reference.height / 2 - state.y;
+      }
+
+      const originMap: Record<string, string> = {
+        top: `${transformX}px calc(100% + ${sideOffset}px)`,
+        bottom: `${transformX}px ${-sideOffset}px`,
+        left: `calc(100% + ${sideOffset}px) ${transformY}px`,
+        right: `${-sideOffset}px ${transformY}px`,
+      };
+
+      style.setProperty('--cl-transform-origin', originMap[side]);
+
+      return {};
+    },
+  };
+}
diff --git a/packages/headless/src/utils/index.ts b/packages/headless/src/utils/index.ts
index 53fd01599c8..ebfd4caefaa 100644
--- a/packages/headless/src/utils/index.ts
+++ b/packages/headless/src/utils/index.ts
@@ -1 +1,2 @@
+export { cssVars } from './css-vars';
 export { type ComponentProps, mergeProps, type RenderProp, renderElement } from './render-element';
diff --git a/packages/headless/vite.config.ts b/packages/headless/vite.config.ts
index ff74ee240e2..3b1539d06df 100644
--- a/packages/headless/vite.config.ts
+++ b/packages/headless/vite.config.ts
@@ -13,6 +13,7 @@ export default defineConfig({
       entry: {
         'primitives/accordion/index': 'src/primitives/accordion/index.ts',
         'primitives/tabs/index': 'src/primitives/tabs/index.ts',
+        'primitives/tooltip/index': 'src/primitives/tooltip/index.ts',
         'primitives/dialog/index': 'src/primitives/dialog/index.ts',
         'utils/index': 'src/utils/index.ts',
         'hooks/use-controllable-state': 'src/hooks/use-controllable-state.ts',

From 054cccf128785f5cc6d32bd53e43c99e368ba193 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Wed, 3 Jun 2026 12:46:36 -0400
Subject: [PATCH 5/7] refactor(headless): split Tooltip into per-file parts for
 tree-shaking

---
 .../headless/src/primitives/tooltip/index.ts  |   5 +-
 .../headless/src/primitives/tooltip/parts.ts  |   7 +
 .../src/primitives/tooltip/tooltip-arrow.tsx  |  22 ++
 .../src/primitives/tooltip/tooltip-context.ts |  33 ++
 .../src/primitives/tooltip/tooltip-group.tsx  |  24 ++
 .../src/primitives/tooltip/tooltip-popup.tsx  |  23 ++
 .../src/primitives/tooltip/tooltip-portal.tsx |  16 +
 .../primitives/tooltip/tooltip-positioner.tsx |  29 ++
 .../src/primitives/tooltip/tooltip-root.tsx   | 138 ++++++++
 .../primitives/tooltip/tooltip-trigger.tsx    |  31 ++
 .../src/primitives/tooltip/tooltip.test.tsx   |  16 +-
 .../src/primitives/tooltip/tooltip.tsx        | 333 ------------------
 12 files changed, 334 insertions(+), 343 deletions(-)
 create mode 100644 packages/headless/src/primitives/tooltip/parts.ts
 create mode 100644 packages/headless/src/primitives/tooltip/tooltip-arrow.tsx
 create mode 100644 packages/headless/src/primitives/tooltip/tooltip-context.ts
 create mode 100644 packages/headless/src/primitives/tooltip/tooltip-group.tsx
 create mode 100644 packages/headless/src/primitives/tooltip/tooltip-popup.tsx
 create mode 100644 packages/headless/src/primitives/tooltip/tooltip-portal.tsx
 create mode 100644 packages/headless/src/primitives/tooltip/tooltip-positioner.tsx
 create mode 100644 packages/headless/src/primitives/tooltip/tooltip-root.tsx
 create mode 100644 packages/headless/src/primitives/tooltip/tooltip-trigger.tsx
 delete mode 100644 packages/headless/src/primitives/tooltip/tooltip.tsx

diff --git a/packages/headless/src/primitives/tooltip/index.ts b/packages/headless/src/primitives/tooltip/index.ts
index 3c1ebcf36e6..3cfd72b6a84 100644
--- a/packages/headless/src/primitives/tooltip/index.ts
+++ b/packages/headless/src/primitives/tooltip/index.ts
@@ -1,3 +1,5 @@
+export * as Tooltip from './parts';
+
 export type {
   TooltipArrowProps,
   TooltipGroupProps,
@@ -6,5 +8,4 @@ export type {
   TooltipPositionerProps,
   TooltipProps,
   TooltipTriggerProps,
-} from './tooltip';
-export { Tooltip } from './tooltip';
+} from './parts';
diff --git a/packages/headless/src/primitives/tooltip/parts.ts b/packages/headless/src/primitives/tooltip/parts.ts
new file mode 100644
index 00000000000..29cab6119b3
--- /dev/null
+++ b/packages/headless/src/primitives/tooltip/parts.ts
@@ -0,0 +1,7 @@
+export { type TooltipProps, TooltipRoot as Root } from './tooltip-root';
+export { type TooltipTriggerProps, TooltipTrigger as Trigger } from './tooltip-trigger';
+export { type TooltipPortalProps, TooltipPortal as Portal } from './tooltip-portal';
+export { type TooltipPositionerProps, TooltipPositioner as Positioner } from './tooltip-positioner';
+export { type TooltipPopupProps, TooltipPopup as Popup } from './tooltip-popup';
+export { type TooltipArrowProps, TooltipArrow as Arrow } from './tooltip-arrow';
+export { type TooltipGroupProps, TooltipGroup as Group } from './tooltip-group';
diff --git a/packages/headless/src/primitives/tooltip/tooltip-arrow.tsx b/packages/headless/src/primitives/tooltip/tooltip-arrow.tsx
new file mode 100644
index 00000000000..e8db3894327
--- /dev/null
+++ b/packages/headless/src/primitives/tooltip/tooltip-arrow.tsx
@@ -0,0 +1,22 @@
+'use client';
+
+import { FloatingArrow } from '@floating-ui/react';
+import React from 'react';
+import { useTooltipContext } from './tooltip-context';
+
+export interface TooltipArrowProps extends React.ComponentPropsWithRef<typeof FloatingArrow> {}
+
+export function TooltipArrow(props: TooltipArrowProps) {
+  const { floatingContext, arrowRef, placement } = useTooltipContext();
+  const side = placement.split('-')[0];
+
+  return (
+    <FloatingArrow
+      data-cl-slot='tooltip-arrow'
+      data-cl-side={side}
+      {...props}
+      ref={arrowRef}
+      context={floatingContext}
+    />
+  );
+}
diff --git a/packages/headless/src/primitives/tooltip/tooltip-context.ts b/packages/headless/src/primitives/tooltip/tooltip-context.ts
new file mode 100644
index 00000000000..892bd03ca53
--- /dev/null
+++ b/packages/headless/src/primitives/tooltip/tooltip-context.ts
@@ -0,0 +1,33 @@
+import type {
+  ExtendedRefs,
+  FloatingContext,
+  Placement,
+  ReferenceType,
+  UseInteractionsReturn,
+} from '@floating-ui/react';
+import { type CSSProperties, createContext, useContext } from 'react';
+import type { TransitionProps } from '../../hooks/use-transition';
+
+export interface TooltipContextValue {
+  open: boolean;
+  floatingContext: FloatingContext;
+  refs: ExtendedRefs<ReferenceType>;
+  floatingStyles: CSSProperties;
+  placement: Placement;
+  getReferenceProps: UseInteractionsReturn['getReferenceProps'];
+  getFloatingProps: UseInteractionsReturn['getFloatingProps'];
+  popupRef: React.RefObject<HTMLDivElement | null>;
+  arrowRef: React.MutableRefObject<SVGSVGElement | null>;
+  mounted: boolean;
+  transitionProps: TransitionProps;
+}
+
+export const TooltipContext = createContext<TooltipContextValue | null>(null);
+
+export function useTooltipContext() {
+  const ctx = useContext(TooltipContext);
+  if (!ctx) {
+    throw new Error('Tooltip compound components must be used within <Tooltip>');
+  }
+  return ctx;
+}
diff --git a/packages/headless/src/primitives/tooltip/tooltip-group.tsx b/packages/headless/src/primitives/tooltip/tooltip-group.tsx
new file mode 100644
index 00000000000..21b8535083b
--- /dev/null
+++ b/packages/headless/src/primitives/tooltip/tooltip-group.tsx
@@ -0,0 +1,24 @@
+'use client';
+
+import { FloatingDelayGroup } from '@floating-ui/react';
+import type { ReactNode } from 'react';
+
+export interface TooltipGroupProps {
+  /** Shared delay config for grouped tooltips. Default: { open: 200, close: 100 } */
+  delay?: number | { open?: number; close?: number };
+  /** Time in ms before the group resets to non-instant phase. Default: 300 */
+  timeoutMs?: number;
+  children: ReactNode;
+}
+
+export function TooltipGroup(props: TooltipGroupProps) {
+  const { delay = { open: 200, close: 100 }, timeoutMs = 300, children } = props;
+  return (
+    <FloatingDelayGroup
+      delay={delay}
+      timeoutMs={timeoutMs}
+    >
+      {children}
+    </FloatingDelayGroup>
+  );
+}
diff --git a/packages/headless/src/primitives/tooltip/tooltip-popup.tsx b/packages/headless/src/primitives/tooltip/tooltip-popup.tsx
new file mode 100644
index 00000000000..a782101cb6f
--- /dev/null
+++ b/packages/headless/src/primitives/tooltip/tooltip-popup.tsx
@@ -0,0 +1,23 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useTooltipContext } from './tooltip-context';
+
+export interface TooltipPopupProps extends ComponentProps<'div'> {}
+
+export function TooltipPopup(props: TooltipPopupProps) {
+  const { render, ...otherProps } = props;
+  const { popupRef, transitionProps } = useTooltipContext();
+
+  const defaultProps = {
+    'data-cl-slot': 'tooltip-popup',
+    ref: popupRef,
+    ...transitionProps,
+  };
+
+  return renderElement({
+    defaultTagName: 'div',
+    render,
+    props: mergeProps<'div'>(defaultProps, otherProps),
+  });
+}
diff --git a/packages/headless/src/primitives/tooltip/tooltip-portal.tsx b/packages/headless/src/primitives/tooltip/tooltip-portal.tsx
new file mode 100644
index 00000000000..91530e798a2
--- /dev/null
+++ b/packages/headless/src/primitives/tooltip/tooltip-portal.tsx
@@ -0,0 +1,16 @@
+'use client';
+
+import { FloatingPortal } from '@floating-ui/react';
+import type { ReactNode } from 'react';
+import { useTooltipContext } from './tooltip-context';
+
+export interface TooltipPortalProps {
+  children: ReactNode;
+  root?: HTMLElement | null | React.RefObject<HTMLElement | null>;
+}
+
+export function TooltipPortal(props: TooltipPortalProps) {
+  const { mounted } = useTooltipContext();
+  if (!mounted) return null;
+  return <FloatingPortal root={props.root}>{props.children}</FloatingPortal>;
+}
diff --git a/packages/headless/src/primitives/tooltip/tooltip-positioner.tsx b/packages/headless/src/primitives/tooltip/tooltip-positioner.tsx
new file mode 100644
index 00000000000..89722922f45
--- /dev/null
+++ b/packages/headless/src/primitives/tooltip/tooltip-positioner.tsx
@@ -0,0 +1,29 @@
+'use client';
+
+import React from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useTooltipContext } from './tooltip-context';
+
+export interface TooltipPositionerProps extends ComponentProps<'div'> {}
+
+export function TooltipPositioner(props: TooltipPositionerProps) {
+  const { render, ...otherProps } = props;
+  const { mounted, refs, floatingStyles, placement, getFloatingProps } = useTooltipContext();
+
+  const side = placement.split('-')[0];
+
+  const defaultProps = {
+    'data-cl-slot': 'tooltip-positioner',
+    'data-cl-side': side,
+    ref: refs.setFloating,
+    style: floatingStyles,
+    ...(getFloatingProps() as React.ComponentPropsWithRef<'div'>),
+  };
+
+  return renderElement({
+    defaultTagName: 'div',
+    render,
+    enabled: mounted,
+    props: mergeProps<'div'>(defaultProps, otherProps),
+  });
+}
diff --git a/packages/headless/src/primitives/tooltip/tooltip-root.tsx b/packages/headless/src/primitives/tooltip/tooltip-root.tsx
new file mode 100644
index 00000000000..a39658f42ff
--- /dev/null
+++ b/packages/headless/src/primitives/tooltip/tooltip-root.tsx
@@ -0,0 +1,138 @@
+'use client';
+
+import {
+  arrow,
+  autoUpdate,
+  FloatingNode,
+  FloatingTree,
+  flip,
+  offset,
+  type Placement,
+  shift,
+  useDelayGroup,
+  useDismiss,
+  useFloating,
+  useFloatingNodeId,
+  useFloatingParentNodeId,
+  useFocus,
+  useHover,
+  useInteractions,
+  useRole,
+} from '@floating-ui/react';
+import { type ReactNode, useMemo, useRef } from 'react';
+import { useControllableState } from '../../hooks/use-controllable-state';
+import { useTransition } from '../../hooks/use-transition';
+import { cssVars } from '../../utils/css-vars';
+import { TooltipContext, type TooltipContextValue } from './tooltip-context';
+
+export interface TooltipProps {
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  placement?: Placement;
+  sideOffset?: number;
+  /** Delay in ms before the tooltip opens on hover. Default: 200 */
+  delay?: number;
+  /** Delay in ms before the tooltip closes on hover out. Default: 0 */
+  closeDelay?: number;
+  children: ReactNode;
+}
+
+function TooltipInner(props: TooltipProps) {
+  const nodeId = useFloatingNodeId();
+
+  const { placement: placementProp = 'top', sideOffset = 4, delay = 200, closeDelay = 0, children } = props;
+
+  const [open, setOpen] = useControllableState(props.open, props.defaultOpen ?? false, props.onOpenChange);
+
+  const arrowRef = useRef<SVGSVGElement | null>(null);
+  const popupRef = useRef<HTMLDivElement | null>(null);
+
+  const {
+    refs,
+    floatingStyles,
+    context: floatingContext,
+    placement,
+  } = useFloating({
+    nodeId,
+    open,
+    onOpenChange: setOpen,
+    placement: placementProp,
+    middleware: [
+      offset(sideOffset),
+      flip({
+        crossAxis: placementProp.includes('-'),
+        fallbackAxisSideDirection: 'start',
+        padding: 5,
+      }),
+      shift({ padding: 5 }),
+      arrow({ element: arrowRef }),
+      cssVars({ sideOffset }),
+    ],
+    whileElementsMounted: autoUpdate,
+  });
+
+  const { mounted, transitionProps } = useTransition({
+    open,
+    ref: popupRef,
+  });
+
+  useDelayGroup(floatingContext, { id: nodeId });
+
+  const hover = useHover(floatingContext, {
+    move: false,
+    delay: { open: delay, close: closeDelay },
+  });
+  const focus = useFocus(floatingContext);
+  const dismiss = useDismiss(floatingContext);
+  const role = useRole(floatingContext, { role: 'tooltip' });
+
+  const { getReferenceProps, getFloatingProps } = useInteractions([hover, focus, dismiss, role]);
+
+  const contextValue = useMemo<TooltipContextValue>(
+    () => ({
+      open,
+      floatingContext,
+      refs,
+      floatingStyles,
+      placement,
+      getReferenceProps,
+      getFloatingProps,
+      popupRef,
+      arrowRef,
+      mounted,
+      transitionProps,
+    }),
+    [
+      open,
+      floatingContext,
+      refs,
+      floatingStyles,
+      placement,
+      getReferenceProps,
+      getFloatingProps,
+      mounted,
+      transitionProps,
+    ],
+  );
+
+  return (
+    <FloatingNode id={nodeId}>
+      <TooltipContext.Provider value={contextValue}>{children}</TooltipContext.Provider>
+    </FloatingNode>
+  );
+}
+
+export function TooltipRoot(props: TooltipProps) {
+  const parentId = useFloatingParentNodeId();
+
+  if (parentId === null) {
+    return (
+      <FloatingTree>
+        <TooltipInner {...props} />
+      </FloatingTree>
+    );
+  }
+
+  return <TooltipInner {...props} />;
+}
diff --git a/packages/headless/src/primitives/tooltip/tooltip-trigger.tsx b/packages/headless/src/primitives/tooltip/tooltip-trigger.tsx
new file mode 100644
index 00000000000..0fee9c1137e
--- /dev/null
+++ b/packages/headless/src/primitives/tooltip/tooltip-trigger.tsx
@@ -0,0 +1,31 @@
+'use client';
+
+import React from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useTooltipContext } from './tooltip-context';
+
+export interface TooltipTriggerProps extends ComponentProps<'button'> {}
+
+export function TooltipTrigger(props: TooltipTriggerProps) {
+  const { render, ...otherProps } = props;
+  const { open, refs, getReferenceProps } = useTooltipContext();
+
+  const state = { open };
+
+  const defaultProps = {
+    type: 'button' as const,
+    'data-cl-slot': 'tooltip-trigger',
+    ref: refs.setReference,
+    ...(getReferenceProps() as React.ComponentPropsWithRef<'button'>),
+  };
+
+  return renderElement({
+    defaultTagName: 'button',
+    render,
+    state,
+    stateAttributesMapping: {
+      open: (v: boolean): Record<string, string> | null => (v ? { 'data-cl-open': '' } : { 'data-cl-closed': '' }),
+    },
+    props: mergeProps<'button'>(defaultProps, otherProps),
+  });
+}
diff --git a/packages/headless/src/primitives/tooltip/tooltip.test.tsx b/packages/headless/src/primitives/tooltip/tooltip.test.tsx
index bbc344768b5..f1f1d3618e5 100644
--- a/packages/headless/src/primitives/tooltip/tooltip.test.tsx
+++ b/packages/headless/src/primitives/tooltip/tooltip.test.tsx
@@ -2,13 +2,13 @@ import { act, cleanup, render, screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { axe } from '../../test-utils/axe';
-import { Tooltip } from './tooltip';
+import { Tooltip } from './index';
 
 afterEach(() => cleanup());
 
-function renderTooltip(props: Partial<React.ComponentProps<typeof Tooltip>> = {}) {
+function renderTooltip(props: Partial<React.ComponentProps<typeof Tooltip.Root>> = {}) {
   return render(
-    <Tooltip
+    <Tooltip.Root
       delay={0}
       {...props}
     >
@@ -16,7 +16,7 @@ function renderTooltip(props: Partial<React.ComponentProps<typeof Tooltip>> = {}
       <Tooltip.Positioner>
         <Tooltip.Popup>Tooltip content</Tooltip.Popup>
       </Tooltip.Positioner>
-    </Tooltip>,
+    </Tooltip.Root>,
   );
 }
 
@@ -246,18 +246,18 @@ describe('Tooltip', () => {
     function renderTooltipGroup() {
       return render(
         <Tooltip.Group delay={{ open: 0, close: 0 }}>
-          <Tooltip delay={0}>
+          <Tooltip.Root delay={0}>
             <Tooltip.Trigger>Button A</Tooltip.Trigger>
             <Tooltip.Positioner>
               <Tooltip.Popup>Tooltip A</Tooltip.Popup>
             </Tooltip.Positioner>
-          </Tooltip>
-          <Tooltip delay={0}>
+          </Tooltip.Root>
+          <Tooltip.Root delay={0}>
             <Tooltip.Trigger>Button B</Tooltip.Trigger>
             <Tooltip.Positioner>
               <Tooltip.Popup>Tooltip B</Tooltip.Popup>
             </Tooltip.Positioner>
-          </Tooltip>
+          </Tooltip.Root>
         </Tooltip.Group>,
       );
     }
diff --git a/packages/headless/src/primitives/tooltip/tooltip.tsx b/packages/headless/src/primitives/tooltip/tooltip.tsx
deleted file mode 100644
index c3af6ad2961..00000000000
--- a/packages/headless/src/primitives/tooltip/tooltip.tsx
+++ /dev/null
@@ -1,333 +0,0 @@
-'use client';
-
-import {
-  arrow,
-  autoUpdate,
-  type ExtendedRefs,
-  FloatingArrow,
-  type FloatingContext,
-  FloatingDelayGroup,
-  FloatingNode,
-  FloatingPortal,
-  FloatingTree,
-  flip,
-  offset,
-  type Placement,
-  type ReferenceType,
-  shift,
-  type UseInteractionsReturn,
-  useDelayGroup,
-  useDismiss,
-  useFloating,
-  useFloatingNodeId,
-  useFloatingParentNodeId,
-  useFocus,
-  useHover,
-  useInteractions,
-  useRole,
-} from '@floating-ui/react';
-import { type CSSProperties, createContext, type ReactNode, useContext, useMemo, useRef } from 'react';
-import { useControllableState } from '../../hooks/use-controllable-state';
-import { type TransitionProps, useTransition } from '../../hooks/use-transition';
-import { cssVars } from '../../utils/css-vars';
-import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
-
-// ---------------------------------------------------------------------------
-// Context
-// ---------------------------------------------------------------------------
-
-interface TooltipContextValue {
-  open: boolean;
-  floatingContext: FloatingContext;
-  refs: ExtendedRefs<ReferenceType>;
-  floatingStyles: CSSProperties;
-  placement: Placement;
-  getReferenceProps: UseInteractionsReturn['getReferenceProps'];
-  getFloatingProps: UseInteractionsReturn['getFloatingProps'];
-  popupRef: React.RefObject<HTMLDivElement | null>;
-  arrowRef: React.MutableRefObject<SVGSVGElement | null>;
-  mounted: boolean;
-  transitionProps: TransitionProps;
-}
-
-const TooltipContext = createContext<TooltipContextValue | null>(null);
-
-function useTooltipContext() {
-  const ctx = useContext(TooltipContext);
-  if (!ctx) {
-    throw new Error('Tooltip compound components must be used within <Tooltip>');
-  }
-  return ctx;
-}
-
-// ---------------------------------------------------------------------------
-// Tooltip (root)
-// ---------------------------------------------------------------------------
-
-export interface TooltipProps {
-  open?: boolean;
-  defaultOpen?: boolean;
-  onOpenChange?: (open: boolean) => void;
-  placement?: Placement;
-  sideOffset?: number;
-  /** Delay in ms before the tooltip opens on hover. Default: 200 */
-  delay?: number;
-  /** Delay in ms before the tooltip closes on hover out. Default: 0 */
-  closeDelay?: number;
-  children: ReactNode;
-}
-
-function TooltipInner(props: TooltipProps) {
-  const nodeId = useFloatingNodeId();
-
-  const { placement: placementProp = 'top', sideOffset = 4, delay = 200, closeDelay = 0, children } = props;
-
-  const [open, setOpen] = useControllableState(props.open, props.defaultOpen ?? false, props.onOpenChange);
-
-  const arrowRef = useRef<SVGSVGElement | null>(null);
-  const popupRef = useRef<HTMLDivElement | null>(null);
-
-  const {
-    refs,
-    floatingStyles,
-    context: floatingContext,
-    placement,
-  } = useFloating({
-    nodeId,
-    open,
-    onOpenChange: setOpen,
-    placement: placementProp,
-    middleware: [
-      offset(sideOffset),
-      flip({
-        crossAxis: placementProp.includes('-'),
-        fallbackAxisSideDirection: 'start',
-        padding: 5,
-      }),
-      shift({ padding: 5 }),
-      arrow({ element: arrowRef }),
-      cssVars({ sideOffset }),
-    ],
-    whileElementsMounted: autoUpdate,
-  });
-
-  const { mounted, transitionProps } = useTransition({
-    open,
-    ref: popupRef,
-  });
-
-  // Integrate with FloatingDelayGroup when inside a Tooltip.Group.
-  // Safe to call unconditionally — no-op without a parent provider.
-  useDelayGroup(floatingContext, { id: nodeId });
-
-  const hover = useHover(floatingContext, {
-    move: false,
-    delay: { open: delay, close: closeDelay },
-  });
-  const focus = useFocus(floatingContext);
-  const dismiss = useDismiss(floatingContext);
-  const role = useRole(floatingContext, { role: 'tooltip' });
-
-  const { getReferenceProps, getFloatingProps } = useInteractions([hover, focus, dismiss, role]);
-
-  const contextValue = useMemo<TooltipContextValue>(
-    () => ({
-      open,
-      floatingContext,
-      refs,
-      floatingStyles,
-      placement,
-      getReferenceProps,
-      getFloatingProps,
-      popupRef,
-      arrowRef,
-      mounted,
-      transitionProps,
-    }),
-    [
-      open,
-      floatingContext,
-      refs,
-      floatingStyles,
-      placement,
-      getReferenceProps,
-      getFloatingProps,
-      mounted,
-      transitionProps,
-    ],
-  );
-
-  return (
-    <FloatingNode id={nodeId}>
-      <TooltipContext.Provider value={contextValue}>{children}</TooltipContext.Provider>
-    </FloatingNode>
-  );
-}
-
-function TooltipRoot(props: TooltipProps) {
-  const parentId = useFloatingParentNodeId();
-
-  if (parentId === null) {
-    return (
-      <FloatingTree>
-        <TooltipInner {...props} />
-      </FloatingTree>
-    );
-  }
-
-  return <TooltipInner {...props} />;
-}
-
-// ---------------------------------------------------------------------------
-// Tooltip.Trigger
-// ---------------------------------------------------------------------------
-
-export interface TooltipTriggerProps extends ComponentProps<'button'> {}
-
-function TooltipTrigger(props: TooltipTriggerProps) {
-  const { render, ...otherProps } = props;
-  const { open, refs, getReferenceProps } = useTooltipContext();
-
-  const state = { open };
-
-  const defaultProps = {
-    type: 'button' as const,
-    'data-cl-slot': 'tooltip-trigger',
-    ref: refs.setReference,
-    ...(getReferenceProps() as React.ComponentPropsWithRef<'button'>),
-  };
-
-  return renderElement({
-    defaultTagName: 'button',
-    render,
-    state,
-    stateAttributesMapping: {
-      open: (v: boolean): Record<string, string> | null => (v ? { 'data-cl-open': '' } : { 'data-cl-closed': '' }),
-    },
-    props: mergeProps<'button'>(defaultProps, otherProps),
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Tooltip.Portal
-// ---------------------------------------------------------------------------
-
-export interface TooltipPortalProps {
-  children: ReactNode;
-  root?: HTMLElement | null | React.RefObject<HTMLElement | null>;
-}
-
-function TooltipPortal(props: TooltipPortalProps) {
-  const { mounted } = useTooltipContext();
-  if (!mounted) return null;
-  return <FloatingPortal root={props.root}>{props.children}</FloatingPortal>;
-}
-
-// ---------------------------------------------------------------------------
-// Tooltip.Positioner
-// ---------------------------------------------------------------------------
-
-export interface TooltipPositionerProps extends ComponentProps<'div'> {}
-
-function TooltipPositioner(props: TooltipPositionerProps) {
-  const { render, ...otherProps } = props;
-  const { mounted, refs, floatingStyles, placement, getFloatingProps } = useTooltipContext();
-
-  const side = placement.split('-')[0];
-
-  const defaultProps = {
-    'data-cl-slot': 'tooltip-positioner',
-    'data-cl-side': side,
-    ref: refs.setFloating,
-    style: floatingStyles,
-    ...(getFloatingProps() as React.ComponentPropsWithRef<'div'>),
-  };
-
-  return renderElement({
-    defaultTagName: 'div',
-    render,
-    enabled: mounted,
-    props: mergeProps<'div'>(defaultProps, otherProps),
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Tooltip.Popup
-// ---------------------------------------------------------------------------
-
-export interface TooltipPopupProps extends ComponentProps<'div'> {}
-
-function TooltipPopup(props: TooltipPopupProps) {
-  const { render, ...otherProps } = props;
-  const { popupRef, transitionProps } = useTooltipContext();
-
-  const defaultProps = {
-    'data-cl-slot': 'tooltip-popup',
-    ref: popupRef,
-    ...transitionProps,
-  };
-
-  return renderElement({
-    defaultTagName: 'div',
-    render,
-    props: mergeProps<'div'>(defaultProps, otherProps),
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Tooltip.Arrow
-// ---------------------------------------------------------------------------
-
-export interface TooltipArrowProps extends React.ComponentPropsWithRef<typeof FloatingArrow> {}
-
-function TooltipArrowComponent(props: TooltipArrowProps) {
-  const { floatingContext, arrowRef, placement } = useTooltipContext();
-  const side = placement.split('-')[0];
-
-  return (
-    <FloatingArrow
-      data-cl-slot='tooltip-arrow'
-      data-cl-side={side}
-      {...props}
-      ref={arrowRef}
-      context={floatingContext}
-    />
-  );
-}
-
-// ---------------------------------------------------------------------------
-// Tooltip.Group
-// ---------------------------------------------------------------------------
-
-export interface TooltipGroupProps {
-  /** Shared delay config for grouped tooltips. Default: { open: 200, close: 100 } */
-  delay?: number | { open?: number; close?: number };
-  /** Time in ms before the group resets to non-instant phase. Default: 300 */
-  timeoutMs?: number;
-  children: ReactNode;
-}
-
-function TooltipGroupRoot(props: TooltipGroupProps) {
-  const { delay = { open: 200, close: 100 }, timeoutMs = 300, children } = props;
-  return (
-    <FloatingDelayGroup
-      delay={delay}
-      timeoutMs={timeoutMs}
-    >
-      {children}
-    </FloatingDelayGroup>
-  );
-}
-
-// ---------------------------------------------------------------------------
-// Compound export
-// ---------------------------------------------------------------------------
-
-export const Tooltip = Object.assign(TooltipRoot, {
-  Trigger: TooltipTrigger,
-  Portal: TooltipPortal,
-  Positioner: TooltipPositioner,
-  Popup: TooltipPopup,
-  Arrow: TooltipArrowComponent,
-  Group: TooltipGroupRoot,
-});

From 048bc915a6de7497855a2cc1f6b10eca5020388c Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Wed, 3 Jun 2026 13:14:22 -0400
Subject: [PATCH 6/7] docs(headless): update Tooltip README for .Root usage

---
 .../headless/src/primitives/tooltip/README.md    | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/packages/headless/src/primitives/tooltip/README.md b/packages/headless/src/primitives/tooltip/README.md
index 41cca266d07..d2c20d6956b 100644
--- a/packages/headless/src/primitives/tooltip/README.md
+++ b/packages/headless/src/primitives/tooltip/README.md
@@ -13,7 +13,7 @@ A floating label that appears on hover or focus. Non-interactive, used for suppl
 ```tsx
 import { Tooltip } from '@/primitives/tooltip';
 
-<Tooltip>
+<Tooltip.Root>
   <Tooltip.Trigger>
     <IconButton aria-label='Settings' />
   </Tooltip.Trigger>
@@ -23,7 +23,7 @@ import { Tooltip } from '@/primitives/tooltip';
       <Tooltip.Arrow />
     </Tooltip.Popup>
   </Tooltip.Positioner>
-</Tooltip>;
+</Tooltip.Root>;
 ```
 
 ### Controlled
@@ -31,30 +31,30 @@ import { Tooltip } from '@/primitives/tooltip';
 ```tsx
 const [open, setOpen] = useState(false);
 
-<Tooltip
+<Tooltip.Root
   open={open}
   onOpenChange={setOpen}
 >
   {/* ... */}
-</Tooltip>;
+</Tooltip.Root>;
 ```
 
 ### Custom Delay
 
 ```tsx
-<Tooltip
+<Tooltip.Root
   delay={500}
   closeDelay={100}
 >
   {/* Opens after 500ms hover, closes 100ms after leaving */}
-</Tooltip>
+</Tooltip.Root>
 ```
 
 ## Parts
 
 | Part                 | Default Element | Description                                      |
 | -------------------- | --------------- | ------------------------------------------------ |
-| `Tooltip`            | —               | Root context provider                            |
+| `Tooltip.Root`       | —               | Root context provider                            |
 | `Tooltip.Trigger`    | `<button>`      | Element that triggers the tooltip on hover/focus |
 | `Tooltip.Portal`     | —               | Portals children (accepts `root` prop)           |
 | `Tooltip.Positioner` | `<div>`         | Floating positioned container                    |
@@ -63,7 +63,7 @@ const [open, setOpen] = useState(false);
 
 ## Props
 
-### `Tooltip` (root)
+### `Tooltip.Root`
 
 | Prop           | Type                      | Default | Description                          |
 | -------------- | ------------------------- | ------- | ------------------------------------ |

From da71e4974d4f7b9ca8646949a05a6185248b328a Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Wed, 3 Jun 2026 13:18:13 -0400
Subject: [PATCH 7/7] fix(headless): update Tooltip context error message for
 .Root usage

---
 packages/headless/src/primitives/tooltip/tooltip-context.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/headless/src/primitives/tooltip/tooltip-context.ts b/packages/headless/src/primitives/tooltip/tooltip-context.ts
index 892bd03ca53..82e4b2e3640 100644
--- a/packages/headless/src/primitives/tooltip/tooltip-context.ts
+++ b/packages/headless/src/primitives/tooltip/tooltip-context.ts
@@ -27,7 +27,7 @@ export const TooltipContext = createContext<TooltipContextValue | null>(null);
 export function useTooltipContext() {
   const ctx = useContext(TooltipContext);
   if (!ctx) {
-    throw new Error('Tooltip compound components must be used within <Tooltip>');
+    throw new Error('Tooltip compound components must be used within <Tooltip.Root>');
   }
   return ctx;
 }