@arun-dev/headless 4.4.0 → 4.5.0

package/dist/anchoring-Btxi0QwC.d.cts

@@ -0,0 +1,12 @@
+/**
+ * CSS anchor positioning for popups placed beside a trigger — Popover and Tooltip
+ * (decision 12). Internal: shared between components, not exported (decision 9).
+ *
+ * The trigger carries a generated `anchor-name`; the popup names it in `position-anchor`
+ * and is placed by `position-area`, flipping across the axis it opens along when there is
+ * no room. All inline, so the browser keeps it attached with nothing measured.
+ */
+type AnchorSide = 'top' | 'bottom' | 'left' | 'right';
+type AnchorAlign = 'start' | 'center' | 'end';
+
+export type { AnchorSide as A, AnchorAlign as a };

package/dist/anchoring-Btxi0QwC.d.ts

@@ -0,0 +1,12 @@
+/**
+ * CSS anchor positioning for popups placed beside a trigger — Popover and Tooltip
+ * (decision 12). Internal: shared between components, not exported (decision 9).
+ *
+ * The trigger carries a generated `anchor-name`; the popup names it in `position-anchor`
+ * and is placed by `position-area`, flipping across the axis it opens along when there is
+ * no room. All inline, so the browser keeps it attached with nothing measured.
+ */
+type AnchorSide = 'top' | 'bottom' | 'left' | 'right';
+type AnchorAlign = 'start' | 'center' | 'end';
+
+export type { AnchorSide as A, AnchorAlign as a };

package/dist/chunk-HCOCPQXS.js

@@ -0,0 +1,27 @@
+// src/core/anchoring.ts
+function anchorNameFor(id) {
+  return `--hl-anchor-${id.replace(/[^a-zA-Z0-9_-]/g, "")}`;
+}
+var POSITION_AREA = {
+  bottom: { start: "bottom span-right", center: "bottom", end: "bottom span-left" },
+  top: { start: "top span-right", center: "top", end: "top span-left" },
+  right: { start: "right span-bottom", center: "right", end: "right span-top" },
+  left: { start: "left span-bottom", center: "left", end: "left span-top" }
+};
+function anchoredPopupStyle(anchorName, side, align) {
+  return {
+    positionAnchor: anchorName,
+    positionArea: POSITION_AREA[side][align],
+    // Flip across the axis it opens on; the other axis is left alone.
+    positionTryFallbacks: side === "top" || side === "bottom" ? "flip-block" : "flip-inline"
+  };
+}
+function anchoredDataAttributes(side, align) {
+  return { "data-side": side, "data-align": align };
+}
+
+export {
+  anchorNameFor,
+  anchoredPopupStyle,
+  anchoredDataAttributes
+};

package/dist/popover/index.cjs

