@primitiv-ui/react 0.1.38 → 0.1.39

package/dist/Popover/Popover.d.ts

@@ -0,0 +1,239 @@
+import type { ReactElement } from "react";
+import type { PopoverAnchorProps, PopoverCloseProps, PopoverContentProps, PopoverDescriptionProps, PopoverRootProps, PopoverTitleProps, PopoverTriggerProps } from "./types.js";
+/**
+ * The root of a Popover — owns open state, generates the ids that wire the
+ * trigger to the content, and provides context to descendants. Renders no DOM
+ * of its own.
+ *
+ * Supports two state modes, statically discriminated at the type level:
+ *
+ * - **Uncontrolled** — pass {@link PopoverRootUncontrolledProps.defaultOpen | `defaultOpen`}
+ *   (or omit it for closed-on-mount). The component owns the open flag
+ *   internally; observe transitions with `onOpenChange`.
+ * - **Controlled** — pass {@link PopoverRootControlledProps.open | `open`} *and*
+ *   {@link PopoverRootControlledProps.onOpenChange | `onOpenChange`} together.
+ *   The parent owns the flag; the component defers every change back through
+ *   the callback.
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * <Popover.Root>
+ *   <Popover.Trigger>Open</Popover.Trigger>
+ *   <Popover.Content>...</Popover.Content>
+ * </Popover.Root>
+ * ```
+ *
+ * @example Controlled
+ * ```tsx
+ * const [open, setOpen] = useState(false);
+ *
+ * <Popover.Root open={open} onOpenChange={setOpen}>
+ *   <Popover.Trigger>Open</Popover.Trigger>
+ *   <Popover.Content>...</Popover.Content>
+ * </Popover.Root>
+ * ```
+ */
+export declare function PopoverRoot({ children, defaultOpen, open, onOpenChange, }: PopoverRootProps): ReactElement;
+export declare namespace PopoverRoot {
+    var displayName: string;
+}
+/**
+ * A button that toggles the popover. Renders `<button type="button">` with
+ * full ARIA wiring:
+ *
+ * - `aria-haspopup="dialog"`
+ * - `aria-expanded` tracks open state
+ * - `aria-controls` points at the `Popover.Content` dialog's id
+ *
+ * Clicking toggles the popover; a consumer `onClick` composes (runs first, can
+ * `event.preventDefault()` to veto the toggle).
+ *
+ * **`asChild` prop.** Pass `asChild` to render any consumer-supplied element
+ * (e.g. an icon button of your own) with the trigger's ARIA, composed event
+ * handlers, and ref merged in. Supply the child's element type via the generic
+ * (e.g. `Popover.Trigger<HTMLAnchorElement>`).
+ *
+ * @extends HTMLButtonElement
+ *
+ * @example
+ * ```tsx
+ * <Popover.Trigger>Open</Popover.Trigger>
+ *
+ * <Popover.Trigger<HTMLAnchorElement> asChild>
+ *   <a href="#panel">Open</a>
+ * </Popover.Trigger>
+ * ```
+ */
+export declare function PopoverTrigger<T extends HTMLElement = HTMLButtonElement>({ children, asChild, ref, ...rest }: PopoverTriggerProps<T>): ReactElement;
+export declare namespace PopoverTrigger {
+    var displayName: string;
+}
+/**
+ * The floating panel, rendered with the native HTML
+ * [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API)
+ * (`popover="auto"`) — no portal, no floating-ui. The browser manages the top
+ * layer and light-dismiss (outside click / Escape); visual placement is your
+ * CSS concern (use CSS anchor positioning against the trigger or
+ * {@link PopoverAnchor | `Popover.Anchor`}).
+ *
+ * Renders a `<div role="dialog">`. On open, focus moves into the panel (first
+ * focusable descendant, else the panel itself — it carries `tabIndex={-1}`).
+ * `Escape` closes and returns focus to the trigger. `aria-labelledby` /
+ * `aria-describedby` are wired automatically when `Popover.Title` /
+ * `Popover.Description` are rendered inside.
+ *
+ * **`asChild` prop.** Pass `asChild` to render a consumer element (e.g. a
+ * `<section>` or a motion wrapper) with the dialog props and internal ref
+ * merged in. A consumer `ref` composes with the internal ref, so open state
+ * keeps working.
+ *
+ * **Styling hook.** `data-state="open" | "closed"`.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * <Popover.Content className="panel">
+ *   <Popover.Title>Filters</Popover.Title>
+ *   <Popover.Close>Done</Popover.Close>
+ * </Popover.Content>
+ * ```
+ */
+export declare function PopoverContent({ children, onKeyDown, asChild, ref, ...rest }: PopoverContentProps): ReactElement;
+export declare namespace PopoverContent {
+    var displayName: string;
+}
+/**
+ * An optional positioning reference. By default the popover is positioned
+ * against the trigger; render `Popover.Anchor` around (or in place of) another
+ * element to anchor the panel there instead — useful when the trigger is a
+ * small icon inside a larger control.
+ *
+ * Renders a `<div>`. Positioning is CSS-driven: attach a CSS `anchor-name` to
+ * this element and a matching `position-anchor` to `Popover.Content`. Pass
+ * `asChild` to project the anchor semantics onto an existing element.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * <Popover.Anchor asChild>
+ *   <div className="field" style={{ anchorName: "--popover" }}>
+ *     <input />
+ *     <Popover.Trigger>▾</Popover.Trigger>
+ *   </div>
+ * </Popover.Anchor>
+ * ```
+ */
+export declare function PopoverAnchor({ children, asChild, ...rest }: PopoverAnchorProps): ReactElement;
+export declare namespace PopoverAnchor {
+    var displayName: string;
+}
+/**
+ * A button that closes the popover and returns focus to the trigger. Renders a
+ * `<button type="button">` whose `onClick` composes with the close — consumer
+ * handlers run first and can `event.preventDefault()` to veto closing.
+ *
+ * Pass `asChild` to render any element (e.g. a text link or your own icon
+ * button) with the close behaviour merged in.
+ *
+ * @extends HTMLButtonElement
+ *
+ * @example
+ * ```tsx
+ * <Popover.Close>Done</Popover.Close>
+ * ```
+ */
+export declare function PopoverClose({ children, onClick, asChild, ...rest }: PopoverCloseProps): ReactElement;
+export declare namespace PopoverClose {
+    var displayName: string;
+}
+/**
+ * The popover's accessible name. Renders an `<h2>` by default and
+ * auto-registers its generated id so `Popover.Content` wires it up as
+ * `aria-labelledby`. Pass `asChild` to render your own heading element (e.g.
+ * an `<h3>`); the id is still registered.
+ *
+ * @extends HTMLHeadingElement
+ *
+ * @example
+ * ```tsx
+ * <Popover.Title>Filters</Popover.Title>
+ * ```
+ */
+export declare function PopoverTitle({ children, asChild, ...rest }: PopoverTitleProps): ReactElement;
+export declare namespace PopoverTitle {
+    var displayName: string;
+}
+/**
+ * The popover's accessible description. Renders a `<p>` by default and
+ * auto-registers its generated id so `Popover.Content` wires it up as
+ * `aria-describedby`. Pass `asChild` to render any element; the id is still
+ * registered.
+ *
+ * @extends HTMLParagraphElement
+ *
+ * @example
+ * ```tsx
+ * <Popover.Description>Narrow the results below.</Popover.Description>
+ * ```
+ */
+export declare function PopoverDescription({ children, asChild, ...rest }: PopoverDescriptionProps): ReactElement;
+export declare namespace PopoverDescription {
+    var displayName: string;
+}
+/** Type of the {@link Popover} compound — the Root callable plus its sub-components. */
+type PopoverCompound = typeof PopoverRoot & {
+    /** The root, owning open state and context. */
+    Root: typeof PopoverRoot;
+    /** The button that toggles the popover. */
+    Trigger: typeof PopoverTrigger;
+    /** An optional positioning reference used instead of the trigger. */
+    Anchor: typeof PopoverAnchor;
+    /** The floating panel. */
+    Content: typeof PopoverContent;
+    /** A button that closes the popover. */
+    Close: typeof PopoverClose;
+    /** The popover's accessible name; auto-wires `aria-labelledby`. */
+    Title: typeof PopoverTitle;
+    /** The popover's accessible description; auto-wires `aria-describedby`. */
+    Description: typeof PopoverDescription;
+};
+/**
+ * Headless, accessible **Popover** — a compound component built on the native
+ * HTML Popover API (`popover="auto"`). A non-modal dialog anchored to a
+ * trigger: the browser owns the top layer and light-dismiss, focus moves into
+ * the panel on open and returns to the trigger on close, and the background
+ * stays interactive (no focus trap — use `Modal` for that). Zero styles ship;
+ * visual placement is your CSS concern (CSS anchor positioning).
+ *
+ * `Popover` is both callable (an alias of {@link PopoverRoot | `Popover.Root`})
+ * and carries its sub-components as static properties.
+ *
+ * - {@link PopoverRoot | `Popover.Root`} — state owner and context provider.
+ * - {@link PopoverTrigger | `Popover.Trigger`} — `<button>` that toggles the popover.
+ * - {@link PopoverAnchor | `Popover.Anchor`} — optional positioning reference.
+ * - {@link PopoverContent | `Popover.Content`} — the native-popover `role="dialog"` panel.
+ * - {@link PopoverClose | `Popover.Close`} — `<button>` that closes the popover.
+ * - {@link PopoverTitle | `Popover.Title`} — accessible name; auto-wires `aria-labelledby`.
+ * - {@link PopoverDescription | `Popover.Description`} — auto-wires `aria-describedby`.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { Popover } from "@primitiv-ui/react";
+ *
+ * <Popover.Root>
+ *   <Popover.Trigger>Filters</Popover.Trigger>
+ *   <Popover.Content>
+ *     <Popover.Title>Filters</Popover.Title>
+ *     <Popover.Description>Narrow the results.</Popover.Description>
+ *     <Popover.Close>Done</Popover.Close>
+ *   </Popover.Content>
+ * </Popover.Root>;
+ * ```
+ *
+ * @see {@link PopoverRoot} for the controlled/uncontrolled state modes.
+ * @see {@link PopoverContent} for focus behaviour and ARIA auto-wiring.
+ */
+declare const PopoverCompound: PopoverCompound;
+export { PopoverCompound as Popover };

