@arun-dev/headless 4.3.0 → 4.5.0

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.3.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",
@@ -64,6 +64,16 @@
         "default": "./dist/dialog/index.cjs"
       }
     },
+    "./popover": {
+      "import": {
+        "types": "./dist/popover/index.d.ts",
+        "default": "./dist/popover/index.js"
+      },
+      "require": {
+        "types": "./dist/popover/index.d.cts",
+        "default": "./dist/popover/index.cjs"
+      }
+    },
     "./radio-group": {
       "import": {
         "types": "./dist/radio-group/index.d.ts",
@@ -83,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": {
@@ -105,7 +125,7 @@
     "@types/react-dom": "19.2.5",
     "@vitest/browser-playwright": "4.1.11",
     "eslint": "9.39.4",
-    "jsdom": "27.0.0",
+    "jsdom": "30.0.1",
     "playwright": "1.63.0",
     "react": "19.2.8",
     "react-dom": "19.2.8",