feat(headless): add Popover primitive

packages/headless/package.json

@@ -17,6 +17,10 @@
  "import": "./dist/primitives/tooltip/index.js",
  "types": "./dist/primitives/tooltip/index.d.ts"
  },
+ "./popover": {
+ "import": "./dist/primitives/popover/index.js",
+ "types": "./dist/primitives/popover/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

packages/headless/src/primitives/popover/README.md

@@ -0,0 +1,111 @@
+# Popover
+
+A floating panel anchored to a trigger element. Supports focus management, ARIA labeling, and enter/exit animations.
+
+## When to Use
+
+- Rich content panels, filter dropdowns, or any non-modal floating content anchored to a trigger.
+- When content includes interactive elements (inputs, buttons) — unlike Tooltip which is display-only.
+- Prefer Popover over Dialog when the content should be anchored to a specific element and the page should remain interactive by default.
+
+## Usage
+
+```tsx
+import { Popover } from '@/primitives/popover';
+
+<Popover.Root>
+ <Popover.Trigger>Settings</Popover.Trigger>
+ <Popover.Positioner>
+ <Popover.Popup>
+ <Popover.Title>Preferences</Popover.Title>
+ <Popover.Description>Adjust your settings below.</Popover.Description>
+ {/* Interactive content here */}
+ <Popover.Close>Done</Popover.Close>
+ </Popover.Popup>
+ </Popover.Positioner>
+</Popover.Root>;
+```
+
+### Controlled
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Popover.Root
+ open={open}
+ onOpenChange={setOpen}
+>
+ {/* ... */}
+</Popover.Root>;
+```
+
+### Modal Mode
+
+```tsx
+<Popover.Root modal>{/* Focus is trapped within the popover */}</Popover.Root>
+```
+
+## Parts
+
+| Part | Default Element | Description |
+| --------------------- | --------------- | ---------------------------------------- |
+| `Popover.Root` | — | Root context provider |
+| `Popover.Trigger` | `<button>` | Toggles the popover on click |
+| `Popover.Portal` | — | Portals children (accepts `root` prop) |
+| `Popover.Positioner` | `<div>` | Floating positioned container |
+| `Popover.Popup` | `<div>` | Visual content wrapper |
+| `Popover.Arrow` | `<svg>` | Optional floating arrow |
+| `Popover.Title` | `<h2>` | Heading, wired to `aria-labelledby` |
+| `Popover.Description` | `<p>` | Description, wired to `aria-describedby` |
+| `Popover.Close` | `<button>` | Closes the popover on click |
+
+## Props
+
+### `Popover.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` | `"bottom"` | Floating UI placement |
+| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
+| `modal` | `boolean` | `false` | Traps focus within the popover |
+
+### `Popover.Trigger`, `Popover.Positioner`, `Popover.Popup`, `Popover.Title`, `Popover.Description`, `Popover.Close`
+
+No additional props beyond standard HTML attributes and the `render` prop.
+
+### `Popover.Arrow`
+
+Accepts all `FloatingArrow` props. `ref` and `context` are injected automatically.
+
+## Keyboard
+
+| Key | Action |
+| -------- | -------------------------------------------------------------------- |
+| `Escape` | Closes the popover |
+| `Tab` | Cycles focus within popover (modal mode) or moves freely (non-modal) |
+
+## Data Attributes
+
+| Attribute | Applies To | Description |
+| --------------------------------- | ----------------- | ---------------------------------------- |
+| `data-cl-slot` | All parts | Part identifier (e.g. `"popover-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. The popup auto-repositions on scroll and resize via `autoUpdate`. Cross-axis flipping is enabled only when using an aligned placement (e.g. `"bottom-start"`).
+
+## Important Notes
+
+- **Title and Description are optional but recommended.** They wire `aria-labelledby` and `aria-describedby` to the positioner. If omitted, those attributes are simply absent.
+- **Non-modal by default.** Unlike Dialog, the page remains interactive behind the popover. Set `modal={true}` for a stricter focus trap.
+- **Nested popovers are supported.** The `FloatingTree` pattern handles nesting automatically.
+
+## ARIA
+
+- Positioner: `role="dialog"`, `aria-labelledby` (from Title), `aria-describedby` (from Description)
+- Trigger: `aria-expanded`, `aria-haspopup="dialog"`, `aria-controls`

packages/headless/src/primitives/popover/index.ts

@@ -0,0 +1,13 @@
+export * as Popover from './parts';
+
+export type {
+ PopoverArrowProps,
+ PopoverCloseProps,
+ PopoverDescriptionProps,
+ PopoverPopupProps,
+ PopoverPortalProps,
+ PopoverPositionerProps,
+ PopoverProps,
+ PopoverTitleProps,
+ PopoverTriggerProps,
+} from './parts';

packages/headless/src/primitives/popover/parts.ts

@@ -0,0 +1,9 @@
+export { type PopoverProps, PopoverRoot as Root } from './popover-root';
+export { type PopoverTriggerProps, PopoverTrigger as Trigger } from './popover-trigger';
+export { type PopoverPortalProps, PopoverPortal as Portal } from './popover-portal';
+export { type PopoverPositionerProps, PopoverPositioner as Positioner } from './popover-positioner';
+export { type PopoverPopupProps, PopoverPopup as Popup } from './popover-popup';
+export { type PopoverArrowProps, PopoverArrow as Arrow } from './popover-arrow';
+export { type PopoverTitleProps, PopoverTitle as Title } from './popover-title';
+export { type PopoverDescriptionProps, PopoverDescription as Description } from './popover-description';
+export { type PopoverCloseProps, PopoverClose as Close } from './popover-close';

packages/headless/src/primitives/popover/popover-arrow.tsx

@@ -0,0 +1,22 @@
+'use client';
+
+import { FloatingArrow } from '@floating-ui/react';
+import React from 'react';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverArrowProps extends React.ComponentPropsWithRef<typeof FloatingArrow> {}
+
+export function PopoverArrow(props: PopoverArrowProps) {
+ const { floatingContext, arrowRef, placement } = usePopoverContext();
+ const side = placement.split('-')[0];
+
+ return (
+ <FloatingArrow
+ data-cl-slot='popover-arrow'
+ data-cl-side={side}
+ {...props}
+ ref={arrowRef}
+ context={floatingContext}
+ />
+ );
+}

packages/headless/src/primitives/popover/popover-close.tsx

@@ -0,0 +1,25 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverCloseProps extends ComponentProps<'button'> {}
+
+export function PopoverClose(props: PopoverCloseProps) {
+ const { render, ...otherProps } = props;
+ const { setOpen } = usePopoverContext();
+
+ const defaultProps = {
+ type: 'button' as const,
+ 'data-cl-slot': 'popover-close',
+ onClick() {
+ setOpen(false);
+ },
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ render,
+ props: mergeProps<'button'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/popover/popover-context.ts

@@ -0,0 +1,39 @@
+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 PopoverContextValue {
+ open: boolean;
+ setOpen: (open: boolean) => void;
+ 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>;
+ modal: boolean;
+ labelId: string | undefined;
+ descriptionId: string | undefined;
+ setLabelId: React.Dispatch<React.SetStateAction<string | undefined>>;
+ setDescriptionId: React.Dispatch<React.SetStateAction<string | undefined>>;
+ mounted: boolean;
+ transitionProps: TransitionProps;
+}
+
+export const PopoverContext = createContext<PopoverContextValue | null>(null);
+
+export function usePopoverContext() {
+ const ctx = useContext(PopoverContext);
+ if (!ctx) {
+ throw new Error('Popover compound components must be used within <Popover.Root>');
+ }
+ return ctx;
+}

packages/headless/src/primitives/popover/popover-description.tsx

@@ -0,0 +1,29 @@
+'use client';
+
+import { useId, useLayoutEffect } from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverDescriptionProps extends ComponentProps<'p'> {}
+
+export function PopoverDescription(props: PopoverDescriptionProps) {
+ const { render, ...otherProps } = props;
+ const { setDescriptionId } = usePopoverContext();
+ const id = useId();
+
+ useLayoutEffect(() => {
+ setDescriptionId(id);
+ return () => setDescriptionId(undefined);
+ }, [id, setDescriptionId]);
+
+ const defaultProps = {
+ 'data-cl-slot': 'popover-description',
+ id,
+ };
+
+ return renderElement({
+ defaultTagName: 'p',
+ render,
+ props: mergeProps<'p'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/popover/popover-popup.tsx

@@ -0,0 +1,23 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverPopupProps extends ComponentProps<'div'> {}
+
+export function PopoverPopup(props: PopoverPopupProps) {
+ const { render, ...otherProps } = props;
+ const { popupRef, transitionProps } = usePopoverContext();
+
+ const defaultProps = {
+ 'data-cl-slot': 'popover-popup',
+ ref: popupRef,
+ ...transitionProps,
+ };
+
+ return renderElement({
+ defaultTagName: 'div',
+ render,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/popover/popover-portal.tsx

@@ -0,0 +1,16 @@
+'use client';
+
+import { FloatingPortal } from '@floating-ui/react';
+import type { ReactNode } from 'react';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverPortalProps {
+ children: ReactNode;
+ root?: HTMLElement | null | React.RefObject<HTMLElement | null>;
+}
+
+export function PopoverPortal(props: PopoverPortalProps) {
+ const { mounted } = usePopoverContext();
+ if (!mounted) return null;
+ return <FloatingPortal root={props.root}>{props.children}</FloatingPortal>;
+}

packages/headless/src/primitives/popover/popover-positioner.tsx

@@ -0,0 +1,42 @@
+'use client';
+
+import { FloatingFocusManager } from '@floating-ui/react';
+import React from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverPositionerProps extends ComponentProps<'div'> {}
+
+export function PopoverPositioner(props: PopoverPositionerProps) {
+ const { render, ...otherProps } = props;
+ const { mounted, floatingContext, refs, floatingStyles, placement, getFloatingProps, modal, labelId, descriptionId } =
+ usePopoverContext();
+
+ const side = placement.split('-')[0];
+
+ const defaultProps = {
+ 'data-cl-slot': 'popover-positioner',
+ 'data-cl-side': side,
+ ref: refs.setFloating,
+ style: floatingStyles,
+ 'aria-labelledby': labelId,
+ 'aria-describedby': descriptionId,
+ ...(getFloatingProps() as React.ComponentPropsWithRef<'div'>),
+ };
+
+ const element = renderElement({
+ defaultTagName: 'div',
+ render,
+ enabled: mounted,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+
+ return (
+ <FloatingFocusManager
+ context={floatingContext}
+ modal={modal}
+ >
+ {element!}
+ </FloatingFocusManager>
+ );
+}

packages/headless/package.json

@@ -17,6 +17,10 @@
  "import": "./dist/primitives/tooltip/index.js",
  "types": "./dist/primitives/tooltip/index.d.ts"
  },
+ "./popover": {
+ "import": "./dist/primitives/popover/index.js",
+ "types": "./dist/primitives/popover/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

packages/headless/src/primitives/popover/README.md

@@ -0,0 +1,111 @@
+# Popover
+
+A floating panel anchored to a trigger element. Supports focus management, ARIA labeling, and enter/exit animations.
+
+## When to Use
+
+- Rich content panels, filter dropdowns, or any non-modal floating content anchored to a trigger.
+- When content includes interactive elements (inputs, buttons) — unlike Tooltip which is display-only.
+- Prefer Popover over Dialog when the content should be anchored to a specific element and the page should remain interactive by default.
+
+## Usage
+
+```tsx
+import { Popover } from '@/primitives/popover';
+
+<Popover.Root>
+ <Popover.Trigger>Settings</Popover.Trigger>
+ <Popover.Positioner>
+ <Popover.Popup>
+ <Popover.Title>Preferences</Popover.Title>
+ <Popover.Description>Adjust your settings below.</Popover.Description>
+ {/* Interactive content here */}
+ <Popover.Close>Done</Popover.Close>
+ </Popover.Popup>
+ </Popover.Positioner>
+</Popover.Root>;
+```
+
+### Controlled
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Popover.Root
+ open={open}
+ onOpenChange={setOpen}
+>
+ {/* ... */}
+</Popover.Root>;
+```
+
+### Modal Mode
+
+```tsx
+<Popover.Root modal>{/* Focus is trapped within the popover */}</Popover.Root>
+```
+
+## Parts
+
+| Part | Default Element | Description |
+| --------------------- | --------------- | ---------------------------------------- |
+| `Popover.Root` | — | Root context provider |
+| `Popover.Trigger` | `<button>` | Toggles the popover on click |
+| `Popover.Portal` | — | Portals children (accepts `root` prop) |
+| `Popover.Positioner` | `<div>` | Floating positioned container |
+| `Popover.Popup` | `<div>` | Visual content wrapper |
+| `Popover.Arrow` | `<svg>` | Optional floating arrow |
+| `Popover.Title` | `<h2>` | Heading, wired to `aria-labelledby` |
+| `Popover.Description` | `<p>` | Description, wired to `aria-describedby` |
+| `Popover.Close` | `<button>` | Closes the popover on click |
+
+## Props
+
+### `Popover.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` | `"bottom"` | Floating UI placement |
+| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
+| `modal` | `boolean` | `false` | Traps focus within the popover |
+
+### `Popover.Trigger`, `Popover.Positioner`, `Popover.Popup`, `Popover.Title`, `Popover.Description`, `Popover.Close`
+
+No additional props beyond standard HTML attributes and the `render` prop.
+
+### `Popover.Arrow`
+
+Accepts all `FloatingArrow` props. `ref` and `context` are injected automatically.
+
+## Keyboard
+
+| Key | Action |
+| -------- | -------------------------------------------------------------------- |
+| `Escape` | Closes the popover |
+| `Tab` | Cycles focus within popover (modal mode) or moves freely (non-modal) |
+
+## Data Attributes
+
+| Attribute | Applies To | Description |
+| --------------------------------- | ----------------- | ---------------------------------------- |
+| `data-cl-slot` | All parts | Part identifier (e.g. `"popover-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. The popup auto-repositions on scroll and resize via `autoUpdate`. Cross-axis flipping is enabled only when using an aligned placement (e.g. `"bottom-start"`).
+
+## Important Notes
+
+- **Title and Description are optional but recommended.** They wire `aria-labelledby` and `aria-describedby` to the positioner. If omitted, those attributes are simply absent.
+- **Non-modal by default.** Unlike Dialog, the page remains interactive behind the popover. Set `modal={true}` for a stricter focus trap.
+- **Nested popovers are supported.** The `FloatingTree` pattern handles nesting automatically.
+
+## ARIA
+
+- Positioner: `role="dialog"`, `aria-labelledby` (from Title), `aria-describedby` (from Description)
+- Trigger: `aria-expanded`, `aria-haspopup="dialog"`, `aria-controls`

packages/headless/src/primitives/popover/index.ts

@@ -0,0 +1,13 @@
+export * as Popover from './parts';
+
+export type {
+ PopoverArrowProps,
+ PopoverCloseProps,
+ PopoverDescriptionProps,
+ PopoverPopupProps,
+ PopoverPortalProps,
+ PopoverPositionerProps,
+ PopoverProps,
+ PopoverTitleProps,
+ PopoverTriggerProps,
+} from './parts';

packages/headless/src/primitives/popover/parts.ts

@@ -0,0 +1,9 @@
+export { type PopoverProps, PopoverRoot as Root } from './popover-root';
+export { type PopoverTriggerProps, PopoverTrigger as Trigger } from './popover-trigger';
+export { type PopoverPortalProps, PopoverPortal as Portal } from './popover-portal';
+export { type PopoverPositionerProps, PopoverPositioner as Positioner } from './popover-positioner';
+export { type PopoverPopupProps, PopoverPopup as Popup } from './popover-popup';
+export { type PopoverArrowProps, PopoverArrow as Arrow } from './popover-arrow';
+export { type PopoverTitleProps, PopoverTitle as Title } from './popover-title';
+export { type PopoverDescriptionProps, PopoverDescription as Description } from './popover-description';
+export { type PopoverCloseProps, PopoverClose as Close } from './popover-close';

packages/headless/src/primitives/popover/popover-arrow.tsx

@@ -0,0 +1,22 @@
+'use client';
+
+import { FloatingArrow } from '@floating-ui/react';
+import React from 'react';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverArrowProps extends React.ComponentPropsWithRef<typeof FloatingArrow> {}
+
+export function PopoverArrow(props: PopoverArrowProps) {
+ const { floatingContext, arrowRef, placement } = usePopoverContext();
+ const side = placement.split('-')[0];
+
+ return (
+ <FloatingArrow
+ data-cl-slot='popover-arrow'
+ data-cl-side={side}
+ {...props}
+ ref={arrowRef}
+ context={floatingContext}
+ />
+ );
+}

packages/headless/src/primitives/popover/popover-close.tsx

@@ -0,0 +1,25 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverCloseProps extends ComponentProps<'button'> {}
+
+export function PopoverClose(props: PopoverCloseProps) {
+ const { render, ...otherProps } = props;
+ const { setOpen } = usePopoverContext();
+
+ const defaultProps = {
+ type: 'button' as const,
+ 'data-cl-slot': 'popover-close',
+ onClick() {
+ setOpen(false);
+ },
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ render,
+ props: mergeProps<'button'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/popover/popover-context.ts

@@ -0,0 +1,39 @@
+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 PopoverContextValue {
+ open: boolean;
+ setOpen: (open: boolean) => void;
+ 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>;
+ modal: boolean;
+ labelId: string | undefined;
+ descriptionId: string | undefined;
+ setLabelId: React.Dispatch<React.SetStateAction<string | undefined>>;
+ setDescriptionId: React.Dispatch<React.SetStateAction<string | undefined>>;
+ mounted: boolean;
+ transitionProps: TransitionProps;
+}
+
+export const PopoverContext = createContext<PopoverContextValue | null>(null);
+
+export function usePopoverContext() {
+ const ctx = useContext(PopoverContext);
+ if (!ctx) {
+ throw new Error('Popover compound components must be used within <Popover.Root>');
+ }
+ return ctx;
+}

packages/headless/src/primitives/popover/popover-description.tsx

@@ -0,0 +1,29 @@
+'use client';
+
+import { useId, useLayoutEffect } from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverDescriptionProps extends ComponentProps<'p'> {}
+
+export function PopoverDescription(props: PopoverDescriptionProps) {
+ const { render, ...otherProps } = props;
+ const { setDescriptionId } = usePopoverContext();
+ const id = useId();
+
+ useLayoutEffect(() => {
+ setDescriptionId(id);
+ return () => setDescriptionId(undefined);
+ }, [id, setDescriptionId]);
+
+ const defaultProps = {
+ 'data-cl-slot': 'popover-description',
+ id,
+ };
+
+ return renderElement({
+ defaultTagName: 'p',
+ render,
+ props: mergeProps<'p'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/popover/popover-popup.tsx

@@ -0,0 +1,23 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverPopupProps extends ComponentProps<'div'> {}
+
+export function PopoverPopup(props: PopoverPopupProps) {
+ const { render, ...otherProps } = props;
+ const { popupRef, transitionProps } = usePopoverContext();
+
+ const defaultProps = {
+ 'data-cl-slot': 'popover-popup',
+ ref: popupRef,
+ ...transitionProps,
+ };
+
+ return renderElement({
+ defaultTagName: 'div',
+ render,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/popover/popover-portal.tsx

@@ -0,0 +1,16 @@
+'use client';
+
+import { FloatingPortal } from '@floating-ui/react';
+import type { ReactNode } from 'react';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverPortalProps {
+ children: ReactNode;
+ root?: HTMLElement | null | React.RefObject<HTMLElement | null>;
+}
+
+export function PopoverPortal(props: PopoverPortalProps) {
+ const { mounted } = usePopoverContext();
+ if (!mounted) return null;
+ return <FloatingPortal root={props.root}>{props.children}</FloatingPortal>;
+}

packages/headless/src/primitives/popover/popover-positioner.tsx

@@ -0,0 +1,42 @@
+'use client';
+
+import { FloatingFocusManager } from '@floating-ui/react';
+import React from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverPositionerProps extends ComponentProps<'div'> {}
+
+export function PopoverPositioner(props: PopoverPositionerProps) {
+ const { render, ...otherProps } = props;
+ const { mounted, floatingContext, refs, floatingStyles, placement, getFloatingProps, modal, labelId, descriptionId } =
+ usePopoverContext();
+
+ const side = placement.split('-')[0];
+
+ const defaultProps = {
+ 'data-cl-slot': 'popover-positioner',
+ 'data-cl-side': side,
+ ref: refs.setFloating,
+ style: floatingStyles,
+ 'aria-labelledby': labelId,
+ 'aria-describedby': descriptionId,
+ ...(getFloatingProps() as React.ComponentPropsWithRef<'div'>),
+ };
+
+ const element = renderElement({
+ defaultTagName: 'div',
+ render,
+ enabled: mounted,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+
+ return (
+ <FloatingFocusManager
+ context={floatingContext}
+ modal={modal}
+ >
+ {element!}
+ </FloatingFocusManager>
+ );
+}

packages/headless/package.json

@@ -17,6 +17,10 @@
  "import": "./dist/primitives/tooltip/index.js",
  "types": "./dist/primitives/tooltip/index.d.ts"
  },
+ "./popover": {
+ "import": "./dist/primitives/popover/index.js",
+ "types": "./dist/primitives/popover/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

packages/headless/src/primitives/popover/README.md

@@ -0,0 +1,111 @@
+# Popover
+
+A floating panel anchored to a trigger element. Supports focus management, ARIA labeling, and enter/exit animations.
+
+## When to Use
+
+- Rich content panels, filter dropdowns, or any non-modal floating content anchored to a trigger.
+- When content includes interactive elements (inputs, buttons) — unlike Tooltip which is display-only.
+- Prefer Popover over Dialog when the content should be anchored to a specific element and the page should remain interactive by default.
+
+## Usage
+
+```tsx
+import { Popover } from '@/primitives/popover';
+
+<Popover.Root>
+ <Popover.Trigger>Settings</Popover.Trigger>
+ <Popover.Positioner>
+ <Popover.Popup>
+ <Popover.Title>Preferences</Popover.Title>
+ <Popover.Description>Adjust your settings below.</Popover.Description>
+ {/* Interactive content here */}
+ <Popover.Close>Done</Popover.Close>
+ </Popover.Popup>
+ </Popover.Positioner>
+</Popover.Root>;
+```
+
+### Controlled
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Popover.Root
+ open={open}
+ onOpenChange={setOpen}
+>
+ {/* ... */}
+</Popover.Root>;
+```
+
+### Modal Mode
+
+```tsx
+<Popover.Root modal>{/* Focus is trapped within the popover */}</Popover.Root>
+```
+
+## Parts
+
+| Part | Default Element | Description |
+| --------------------- | --------------- | ---------------------------------------- |
+| `Popover.Root` | — | Root context provider |
+| `Popover.Trigger` | `<button>` | Toggles the popover on click |
+| `Popover.Portal` | — | Portals children (accepts `root` prop) |
+| `Popover.Positioner` | `<div>` | Floating positioned container |
+| `Popover.Popup` | `<div>` | Visual content wrapper |
+| `Popover.Arrow` | `<svg>` | Optional floating arrow |
+| `Popover.Title` | `<h2>` | Heading, wired to `aria-labelledby` |
+| `Popover.Description` | `<p>` | Description, wired to `aria-describedby` |
+| `Popover.Close` | `<button>` | Closes the popover on click |
+
+## Props
+
+### `Popover.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` | `"bottom"` | Floating UI placement |
+| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
+| `modal` | `boolean` | `false` | Traps focus within the popover |
+
+### `Popover.Trigger`, `Popover.Positioner`, `Popover.Popup`, `Popover.Title`, `Popover.Description`, `Popover.Close`
+
+No additional props beyond standard HTML attributes and the `render` prop.
+
+### `Popover.Arrow`
+
+Accepts all `FloatingArrow` props. `ref` and `context` are injected automatically.
+
+## Keyboard
+
+| Key | Action |
+| -------- | -------------------------------------------------------------------- |
+| `Escape` | Closes the popover |
+| `Tab` | Cycles focus within popover (modal mode) or moves freely (non-modal) |
+
+## Data Attributes
+
+| Attribute | Applies To | Description |
+| --------------------------------- | ----------------- | ---------------------------------------- |
+| `data-cl-slot` | All parts | Part identifier (e.g. `"popover-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. The popup auto-repositions on scroll and resize via `autoUpdate`. Cross-axis flipping is enabled only when using an aligned placement (e.g. `"bottom-start"`).
+
+## Important Notes
+
+- **Title and Description are optional but recommended.** They wire `aria-labelledby` and `aria-describedby` to the positioner. If omitted, those attributes are simply absent.
+- **Non-modal by default.** Unlike Dialog, the page remains interactive behind the popover. Set `modal={true}` for a stricter focus trap.
+- **Nested popovers are supported.** The `FloatingTree` pattern handles nesting automatically.
+
+## ARIA
+
+- Positioner: `role="dialog"`, `aria-labelledby` (from Title), `aria-describedby` (from Description)
+- Trigger: `aria-expanded`, `aria-haspopup="dialog"`, `aria-controls`

packages/headless/src/primitives/popover/index.ts

@@ -0,0 +1,13 @@
+export * as Popover from './parts';
+
+export type {
+ PopoverArrowProps,
+ PopoverCloseProps,
+ PopoverDescriptionProps,
+ PopoverPopupProps,
+ PopoverPortalProps,
+ PopoverPositionerProps,
+ PopoverProps,
+ PopoverTitleProps,
+ PopoverTriggerProps,
+} from './parts';

packages/headless/src/primitives/popover/parts.ts

@@ -0,0 +1,9 @@
+export { type PopoverProps, PopoverRoot as Root } from './popover-root';
+export { type PopoverTriggerProps, PopoverTrigger as Trigger } from './popover-trigger';
+export { type PopoverPortalProps, PopoverPortal as Portal } from './popover-portal';
+export { type PopoverPositionerProps, PopoverPositioner as Positioner } from './popover-positioner';
+export { type PopoverPopupProps, PopoverPopup as Popup } from './popover-popup';
+export { type PopoverArrowProps, PopoverArrow as Arrow } from './popover-arrow';
+export { type PopoverTitleProps, PopoverTitle as Title } from './popover-title';
+export { type PopoverDescriptionProps, PopoverDescription as Description } from './popover-description';
+export { type PopoverCloseProps, PopoverClose as Close } from './popover-close';

packages/headless/src/primitives/popover/popover-arrow.tsx

@@ -0,0 +1,22 @@
+'use client';
+
+import { FloatingArrow } from '@floating-ui/react';
+import React from 'react';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverArrowProps extends React.ComponentPropsWithRef<typeof FloatingArrow> {}
+
+export function PopoverArrow(props: PopoverArrowProps) {
+ const { floatingContext, arrowRef, placement } = usePopoverContext();
+ const side = placement.split('-')[0];
+
+ return (
+ <FloatingArrow
+ data-cl-slot='popover-arrow'
+ data-cl-side={side}
+ {...props}
+ ref={arrowRef}
+ context={floatingContext}
+ />
+ );
+}

packages/headless/src/primitives/popover/popover-close.tsx

@@ -0,0 +1,25 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverCloseProps extends ComponentProps<'button'> {}
+
+export function PopoverClose(props: PopoverCloseProps) {
+ const { render, ...otherProps } = props;
+ const { setOpen } = usePopoverContext();
+
+ const defaultProps = {
+ type: 'button' as const,
+ 'data-cl-slot': 'popover-close',
+ onClick() {
+ setOpen(false);
+ },
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ render,
+ props: mergeProps<'button'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/popover/popover-context.ts

@@ -0,0 +1,39 @@
+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 PopoverContextValue {
+ open: boolean;
+ setOpen: (open: boolean) => void;
+ 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>;
+ modal: boolean;
+ labelId: string | undefined;
+ descriptionId: string | undefined;
+ setLabelId: React.Dispatch<React.SetStateAction<string | undefined>>;
+ setDescriptionId: React.Dispatch<React.SetStateAction<string | undefined>>;
+ mounted: boolean;
+ transitionProps: TransitionProps;
+}
+
+export const PopoverContext = createContext<PopoverContextValue | null>(null);
+
+export function usePopoverContext() {
+ const ctx = useContext(PopoverContext);
+ if (!ctx) {
+ throw new Error('Popover compound components must be used within <Popover.Root>');
+ }
+ return ctx;
+}

packages/headless/src/primitives/popover/popover-description.tsx

@@ -0,0 +1,29 @@
+'use client';
+
+import { useId, useLayoutEffect } from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverDescriptionProps extends ComponentProps<'p'> {}
+
+export function PopoverDescription(props: PopoverDescriptionProps) {
+ const { render, ...otherProps } = props;
+ const { setDescriptionId } = usePopoverContext();
+ const id = useId();
+
+ useLayoutEffect(() => {
+ setDescriptionId(id);
+ return () => setDescriptionId(undefined);
+ }, [id, setDescriptionId]);
+
+ const defaultProps = {
+ 'data-cl-slot': 'popover-description',
+ id,
+ };
+
+ return renderElement({
+ defaultTagName: 'p',
+ render,
+ props: mergeProps<'p'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/popover/popover-popup.tsx

@@ -0,0 +1,23 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverPopupProps extends ComponentProps<'div'> {}
+
+export function PopoverPopup(props: PopoverPopupProps) {
+ const { render, ...otherProps } = props;
+ const { popupRef, transitionProps } = usePopoverContext();
+
+ const defaultProps = {
+ 'data-cl-slot': 'popover-popup',
+ ref: popupRef,
+ ...transitionProps,
+ };
+
+ return renderElement({
+ defaultTagName: 'div',
+ render,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/popover/popover-portal.tsx

@@ -0,0 +1,16 @@
+'use client';
+
+import { FloatingPortal } from '@floating-ui/react';
+import type { ReactNode } from 'react';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverPortalProps {
+ children: ReactNode;
+ root?: HTMLElement | null | React.RefObject<HTMLElement | null>;
+}
+
+export function PopoverPortal(props: PopoverPortalProps) {
+ const { mounted } = usePopoverContext();
+ if (!mounted) return null;
+ return <FloatingPortal root={props.root}>{props.children}</FloatingPortal>;
+}

packages/headless/src/primitives/popover/popover-positioner.tsx

@@ -0,0 +1,42 @@
+'use client';
+
+import { FloatingFocusManager } from '@floating-ui/react';
+import React from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverPositionerProps extends ComponentProps<'div'> {}
+
+export function PopoverPositioner(props: PopoverPositionerProps) {
+ const { render, ...otherProps } = props;
+ const { mounted, floatingContext, refs, floatingStyles, placement, getFloatingProps, modal, labelId, descriptionId } =
+ usePopoverContext();
+
+ const side = placement.split('-')[0];
+
+ const defaultProps = {
+ 'data-cl-slot': 'popover-positioner',
+ 'data-cl-side': side,
+ ref: refs.setFloating,
+ style: floatingStyles,
+ 'aria-labelledby': labelId,
+ 'aria-describedby': descriptionId,
+ ...(getFloatingProps() as React.ComponentPropsWithRef<'div'>),
+ };
+
+ const element = renderElement({
+ defaultTagName: 'div',
+ render,
+ enabled: mounted,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+
+ return (
+ <FloatingFocusManager
+ context={floatingContext}
+ modal={modal}
+ >
+ {element!}
+ </FloatingFocusManager>
+ );
+}

packages/headless/package.json

@@ -17,6 +17,10 @@
  "import": "./dist/primitives/tooltip/index.js",
  "types": "./dist/primitives/tooltip/index.d.ts"
  },
+ "./popover": {
+ "import": "./dist/primitives/popover/index.js",
+ "types": "./dist/primitives/popover/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

packages/headless/src/primitives/popover/README.md

@@ -0,0 +1,111 @@
+# Popover
+
+A floating panel anchored to a trigger element. Supports focus management, ARIA labeling, and enter/exit animations.
+
+## When to Use
+
+- Rich content panels, filter dropdowns, or any non-modal floating content anchored to a trigger.
+- When content includes interactive elements (inputs, buttons) — unlike Tooltip which is display-only.
+- Prefer Popover over Dialog when the content should be anchored to a specific element and the page should remain interactive by default.
+
+## Usage
+
+```tsx
+import { Popover } from '@/primitives/popover';
+
+<Popover.Root>
+ <Popover.Trigger>Settings</Popover.Trigger>
+ <Popover.Positioner>
+ <Popover.Popup>
+ <Popover.Title>Preferences</Popover.Title>
+ <Popover.Description>Adjust your settings below.</Popover.Description>
+ {/* Interactive content here */}
+ <Popover.Close>Done</Popover.Close>
+ </Popover.Popup>
+ </Popover.Positioner>
+</Popover.Root>;
+```
+
+### Controlled
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Popover.Root
+ open={open}
+ onOpenChange={setOpen}
+>
+ {/* ... */}
+</Popover.Root>;
+```
+
+### Modal Mode
+
+```tsx
+<Popover.Root modal>{/* Focus is trapped within the popover */}</Popover.Root>
+```
+
+## Parts
+
+| Part | Default Element | Description |
+| --------------------- | --------------- | ---------------------------------------- |
+| `Popover.Root` | — | Root context provider |
+| `Popover.Trigger` | `<button>` | Toggles the popover on click |
+| `Popover.Portal` | — | Portals children (accepts `root` prop) |
+| `Popover.Positioner` | `<div>` | Floating positioned container |
+| `Popover.Popup` | `<div>` | Visual content wrapper |
+| `Popover.Arrow` | `<svg>` | Optional floating arrow |
+| `Popover.Title` | `<h2>` | Heading, wired to `aria-labelledby` |
+| `Popover.Description` | `<p>` | Description, wired to `aria-describedby` |
+| `Popover.Close` | `<button>` | Closes the popover on click |
+
+## Props
+
+### `Popover.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` | `"bottom"` | Floating UI placement |
+| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
+| `modal` | `boolean` | `false` | Traps focus within the popover |
+
+### `Popover.Trigger`, `Popover.Positioner`, `Popover.Popup`, `Popover.Title`, `Popover.Description`, `Popover.Close`
+
+No additional props beyond standard HTML attributes and the `render` prop.
+
+### `Popover.Arrow`
+
+Accepts all `FloatingArrow` props. `ref` and `context` are injected automatically.
+
+## Keyboard
+
+| Key | Action |
+| -------- | -------------------------------------------------------------------- |
+| `Escape` | Closes the popover |
+| `Tab` | Cycles focus within popover (modal mode) or moves freely (non-modal) |
+
+## Data Attributes
+
+| Attribute | Applies To | Description |
+| --------------------------------- | ----------------- | ---------------------------------------- |
+| `data-cl-slot` | All parts | Part identifier (e.g. `"popover-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. The popup auto-repositions on scroll and resize via `autoUpdate`. Cross-axis flipping is enabled only when using an aligned placement (e.g. `"bottom-start"`).
+
+## Important Notes
+
+- **Title and Description are optional but recommended.** They wire `aria-labelledby` and `aria-describedby` to the positioner. If omitted, those attributes are simply absent.
+- **Non-modal by default.** Unlike Dialog, the page remains interactive behind the popover. Set `modal={true}` for a stricter focus trap.
+- **Nested popovers are supported.** The `FloatingTree` pattern handles nesting automatically.
+
+## ARIA
+
+- Positioner: `role="dialog"`, `aria-labelledby` (from Title), `aria-describedby` (from Description)
+- Trigger: `aria-expanded`, `aria-haspopup="dialog"`, `aria-controls`

packages/headless/src/primitives/popover/index.ts

@@ -0,0 +1,13 @@
+export * as Popover from './parts';
+
+export type {
+ PopoverArrowProps,
+ PopoverCloseProps,
+ PopoverDescriptionProps,
+ PopoverPopupProps,
+ PopoverPortalProps,
+ PopoverPositionerProps,
+ PopoverProps,
+ PopoverTitleProps,
+ PopoverTriggerProps,
+} from './parts';

packages/headless/src/primitives/popover/parts.ts

@@ -0,0 +1,9 @@
+export { type PopoverProps, PopoverRoot as Root } from './popover-root';
+export { type PopoverTriggerProps, PopoverTrigger as Trigger } from './popover-trigger';
+export { type PopoverPortalProps, PopoverPortal as Portal } from './popover-portal';
+export { type PopoverPositionerProps, PopoverPositioner as Positioner } from './popover-positioner';
+export { type PopoverPopupProps, PopoverPopup as Popup } from './popover-popup';
+export { type PopoverArrowProps, PopoverArrow as Arrow } from './popover-arrow';
+export { type PopoverTitleProps, PopoverTitle as Title } from './popover-title';
+export { type PopoverDescriptionProps, PopoverDescription as Description } from './popover-description';
+export { type PopoverCloseProps, PopoverClose as Close } from './popover-close';

packages/headless/src/primitives/popover/popover-arrow.tsx

@@ -0,0 +1,22 @@
+'use client';
+
+import { FloatingArrow } from '@floating-ui/react';
+import React from 'react';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverArrowProps extends React.ComponentPropsWithRef<typeof FloatingArrow> {}
+
+export function PopoverArrow(props: PopoverArrowProps) {
+ const { floatingContext, arrowRef, placement } = usePopoverContext();
+ const side = placement.split('-')[0];
+
+ return (
+ <FloatingArrow
+ data-cl-slot='popover-arrow'
+ data-cl-side={side}
+ {...props}
+ ref={arrowRef}
+ context={floatingContext}
+ />
+ );
+}

packages/headless/src/primitives/popover/popover-close.tsx

@@ -0,0 +1,25 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverCloseProps extends ComponentProps<'button'> {}
+
+export function PopoverClose(props: PopoverCloseProps) {
+ const { render, ...otherProps } = props;
+ const { setOpen } = usePopoverContext();
+
+ const defaultProps = {
+ type: 'button' as const,
+ 'data-cl-slot': 'popover-close',
+ onClick() {
+ setOpen(false);
+ },
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ render,
+ props: mergeProps<'button'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/popover/popover-context.ts

@@ -0,0 +1,39 @@
+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 PopoverContextValue {
+ open: boolean;
+ setOpen: (open: boolean) => void;
+ 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>;
+ modal: boolean;
+ labelId: string | undefined;
+ descriptionId: string | undefined;
+ setLabelId: React.Dispatch<React.SetStateAction<string | undefined>>;
+ setDescriptionId: React.Dispatch<React.SetStateAction<string | undefined>>;
+ mounted: boolean;
+ transitionProps: TransitionProps;
+}
+
+export const PopoverContext = createContext<PopoverContextValue | null>(null);
+
+export function usePopoverContext() {
+ const ctx = useContext(PopoverContext);
+ if (!ctx) {
+ throw new Error('Popover compound components must be used within <Popover.Root>');
+ }
+ return ctx;
+}

packages/headless/src/primitives/popover/popover-description.tsx

@@ -0,0 +1,29 @@
+'use client';
+
+import { useId, useLayoutEffect } from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverDescriptionProps extends ComponentProps<'p'> {}
+
+export function PopoverDescription(props: PopoverDescriptionProps) {
+ const { render, ...otherProps } = props;
+ const { setDescriptionId } = usePopoverContext();
+ const id = useId();
+
+ useLayoutEffect(() => {
+ setDescriptionId(id);
+ return () => setDescriptionId(undefined);
+ }, [id, setDescriptionId]);
+
+ const defaultProps = {
+ 'data-cl-slot': 'popover-description',
+ id,
+ };
+
+ return renderElement({
+ defaultTagName: 'p',
+ render,
+ props: mergeProps<'p'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/popover/popover-popup.tsx

@@ -0,0 +1,23 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverPopupProps extends ComponentProps<'div'> {}
+
+export function PopoverPopup(props: PopoverPopupProps) {
+ const { render, ...otherProps } = props;
+ const { popupRef, transitionProps } = usePopoverContext();
+
+ const defaultProps = {
+ 'data-cl-slot': 'popover-popup',
+ ref: popupRef,
+ ...transitionProps,
+ };
+
+ return renderElement({
+ defaultTagName: 'div',
+ render,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/popover/popover-portal.tsx

@@ -0,0 +1,16 @@
+'use client';
+
+import { FloatingPortal } from '@floating-ui/react';
+import type { ReactNode } from 'react';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverPortalProps {
+ children: ReactNode;
+ root?: HTMLElement | null | React.RefObject<HTMLElement | null>;
+}
+
+export function PopoverPortal(props: PopoverPortalProps) {
+ const { mounted } = usePopoverContext();
+ if (!mounted) return null;
+ return <FloatingPortal root={props.root}>{props.children}</FloatingPortal>;
+}

packages/headless/src/primitives/popover/popover-positioner.tsx

@@ -0,0 +1,42 @@
+'use client';
+
+import { FloatingFocusManager } from '@floating-ui/react';
+import React from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverPositionerProps extends ComponentProps<'div'> {}
+
+export function PopoverPositioner(props: PopoverPositionerProps) {
+ const { render, ...otherProps } = props;
+ const { mounted, floatingContext, refs, floatingStyles, placement, getFloatingProps, modal, labelId, descriptionId } =
+ usePopoverContext();
+
+ const side = placement.split('-')[0];
+
+ const defaultProps = {
+ 'data-cl-slot': 'popover-positioner',
+ 'data-cl-side': side,
+ ref: refs.setFloating,
+ style: floatingStyles,
+ 'aria-labelledby': labelId,
+ 'aria-describedby': descriptionId,
+ ...(getFloatingProps() as React.ComponentPropsWithRef<'div'>),
+ };
+
+ const element = renderElement({
+ defaultTagName: 'div',
+ render,
+ enabled: mounted,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+
+ return (
+ <FloatingFocusManager
+ context={floatingContext}
+ modal={modal}
+ >
+ {element!}
+ </FloatingFocusManager>
+ );
+}

packages/headless/package.json

@@ -17,6 +17,10 @@
  "import": "./dist/primitives/tooltip/index.js",
  "types": "./dist/primitives/tooltip/index.d.ts"
  },
+ "./popover": {
+ "import": "./dist/primitives/popover/index.js",
+ "types": "./dist/primitives/popover/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

packages/headless/src/primitives/popover/README.md

@@ -0,0 +1,111 @@
+# Popover
+
+A floating panel anchored to a trigger element. Supports focus management, ARIA labeling, and enter/exit animations.
+
+## When to Use
+
+- Rich content panels, filter dropdowns, or any non-modal floating content anchored to a trigger.
+- When content includes interactive elements (inputs, buttons) — unlike Tooltip which is display-only.
+- Prefer Popover over Dialog when the content should be anchored to a specific element and the page should remain interactive by default.
+
+## Usage
+
+```tsx
+import { Popover } from '@/primitives/popover';
+
+<Popover.Root>
+ <Popover.Trigger>Settings</Popover.Trigger>
+ <Popover.Positioner>
+ <Popover.Popup>
+ <Popover.Title>Preferences</Popover.Title>
+ <Popover.Description>Adjust your settings below.</Popover.Description>
+ {/* Interactive content here */}
+ <Popover.Close>Done</Popover.Close>
+ </Popover.Popup>
+ </Popover.Positioner>
+</Popover.Root>;
+```
+
+### Controlled
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Popover.Root
+ open={open}
+ onOpenChange={setOpen}
+>
+ {/* ... */}
+</Popover.Root>;
+```
+
+### Modal Mode
+
+```tsx
+<Popover.Root modal>{/* Focus is trapped within the popover */}</Popover.Root>
+```
+
+## Parts
+
+| Part | Default Element | Description |
+| --------------------- | --------------- | ---------------------------------------- |
+| `Popover.Root` | — | Root context provider |
+| `Popover.Trigger` | `<button>` | Toggles the popover on click |
+| `Popover.Portal` | — | Portals children (accepts `root` prop) |
+| `Popover.Positioner` | `<div>` | Floating positioned container |
+| `Popover.Popup` | `<div>` | Visual content wrapper |
+| `Popover.Arrow` | `<svg>` | Optional floating arrow |
+| `Popover.Title` | `<h2>` | Heading, wired to `aria-labelledby` |
+| `Popover.Description` | `<p>` | Description, wired to `aria-describedby` |
+| `Popover.Close` | `<button>` | Closes the popover on click |
+
+## Props
+
+### `Popover.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` | `"bottom"` | Floating UI placement |
+| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
+| `modal` | `boolean` | `false` | Traps focus within the popover |
+
+### `Popover.Trigger`, `Popover.Positioner`, `Popover.Popup`, `Popover.Title`, `Popover.Description`, `Popover.Close`
+
+No additional props beyond standard HTML attributes and the `render` prop.
+
+### `Popover.Arrow`
+
+Accepts all `FloatingArrow` props. `ref` and `context` are injected automatically.
+
+## Keyboard
+
+| Key | Action |
+| -------- | -------------------------------------------------------------------- |
+| `Escape` | Closes the popover |
+| `Tab` | Cycles focus within popover (modal mode) or moves freely (non-modal) |
+
+## Data Attributes
+
+| Attribute | Applies To | Description |
+| --------------------------------- | ----------------- | ---------------------------------------- |
+| `data-cl-slot` | All parts | Part identifier (e.g. `"popover-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. The popup auto-repositions on scroll and resize via `autoUpdate`. Cross-axis flipping is enabled only when using an aligned placement (e.g. `"bottom-start"`).
+
+## Important Notes
+
+- **Title and Description are optional but recommended.** They wire `aria-labelledby` and `aria-describedby` to the positioner. If omitted, those attributes are simply absent.
+- **Non-modal by default.** Unlike Dialog, the page remains interactive behind the popover. Set `modal={true}` for a stricter focus trap.
+- **Nested popovers are supported.** The `FloatingTree` pattern handles nesting automatically.
+
+## ARIA
+
+- Positioner: `role="dialog"`, `aria-labelledby` (from Title), `aria-describedby` (from Description)
+- Trigger: `aria-expanded`, `aria-haspopup="dialog"`, `aria-controls`

packages/headless/src/primitives/popover/index.ts

@@ -0,0 +1,13 @@
+export * as Popover from './parts';
+
+export type {
+ PopoverArrowProps,
+ PopoverCloseProps,
+ PopoverDescriptionProps,
+ PopoverPopupProps,
+ PopoverPortalProps,
+ PopoverPositionerProps,
+ PopoverProps,
+ PopoverTitleProps,
+ PopoverTriggerProps,
+} from './parts';

packages/headless/src/primitives/popover/parts.ts

@@ -0,0 +1,9 @@
+export { type PopoverProps, PopoverRoot as Root } from './popover-root';
+export { type PopoverTriggerProps, PopoverTrigger as Trigger } from './popover-trigger';
+export { type PopoverPortalProps, PopoverPortal as Portal } from './popover-portal';
+export { type PopoverPositionerProps, PopoverPositioner as Positioner } from './popover-positioner';
+export { type PopoverPopupProps, PopoverPopup as Popup } from './popover-popup';
+export { type PopoverArrowProps, PopoverArrow as Arrow } from './popover-arrow';
+export { type PopoverTitleProps, PopoverTitle as Title } from './popover-title';
+export { type PopoverDescriptionProps, PopoverDescription as Description } from './popover-description';
+export { type PopoverCloseProps, PopoverClose as Close } from './popover-close';

packages/headless/src/primitives/popover/popover-arrow.tsx

@@ -0,0 +1,22 @@
+'use client';
+
+import { FloatingArrow } from '@floating-ui/react';
+import React from 'react';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverArrowProps extends React.ComponentPropsWithRef<typeof FloatingArrow> {}
+
+export function PopoverArrow(props: PopoverArrowProps) {
+ const { floatingContext, arrowRef, placement } = usePopoverContext();
+ const side = placement.split('-')[0];
+
+ return (
+ <FloatingArrow
+ data-cl-slot='popover-arrow'
+ data-cl-side={side}
+ {...props}
+ ref={arrowRef}
+ context={floatingContext}
+ />
+ );
+}

packages/headless/src/primitives/popover/popover-close.tsx

@@ -0,0 +1,25 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverCloseProps extends ComponentProps<'button'> {}
+
+export function PopoverClose(props: PopoverCloseProps) {
+ const { render, ...otherProps } = props;
+ const { setOpen } = usePopoverContext();
+
+ const defaultProps = {
+ type: 'button' as const,
+ 'data-cl-slot': 'popover-close',
+ onClick() {
+ setOpen(false);
+ },
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ render,
+ props: mergeProps<'button'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/popover/popover-context.ts

@@ -0,0 +1,39 @@
+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 PopoverContextValue {
+ open: boolean;
+ setOpen: (open: boolean) => void;
+ 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>;
+ modal: boolean;
+ labelId: string | undefined;
+ descriptionId: string | undefined;
+ setLabelId: React.Dispatch<React.SetStateAction<string | undefined>>;
+ setDescriptionId: React.Dispatch<React.SetStateAction<string | undefined>>;
+ mounted: boolean;
+ transitionProps: TransitionProps;
+}
+
+export const PopoverContext = createContext<PopoverContextValue | null>(null);
+
+export function usePopoverContext() {
+ const ctx = useContext(PopoverContext);
+ if (!ctx) {
+ throw new Error('Popover compound components must be used within <Popover.Root>');
+ }
+ return ctx;
+}

packages/headless/src/primitives/popover/popover-description.tsx

@@ -0,0 +1,29 @@
+'use client';
+
+import { useId, useLayoutEffect } from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverDescriptionProps extends ComponentProps<'p'> {}
+
+export function PopoverDescription(props: PopoverDescriptionProps) {
+ const { render, ...otherProps } = props;
+ const { setDescriptionId } = usePopoverContext();
+ const id = useId();
+
+ useLayoutEffect(() => {
+ setDescriptionId(id);
+ return () => setDescriptionId(undefined);
+ }, [id, setDescriptionId]);
+
+ const defaultProps = {
+ 'data-cl-slot': 'popover-description',
+ id,
+ };
+
+ return renderElement({
+ defaultTagName: 'p',
+ render,
+ props: mergeProps<'p'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/popover/popover-popup.tsx

@@ -0,0 +1,23 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverPopupProps extends ComponentProps<'div'> {}
+
+export function PopoverPopup(props: PopoverPopupProps) {
+ const { render, ...otherProps } = props;
+ const { popupRef, transitionProps } = usePopoverContext();
+
+ const defaultProps = {
+ 'data-cl-slot': 'popover-popup',
+ ref: popupRef,
+ ...transitionProps,
+ };
+
+ return renderElement({
+ defaultTagName: 'div',
+ render,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/popover/popover-portal.tsx

@@ -0,0 +1,16 @@
+'use client';
+
+import { FloatingPortal } from '@floating-ui/react';
+import type { ReactNode } from 'react';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverPortalProps {
+ children: ReactNode;
+ root?: HTMLElement | null | React.RefObject<HTMLElement | null>;
+}
+
+export function PopoverPortal(props: PopoverPortalProps) {
+ const { mounted } = usePopoverContext();
+ if (!mounted) return null;
+ return <FloatingPortal root={props.root}>{props.children}</FloatingPortal>;
+}

packages/headless/src/primitives/popover/popover-positioner.tsx

@@ -0,0 +1,42 @@
+'use client';
+
+import { FloatingFocusManager } from '@floating-ui/react';
+import React from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverPositionerProps extends ComponentProps<'div'> {}
+
+export function PopoverPositioner(props: PopoverPositionerProps) {
+ const { render, ...otherProps } = props;
+ const { mounted, floatingContext, refs, floatingStyles, placement, getFloatingProps, modal, labelId, descriptionId } =
+ usePopoverContext();
+
+ const side = placement.split('-')[0];
+
+ const defaultProps = {
+ 'data-cl-slot': 'popover-positioner',
+ 'data-cl-side': side,
+ ref: refs.setFloating,
+ style: floatingStyles,
+ 'aria-labelledby': labelId,
+ 'aria-describedby': descriptionId,
+ ...(getFloatingProps() as React.ComponentPropsWithRef<'div'>),
+ };
+
+ const element = renderElement({
+ defaultTagName: 'div',
+ render,
+ enabled: mounted,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+
+ return (
+ <FloatingFocusManager
+ context={floatingContext}
+ modal={modal}
+ >
+ {element!}
+ </FloatingFocusManager>
+ );
+}

packages/headless/package.json

@@ -17,6 +17,10 @@
  "import": "./dist/primitives/tooltip/index.js",
  "types": "./dist/primitives/tooltip/index.d.ts"
  },
+ "./popover": {
+ "import": "./dist/primitives/popover/index.js",
+ "types": "./dist/primitives/popover/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

packages/headless/src/primitives/popover/README.md

@@ -0,0 +1,111 @@
+# Popover
+
+A floating panel anchored to a trigger element. Supports focus management, ARIA labeling, and enter/exit animations.
+
+## When to Use
+
+- Rich content panels, filter dropdowns, or any non-modal floating content anchored to a trigger.
+- When content includes interactive elements (inputs, buttons) — unlike Tooltip which is display-only.
+- Prefer Popover over Dialog when the content should be anchored to a specific element and the page should remain interactive by default.
+
+## Usage
+
+```tsx
+import { Popover } from '@/primitives/popover';
+
+<Popover.Root>
+ <Popover.Trigger>Settings</Popover.Trigger>
+ <Popover.Positioner>
+ <Popover.Popup>
+ <Popover.Title>Preferences</Popover.Title>
+ <Popover.Description>Adjust your settings below.</Popover.Description>
+ {/* Interactive content here */}
+ <Popover.Close>Done</Popover.Close>
+ </Popover.Popup>
+ </Popover.Positioner>
+</Popover.Root>;
+```
+
+### Controlled
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Popover.Root
+ open={open}
+ onOpenChange={setOpen}
+>
+ {/* ... */}
+</Popover.Root>;
+```
+
+### Modal Mode
+
+```tsx
+<Popover.Root modal>{/* Focus is trapped within the popover */}</Popover.Root>
+```
+
+## Parts
+
+| Part | Default Element | Description |
+| --------------------- | --------------- | ---------------------------------------- |
+| `Popover.Root` | — | Root context provider |
+| `Popover.Trigger` | `<button>` | Toggles the popover on click |
+| `Popover.Portal` | — | Portals children (accepts `root` prop) |
+| `Popover.Positioner` | `<div>` | Floating positioned container |
+| `Popover.Popup` | `<div>` | Visual content wrapper |
+| `Popover.Arrow` | `<svg>` | Optional floating arrow |
+| `Popover.Title` | `<h2>` | Heading, wired to `aria-labelledby` |
+| `Popover.Description` | `<p>` | Description, wired to `aria-describedby` |
+| `Popover.Close` | `<button>` | Closes the popover on click |
+
+## Props
+
+### `Popover.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` | `"bottom"` | Floating UI placement |
+| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
+| `modal` | `boolean` | `false` | Traps focus within the popover |
+
+### `Popover.Trigger`, `Popover.Positioner`, `Popover.Popup`, `Popover.Title`, `Popover.Description`, `Popover.Close`
+
+No additional props beyond standard HTML attributes and the `render` prop.
+
+### `Popover.Arrow`
+
+Accepts all `FloatingArrow` props. `ref` and `context` are injected automatically.
+
+## Keyboard
+
+| Key | Action |
+| -------- | -------------------------------------------------------------------- |
+| `Escape` | Closes the popover |
+| `Tab` | Cycles focus within popover (modal mode) or moves freely (non-modal) |
+
+## Data Attributes
+
+| Attribute | Applies To | Description |
+| --------------------------------- | ----------------- | ---------------------------------------- |
+| `data-cl-slot` | All parts | Part identifier (e.g. `"popover-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. The popup auto-repositions on scroll and resize via `autoUpdate`. Cross-axis flipping is enabled only when using an aligned placement (e.g. `"bottom-start"`).
+
+## Important Notes
+
+- **Title and Description are optional but recommended.** They wire `aria-labelledby` and `aria-describedby` to the positioner. If omitted, those attributes are simply absent.
+- **Non-modal by default.** Unlike Dialog, the page remains interactive behind the popover. Set `modal={true}` for a stricter focus trap.
+- **Nested popovers are supported.** The `FloatingTree` pattern handles nesting automatically.
+
+## ARIA
+
+- Positioner: `role="dialog"`, `aria-labelledby` (from Title), `aria-describedby` (from Description)
+- Trigger: `aria-expanded`, `aria-haspopup="dialog"`, `aria-controls`

packages/headless/src/primitives/popover/index.ts

@@ -0,0 +1,13 @@
+export * as Popover from './parts';
+
+export type {
+ PopoverArrowProps,
+ PopoverCloseProps,
+ PopoverDescriptionProps,
+ PopoverPopupProps,
+ PopoverPortalProps,
+ PopoverPositionerProps,
+ PopoverProps,
+ PopoverTitleProps,
+ PopoverTriggerProps,
+} from './parts';

packages/headless/src/primitives/popover/parts.ts

@@ -0,0 +1,9 @@
+export { type PopoverProps, PopoverRoot as Root } from './popover-root';
+export { type PopoverTriggerProps, PopoverTrigger as Trigger } from './popover-trigger';
+export { type PopoverPortalProps, PopoverPortal as Portal } from './popover-portal';
+export { type PopoverPositionerProps, PopoverPositioner as Positioner } from './popover-positioner';
+export { type PopoverPopupProps, PopoverPopup as Popup } from './popover-popup';
+export { type PopoverArrowProps, PopoverArrow as Arrow } from './popover-arrow';
+export { type PopoverTitleProps, PopoverTitle as Title } from './popover-title';
+export { type PopoverDescriptionProps, PopoverDescription as Description } from './popover-description';
+export { type PopoverCloseProps, PopoverClose as Close } from './popover-close';

packages/headless/src/primitives/popover/popover-arrow.tsx

@@ -0,0 +1,22 @@
+'use client';
+
+import { FloatingArrow } from '@floating-ui/react';
+import React from 'react';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverArrowProps extends React.ComponentPropsWithRef<typeof FloatingArrow> {}
+
+export function PopoverArrow(props: PopoverArrowProps) {
+ const { floatingContext, arrowRef, placement } = usePopoverContext();
+ const side = placement.split('-')[0];
+
+ return (
+ <FloatingArrow
+ data-cl-slot='popover-arrow'
+ data-cl-side={side}
+ {...props}
+ ref={arrowRef}
+ context={floatingContext}
+ />
+ );
+}

packages/headless/src/primitives/popover/popover-close.tsx

@@ -0,0 +1,25 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverCloseProps extends ComponentProps<'button'> {}
+
+export function PopoverClose(props: PopoverCloseProps) {
+ const { render, ...otherProps } = props;
+ const { setOpen } = usePopoverContext();
+
+ const defaultProps = {
+ type: 'button' as const,
+ 'data-cl-slot': 'popover-close',
+ onClick() {
+ setOpen(false);
+ },
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ render,
+ props: mergeProps<'button'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/popover/popover-context.ts

@@ -0,0 +1,39 @@
+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 PopoverContextValue {
+ open: boolean;
+ setOpen: (open: boolean) => void;
+ 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>;
+ modal: boolean;
+ labelId: string | undefined;
+ descriptionId: string | undefined;
+ setLabelId: React.Dispatch<React.SetStateAction<string | undefined>>;
+ setDescriptionId: React.Dispatch<React.SetStateAction<string | undefined>>;
+ mounted: boolean;
+ transitionProps: TransitionProps;
+}
+
+export const PopoverContext = createContext<PopoverContextValue | null>(null);
+
+export function usePopoverContext() {
+ const ctx = useContext(PopoverContext);
+ if (!ctx) {
+ throw new Error('Popover compound components must be used within <Popover.Root>');
+ }
+ return ctx;
+}

packages/headless/src/primitives/popover/popover-description.tsx

@@ -0,0 +1,29 @@
+'use client';
+
+import { useId, useLayoutEffect } from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverDescriptionProps extends ComponentProps<'p'> {}
+
+export function PopoverDescription(props: PopoverDescriptionProps) {
+ const { render, ...otherProps } = props;
+ const { setDescriptionId } = usePopoverContext();
+ const id = useId();
+
+ useLayoutEffect(() => {
+ setDescriptionId(id);
+ return () => setDescriptionId(undefined);
+ }, [id, setDescriptionId]);
+
+ const defaultProps = {
+ 'data-cl-slot': 'popover-description',
+ id,
+ };
+
+ return renderElement({
+ defaultTagName: 'p',
+ render,
+ props: mergeProps<'p'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/popover/popover-popup.tsx

@@ -0,0 +1,23 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverPopupProps extends ComponentProps<'div'> {}
+
+export function PopoverPopup(props: PopoverPopupProps) {
+ const { render, ...otherProps } = props;
+ const { popupRef, transitionProps } = usePopoverContext();
+
+ const defaultProps = {
+ 'data-cl-slot': 'popover-popup',
+ ref: popupRef,
+ ...transitionProps,
+ };
+
+ return renderElement({
+ defaultTagName: 'div',
+ render,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/popover/popover-portal.tsx

@@ -0,0 +1,16 @@
+'use client';
+
+import { FloatingPortal } from '@floating-ui/react';
+import type { ReactNode } from 'react';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverPortalProps {
+ children: ReactNode;
+ root?: HTMLElement | null | React.RefObject<HTMLElement | null>;
+}
+
+export function PopoverPortal(props: PopoverPortalProps) {
+ const { mounted } = usePopoverContext();
+ if (!mounted) return null;
+ return <FloatingPortal root={props.root}>{props.children}</FloatingPortal>;
+}

packages/headless/src/primitives/popover/popover-positioner.tsx

@@ -0,0 +1,42 @@
+'use client';
+
+import { FloatingFocusManager } from '@floating-ui/react';
+import React from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverPositionerProps extends ComponentProps<'div'> {}
+
+export function PopoverPositioner(props: PopoverPositionerProps) {
+ const { render, ...otherProps } = props;
+ const { mounted, floatingContext, refs, floatingStyles, placement, getFloatingProps, modal, labelId, descriptionId } =
+ usePopoverContext();
+
+ const side = placement.split('-')[0];
+
+ const defaultProps = {
+ 'data-cl-slot': 'popover-positioner',
+ 'data-cl-side': side,
+ ref: refs.setFloating,
+ style: floatingStyles,
+ 'aria-labelledby': labelId,
+ 'aria-describedby': descriptionId,
+ ...(getFloatingProps() as React.ComponentPropsWithRef<'div'>),
+ };
+
+ const element = renderElement({
+ defaultTagName: 'div',
+ render,
+ enabled: mounted,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+
+ return (
+ <FloatingFocusManager
+ context={floatingContext}
+ modal={modal}
+ >
+ {element!}
+ </FloatingFocusManager>
+ );
+}

packages/headless/package.json

@@ -17,6 +17,10 @@
  "import": "./dist/primitives/tooltip/index.js",
  "types": "./dist/primitives/tooltip/index.d.ts"
  },
+ "./popover": {
+ "import": "./dist/primitives/popover/index.js",
+ "types": "./dist/primitives/popover/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

packages/headless/src/primitives/popover/README.md

@@ -0,0 +1,111 @@
+# Popover
+
+A floating panel anchored to a trigger element. Supports focus management, ARIA labeling, and enter/exit animations.
+
+## When to Use
+
+- Rich content panels, filter dropdowns, or any non-modal floating content anchored to a trigger.
+- When content includes interactive elements (inputs, buttons) — unlike Tooltip which is display-only.
+- Prefer Popover over Dialog when the content should be anchored to a specific element and the page should remain interactive by default.
+
+## Usage
+
+```tsx
+import { Popover } from '@/primitives/popover';
+
+<Popover.Root>
+ <Popover.Trigger>Settings</Popover.Trigger>
+ <Popover.Positioner>
+ <Popover.Popup>
+ <Popover.Title>Preferences</Popover.Title>
+ <Popover.Description>Adjust your settings below.</Popover.Description>
+ {/* Interactive content here */}
+ <Popover.Close>Done</Popover.Close>
+ </Popover.Popup>
+ </Popover.Positioner>
+</Popover.Root>;
+```
+
+### Controlled
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Popover.Root
+ open={open}
+ onOpenChange={setOpen}
+>
+ {/* ... */}
+</Popover.Root>;
+```
+
+### Modal Mode
+
+```tsx
+<Popover.Root modal>{/* Focus is trapped within the popover */}</Popover.Root>
+```
+
+## Parts
+
+| Part | Default Element | Description |
+| --------------------- | --------------- | ---------------------------------------- |
+| `Popover.Root` | — | Root context provider |
+| `Popover.Trigger` | `<button>` | Toggles the popover on click |
+| `Popover.Portal` | — | Portals children (accepts `root` prop) |
+| `Popover.Positioner` | `<div>` | Floating positioned container |
+| `Popover.Popup` | `<div>` | Visual content wrapper |
+| `Popover.Arrow` | `<svg>` | Optional floating arrow |
+| `Popover.Title` | `<h2>` | Heading, wired to `aria-labelledby` |
+| `Popover.Description` | `<p>` | Description, wired to `aria-describedby` |
+| `Popover.Close` | `<button>` | Closes the popover on click |
+
+## Props
+
+### `Popover.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` | `"bottom"` | Floating UI placement |
+| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
+| `modal` | `boolean` | `false` | Traps focus within the popover |
+
+### `Popover.Trigger`, `Popover.Positioner`, `Popover.Popup`, `Popover.Title`, `Popover.Description`, `Popover.Close`
+
+No additional props beyond standard HTML attributes and the `render` prop.
+
+### `Popover.Arrow`
+
+Accepts all `FloatingArrow` props. `ref` and `context` are injected automatically.
+
+## Keyboard
+
+| Key | Action |
+| -------- | -------------------------------------------------------------------- |
+| `Escape` | Closes the popover |
+| `Tab` | Cycles focus within popover (modal mode) or moves freely (non-modal) |
+
+## Data Attributes
+
+| Attribute | Applies To | Description |
+| --------------------------------- | ----------------- | ---------------------------------------- |
+| `data-cl-slot` | All parts | Part identifier (e.g. `"popover-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. The popup auto-repositions on scroll and resize via `autoUpdate`. Cross-axis flipping is enabled only when using an aligned placement (e.g. `"bottom-start"`).
+
+## Important Notes
+
+- **Title and Description are optional but recommended.** They wire `aria-labelledby` and `aria-describedby` to the positioner. If omitted, those attributes are simply absent.
+- **Non-modal by default.** Unlike Dialog, the page remains interactive behind the popover. Set `modal={true}` for a stricter focus trap.
+- **Nested popovers are supported.** The `FloatingTree` pattern handles nesting automatically.
+
+## ARIA
+
+- Positioner: `role="dialog"`, `aria-labelledby` (from Title), `aria-describedby` (from Description)
+- Trigger: `aria-expanded`, `aria-haspopup="dialog"`, `aria-controls`

packages/headless/src/primitives/popover/index.ts

@@ -0,0 +1,13 @@
+export * as Popover from './parts';
+
+export type {
+ PopoverArrowProps,
+ PopoverCloseProps,
+ PopoverDescriptionProps,
+ PopoverPopupProps,
+ PopoverPortalProps,
+ PopoverPositionerProps,
+ PopoverProps,
+ PopoverTitleProps,
+ PopoverTriggerProps,
+} from './parts';

packages/headless/src/primitives/popover/parts.ts

@@ -0,0 +1,9 @@
+export { type PopoverProps, PopoverRoot as Root } from './popover-root';
+export { type PopoverTriggerProps, PopoverTrigger as Trigger } from './popover-trigger';
+export { type PopoverPortalProps, PopoverPortal as Portal } from './popover-portal';
+export { type PopoverPositionerProps, PopoverPositioner as Positioner } from './popover-positioner';
+export { type PopoverPopupProps, PopoverPopup as Popup } from './popover-popup';
+export { type PopoverArrowProps, PopoverArrow as Arrow } from './popover-arrow';
+export { type PopoverTitleProps, PopoverTitle as Title } from './popover-title';
+export { type PopoverDescriptionProps, PopoverDescription as Description } from './popover-description';
+export { type PopoverCloseProps, PopoverClose as Close } from './popover-close';

packages/headless/src/primitives/popover/popover-arrow.tsx

@@ -0,0 +1,22 @@
+'use client';
+
+import { FloatingArrow } from '@floating-ui/react';
+import React from 'react';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverArrowProps extends React.ComponentPropsWithRef<typeof FloatingArrow> {}
+
+export function PopoverArrow(props: PopoverArrowProps) {
+ const { floatingContext, arrowRef, placement } = usePopoverContext();
+ const side = placement.split('-')[0];
+
+ return (
+ <FloatingArrow
+ data-cl-slot='popover-arrow'
+ data-cl-side={side}
+ {...props}
+ ref={arrowRef}
+ context={floatingContext}
+ />
+ );
+}

packages/headless/src/primitives/popover/popover-close.tsx

@@ -0,0 +1,25 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverCloseProps extends ComponentProps<'button'> {}
+
+export function PopoverClose(props: PopoverCloseProps) {
+ const { render, ...otherProps } = props;
+ const { setOpen } = usePopoverContext();
+
+ const defaultProps = {
+ type: 'button' as const,
+ 'data-cl-slot': 'popover-close',
+ onClick() {
+ setOpen(false);
+ },
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ render,
+ props: mergeProps<'button'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/popover/popover-context.ts

@@ -0,0 +1,39 @@
+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 PopoverContextValue {
+ open: boolean;
+ setOpen: (open: boolean) => void;
+ 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>;
+ modal: boolean;
+ labelId: string | undefined;
+ descriptionId: string | undefined;
+ setLabelId: React.Dispatch<React.SetStateAction<string | undefined>>;
+ setDescriptionId: React.Dispatch<React.SetStateAction<string | undefined>>;
+ mounted: boolean;
+ transitionProps: TransitionProps;
+}
+
+export const PopoverContext = createContext<PopoverContextValue | null>(null);
+
+export function usePopoverContext() {
+ const ctx = useContext(PopoverContext);
+ if (!ctx) {
+ throw new Error('Popover compound components must be used within <Popover.Root>');
+ }
+ return ctx;
+}

packages/headless/src/primitives/popover/popover-description.tsx

@@ -0,0 +1,29 @@
+'use client';
+
+import { useId, useLayoutEffect } from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverDescriptionProps extends ComponentProps<'p'> {}
+
+export function PopoverDescription(props: PopoverDescriptionProps) {
+ const { render, ...otherProps } = props;
+ const { setDescriptionId } = usePopoverContext();
+ const id = useId();
+
+ useLayoutEffect(() => {
+ setDescriptionId(id);
+ return () => setDescriptionId(undefined);
+ }, [id, setDescriptionId]);
+
+ const defaultProps = {
+ 'data-cl-slot': 'popover-description',
+ id,
+ };
+
+ return renderElement({
+ defaultTagName: 'p',
+ render,
+ props: mergeProps<'p'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/popover/popover-popup.tsx

@@ -0,0 +1,23 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverPopupProps extends ComponentProps<'div'> {}
+
+export function PopoverPopup(props: PopoverPopupProps) {
+ const { render, ...otherProps } = props;
+ const { popupRef, transitionProps } = usePopoverContext();
+
+ const defaultProps = {
+ 'data-cl-slot': 'popover-popup',
+ ref: popupRef,
+ ...transitionProps,
+ };
+
+ return renderElement({
+ defaultTagName: 'div',
+ render,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/popover/popover-portal.tsx

@@ -0,0 +1,16 @@
+'use client';
+
+import { FloatingPortal } from '@floating-ui/react';
+import type { ReactNode } from 'react';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverPortalProps {
+ children: ReactNode;
+ root?: HTMLElement | null | React.RefObject<HTMLElement | null>;
+}
+
+export function PopoverPortal(props: PopoverPortalProps) {
+ const { mounted } = usePopoverContext();
+ if (!mounted) return null;
+ return <FloatingPortal root={props.root}>{props.children}</FloatingPortal>;
+}

packages/headless/src/primitives/popover/popover-positioner.tsx

@@ -0,0 +1,42 @@
+'use client';
+
+import { FloatingFocusManager } from '@floating-ui/react';
+import React from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverPositionerProps extends ComponentProps<'div'> {}
+
+export function PopoverPositioner(props: PopoverPositionerProps) {
+ const { render, ...otherProps } = props;
+ const { mounted, floatingContext, refs, floatingStyles, placement, getFloatingProps, modal, labelId, descriptionId } =
+ usePopoverContext();
+
+ const side = placement.split('-')[0];
+
+ const defaultProps = {
+ 'data-cl-slot': 'popover-positioner',
+ 'data-cl-side': side,
+ ref: refs.setFloating,
+ style: floatingStyles,
+ 'aria-labelledby': labelId,
+ 'aria-describedby': descriptionId,
+ ...(getFloatingProps() as React.ComponentPropsWithRef<'div'>),
+ };
+
+ const element = renderElement({
+ defaultTagName: 'div',
+ render,
+ enabled: mounted,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+
+ return (
+ <FloatingFocusManager
+ context={floatingContext}
+ modal={modal}
+ >
+ {element!}
+ </FloatingFocusManager>
+ );
+}

packages/headless/package.json

@@ -17,6 +17,10 @@
  "import": "./dist/primitives/tooltip/index.js",
  "types": "./dist/primitives/tooltip/index.d.ts"
  },
+ "./popover": {
+ "import": "./dist/primitives/popover/index.js",
+ "types": "./dist/primitives/popover/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

packages/headless/src/primitives/popover/README.md

@@ -0,0 +1,111 @@
+# Popover
+
+A floating panel anchored to a trigger element. Supports focus management, ARIA labeling, and enter/exit animations.
+
+## When to Use
+
+- Rich content panels, filter dropdowns, or any non-modal floating content anchored to a trigger.
+- When content includes interactive elements (inputs, buttons) — unlike Tooltip which is display-only.
+- Prefer Popover over Dialog when the content should be anchored to a specific element and the page should remain interactive by default.
+
+## Usage
+
+```tsx
+import { Popover } from '@/primitives/popover';
+
+<Popover.Root>
+ <Popover.Trigger>Settings</Popover.Trigger>
+ <Popover.Positioner>
+ <Popover.Popup>
+ <Popover.Title>Preferences</Popover.Title>
+ <Popover.Description>Adjust your settings below.</Popover.Description>
+ {/* Interactive content here */}
+ <Popover.Close>Done</Popover.Close>
+ </Popover.Popup>
+ </Popover.Positioner>
+</Popover.Root>;
+```
+
+### Controlled
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Popover.Root
+ open={open}
+ onOpenChange={setOpen}
+>
+ {/* ... */}
+</Popover.Root>;
+```
+
+### Modal Mode
+
+```tsx
+<Popover.Root modal>{/* Focus is trapped within the popover */}</Popover.Root>
+```
+
+## Parts
+
+| Part | Default Element | Description |
+| --------------------- | --------------- | ---------------------------------------- |
+| `Popover.Root` | — | Root context provider |
+| `Popover.Trigger` | `<button>` | Toggles the popover on click |
+| `Popover.Portal` | — | Portals children (accepts `root` prop) |
+| `Popover.Positioner` | `<div>` | Floating positioned container |
+| `Popover.Popup` | `<div>` | Visual content wrapper |
+| `Popover.Arrow` | `<svg>` | Optional floating arrow |
+| `Popover.Title` | `<h2>` | Heading, wired to `aria-labelledby` |
+| `Popover.Description` | `<p>` | Description, wired to `aria-describedby` |
+| `Popover.Close` | `<button>` | Closes the popover on click |
+
+## Props
+
+### `Popover.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` | `"bottom"` | Floating UI placement |
+| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
+| `modal` | `boolean` | `false` | Traps focus within the popover |
+
+### `Popover.Trigger`, `Popover.Positioner`, `Popover.Popup`, `Popover.Title`, `Popover.Description`, `Popover.Close`
+
+No additional props beyond standard HTML attributes and the `render` prop.
+
+### `Popover.Arrow`
+
+Accepts all `FloatingArrow` props. `ref` and `context` are injected automatically.
+
+## Keyboard
+
+| Key | Action |
+| -------- | -------------------------------------------------------------------- |
+| `Escape` | Closes the popover |
+| `Tab` | Cycles focus within popover (modal mode) or moves freely (non-modal) |
+
+## Data Attributes
+
+| Attribute | Applies To | Description |
+| --------------------------------- | ----------------- | ---------------------------------------- |
+| `data-cl-slot` | All parts | Part identifier (e.g. `"popover-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. The popup auto-repositions on scroll and resize via `autoUpdate`. Cross-axis flipping is enabled only when using an aligned placement (e.g. `"bottom-start"`).
+
+## Important Notes
+
+- **Title and Description are optional but recommended.** They wire `aria-labelledby` and `aria-describedby` to the positioner. If omitted, those attributes are simply absent.
+- **Non-modal by default.** Unlike Dialog, the page remains interactive behind the popover. Set `modal={true}` for a stricter focus trap.
+- **Nested popovers are supported.** The `FloatingTree` pattern handles nesting automatically.
+
+## ARIA
+
+- Positioner: `role="dialog"`, `aria-labelledby` (from Title), `aria-describedby` (from Description)
+- Trigger: `aria-expanded`, `aria-haspopup="dialog"`, `aria-controls`

packages/headless/src/primitives/popover/index.ts

@@ -0,0 +1,13 @@
+export * as Popover from './parts';
+
+export type {
+ PopoverArrowProps,
+ PopoverCloseProps,
+ PopoverDescriptionProps,
+ PopoverPopupProps,
+ PopoverPortalProps,
+ PopoverPositionerProps,
+ PopoverProps,
+ PopoverTitleProps,
+ PopoverTriggerProps,
+} from './parts';

packages/headless/src/primitives/popover/parts.ts

@@ -0,0 +1,9 @@
+export { type PopoverProps, PopoverRoot as Root } from './popover-root';
+export { type PopoverTriggerProps, PopoverTrigger as Trigger } from './popover-trigger';
+export { type PopoverPortalProps, PopoverPortal as Portal } from './popover-portal';
+export { type PopoverPositionerProps, PopoverPositioner as Positioner } from './popover-positioner';
+export { type PopoverPopupProps, PopoverPopup as Popup } from './popover-popup';
+export { type PopoverArrowProps, PopoverArrow as Arrow } from './popover-arrow';
+export { type PopoverTitleProps, PopoverTitle as Title } from './popover-title';
+export { type PopoverDescriptionProps, PopoverDescription as Description } from './popover-description';
+export { type PopoverCloseProps, PopoverClose as Close } from './popover-close';

packages/headless/src/primitives/popover/popover-arrow.tsx

@@ -0,0 +1,22 @@
+'use client';
+
+import { FloatingArrow } from '@floating-ui/react';
+import React from 'react';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverArrowProps extends React.ComponentPropsWithRef<typeof FloatingArrow> {}
+
+export function PopoverArrow(props: PopoverArrowProps) {
+ const { floatingContext, arrowRef, placement } = usePopoverContext();
+ const side = placement.split('-')[0];
+
+ return (
+ <FloatingArrow
+ data-cl-slot='popover-arrow'
+ data-cl-side={side}
+ {...props}
+ ref={arrowRef}
+ context={floatingContext}
+ />
+ );
+}

packages/headless/src/primitives/popover/popover-close.tsx

@@ -0,0 +1,25 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverCloseProps extends ComponentProps<'button'> {}
+
+export function PopoverClose(props: PopoverCloseProps) {
+ const { render, ...otherProps } = props;
+ const { setOpen } = usePopoverContext();
+
+ const defaultProps = {
+ type: 'button' as const,
+ 'data-cl-slot': 'popover-close',
+ onClick() {
+ setOpen(false);
+ },
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ render,
+ props: mergeProps<'button'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/popover/popover-context.ts

@@ -0,0 +1,39 @@
+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 PopoverContextValue {
+ open: boolean;
+ setOpen: (open: boolean) => void;
+ 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>;
+ modal: boolean;
+ labelId: string | undefined;
+ descriptionId: string | undefined;
+ setLabelId: React.Dispatch<React.SetStateAction<string | undefined>>;
+ setDescriptionId: React.Dispatch<React.SetStateAction<string | undefined>>;
+ mounted: boolean;
+ transitionProps: TransitionProps;
+}
+
+export const PopoverContext = createContext<PopoverContextValue | null>(null);
+
+export function usePopoverContext() {
+ const ctx = useContext(PopoverContext);
+ if (!ctx) {
+ throw new Error('Popover compound components must be used within <Popover.Root>');
+ }
+ return ctx;
+}

packages/headless/src/primitives/popover/popover-description.tsx

@@ -0,0 +1,29 @@
+'use client';
+
+import { useId, useLayoutEffect } from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverDescriptionProps extends ComponentProps<'p'> {}
+
+export function PopoverDescription(props: PopoverDescriptionProps) {
+ const { render, ...otherProps } = props;
+ const { setDescriptionId } = usePopoverContext();
+ const id = useId();
+
+ useLayoutEffect(() => {
+ setDescriptionId(id);
+ return () => setDescriptionId(undefined);
+ }, [id, setDescriptionId]);
+
+ const defaultProps = {
+ 'data-cl-slot': 'popover-description',
+ id,
+ };
+
+ return renderElement({
+ defaultTagName: 'p',
+ render,
+ props: mergeProps<'p'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/popover/popover-popup.tsx

@@ -0,0 +1,23 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverPopupProps extends ComponentProps<'div'> {}
+
+export function PopoverPopup(props: PopoverPopupProps) {
+ const { render, ...otherProps } = props;
+ const { popupRef, transitionProps } = usePopoverContext();
+
+ const defaultProps = {
+ 'data-cl-slot': 'popover-popup',
+ ref: popupRef,
+ ...transitionProps,
+ };
+
+ return renderElement({
+ defaultTagName: 'div',
+ render,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/popover/popover-portal.tsx

@@ -0,0 +1,16 @@
+'use client';
+
+import { FloatingPortal } from '@floating-ui/react';
+import type { ReactNode } from 'react';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverPortalProps {
+ children: ReactNode;
+ root?: HTMLElement | null | React.RefObject<HTMLElement | null>;
+}
+
+export function PopoverPortal(props: PopoverPortalProps) {
+ const { mounted } = usePopoverContext();
+ if (!mounted) return null;
+ return <FloatingPortal root={props.root}>{props.children}</FloatingPortal>;
+}

packages/headless/src/primitives/popover/popover-positioner.tsx

@@ -0,0 +1,42 @@
+'use client';
+
+import { FloatingFocusManager } from '@floating-ui/react';
+import React from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { usePopoverContext } from './popover-context';
+
+export interface PopoverPositionerProps extends ComponentProps<'div'> {}
+
+export function PopoverPositioner(props: PopoverPositionerProps) {
+ const { render, ...otherProps } = props;
+ const { mounted, floatingContext, refs, floatingStyles, placement, getFloatingProps, modal, labelId, descriptionId } =
+ usePopoverContext();
+
+ const side = placement.split('-')[0];
+
+ const defaultProps = {
+ 'data-cl-slot': 'popover-positioner',
+ 'data-cl-side': side,
+ ref: refs.setFloating,
+ style: floatingStyles,
+ 'aria-labelledby': labelId,
+ 'aria-describedby': descriptionId,
+ ...(getFloatingProps() as React.ComponentPropsWithRef<'div'>),
+ };
+
+ const element = renderElement({
+ defaultTagName: 'div',
+ render,
+ enabled: mounted,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+
+ return (
+ <FloatingFocusManager
+ context={floatingContext}
+ modal={modal}
+ >
+ {element!}
+ </FloatingFocusManager>
+ );
+}