package/dist/Popover/Popover.js

@@ -0,0 +1,293 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useId } from "react";
+import { Slot, composeEventHandlers } from "../Slot/index.js";
+import { PopoverContext, usePopoverContext } from "./PopoverContext.js";
+import { usePopoverContent, usePopoverRoot, usePopoverTrigger, } from "./hooks/index.js";
+/**
+ * The root of a Popover — owns open state, generates the ids that wire the
+ * trigger to the content, and provides context to descendants. Renders no DOM
+ * of its own.
+ *
+ * Supports two state modes, statically discriminated at the type level:
+ *
+ * - **Uncontrolled** — pass {@link PopoverRootUncontrolledProps.defaultOpen | `defaultOpen`}
+ *   (or omit it for closed-on-mount). The component owns the open flag
+ *   internally; observe transitions with `onOpenChange`.
+ * - **Controlled** — pass {@link PopoverRootControlledProps.open | `open`} *and*
+ *   {@link PopoverRootControlledProps.onOpenChange | `onOpenChange`} together.
+ *   The parent owns the flag; the component defers every change back through
+ *   the callback.
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * <Popover.Root>
+ *   <Popover.Trigger>Open</Popover.Trigger>
+ *   <Popover.Content>...</Popover.Content>
+ * </Popover.Root>
+ * ```
+ *
+ * @example Controlled
+ * ```tsx
+ * const [open, setOpen] = useState(false);
+ *
+ * <Popover.Root open={open} onOpenChange={setOpen}>
+ *   <Popover.Trigger>Open</Popover.Trigger>
+ *   <Popover.Content>...</Popover.Content>
+ * </Popover.Root>
+ * ```
+ */
+export function PopoverRoot({ children, defaultOpen, open, onOpenChange, }) {
+    const { contextValue } = usePopoverRoot({ defaultOpen, open, onOpenChange });
+    return (_jsx(PopoverContext.Provider, { value: contextValue, children: children }));
+}
+/** @internal */
+PopoverRoot.displayName = "PopoverRoot";
+/**
+ * A button that toggles the popover. Renders `<button type="button">` with
+ * full ARIA wiring:
+ *
+ * - `aria-haspopup="dialog"`
+ * - `aria-expanded` tracks open state
+ * - `aria-controls` points at the `Popover.Content` dialog's id
+ *
+ * Clicking toggles the popover; a consumer `onClick` composes (runs first, can
+ * `event.preventDefault()` to veto the toggle).
+ *
+ * **`asChild` prop.** Pass `asChild` to render any consumer-supplied element
+ * (e.g. an icon button of your own) with the trigger's ARIA, composed event
+ * handlers, and ref merged in. Supply the child's element type via the generic
+ * (e.g. `Popover.Trigger<HTMLAnchorElement>`).
+ *
+ * @extends HTMLButtonElement
+ *
+ * @example
+ * ```tsx
+ * <Popover.Trigger>Open</Popover.Trigger>
+ *
+ * <Popover.Trigger<HTMLAnchorElement> asChild>
+ *   <a href="#panel">Open</a>
+ * </Popover.Trigger>
+ * ```
+ */
+export function PopoverTrigger({ children, asChild = false, ref, ...rest }) {
+    const { triggerProps } = usePopoverTrigger({
+        ref: ref,
+        asChild,
+        ...rest,
+    });
+    if (asChild) {
+        return _jsx(Slot, { ...triggerProps, children: children });
+    }
+    return (_jsx("button", { type: "button", ...triggerProps, children: children }));
+}
+/** @internal */
+PopoverTrigger.displayName = "PopoverTrigger";
+/**
+ * The floating panel, rendered with the native HTML
+ * [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API)
+ * (`popover="auto"`) — no portal, no floating-ui. The browser manages the top
+ * layer and light-dismiss (outside click / Escape); visual placement is your
+ * CSS concern (use CSS anchor positioning against the trigger or
+ * {@link PopoverAnchor | `Popover.Anchor`}).
+ *
+ * Renders a `<div role="dialog">`. On open, focus moves into the panel (first
+ * focusable descendant, else the panel itself — it carries `tabIndex={-1}`).
+ * `Escape` closes and returns focus to the trigger. `aria-labelledby` /
+ * `aria-describedby` are wired automatically when `Popover.Title` /
+ * `Popover.Description` are rendered inside.
+ *
+ * **`asChild` prop.** Pass `asChild` to render a consumer element (e.g. a
+ * `<section>` or a motion wrapper) with the dialog props and internal ref
+ * merged in. A consumer `ref` composes with the internal ref, so open state
+ * keeps working.
+ *
+ * **Styling hook.** `data-state="open" | "closed"`.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * <Popover.Content className="panel">
+ *   <Popover.Title>Filters</Popover.Title>
+ *   <Popover.Close>Done</Popover.Close>
+ * </Popover.Content>
+ * ```
+ */
+export function PopoverContent({ children, onKeyDown, asChild = false, ref, ...rest }) {
+    const { contentProps } = usePopoverContent({
+        onKeyDown,
+        ref: ref,
+    });
+    if (asChild) {
+        return (_jsx(Slot, { ...rest, ...contentProps, children: children }));
+    }
+    return (_jsx("div", { ...rest, ...contentProps, children: children }));
+}
+/** @internal */
+PopoverContent.displayName = "PopoverContent";
+/**
+ * An optional positioning reference. By default the popover is positioned
+ * against the trigger; render `Popover.Anchor` around (or in place of) another
+ * element to anchor the panel there instead — useful when the trigger is a
+ * small icon inside a larger control.
+ *
+ * Renders a `<div>`. Positioning is CSS-driven: attach a CSS `anchor-name` to
+ * this element and a matching `position-anchor` to `Popover.Content`. Pass
+ * `asChild` to project the anchor semantics onto an existing element.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * <Popover.Anchor asChild>
+ *   <div className="field" style={{ anchorName: "--popover" }}>
+ *     <input />
+ *     <Popover.Trigger>▾</Popover.Trigger>
+ *   </div>
+ * </Popover.Anchor>
+ * ```
+ */
+export function PopoverAnchor({ children, asChild = false, ...rest }) {
+    // Consume context so an Anchor rendered outside a Root throws, matching the
+    // other sub-components. Positioning itself is a CSS (anchor-name) concern.
+    usePopoverContext();
+    if (asChild) {
+        return _jsx(Slot, { ...rest, children: children });
+    }
+    return _jsx("div", { ...rest, children: children });
+}
+/** @internal */
+PopoverAnchor.displayName = "PopoverAnchor";
+/**
+ * A button that closes the popover and returns focus to the trigger. Renders a
+ * `<button type="button">` whose `onClick` composes with the close — consumer
+ * handlers run first and can `event.preventDefault()` to veto closing.
+ *
+ * Pass `asChild` to render any element (e.g. a text link or your own icon
+ * button) with the close behaviour merged in.
+ *
+ * @extends HTMLButtonElement
+ *
+ * @example
+ * ```tsx
+ * <Popover.Close>Done</Popover.Close>
+ * ```
+ */
+export function PopoverClose({ children, onClick, asChild = false, ...rest }) {
+    const { setOpen, triggerRef } = usePopoverContext();
+    const closeProps = {
+        ...rest,
+        onClick: composeEventHandlers(onClick, () => {
+            setOpen(false);
+            triggerRef.current?.focus();
+        }),
+    };
+    if (asChild) {
+        return _jsx(Slot, { ...closeProps, children: children });
+    }
+    return (_jsx("button", { type: "button", ...closeProps, children: children }));
+}
+/** @internal */
+PopoverClose.displayName = "PopoverClose";
+/**
+ * The popover's accessible name. Renders an `<h2>` by default and
+ * auto-registers its generated id so `Popover.Content` wires it up as
+ * `aria-labelledby`. Pass `asChild` to render your own heading element (e.g.
+ * an `<h3>`); the id is still registered.
+ *
+ * @extends HTMLHeadingElement
+ *
+ * @example
+ * ```tsx
+ * <Popover.Title>Filters</Popover.Title>
+ * ```
+ */
+export function PopoverTitle({ children, asChild = false, ...rest }) {
+    const { registerTitle } = usePopoverContext();
+    const id = useId();
+    useEffect(() => {
+        registerTitle(id);
+        return () => registerTitle(undefined);
+    }, [registerTitle, id]);
+    if (asChild) {
+        return (_jsx(Slot, { id: id, ...rest, children: children }));
+    }
+    return (_jsx("h2", { id: id, ...rest, children: children }));
+}
+/** @internal */
+PopoverTitle.displayName = "PopoverTitle";
+/**
+ * The popover's accessible description. Renders a `<p>` by default and
+ * auto-registers its generated id so `Popover.Content` wires it up as
+ * `aria-describedby`. Pass `asChild` to render any element; the id is still
+ * registered.
+ *
+ * @extends HTMLParagraphElement
+ *
+ * @example
+ * ```tsx
+ * <Popover.Description>Narrow the results below.</Popover.Description>
+ * ```
+ */
+export function PopoverDescription({ children, asChild = false, ...rest }) {
+    const { registerDescription } = usePopoverContext();
+    const id = useId();
+    useEffect(() => {
+        registerDescription(id);
+        return () => registerDescription(undefined);
+    }, [registerDescription, id]);
+    if (asChild) {
+        return (_jsx(Slot, { id: id, ...rest, children: children }));
+    }
+    return (_jsx("p", { id: id, ...rest, children: children }));
+}
+/** @internal */
+PopoverDescription.displayName = "PopoverDescription";
+/**
+ * Headless, accessible **Popover** — a compound component built on the native
+ * HTML Popover API (`popover="auto"`). A non-modal dialog anchored to a
+ * trigger: the browser owns the top layer and light-dismiss, focus moves into
+ * the panel on open and returns to the trigger on close, and the background
+ * stays interactive (no focus trap — use `Modal` for that). Zero styles ship;
+ * visual placement is your CSS concern (CSS anchor positioning).
+ *
+ * `Popover` is both callable (an alias of {@link PopoverRoot | `Popover.Root`})
+ * and carries its sub-components as static properties.
+ *
+ * - {@link PopoverRoot | `Popover.Root`} — state owner and context provider.
+ * - {@link PopoverTrigger | `Popover.Trigger`} — `<button>` that toggles the popover.
+ * - {@link PopoverAnchor | `Popover.Anchor`} — optional positioning reference.
+ * - {@link PopoverContent | `Popover.Content`} — the native-popover `role="dialog"` panel.
+ * - {@link PopoverClose | `Popover.Close`} — `<button>` that closes the popover.
+ * - {@link PopoverTitle | `Popover.Title`} — accessible name; auto-wires `aria-labelledby`.
+ * - {@link PopoverDescription | `Popover.Description`} — auto-wires `aria-describedby`.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { Popover } from "@primitiv-ui/react";
+ *
+ * <Popover.Root>
+ *   <Popover.Trigger>Filters</Popover.Trigger>
+ *   <Popover.Content>
+ *     <Popover.Title>Filters</Popover.Title>
+ *     <Popover.Description>Narrow the results.</Popover.Description>
+ *     <Popover.Close>Done</Popover.Close>
+ *   </Popover.Content>
+ * </Popover.Root>;
+ * ```
+ *
+ * @see {@link PopoverRoot} for the controlled/uncontrolled state modes.
+ * @see {@link PopoverContent} for focus behaviour and ARIA auto-wiring.
+ */
+const PopoverCompound = Object.assign(PopoverRoot, {
+    Root: PopoverRoot,
+    Trigger: PopoverTrigger,
+    Anchor: PopoverAnchor,
+    Content: PopoverContent,
+    Close: PopoverClose,
+    Title: PopoverTitle,
+    Description: PopoverDescription,
+});
+PopoverCompound.displayName = "Popover";
+export { PopoverCompound as Popover };

