@arun-dev/headless 4.2.0 → 4.4.0

package/dist/popover/index.d.ts

@@ -0,0 +1,98 @@
+import * as react from 'react';
+import { ReactNode, ReactElement, Ref, ComponentPropsWithRef } from 'react';
+
+type PopoverRootProps = {
+    /**
+     * 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 request to open or close — Trigger, Close, Esc, or a click outside.
+     * A controlled popover moves only if the parent accepts it.
+     */
+    onOpenChange?: (open: boolean) => void;
+    children?: ReactNode;
+};
+/**
+ * Holds a popover's state and shares it with its parts. Renders no element of its own.
+ *
+ * The popup is a native `popover`, placed by CSS anchor positioning (decision 12): the
+ * platform supplies the top layer, light dismiss, Esc, the Tab order from the trigger and
+ * focus return; the browser keeps it attached. This component adds state, one setter every
+ * close goes through, and the anchor wiring.
+ */
+declare function PopoverRoot({ open: openProp, defaultOpen, onOpenChange, children, }: PopoverRootProps): react.JSX.Element;
+
+type PopoverTriggerOwnProps = {
+    /** 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 PopoverTriggerProps = PopoverTriggerOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof PopoverTriggerOwnProps>;
+/**
+ * Opens and closes the popover, and is what it is anchored to: it carries the
+ * `anchor-name` the popup positions against. A native `<button>`, so focus and activation
+ * are the platform's.
+ *
+ * It becomes the popup's invoker when it opens, so a click on it while open is not a
+ * click outside — it toggles the popover closed rather than light-dismissing and reopening.
+ */
+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 PopoverPopupOwnProps = {
+    /** Which side of the trigger to open on. Flips to the opposite side when there is no room. */
+    side?: PopoverSide;
+    /** Where along that side: flush with the trigger's start or end edge, or centred on it. */
+    align?: PopoverAlign;
+    /** 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 PopoverPopupProps = PopoverPopupOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof PopoverPopupOwnProps | 'popover'>;
+/**
+ * The popup: a native `popover="auto"`, shown with `showPopover({ source })` whenever the
+ * Root is open and hidden when it is not. State drives the element, never the reverse.
+ *
+ * Placement is CSS anchor positioning, set inline: `position-anchor` names the trigger,
+ * `position-area` comes from `side` and `align`, and `position-try-fallbacks` flips it
+ * when there is no room (decision 12). `data-side` and `data-align` repeat the request —
+ * not where a fallback moved it, which script cannot observe.
+ *
+ * Light dismiss and Esc close the element before anyone is asked; the `toggle` event
+ * reports it through the Root, and the element reopens if the state stays open.
+ *
+ * `role="dialog"`, non-modal. Name it with `aria-label` or `aria-labelledby`.
+ */
+declare function PopoverPopup({ side, align, className, children, render, ...rest }: PopoverPopupProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type PopoverCloseOwnProps = {
+    /** 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 PopoverCloseProps = PopoverCloseOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof PopoverCloseOwnProps>;
+/**
+ * Closes the popover. Esc and a click outside already do; this is the visible way, for
+ * pointer users and for screen reader users who would not guess either.
+ */
+declare function PopoverClose({ className, children, render, ...rest }: PopoverCloseProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+declare namespace index_parts {
+  export { PopoverClose as Close, PopoverPopup as Popup, PopoverRoot as Root, PopoverTrigger as Trigger };
+}
+
+/** The state Popover.Root shares with its parts, and projects as `data-*` attributes. */
+type PopoverState = {
+    open: boolean;
+};
+
+export { index_parts as Popover, type PopoverAlign, type PopoverCloseProps, type PopoverPopupProps, type PopoverRootProps, type PopoverSide, type PopoverState, type PopoverTriggerProps };

package/dist/popover/index.js

@@ -0,0 +1,176 @@
+import {
+  useControlled
+} from "../chunk-UEIB3I3T.js";
+import {
+  __export,
+  useRender
+} from "../chunk-OQTWWZ4B.js";
+
+// src/popover/index.parts.ts
+var index_parts_exports = {};
+__export(index_parts_exports, {
+  Close: () => PopoverClose,
+  Popup: () => PopoverPopup,
+  Root: () => PopoverRoot,
+  Trigger: () => PopoverTrigger
+});
+
+// src/popover/PopoverRoot.tsx
+import { useCallback, useId, useMemo, useRef } from "react";
+
+// src/popover/PopoverRootContext.ts
+import { createContext, useContext } from "react";
+var PopoverRootContext = createContext(null);
+function usePopoverRootContext(part) {
+  const context = useContext(PopoverRootContext);
+  if (context === null) {
+    throw new Error(`<Popover.${part}> must be rendered inside <Popover.Root>.`);
+  }
+  return context;
+}
+
+// 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,
+  onOpenChange,
+  children
+}) {
+  const [open, setOpenState] = useControlled({
+    controlled: openProp,
+    default: defaultOpen ?? false,
+    name: "Popover.Root",
+    state: "open"
+  });
+  const setOpen = useCallback(
+    (next) => {
+      if (next === open) return;
+      setOpenState(next);
+      onOpenChange?.(next);
+    },
+    [open, setOpenState, onOpenChange]
+  );
+  const id = useId();
+  const triggerRef = useRef(null);
+  const context = useMemo(
+    () => ({ open, setOpen, popupId: id, anchorName: toAnchorName(id), triggerRef }),
+    [open, setOpen, id]
+  );
+  return /* @__PURE__ */ jsx(PopoverRootContext.Provider, { value: context, children });
+}
+
+// src/popover/popoverDataAttributes.ts
+function popoverDataAttributes({ open }) {
+  return {
+    "data-open": open ? "" : void 0,
+    "data-closed": open ? void 0 : ""
+  };
+}
+
+// src/popover/PopoverTrigger.tsx
+function PopoverTrigger({ className, children, render, ...rest }) {
+  const { open, setOpen, popupId, anchorName, triggerRef } = usePopoverRootContext("Trigger");
+  return useRender({
+    render,
+    defaultTagName: "button",
+    props: {
+      type: "button",
+      "aria-haspopup": "dialog",
+      "aria-expanded": open,
+      "aria-controls": popupId,
+      ...popoverDataAttributes({ open }),
+      style: { anchorName },
+      className,
+      children,
+      ref: triggerRef,
+      onClick() {
+        setOpen(!open);
+      }
+    },
+    consumerProps: 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",
+  className,
+  children,
+  render,
+  ...rest
+}) {
+  const { open, setOpen, popupId, anchorName, triggerRef } = usePopoverRootContext("Popup");
+  const elementRef = useRef2(null);
+  const [, resync] = useReducer((n) => n + 1, 0);
+  useEffect(() => {
+    const popup = elementRef.current;
+    if (!popup || typeof popup.showPopover !== "function") return;
+    const shown = popup.matches(":popover-open");
+    if (open && !shown) {
+      popup.showPopover({ source: triggerRef.current ?? void 0 });
+    } else if (!open && shown) popup.hidePopover();
+  });
+  return useRender({
+    render,
+    defaultTagName: "div",
+    props: {
+      id: popupId,
+      popover: "auto",
+      role: "dialog",
+      "data-side": side,
+      "data-align": align,
+      ...popoverDataAttributes({ open }),
+      style: {
+        positionAnchor: anchorName,
+        positionArea: POSITION_AREA[side][align],
+        positionTryFallbacks: tryFallbacks(side)
+      },
+      className,
+      children,
+      ref: elementRef,
+      onToggle(event) {
+        if (event.target !== event.currentTarget) return;
+        if (event.nativeEvent.newState !== "closed") return;
+        setOpen(false);
+        resync();
+      }
+    },
+    consumerProps: rest
+  });
+}
+
+// src/popover/PopoverClose.tsx
+function PopoverClose({ className, children, render, ...rest }) {
+  const { setOpen } = usePopoverRootContext("Close");
+  return useRender({
+    render,
+    defaultTagName: "button",
+    props: {
+      type: "button",
+      className,
+      children,
+      onClick() {
+        setOpen(false);
+      }
+    },
+    consumerProps: rest
+  });
+}
+export {
+  index_parts_exports as Popover
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arun-dev/headless",
-  "version": "4.2.0",
+  "version": "4.4.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",
@@ -54,6 +54,26 @@
         "default": "./dist/checkbox/index.cjs"
       }
     },
+    "./dialog": {
+      "import": {
+        "types": "./dist/dialog/index.d.ts",
+        "default": "./dist/dialog/index.js"
+      },
+      "require": {
+        "types": "./dist/dialog/index.d.cts",
+        "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",
@@ -93,8 +113,10 @@
     "@testing-library/react": "16.3.0",
     "@types/react": "19.2.18",
     "@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",
     "tsup": "8.5.1",
@@ -109,6 +131,7 @@
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "test": "pnpm run test:unit",
-    "test:unit": "vitest run --passWithNoTests --config vitest.unit.config.ts"
+    "test:unit": "vitest run --passWithNoTests --config vitest.unit.config.ts",
+    "test:browser": "vitest run --config vitest.browser.config.ts"
   }
 }