@@ -36,6 +36,28 @@ __export(index_parts_exports, {
 // src/popover/PopoverRoot.tsx
 var import_react3 = require("react");
 
+// src/core/anchoring.ts
+function anchorNameFor(id) {
+  return `--hl-anchor-${id.replace(/[^a-zA-Z0-9_-]/g, "")}`;
+}
+var POSITION_AREA = {
+  bottom: { start: "bottom span-right", center: "bottom", end: "bottom span-left" },
+  top: { start: "top span-right", center: "top", end: "top span-left" },
+  right: { start: "right span-bottom", center: "right", end: "right span-top" },
+  left: { start: "left span-bottom", center: "left", end: "left span-top" }
+};
+function anchoredPopupStyle(anchorName, side, align) {
+  return {
+    positionAnchor: anchorName,
+    positionArea: POSITION_AREA[side][align],
+    // Flip across the axis it opens on; the other axis is left alone.
+    positionTryFallbacks: side === "top" || side === "bottom" ? "flip-block" : "flip-inline"
+  };
+}
+function anchoredDataAttributes(side, align) {
+  return { "data-side": side, "data-align": align };
+}
+
 // src/core/useControlled.ts
 var import_react = require("react");
 function useControlled({
@@ -82,9 +104,6 @@ function usePopoverRootContext(part) {
 
 // src/popover/PopoverRoot.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
-function toAnchorName(id) {
-  return `--hl-anchor-${id.replace(/[^a-zA-Z0-9_-]/g, "")}`;
-}
 function PopoverRoot({
   open: openProp,
   defaultOpen,
@@ -108,7 +127,7 @@ function PopoverRoot({
   const id = (0, import_react3.useId)();
   const triggerRef = (0, import_react3.useRef)(null);
   const context = (0, import_react3.useMemo)(
-    () => ({ open, setOpen, popupId: id, anchorName: toAnchorName(id), triggerRef }),
+    () => ({ open, setOpen, popupId: id, anchorName: anchorNameFor(id), triggerRef }),
     [open, setOpen, id]
   );
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(PopoverRootContext.Provider, { value: context, children });
@@ -237,15 +256,6 @@ function PopoverTrigger({ className, children, render, ...rest }) {
 
 // src/popover/PopoverPopup.tsx
 var import_react5 = require("react");
-var POSITION_AREA = {
-  bottom: { start: "bottom span-right", center: "bottom", end: "bottom span-left" },
-  top: { start: "top span-right", center: "top", end: "top span-left" },
-  right: { start: "right span-bottom", center: "right", end: "right span-top" },
-  left: { start: "left span-bottom", center: "left", end: "left span-top" }
-};
-function tryFallbacks(side) {
-  return side === "top" || side === "bottom" ? "flip-block" : "flip-inline";
-}
 function PopoverPopup({
   side = "bottom",
   align = "center",
@@ -272,14 +282,9 @@ function PopoverPopup({
       id: popupId,
       popover: "auto",
       role: "dialog",
-      "data-side": side,
-      "data-align": align,
+      ...anchoredDataAttributes(side, align),
       ...popoverDataAttributes({ open }),
-      style: {
-        positionAnchor: anchorName,
-        positionArea: POSITION_AREA[side][align],
-        positionTryFallbacks: tryFallbacks(side)
-      },
+      style: anchoredPopupStyle(anchorName, side, align),
       className,
       children,
       ref: elementRef,

package/dist/popover/index.d.cts

@@ -1,5 +1,6 @@
 import * as react from 'react';
 import { ReactNode, ReactElement, Ref, ComponentPropsWithRef } from 'react';
+import { A as AnchorSide, a as AnchorAlign } from '../anchoring-Btxi0QwC.cjs';
 
 type PopoverRootProps = {
     /**
@@ -44,8 +45,8 @@ type PopoverTriggerProps = PopoverTriggerOwnProps & Omit<ComponentPropsWithRef<'
  */
 declare function PopoverTrigger({ className, children, render, ...rest }: PopoverTriggerProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
 
-type PopoverSide = 'top' | 'bottom' | 'left' | 'right';
-type PopoverAlign = 'start' | 'center' | 'end';
+type PopoverSide = AnchorSide;
+type PopoverAlign = AnchorAlign;
 type PopoverPopupOwnProps = {
     /** Which side of the trigger to open on. Flips to the opposite side when there is no room. */
     side?: PopoverSide;

package/dist/popover/index.d.ts

@@ -1,5 +1,6 @@
 import * as react from 'react';
 import { ReactNode, ReactElement, Ref, ComponentPropsWithRef } from 'react';
+import { A as AnchorSide, a as AnchorAlign } from '../anchoring-Btxi0QwC.js';
 
 type PopoverRootProps = {
     /**
@@ -44,8 +45,8 @@ type PopoverTriggerProps = PopoverTriggerOwnProps & Omit<ComponentPropsWithRef<'
  */
 declare function PopoverTrigger({ className, children, render, ...rest }: PopoverTriggerProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
 
-type PopoverSide = 'top' | 'bottom' | 'left' | 'right';
-type PopoverAlign = 'start' | 'center' | 'end';
+type PopoverSide = AnchorSide;
+type PopoverAlign = AnchorAlign;
 type PopoverPopupOwnProps = {
     /** Which side of the trigger to open on. Flips to the opposite side when there is no room. */
     side?: PopoverSide;

package/dist/popover/index.js

@@ -1,3 +1,8 @@
+import {
+  anchorNameFor,
+  anchoredDataAttributes,
+  anchoredPopupStyle
+} from "../chunk-HCOCPQXS.js";
 import {
   useControlled
 } from "../chunk-UEIB3I3T.js";
@@ -31,9 +36,6 @@ function usePopoverRootContext(part) {
 
 // src/popover/PopoverRoot.tsx
 import { jsx } from "react/jsx-runtime";
-function toAnchorName(id) {
-  return `--hl-anchor-${id.replace(/[^a-zA-Z0-9_-]/g, "")}`;
-}
 function PopoverRoot({
   open: openProp,
   defaultOpen,
@@ -57,7 +59,7 @@ function PopoverRoot({
   const id = useId();
   const triggerRef = useRef(null);
   const context = useMemo(
-    () => ({ open, setOpen, popupId: id, anchorName: toAnchorName(id), triggerRef }),
+    () => ({ open, setOpen, popupId: id, anchorName: anchorNameFor(id), triggerRef }),
     [open, setOpen, id]
   );
   return /* @__PURE__ */ jsx(PopoverRootContext.Provider, { value: context, children });
@@ -97,15 +99,6 @@ function PopoverTrigger({ className, children, render, ...rest }) {
 
 // src/popover/PopoverPopup.tsx
 import { useEffect, useReducer, useRef as useRef2 } from "react";
-var POSITION_AREA = {
-  bottom: { start: "bottom span-right", center: "bottom", end: "bottom span-left" },
-  top: { start: "top span-right", center: "top", end: "top span-left" },
-  right: { start: "right span-bottom", center: "right", end: "right span-top" },
-  left: { start: "left span-bottom", center: "left", end: "left span-top" }
-};
-function tryFallbacks(side) {
-  return side === "top" || side === "bottom" ? "flip-block" : "flip-inline";
-}
 function PopoverPopup({
   side = "bottom",
   align = "center",
@@ -132,14 +125,9 @@ function PopoverPopup({
       id: popupId,
       popover: "auto",
       role: "dialog",
-      "data-side": side,
-      "data-align": align,
+      ...anchoredDataAttributes(side, align),
       ...popoverDataAttributes({ open }),
-      style: {
-        positionAnchor: anchorName,
-        positionArea: POSITION_AREA[side][align],
-        positionTryFallbacks: tryFallbacks(side)
-      },
+      style: anchoredPopupStyle(anchorName, side, align),
       className,
       children,
       ref: elementRef,

package/dist/tooltip/index.cjs

@@ -0,0 +1,364 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/tooltip/index.ts
+var tooltip_exports = {};
+__export(tooltip_exports, {
+  Tooltip: () => index_parts_exports
+});
+module.exports = __toCommonJS(tooltip_exports);
+
+// src/tooltip/index.parts.ts
+var index_parts_exports = {};
+__export(index_parts_exports, {
+  Popup: () => TooltipPopup,
+  Root: () => TooltipRoot,
+  Trigger: () => TooltipTrigger
+});
+
+// src/tooltip/TooltipRoot.tsx
+var import_react3 = require("react");
+
+// src/core/anchoring.ts
+function anchorNameFor(id) {
+  return `--hl-anchor-${id.replace(/[^a-zA-Z0-9_-]/g, "")}`;
+}
+var POSITION_AREA = {
+  bottom: { start: "bottom span-right", center: "bottom", end: "bottom span-left" },
+  top: { start: "top span-right", center: "top", end: "top span-left" },
+  right: { start: "right span-bottom", center: "right", end: "right span-top" },
+  left: { start: "left span-bottom", center: "left", end: "left span-top" }
+};
+function anchoredPopupStyle(anchorName, side, align) {
+  return {
+    positionAnchor: anchorName,
+    positionArea: POSITION_AREA[side][align],
+    // Flip across the axis it opens on; the other axis is left alone.
+    positionTryFallbacks: side === "top" || side === "bottom" ? "flip-block" : "flip-inline"
+  };
+}
+function anchoredDataAttributes(side, align) {
+  return { "data-side": side, "data-align": align };
+}
+
+// src/core/useControlled.ts
+var import_react = require("react");
+function useControlled({
+  controlled,
+  default: defaultValue,
+  name = "Component",
+  state = "value"
+}) {
+  const { current: isControlled } = (0, import_react.useRef)(controlled !== void 0);
+  const [uncontrolled, setUncontrolled] = (0, import_react.useState)(defaultValue);
+  const defaultRef = (0, import_react.useRef)(defaultValue);
+  const value = isControlled ? controlled : uncontrolled;
+  if (process.env.NODE_ENV !== "production") {
+    if (isControlled !== (controlled !== void 0)) {
+      console.error(
+        `${name}: cannot switch between controlled and uncontrolled \`${state}\`. Decide which one this component is for the whole of its life.`
+      );
+    }
+    if (!isControlled && defaultRef.current !== defaultValue) {
+      console.error(
+        `${name}: cannot change the default \`${state}\` after mount. It is only read once, so later changes are silently ignored.`
+      );
+    }
+  }
+  const setValue = (0, import_react.useCallback)(
+    (next) => {
+      if (!isControlled) setUncontrolled(next);
+    },
+    [isControlled]
+  );
+  return [value, setValue];
+}
+
+// src/tooltip/TooltipRootContext.ts
+var import_react2 = require("react");
+var TooltipRootContext = (0, import_react2.createContext)(null);
+function useTooltipRootContext(part) {
+  const context = (0, import_react2.useContext)(TooltipRootContext);
+  if (context === null) {
+    throw new Error(`<Tooltip.${part}> must be rendered inside <Tooltip.Root>.`);
+  }
+  return context;
+}
+
+// src/tooltip/TooltipRoot.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var WARM_WINDOW = 300;
+var openCount = 0;
+var lastClosedAt = Number.NEGATIVE_INFINITY;
+function isWarm() {
+  return openCount > 0 || Date.now() - lastClosedAt < WARM_WINDOW;
+}
+function TooltipRoot({
+  open: openProp,
+  defaultOpen,
+  onOpenChange,
+  delay = 600,
+  closeDelay = 100,
+  children
+}) {
+  const [open, setOpenState] = useControlled({
+    controlled: openProp,
+    default: defaultOpen ?? false,
+    name: "Tooltip.Root",
+    state: "open"
+  });
+  const timer = (0, import_react3.useRef)(void 0);
+  const cancelPending = (0, import_react3.useCallback)(() => {
+    clearTimeout(timer.current);
+    timer.current = void 0;
+  }, []);
+  const setOpen = (0, import_react3.useCallback)(
+    (next) => {
+      cancelPending();
+      if (next === open) return;
+      setOpenState(next);
+      onOpenChange?.(next);
+    },
+    [open, setOpenState, onOpenChange, cancelPending]
+  );
+  const openAfterDelay = (0, import_react3.useCallback)(() => {
+    cancelPending();
+    if (open) return;
+    if (isWarm()) setOpen(true);
+    else timer.current = setTimeout(() => setOpen(true), delay);
+  }, [open, delay, setOpen, cancelPending]);
+  const closeAfterGrace = (0, import_react3.useCallback)(() => {
+    cancelPending();
+    if (!open) return;
+    timer.current = setTimeout(() => setOpen(false), closeDelay);
+  }, [open, closeDelay, setOpen, cancelPending]);
+  (0, import_react3.useEffect)(() => cancelPending, [cancelPending]);
+  (0, import_react3.useEffect)(() => {
+    if (!open) return;
+    openCount += 1;
+    return () => {
+      openCount -= 1;
+      lastClosedAt = Date.now();
+    };
+  }, [open]);
+  const id = (0, import_react3.useId)();
+  const context = (0, import_react3.useMemo)(
+    () => ({
+      open,
+      setOpen,
+      openAfterDelay,
+      closeAfterGrace,
+      cancelPending,
+      popupId: id,
+      anchorName: anchorNameFor(id)
+    }),
+    [open, setOpen, openAfterDelay, closeAfterGrace, cancelPending, id]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(TooltipRootContext.Provider, { value: context, children });
+}
+
+// src/core/useRender.ts
+var import_react4 = require("react");
+
+// src/core/mergeProps.ts
+function isEventHandler(key) {
+  return key.length > 2 && key.startsWith("on") && key[2] === key[2]?.toUpperCase();
+}
+function mergeRefs(...refs) {
+  return (node) => {
+    const cleanups = refs.map((ref) => {
+      if (typeof ref === "function") {
+        const result = ref(node);
+        return typeof result === "function" ? result : () => ref(null);
+      }
+      if (ref && typeof ref === "object") {
+        ref.current = node;
+        return () => {
+          ref.current = null;
+        };
+      }
+      return void 0;
+    });
+    return () => {
+      cleanups.forEach((cleanup) => {
+        if (typeof cleanup === "function") cleanup();
+      });
+    };
+  };
+}
+function isSyntheticEvent(event) {
+  return typeof event === "object" && event !== null && "nativeEvent" in event;
+}
+function makeEventPreventable(event) {
+  if (Object.prototype.hasOwnProperty.call(event, "preventComponentHandler")) return;
+  const target = event;
+  target.preventComponentHandler = () => {
+    target.componentHandlerPrevented = true;
+  };
+}
+function isComponentHandlerPrevented(event) {
+  return typeof event === "object" && event !== null && event.componentHandlerPrevented === true;
+}
+function chainHandlers(earlier, value) {
+  return (...args) => {
+    const event = args[0];
+    if (isSyntheticEvent(event)) makeEventPreventable(event);
+    value(...args);
+    if (isComponentHandlerPrevented(event)) return;
+    earlier(...args);
+  };
+}
+function mergeProps(...objects) {
+  const merged = {};
+  for (const props of objects) {
+    if (!props) continue;
+    for (const key of Object.keys(props)) {
+      const value = props[key];
+      if (value === void 0) continue;
+      if (isEventHandler(key) && typeof value === "function") {
+        const earlier = merged[key];
+        merged[key] = typeof earlier === "function" ? chainHandlers(earlier, value) : value;
+      } else if (key === "className") {
+        merged.className = merged.className ? `${String(merged.className)} ${String(value)}` : value;
+      } else if (key === "style") {
+        merged.style = { ...merged.style, ...value };
+      } else if (key === "ref") {
+        merged.ref = merged.ref ? mergeRefs(merged.ref, value) : value;
+      } else {
+        merged[key] = value;
+      }
+    }
+  }
+  return merged;
+}
+
+// src/core/useRender.ts
+function useRender({
+  render,
+  defaultTagName,
+  props,
+  consumerProps
+}) {
+  const merged = mergeProps(props, consumerProps);
+  if ((0, import_react4.isValidElement)(render)) {
+    return (0, import_react4.cloneElement)(render, mergeProps(merged, render.props));
+  }
+  return (0, import_react4.createElement)(defaultTagName, merged);
+}
+
+// src/tooltip/tooltipDataAttributes.ts
+function tooltipDataAttributes({ open }) {
+  return {
+    "data-open": open ? "" : void 0,
+    "data-closed": open ? void 0 : ""
+  };
+}
+
+// src/tooltip/TooltipTrigger.tsx
+function TooltipTrigger({
+  className,
+  children,
+  render,
+  "aria-describedby": describedBy,
+  ...rest
+}) {
+  const { open, setOpen, openAfterDelay, closeAfterGrace, popupId, anchorName } = useTooltipRootContext("Trigger");
+  return useRender({
+    render,
+    defaultTagName: "button",
+    props: {
+      type: "button",
+      "aria-describedby": describedBy ? `${describedBy} ${popupId}` : popupId,
+      ...tooltipDataAttributes({ open }),
+      style: { anchorName },
+      className,
+      children,
+      onPointerEnter(event) {
+        if (event.pointerType !== "touch") openAfterDelay();
+      },
+      onPointerLeave(event) {
+        if (event.pointerType !== "touch") closeAfterGrace();
+      },
+      onPointerDown() {
+        setOpen(false);
+      },
+      onFocus(event) {
+        if (event.currentTarget.matches(":focus-visible")) setOpen(true);
+      },
+      onBlur() {
+        setOpen(false);
+      }
+    },
+    consumerProps: rest
+  });
+}
+
+// src/tooltip/TooltipPopup.tsx
+var import_react5 = require("react");
+function TooltipPopup({
+  side = "top",
+  align = "center",
+  className,
+  children,
+  render,
+  ...rest
+}) {
+  const { open, setOpen, cancelPending, closeAfterGrace, popupId, anchorName } = useTooltipRootContext("Popup");
+  const elementRef = (0, import_react5.useRef)(null);
+  (0, import_react5.useEffect)(() => {
+    const popup = elementRef.current;
+    if (!popup || typeof popup.showPopover !== "function") return;
+    const shown = popup.matches(":popover-open");
+    if (open && !shown) popup.showPopover();
+    else if (!open && shown) popup.hidePopover();
+  });
+  (0, import_react5.useEffect)(() => {
+    if (!open) return;
+    function onKeyDown(event) {
+      if (event.key !== "Escape") return;
+      event.preventDefault();
+      event.stopPropagation();
+      setOpen(false);
+    }
+    document.addEventListener("keydown", onKeyDown, true);
+    return () => document.removeEventListener("keydown", onKeyDown, true);
+  }, [open, setOpen]);
+  return useRender({
+    render,
+    defaultTagName: "div",
+    props: {
+      id: popupId,
+      popover: "manual",
+      role: "tooltip",
+      ...anchoredDataAttributes(side, align),
+      ...tooltipDataAttributes({ open }),
+      style: anchoredPopupStyle(anchorName, side, align),
+      className,
+      children,
+      ref: elementRef,
+      onPointerEnter: cancelPending,
+      onPointerLeave: closeAfterGrace
+    },
+    consumerProps: rest
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Tooltip
+});

package/dist/tooltip/index.d.cts

@@ -0,0 +1,92 @@
+import * as react from 'react';
+import { ReactNode, ReactElement, Ref, ComponentPropsWithRef } from 'react';
+import { A as AnchorSide, a as AnchorAlign } from '../anchoring-Btxi0QwC.cjs';
+
+type TooltipRootProps = {
+    /**
+     * Controlled state. Provide `onOpenChange` alongside it.
+     *
+     * Never `undefined` once mounted: the mode is latched at mount, as for Switch.
+     */
+    open?: boolean;
+    /** Initial state when uncontrolled. Read once, at mount. */
+    defaultOpen?: boolean;
+    /** Called on every open and close, after any delay has run. */
+    onOpenChange?: (open: boolean) => void;
+    /** Milliseconds a pointer rests on the trigger before it opens. Focus opens at once. */
+    delay?: number;
+    /**
+     * Milliseconds between the pointer leaving and the tooltip closing — time to move onto
+     * the tooltip, which then stays open while hovered (WCAG 1.4.13).
+     */
+    closeDelay?: number;
+    children?: ReactNode;
+};
+/**
+ * Holds a tooltip's state and timers, and shares them with its parts. Renders no element.
+ *
+ * The popup is a native `popover="manual"`, anchored like Popover (decision 12). `hint`
+ * would be the natural fit, but Safari lacks it; `manual` behaves the same everywhere and,
+ * like `hint`, does not close an open Popover when it shows. What `manual` leaves out —
+ * opening on hover and focus, closing on leave, blur and Esc — is the timing below.
+ */
+declare function TooltipRoot({ open: openProp, defaultOpen, onOpenChange, delay, closeDelay, children, }: TooltipRootProps): react.JSX.Element;
+
+type TooltipTriggerOwnProps = {
+    /** Element to render instead of the default `<button>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type TooltipTriggerProps = TooltipTriggerOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof TooltipTriggerOwnProps>;
+/**
+ * The element the tooltip describes and is anchored to. A native `<button>` by default;
+ * render another focusable element when the tooltip belongs to one — a Popover.Trigger,
+ * say, or a link.
+ *
+ * - A mouse or pen resting on it opens the tooltip after the Root's `delay`; leaving
+ *   closes it after `closeDelay`. Touch never opens it: there is no hover to end it.
+ * - Keyboard focus opens it at once; blur closes it. Focus from a click does not open it —
+ *   only `:focus-visible` does.
+ * - Pressing it closes the tooltip, since the press is what the user came to do.
+ *
+ * `aria-describedby` points at the tooltip at all times — the description is read from the
+ * hidden element too — and is joined with any of yours.
+ */
+declare function TooltipTrigger({ className, children, render, 'aria-describedby': describedBy, ...rest }: TooltipTriggerProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type TooltipSide = AnchorSide;
+type TooltipAlign = AnchorAlign;
+type TooltipPopupOwnProps = {
+    /** Which side of the trigger to show on. Flips to the opposite side when there is no room. */
+    side?: TooltipSide;
+    /** Where along that side: flush with the trigger's start or end edge, or centred on it. */
+    align?: TooltipAlign;
+    /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type TooltipPopupProps = TooltipPopupOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof TooltipPopupOwnProps | 'popover'>;
+/**
+ * The tooltip: a native `popover="manual"` with `role="tooltip"`, anchored to the trigger
+ * as Popover is (decision 12). State drives the element, never the reverse.
+ *
+ * It stays open while the pointer is on it, so its text can be read and selected, and
+ * closes on Esc — which closes only the tooltip, not a Dialog or Popover beneath it.
+ *
+ * Text only, by the ARIA pattern: it describes the trigger and is never focused, so it must
+ * not hold anything interactive. Use a Popover for that.
+ */
+declare function TooltipPopup({ side, align, className, children, render, ...rest }: TooltipPopupProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+declare namespace index_parts {
+  export { TooltipPopup as Popup, TooltipRoot as Root, TooltipTrigger as Trigger };
+}
+
+/** The state Tooltip.Root shares with its parts, and projects as `data-*` attributes. */
+type TooltipState = {
+    open: boolean;
+};
+
+export { index_parts as Tooltip, type TooltipAlign, type TooltipPopupProps, type TooltipRootProps, type TooltipSide, type TooltipState, type TooltipTriggerProps };

package/dist/tooltip/index.d.ts

@@ -0,0 +1,92 @@
+import * as react from 'react';
+import { ReactNode, ReactElement, Ref, ComponentPropsWithRef } from 'react';
+import { A as AnchorSide, a as AnchorAlign } from '../anchoring-Btxi0QwC.js';
+
+type TooltipRootProps = {
+    /**
+     * Controlled state. Provide `onOpenChange` alongside it.
+     *
+     * Never `undefined` once mounted: the mode is latched at mount, as for Switch.
+     */
+    open?: boolean;
+    /** Initial state when uncontrolled. Read once, at mount. */
+    defaultOpen?: boolean;
+    /** Called on every open and close, after any delay has run. */
+    onOpenChange?: (open: boolean) => void;
+    /** Milliseconds a pointer rests on the trigger before it opens. Focus opens at once. */
+    delay?: number;
+    /**
+     * Milliseconds between the pointer leaving and the tooltip closing — time to move onto
+     * the tooltip, which then stays open while hovered (WCAG 1.4.13).
+     */
+    closeDelay?: number;
+    children?: ReactNode;
+};
+/**
+ * Holds a tooltip's state and timers, and shares them with its parts. Renders no element.
+ *
+ * The popup is a native `popover="manual"`, anchored like Popover (decision 12). `hint`
+ * would be the natural fit, but Safari lacks it; `manual` behaves the same everywhere and,
+ * like `hint`, does not close an open Popover when it shows. What `manual` leaves out —
+ * opening on hover and focus, closing on leave, blur and Esc — is the timing below.
+ */
+declare function TooltipRoot({ open: openProp, defaultOpen, onOpenChange, delay, closeDelay, children, }: TooltipRootProps): react.JSX.Element;
+
+type TooltipTriggerOwnProps = {
+    /** Element to render instead of the default `<button>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type TooltipTriggerProps = TooltipTriggerOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof TooltipTriggerOwnProps>;
+/**
+ * The element the tooltip describes and is anchored to. A native `<button>` by default;
+ * render another focusable element when the tooltip belongs to one — a Popover.Trigger,
+ * say, or a link.
+ *
+ * - A mouse or pen resting on it opens the tooltip after the Root's `delay`; leaving
+ *   closes it after `closeDelay`. Touch never opens it: there is no hover to end it.
+ * - Keyboard focus opens it at once; blur closes it. Focus from a click does not open it —
+ *   only `:focus-visible` does.
+ * - Pressing it closes the tooltip, since the press is what the user came to do.
+ *
+ * `aria-describedby` points at the tooltip at all times — the description is read from the
+ * hidden element too — and is joined with any of yours.
+ */
+declare function TooltipTrigger({ className, children, render, 'aria-describedby': describedBy, ...rest }: TooltipTriggerProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type TooltipSide = AnchorSide;
+type TooltipAlign = AnchorAlign;
+type TooltipPopupOwnProps = {
+    /** Which side of the trigger to show on. Flips to the opposite side when there is no room. */
+    side?: TooltipSide;
+    /** Where along that side: flush with the trigger's start or end edge, or centred on it. */
+    align?: TooltipAlign;
+    /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type TooltipPopupProps = TooltipPopupOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof TooltipPopupOwnProps | 'popover'>;
+/**
+ * The tooltip: a native `popover="manual"` with `role="tooltip"`, anchored to the trigger
+ * as Popover is (decision 12). State drives the element, never the reverse.
+ *
+ * It stays open while the pointer is on it, so its text can be read and selected, and
+ * closes on Esc — which closes only the tooltip, not a Dialog or Popover beneath it.
+ *
+ * Text only, by the ARIA pattern: it describes the trigger and is never focused, so it must
+ * not hold anything interactive. Use a Popover for that.
+ */
+declare function TooltipPopup({ side, align, className, children, render, ...rest }: TooltipPopupProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+declare namespace index_parts {
+  export { TooltipPopup as Popup, TooltipRoot as Root, TooltipTrigger as Trigger };
+}
+
+/** The state Tooltip.Root shares with its parts, and projects as `data-*` attributes. */
+type TooltipState = {
+    open: boolean;
+};
+
+export { index_parts as Tooltip, type TooltipAlign, type TooltipPopupProps, type TooltipRootProps, type TooltipSide, type TooltipState, type TooltipTriggerProps };

package/dist/tooltip/index.js

@@ -0,0 +1,206 @@
+import {
+  anchorNameFor,
+  anchoredDataAttributes,
+  anchoredPopupStyle
+} from "../chunk-HCOCPQXS.js";
+import {
+  useControlled
+} from "../chunk-UEIB3I3T.js";
+import {
+  __export,
+  useRender
+} from "../chunk-OQTWWZ4B.js";
+
+// src/tooltip/index.parts.ts
+var index_parts_exports = {};
+__export(index_parts_exports, {
+  Popup: () => TooltipPopup,
+  Root: () => TooltipRoot,
+  Trigger: () => TooltipTrigger
+});
+
+// src/tooltip/TooltipRoot.tsx
+import { useCallback, useEffect, useId, useMemo, useRef } from "react";
+
+// src/tooltip/TooltipRootContext.ts
+import { createContext, useContext } from "react";
+var TooltipRootContext = createContext(null);
+function useTooltipRootContext(part) {
+  const context = useContext(TooltipRootContext);
+  if (context === null) {
+    throw new Error(`<Tooltip.${part}> must be rendered inside <Tooltip.Root>.`);
+  }
+  return context;
+}
+
+// src/tooltip/TooltipRoot.tsx
+import { jsx } from "react/jsx-runtime";
+var WARM_WINDOW = 300;
+var openCount = 0;
+var lastClosedAt = Number.NEGATIVE_INFINITY;
+function isWarm() {
+  return openCount > 0 || Date.now() - lastClosedAt < WARM_WINDOW;
+}
+function TooltipRoot({
+  open: openProp,
+  defaultOpen,
+  onOpenChange,
+  delay = 600,
+  closeDelay = 100,
+  children
+}) {
+  const [open, setOpenState] = useControlled({
+    controlled: openProp,
+    default: defaultOpen ?? false,
+    name: "Tooltip.Root",
+    state: "open"
+  });
+  const timer = useRef(void 0);
+  const cancelPending = useCallback(() => {
+    clearTimeout(timer.current);
+    timer.current = void 0;
+  }, []);
+  const setOpen = useCallback(
+    (next) => {
+      cancelPending();
+      if (next === open) return;
+      setOpenState(next);
+      onOpenChange?.(next);
+    },
+    [open, setOpenState, onOpenChange, cancelPending]
+  );
+  const openAfterDelay = useCallback(() => {
+    cancelPending();
+    if (open) return;
+    if (isWarm()) setOpen(true);
+    else timer.current = setTimeout(() => setOpen(true), delay);
+  }, [open, delay, setOpen, cancelPending]);
+  const closeAfterGrace = useCallback(() => {
+    cancelPending();
+    if (!open) return;
+    timer.current = setTimeout(() => setOpen(false), closeDelay);
+  }, [open, closeDelay, setOpen, cancelPending]);
+  useEffect(() => cancelPending, [cancelPending]);
+  useEffect(() => {
+    if (!open) return;
+    openCount += 1;
+    return () => {
+      openCount -= 1;
+      lastClosedAt = Date.now();
+    };
+  }, [open]);
+  const id = useId();
+  const context = useMemo(
+    () => ({
+      open,
+      setOpen,
+      openAfterDelay,
+      closeAfterGrace,
+      cancelPending,
+      popupId: id,
+      anchorName: anchorNameFor(id)
+    }),
+    [open, setOpen, openAfterDelay, closeAfterGrace, cancelPending, id]
+  );
+  return /* @__PURE__ */ jsx(TooltipRootContext.Provider, { value: context, children });
+}
+
+// src/tooltip/tooltipDataAttributes.ts
+function tooltipDataAttributes({ open }) {
+  return {
+    "data-open": open ? "" : void 0,
+    "data-closed": open ? void 0 : ""
+  };
+}
+
+// src/tooltip/TooltipTrigger.tsx
+function TooltipTrigger({
+  className,
+  children,
+  render,
+  "aria-describedby": describedBy,
+  ...rest
+}) {
+  const { open, setOpen, openAfterDelay, closeAfterGrace, popupId, anchorName } = useTooltipRootContext("Trigger");
+  return useRender({
+    render,
+    defaultTagName: "button",
+    props: {
+      type: "button",
+      "aria-describedby": describedBy ? `${describedBy} ${popupId}` : popupId,
+      ...tooltipDataAttributes({ open }),
+      style: { anchorName },
+      className,
+      children,
+      onPointerEnter(event) {
+        if (event.pointerType !== "touch") openAfterDelay();
+      },
+      onPointerLeave(event) {
+        if (event.pointerType !== "touch") closeAfterGrace();
+      },
+      onPointerDown() {
+        setOpen(false);
+      },
+      onFocus(event) {
+        if (event.currentTarget.matches(":focus-visible")) setOpen(true);
+      },
+      onBlur() {
+        setOpen(false);
+      }
+    },
+    consumerProps: rest
+  });
+}
+
+// src/tooltip/TooltipPopup.tsx
+import { useEffect as useEffect2, useRef as useRef2 } from "react";
+function TooltipPopup({
+  side = "top",
+  align = "center",
+  className,
+  children,
+  render,
+  ...rest
+}) {
+  const { open, setOpen, cancelPending, closeAfterGrace, popupId, anchorName } = useTooltipRootContext("Popup");
+  const elementRef = useRef2(null);
+  useEffect2(() => {
+    const popup = elementRef.current;
+    if (!popup || typeof popup.showPopover !== "function") return;
+    const shown = popup.matches(":popover-open");
+    if (open && !shown) popup.showPopover();
+    else if (!open && shown) popup.hidePopover();
+  });
+  useEffect2(() => {
+    if (!open) return;
+    function onKeyDown(event) {
+      if (event.key !== "Escape") return;
+      event.preventDefault();
+      event.stopPropagation();
+      setOpen(false);
+    }
+    document.addEventListener("keydown", onKeyDown, true);
+    return () => document.removeEventListener("keydown", onKeyDown, true);
+  }, [open, setOpen]);
+  return useRender({
+    render,
+    defaultTagName: "div",
+    props: {
+      id: popupId,
+      popover: "manual",
+      role: "tooltip",
+      ...anchoredDataAttributes(side, align),
+      ...tooltipDataAttributes({ open }),
+      style: anchoredPopupStyle(anchorName, side, align),
+      className,
+      children,
+      ref: elementRef,
+      onPointerEnter: cancelPending,
+      onPointerLeave: closeAfterGrace
+    },
+    consumerProps: rest
+  });
+}
+export {
+  index_parts_exports as Tooltip
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arun-dev/headless",
-  "version": "4.4.0",
+  "version": "4.5.0",
   "description": "Unstyled React behaviour primitives — render engine, controlled/uncontrolled state, and data-* state projection. Ships no CSS and no class names.",
   "license": "MIT",
   "type": "module",
@@ -93,6 +93,16 @@
         "types": "./dist/switch/index.d.cts",
         "default": "./dist/switch/index.cjs"
       }
+    },
+    "./tooltip": {
+      "import": {
+        "types": "./dist/tooltip/index.d.ts",
+        "default": "./dist/tooltip/index.js"
+      },
+      "require": {
+        "types": "./dist/tooltip/index.d.cts",
+        "default": "./dist/tooltip/index.cjs"
+      }
     }
   },
   "publishConfig": {