package/dist/Popover/PopoverContext.d.ts

@@ -0,0 +1,4 @@
+import type { Context } from "react";
+import { PopoverContextValue } from "./types.js";
+export declare const PopoverContext: Context<PopoverContextValue | null>;
+export declare const usePopoverContext: () => PopoverContextValue;

package/dist/Popover/PopoverContext.js

@@ -0,0 +1,5 @@
+"use client";
+import { createStrictContext } from "../utils/index.js";
+const popoverContext = createStrictContext("Popover sub-components must be rendered inside a <Popover.Root>.", "PopoverContext");
+export const PopoverContext = popoverContext[0];
+export const usePopoverContext = popoverContext[1];

package/dist/Popover/hooks/index.d.ts

@@ -0,0 +1,3 @@
+export { usePopoverRoot } from "./usePopoverRoot.js";
+export { usePopoverTrigger } from "./usePopoverTrigger.js";
+export { usePopoverContent } from "./usePopoverContent.js";

package/dist/Popover/hooks/index.js

@@ -0,0 +1,3 @@
+export { usePopoverRoot } from "./usePopoverRoot.js";
+export { usePopoverTrigger } from "./usePopoverTrigger.js";
+export { usePopoverContent } from "./usePopoverContent.js";

package/dist/Popover/hooks/usePopoverContent.d.ts

@@ -0,0 +1,19 @@
+import { KeyboardEvent, KeyboardEventHandler, Ref } from "react";
+type UsePopoverContentArgs = {
+    onKeyDown?: KeyboardEventHandler<HTMLDivElement>;
+    ref?: Ref<HTMLDivElement>;
+};
+export declare function usePopoverContent({ onKeyDown, ref, }?: UsePopoverContentArgs): {
+    contentProps: {
+        ref: import("react").RefObject<HTMLDivElement | null> | ((node: HTMLDivElement) => void);
+        id: string;
+        role: "dialog";
+        popover: "auto";
+        tabIndex: number;
+        "aria-labelledby": string | undefined;
+        "aria-describedby": string | undefined;
+        "data-state": "open" | "closed";
+        onKeyDown: (event: KeyboardEvent<HTMLDivElement>) => void;
+    };
+};
+export {};

package/dist/Popover/hooks/usePopoverContent.js

@@ -0,0 +1,83 @@
+"use client";
+import { useEffect, useRef, } from "react";
+import { composeEventHandlers, composeRefs } from "../../Slot/index.js";
+import { FOCUSABLE_SELECTOR } from "../../utils/index.js";
+import { usePopoverContext } from "../PopoverContext.js";
+export function usePopoverContent({ onKeyDown, ref, } = {}) {
+    const { open, setOpen, contentId, triggerRef, titleId, descriptionId } = usePopoverContext();
+    const contentRef = useRef(null);
+    const composedRef = ref ? composeRefs(contentRef, ref) : contentRef;
+    useEffect(() => {
+        const content = contentRef.current;
+        if (open) {
+            content.showPopover();
+            // Move focus into the popover (WAI-ARIA non-modal dialog): the first
+            // focusable descendant, or the content itself (it carries tabIndex=-1).
+            const focusable = content.querySelector(FOCUSABLE_SELECTOR);
+            (focusable ?? content).focus();
+        }
+        else {
+            try {
+                content.hidePopover();
+            }
+            catch {
+                // already hidden — no-op (e.g. browser already light-dismissed it)
+            }
+        }
+    }, [open]);
+    // Sync React state when the browser closes the popover without our code
+    // doing it (real-browser ToggleEvent on light-dismiss or native Escape).
+    useEffect(() => {
+        const content = contentRef.current;
+        const handleToggle = (event) => {
+            if (event.newState === "closed")
+                setOpen(false);
+        };
+        content.addEventListener("toggle", handleToggle);
+        return () => content.removeEventListener("toggle", handleToggle);
+    }, [setOpen]);
+    // Close on clicks outside the popover. This is only a fallback for
+    // environments WITHOUT the native Popover API (e.g. jsdom): a real browser
+    // already light-dismisses an `auto` popover on an outside click and fires the
+    // `toggle` event we sync above. Running this listener in a real browser is
+    // not just redundant — React 19 can flush this effect synchronously inside
+    // the very click that opened the popover from an external control, so the
+    // listener would catch that click and immediately re-close it. Gate it to
+    // non-native environments; `"popover" in HTMLElement.prototype` is true only
+    // where the native API (and its own light-dismiss) exists.
+    useEffect(() => {
+        if (!open)
+            return;
+        if ("popover" in HTMLElement.prototype)
+            return;
+        const handleClick = (event) => {
+            const target = event.target;
+            if (triggerRef.current?.contains(target))
+                return;
+            if (target.closest?.("[popover]"))
+                return;
+            setOpen(false);
+        };
+        document.addEventListener("click", handleClick);
+        return () => document.removeEventListener("click", handleClick);
+    }, [open, setOpen, triggerRef]);
+    const handleKeyDown = (event) => {
+        if (event.key === "Escape") {
+            event.preventDefault();
+            setOpen(false);
+            triggerRef.current?.focus();
+        }
+    };
+    const contentProps = {
+        ref: composedRef,
+        id: contentId,
+        role: "dialog",
+        popover: "auto",
+        tabIndex: -1,
+        "aria-labelledby": titleId,
+        "aria-describedby": descriptionId,
+        "data-state": (open ? "open" : "closed"),
+        onKeyDown: composeEventHandlers(onKeyDown, handleKeyDown),
+    };
+    return { contentProps };
+}

package/dist/Popover/hooks/usePopoverRoot.d.ts

@@ -0,0 +1,10 @@
+import { PopoverContextValue } from "../types.js";
+type UsePopoverRootArgs = {
+    defaultOpen?: boolean;
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+};
+export declare function usePopoverRoot({ defaultOpen, open: controlledOpen, onOpenChange, }: UsePopoverRootArgs): {
+    contextValue: PopoverContextValue;
+};
+export {};