@tensor_1/react 2.6.0 → 2.7.0

package/dist/components/Field.js

@@ -1,12 +1,18 @@
 import { jsx, jsxs } from "react/jsx-runtime";
+import { cloneElement, isValidElement, useId } from "react";
 import { cx } from "../cx.js";
 function Field({ label, hint, error, success, required, children, className, htmlFor }) {
+  const uid = useId();
+  const msgId = `${uid}-msg`;
+  const describedBy = error || success || hint ? msgId : void 0;
+  const control = isValidElement(children) ? cloneElement(children, {
+    "aria-describedby": [children.props["aria-describedby"], describedBy].filter(Boolean).join(" ") || void 0,
+    "aria-invalid": error ? true : children.props["aria-invalid"]
+  }) : children;
   return /* @__PURE__ */ jsxs("div", { className: cx("uix-field", className), children: [
     label && /* @__PURE__ */ jsx("label", { className: "uix-field__label", htmlFor, "data-required": required || void 0, children: label }),
-    children,
-    error && /* @__PURE__ */ jsx("span", { className: "uix-field__error", children: error }),
-    success && !error && /* @__PURE__ */ jsx("span", { className: "uix-field__success", children: success }),
-    hint && !error && !success && /* @__PURE__ */ jsx("span", { className: "uix-field__hint", children: hint })
+    control,
+    /* @__PURE__ */ jsx("div", { className: "uix-field__msg", id: msgId, children: error ? /* @__PURE__ */ jsx("span", { className: "uix-field__error", role: "alert", children: error }) : success ? /* @__PURE__ */ jsx("span", { className: "uix-field__success", children: success }) : hint ? /* @__PURE__ */ jsx("span", { className: "uix-field__hint", children: hint }) : null })
   ] });
 }
 export {

package/dist/components/Popover.d.ts

@@ -1,5 +1,6 @@
 import * as react from 'react';
-import { HTMLAttributes, ReactNode } from 'react';
+import { HTMLAttributes, RefObject, ReactNode } from 'react';
+import { Placement } from '../overlay-position.js';
 
 interface PopoverProps extends HTMLAttributes<HTMLDivElement> {
     /**
@@ -7,12 +8,25 @@ interface PopoverProps extends HTMLAttributes<HTMLDivElement> {
      * wires to it via `popoverTarget={id}`. Pass `"manual"` to control open state yourself.
      */
     popover?: 'auto' | 'manual';
+    /**
+     * Element (or ref) to anchor against. When set, the popover is placed with
+     * cross-browser JS positioning — flip when it won't fit, shift to stay on-screen —
+     * instead of relying on CSS `anchor()`, which is Chromium-only and detaches the
+     * popover from its trigger everywhere else. The native Popover API still provides
+     * the top layer (so it escapes `overflow` clipping) and light-dismiss.
+     */
+    anchor?: RefObject<HTMLElement | null> | HTMLElement | null;
+    /** Preferred placement when `anchor` is set. Default `'bottom-start'`. */
+    placement?: Placement;
+    /** Gap between the trigger and the popover, in px. Default 6. */
+    offset?: number;
     children?: ReactNode;
 }
 /**
- * Anchored surface over `.uix-popover`, using the native Popover API.
- * Compose ITSM things like a filter popover by putting controls inside.
+ * Anchored surface over `.uix-popover`, using the native Popover API. Compose ITSM
+ * things like a filter popover, menu, or rich select by putting controls inside.
+ * Pass `anchor` to get collision-aware, cross-browser placement (UIX-FIX-02).
  */
-declare function Popover({ popover, children, className, ...props }: PopoverProps): react.JSX.Element;
+declare function Popover({ popover, anchor, placement, offset, className, children, ...props }: PopoverProps): react.JSX.Element;
 
 export { Popover, type PopoverProps };

package/dist/components/Popover.js

@@ -1,8 +1,37 @@
+"use client";
 import { jsx } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
 import { cx } from "../cx.js";
-function Popover({ popover = "auto", children, className, ...props }) {
+import { useAnchoredPosition } from "../hooks/useAnchoredPosition.js";
+function Popover({
+  popover = "auto",
+  anchor,
+  placement = "bottom-start",
+  offset = 6,
+  className,
+  children,
+  ...props
+}) {
+  const ref = useRef(null);
+  const [open, setOpen] = useState(false);
   const popoverAttr = { popover };
-  return /* @__PURE__ */ jsx("div", { className: cx("uix-popover", className), ...popoverAttr, ...props, children });
+  const reposition = useAnchoredPosition(anchor ?? null, ref, {
+    open: open && !!anchor,
+    placement,
+    offset
+  });
+  useEffect(() => {
+    const el = ref.current;
+    if (!el || !anchor) return;
+    const sync = () => {
+      const isOpen = el.matches(":popover-open");
+      if (isOpen) reposition();
+      setOpen(isOpen);
+    };
+    el.addEventListener("toggle", sync);
+    return () => el.removeEventListener("toggle", sync);
+  }, [anchor, reposition]);
+  return /* @__PURE__ */ jsx("div", { ref, className: cx("uix-popover", className), ...popoverAttr, ...props, children });
 }
 export {
   Popover

package/dist/components/Toast.js

@@ -1,16 +1,17 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { cx } from "../cx.js";
 function Toast({ title, message, tone, icon, onClose, leaving, className, ...props }) {
+  const assertive = tone === "danger";
   return /* @__PURE__ */ jsxs(
     "div",
     {
       className: cx("uix-toast", tone && `uix-toast--${tone}`, className),
       "data-leaving": leaving || void 0,
-      role: "status",
-      "aria-live": "polite",
+      role: assertive ? "alert" : "status",
+      "aria-live": assertive ? "assertive" : "polite",
       ...props,
       children: [
-        icon && /* @__PURE__ */ jsx("div", { className: "uix-toast__icon", children: icon }),
+        icon && /* @__PURE__ */ jsx("div", { className: "uix-toast__icon", "aria-hidden": "true", children: icon }),
         /* @__PURE__ */ jsxs("div", { className: "uix-toast__body", children: [
           title && /* @__PURE__ */ jsx("div", { className: "uix-toast__title", children: title }),
           message && /* @__PURE__ */ jsx("div", { className: "uix-toast__msg", children: message })
@@ -21,7 +22,7 @@ function Toast({ title, message, tone, icon, onClose, leaving, className, ...pro
   );
 }
 function Toaster({ children, className, ...props }) {
-  return /* @__PURE__ */ jsx("div", { className: cx("uix-toaster", className), "aria-live": "polite", "aria-atomic": "false", ...props, children });
+  return /* @__PURE__ */ jsx("div", { className: cx("uix-toaster", className), ...props, children });
 }
 export {
   Toast,

package/dist/components/Tooltip.d.ts

@@ -1,16 +1,20 @@
 import * as react from 'react';
 import { HTMLAttributes, ReactNode } from 'react';
+import { Placement } from '../overlay-position.js';
 
 interface TooltipProps extends HTMLAttributes<HTMLSpanElement> {
-    /** Tooltip text. Rendered via the CSS `[data-uix-tip]` hover/focus tooltip. */
+    /** Tooltip text. */
     label: string;
+    /** Preferred placement. Default `'top'`. */
+    placement?: Placement;
     children?: ReactNode;
 }
 /**
- * Thin wrapper over the CSS-only tooltip (`[data-uix-tip]`). Wraps its children
- * in a span carrying the attribute; the bubble is drawn entirely in CSS on
- * hover/focus. For keyboard reveal, ensure a focusable child or pass `tabIndex`.
+ * Tooltip whose bubble renders in the top layer via the native Popover API, so it
+ * escapes any `overflow: hidden/scroll` ancestor that would clip the old CSS-only
+ * `[data-uix-tip]` tooltip (UIX-FIX-02). Positioned by the shared overlay engine
+ * (flip/shift), shown on hover and keyboard focus, dismissed on blur or Escape.
  */
-declare function Tooltip({ label, children, ...props }: TooltipProps): react.JSX.Element;
+declare function Tooltip({ label, placement, className, children, ...props }: TooltipProps): react.JSX.Element;
 
 export { Tooltip, type TooltipProps };

package/dist/components/Tooltip.js

@@ -1,6 +1,64 @@
-import { jsx } from "react/jsx-runtime";
-function Tooltip({ label, children, ...props }) {
-  return /* @__PURE__ */ jsx("span", { "data-uix-tip": label, ...props, children });
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useRef, useState } from "react";
+import { cx } from "../cx.js";
+import { useAnchoredPosition } from "../hooks/useAnchoredPosition.js";
+function Tooltip({ label, placement = "top", className, children, ...props }) {
+  const triggerRef = useRef(null);
+  const bubbleRef = useRef(null);
+  const [open, setOpen] = useState(false);
+  const id = useId();
+  useAnchoredPosition(triggerRef, bubbleRef, { open, placement, offset: 6 });
+  const show = () => {
+    const b = bubbleRef.current;
+    if (b && !b.matches(":popover-open")) {
+      try {
+        b.showPopover();
+      } catch {
+      }
+    }
+    setOpen(true);
+  };
+  const hide = () => {
+    const b = bubbleRef.current;
+    if (b && b.matches(":popover-open")) {
+      try {
+        b.hidePopover();
+      } catch {
+      }
+    }
+    setOpen(false);
+  };
+  useEffect(() => () => {
+    const b = bubbleRef.current;
+    if (b && b.matches(":popover-open")) {
+      try {
+        b.hidePopover();
+      } catch {
+      }
+    }
+  }, []);
+  const bubbleAttr = { popover: "manual" };
+  return /* @__PURE__ */ jsxs(
+    "span",
+    {
+      ref: triggerRef,
+      className: cx("uix-tooltip", className),
+      "aria-describedby": id,
+      onMouseEnter: show,
+      onMouseLeave: hide,
+      onFocus: show,
+      onBlur: hide,
+      onKeyDown: (e) => {
+        if (e.key === "Escape") hide();
+      },
+      ...props,
+      children: [
+        children,
+        /* @__PURE__ */ jsx("span", { ref: bubbleRef, id, role: "tooltip", className: "uix-tooltip__bubble", ...bubbleAttr, children: label })
+      ]
+    }
+  );
 }
 export {
   Tooltip

package/dist/components/Tree.d.ts

@@ -11,8 +11,11 @@ interface TreeNodeProps {
     node: TreeNodeData;
     expanded: Set<string>;
     selected?: string;
+    selectable: boolean;
+    tabbableId?: string;
     onToggle: (id: string) => void;
     onSelect?: (id: string) => void;
+    onFocusNode: (id: string) => void;
     level?: number;
 }
 interface TreeProps extends Omit<HTMLAttributes<HTMLUListElement>, 'onSelect' | 'onChange'> {
@@ -22,7 +25,18 @@ interface TreeProps extends Omit<HTMLAttributes<HTMLUListElement>, 'onSelect' |
     selected?: string;
     onToggle?: (id: string) => void;
     onSelect?: (id: string) => void;
+    /**
+     * Virtualize a large tree — render only the rows in view (UIX-FIX-05). Defaults to auto
+     * (on past the engine's `shouldVirtualize` threshold of visible rows). When on, the tree is
+     * flattened to a scrollable list of `maxHeight` with fixed-height rows; a11y is preserved via
+     * `aria-level` / `aria-setsize` / `aria-posinset` instead of nested `role="group"`s.
+     */
+    virtualize?: boolean;
+    /** Fixed row height (px) used for virtualization. Default 32. */
+    rowHeight?: number;
+    /** Scroll-viewport height (px) when virtualizing. Default 384. */
+    maxHeight?: number;
 }
-declare function Tree({ nodes, expanded: controlledExpanded, defaultExpanded, selected, onToggle, onSelect, className, ...props }: TreeProps): react.JSX.Element;
+declare function Tree({ nodes, expanded: controlledExpanded, defaultExpanded, selected, onToggle, onSelect, virtualize, rowHeight, maxHeight, className, ...props }: TreeProps): react.JSX.Element;
 
 export { Tree, type TreeNodeData, type TreeNodeProps, type TreeProps };

package/dist/components/Tree.js

@@ -1,47 +1,76 @@
 "use client";
 import { jsx, jsxs } from "react/jsx-runtime";
-import { useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { cx } from "../cx.js";
+import { flattenTree, treeNav } from "../tree-model.js";
+import { virtualWindow, shouldVirtualize } from "../table-engine.js";
 const ChevronIcon = () => /* @__PURE__ */ jsx("svg", { viewBox: "0 0 12 12", fill: "none", stroke: "currentColor", strokeWidth: 1.5, strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: /* @__PURE__ */ jsx("path", { d: "M2 4l4 4 4-4" }) });
-function TreeNode({ node, expanded, selected, onToggle, onSelect, level = 0 }) {
+function TreeNode({ node, expanded, selected, selectable, tabbableId, onToggle, onSelect, onFocusNode, level = 1 }) {
   const hasChildren = Array.isArray(node.children) && node.children.length > 0;
   const isExpanded = expanded.has(node.id);
-  return /* @__PURE__ */ jsxs("li", { children: [
-    /* @__PURE__ */ jsxs(
-      "button",
-      {
-        className: "uix-tree__row",
-        "aria-expanded": hasChildren ? isExpanded : void 0,
-        "aria-selected": selected === node.id,
-        onClick: () => {
-          if (hasChildren) onToggle(node.id);
-          onSelect?.(node.id);
-        },
-        children: [
+  return /* @__PURE__ */ jsxs(
+    "li",
+    {
+      role: "treeitem",
+      "aria-level": level,
+      "aria-expanded": hasChildren ? isExpanded : void 0,
+      "aria-selected": selectable ? selected === node.id : void 0,
+      "data-id": node.id,
+      tabIndex: tabbableId === node.id ? 0 : -1,
+      className: "uix-tree__item",
+      onFocus: (e) => {
+        if (e.target === e.currentTarget) onFocusNode(node.id);
+      },
+      onClick: (e) => {
+        e.stopPropagation();
+        if (hasChildren) onToggle(node.id);
+        onSelect?.(node.id);
+        onFocusNode(node.id);
+      },
+      children: [
+        /* @__PURE__ */ jsxs("span", { className: "uix-tree__row", children: [
           /* @__PURE__ */ jsx("span", { className: "uix-tree__toggle", children: hasChildren && /* @__PURE__ */ jsx(ChevronIcon, {}) }),
           node.icon && /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: node.icon }),
-          node.label
-        ]
-      }
-    ),
-    hasChildren && isExpanded && /* @__PURE__ */ jsx("ul", { children: node.children.map((child) => /* @__PURE__ */ jsx(
-      TreeNode,
-      {
-        node: child,
-        expanded,
-        selected,
-        onToggle,
-        onSelect,
-        level: level + 1
-      },
-      child.id
-    )) })
-  ] });
+          /* @__PURE__ */ jsx("span", { className: "uix-tree__label", children: node.label })
+        ] }),
+        hasChildren && isExpanded && /* @__PURE__ */ jsx("ul", { role: "group", className: "uix-tree__group", children: node.children.map((child) => /* @__PURE__ */ jsx(
+          TreeNode,
+          {
+            node: child,
+            expanded,
+            selected,
+            selectable,
+            tabbableId,
+            onToggle,
+            onSelect,
+            onFocusNode,
+            level: level + 1
+          },
+          child.id
+        )) })
+      ]
+    }
+  );
 }
-function Tree({ nodes, expanded: controlledExpanded, defaultExpanded, selected, onToggle, onSelect, className, ...props }) {
+function Tree({
+  nodes,
+  expanded: controlledExpanded,
+  defaultExpanded,
+  selected,
+  onToggle,
+  onSelect,
+  virtualize,
+  rowHeight = 32,
+  maxHeight = 384,
+  className,
+  ...props
+}) {
   const [internalExpanded, setInternalExpanded] = useState(defaultExpanded ?? /* @__PURE__ */ new Set());
   const expanded = controlledExpanded ?? internalExpanded;
-  function handleToggle(id) {
+  const rootRef = useRef(null);
+  const [focusedId, setFocusedId] = useState(void 0);
+  const selectable = selected !== void 0 || onSelect != null;
+  const handleToggle = useCallback((id) => {
     if (!controlledExpanded) {
       setInternalExpanded((prev) => {
         const next = new Set(prev);
@@ -51,19 +80,202 @@ function Tree({ nodes, expanded: controlledExpanded, defaultExpanded, selected,
       });
     }
     onToggle?.(id);
+  }, [controlledExpanded, onToggle]);
+  const flat = useMemo(() => flattenTree(nodes, expanded), [nodes, expanded]);
+  const useVirtual = virtualize ?? shouldVirtualize(flat.length);
+  const tabbableId = focusedId ?? selected ?? nodes[0]?.id;
+  if (useVirtual) {
+    return /* @__PURE__ */ jsx(
+      VirtualTreeView,
+      {
+        flat,
+        rowHeight,
+        maxHeight,
+        selectable,
+        selected,
+        tabbableId,
+        onToggle: handleToggle,
+        onSelect,
+        focusedId,
+        setFocusedId,
+        className,
+        ...props
+      }
+    );
   }
-  return /* @__PURE__ */ jsx("ul", { className: cx("uix-tree", className), role: "tree", ...props, children: nodes.map((node) => /* @__PURE__ */ jsx(
+  const treeItems = () => Array.from(rootRef.current?.querySelectorAll('[role="treeitem"]') ?? []);
+  const focusItem = (el) => {
+    if (el) {
+      el.focus();
+      setFocusedId(el.dataset.id);
+    }
+  };
+  const onKeyDown = (e) => {
+    const cur = e.target.closest('[role="treeitem"]');
+    if (!cur || !rootRef.current?.contains(cur)) return;
+    const list = treeItems();
+    const idx = list.indexOf(cur);
+    const id = cur.dataset.id;
+    const exp = cur.getAttribute("aria-expanded");
+    switch (e.key) {
+      case "ArrowDown":
+        e.preventDefault();
+        focusItem(list[Math.min(idx + 1, list.length - 1)]);
+        break;
+      case "ArrowUp":
+        e.preventDefault();
+        focusItem(list[Math.max(idx - 1, 0)]);
+        break;
+      case "Home":
+        e.preventDefault();
+        focusItem(list[0]);
+        break;
+      case "End":
+        e.preventDefault();
+        focusItem(list[list.length - 1]);
+        break;
+      case "ArrowRight":
+        e.preventDefault();
+        if (exp === "false") handleToggle(id);
+        else if (exp === "true") focusItem(cur.querySelector(':scope > [role="group"] > [role="treeitem"]'));
+        break;
+      case "ArrowLeft":
+        e.preventDefault();
+        if (exp === "true") handleToggle(id);
+        else focusItem(cur.parentElement?.closest('[role="treeitem"]'));
+        break;
+      case "Enter":
+      case " ":
+        e.preventDefault();
+        if (exp !== null) handleToggle(id);
+        onSelect?.(id);
+        setFocusedId(id);
+        break;
+      default:
+        break;
+    }
+  };
+  return /* @__PURE__ */ jsx("ul", { ref: rootRef, className: cx("uix-tree", className), role: "tree", onKeyDown, ...props, children: nodes.map((node) => /* @__PURE__ */ jsx(
     TreeNode,
     {
       node,
       expanded,
       selected,
+      selectable,
+      tabbableId,
       onToggle: handleToggle,
-      onSelect
+      onSelect,
+      onFocusNode: setFocusedId,
+      level: 1
     },
     node.id
   )) });
 }
+function VirtualTreeView({
+  flat,
+  rowHeight,
+  maxHeight,
+  selectable,
+  selected,
+  tabbableId,
+  onToggle,
+  onSelect,
+  focusedId,
+  setFocusedId,
+  className,
+  ...props
+}) {
+  const scrollRef = useRef(null);
+  const [scrollTop, setScrollTop] = useState(0);
+  const pendingFocus = useRef(false);
+  const win = virtualWindow(scrollTop, maxHeight, rowHeight, flat.length);
+  const rows = flat.slice(win.start, win.end);
+  useEffect(() => {
+    if (!pendingFocus.current || focusedId == null) return;
+    const el = scrollRef.current?.querySelector(`[role="treeitem"][data-id="${CSS.escape(focusedId)}"]`);
+    if (el) {
+      el.focus();
+      pendingFocus.current = false;
+    }
+  }, [focusedId, win.start, win.end]);
+  const moveTo = (id) => {
+    const i = flat.findIndex((f) => f.node.id === id);
+    if (i < 0) return;
+    const top = i * rowHeight;
+    let next = scrollTop;
+    if (top < scrollTop) next = top;
+    else if (top + rowHeight > scrollTop + maxHeight) next = top + rowHeight - maxHeight;
+    if (next !== scrollTop) {
+      if (scrollRef.current) scrollRef.current.scrollTop = next;
+      setScrollTop(next);
+    }
+    pendingFocus.current = true;
+    setFocusedId(id);
+  };
+  const onKeyDown = (e) => {
+    const curId = e.target.closest('[role="treeitem"]')?.dataset.id ?? focusedId;
+    const act = treeNav(flat, curId, e.key);
+    if (act.focusId === void 0 && act.toggleId === void 0 && act.selectId === void 0) return;
+    e.preventDefault();
+    if (act.toggleId !== void 0) onToggle(act.toggleId);
+    if (act.selectId !== void 0) {
+      onSelect?.(act.selectId);
+      if (act.focusId === void 0) {
+        pendingFocus.current = true;
+        setFocusedId(act.selectId);
+      }
+    }
+    if (act.focusId !== void 0) moveTo(act.focusId);
+  };
+  return /* @__PURE__ */ jsxs(
+    "ul",
+    {
+      ref: scrollRef,
+      className: cx("uix-tree", "uix-tree--virtual", className),
+      role: "tree",
+      style: { maxHeight, overflow: "auto" },
+      onScroll: (e) => setScrollTop(e.currentTarget.scrollTop),
+      onKeyDown,
+      ...props,
+      children: [
+        win.padTop > 0 && /* @__PURE__ */ jsx("li", { "aria-hidden": "true", style: { height: win.padTop } }),
+        rows.map((f) => {
+          const rowStyle = { height: rowHeight, paddingLeft: `calc(${f.level - 1} * var(--uix-space-5))` };
+          return /* @__PURE__ */ jsx(
+            "li",
+            {
+              role: "treeitem",
+              "aria-level": f.level,
+              "aria-setsize": f.setsize,
+              "aria-posinset": f.posinset,
+              "aria-expanded": f.hasChildren ? f.isExpanded : void 0,
+              "aria-selected": selectable ? selected === f.node.id : void 0,
+              "data-id": f.node.id,
+              tabIndex: tabbableId === f.node.id ? 0 : -1,
+              className: "uix-tree__item",
+              onFocus: (e) => {
+                if (e.target === e.currentTarget) setFocusedId(f.node.id);
+              },
+              onClick: (e) => {
+                e.stopPropagation();
+                if (f.hasChildren) onToggle(f.node.id);
+                onSelect?.(f.node.id);
+                setFocusedId(f.node.id);
+              },
+              children: /* @__PURE__ */ jsxs("span", { className: "uix-tree__row", style: rowStyle, children: [
+                /* @__PURE__ */ jsx("span", { className: "uix-tree__toggle", children: f.hasChildren && /* @__PURE__ */ jsx(ChevronIcon, {}) }),
+                f.node.icon && /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: f.node.icon }),
+                /* @__PURE__ */ jsx("span", { className: "uix-tree__label", children: f.node.label })
+              ] })
+            },
+            f.node.id
+          );
+        }),
+        win.padBottom > 0 && /* @__PURE__ */ jsx("li", { "aria-hidden": "true", style: { height: win.padBottom } })
+      ]
+    }
+  );
+}
 export {
   Tree
 };

package/dist/hooks/useAnchoredPosition.d.ts

@@ -0,0 +1,22 @@
+import { RefObject } from 'react';
+import { Placement } from '../overlay-position.js';
+
+interface UseAnchoredPositionOptions {
+    /** Reposition while true, and (re)attach scroll/resize listeners. */
+    open: boolean;
+    placement?: Placement;
+    offset?: number;
+    padding?: number;
+}
+/**
+ * Position a floating element (a native-popover overlay) against an anchor with
+ * cross-browser flip/shift — the DOM half of the overlay-position engine (UIX-FIX-02).
+ *
+ * Measures both elements with getBoundingClientRect, applies `position: fixed` + left/top
+ * (overriding the popover's default centered `inset:0; margin:auto`), and keeps the overlay
+ * glued to its anchor on scroll/resize while `open`. Returns a `reposition` fn for callers
+ * that want to nudge it manually (e.g. right when a native popover's `toggle` fires).
+ */
+declare function useAnchoredPosition(anchor: RefObject<HTMLElement | null> | HTMLElement | null | undefined, floatingRef: RefObject<HTMLElement | null>, { open, placement, offset, padding }: UseAnchoredPositionOptions): () => void;
+
+export { type UseAnchoredPositionOptions, useAnchoredPosition };

package/dist/hooks/useAnchoredPosition.js

@@ -0,0 +1,44 @@
+"use client";
+import { useCallback, useEffect, useLayoutEffect, useRef } from "react";
+import { computePosition } from "../overlay-position.js";
+const useIsomorphicLayoutEffect = typeof document !== "undefined" ? useLayoutEffect : useEffect;
+const resolve = (a) => a && typeof a === "object" && "current" in a ? a.current : a ?? null;
+function useAnchoredPosition(anchor, floatingRef, { open, placement = "bottom-start", offset = 6, padding = 8 }) {
+  const opts = useRef({ placement, offset, padding });
+  opts.current = { placement, offset, padding };
+  const reposition = useCallback(() => {
+    const anchorEl = resolve(anchor);
+    const floating = floatingRef.current;
+    if (!anchorEl || !floating) return;
+    const s = floating.style;
+    s.position = "fixed";
+    s.inset = "auto";
+    s.margin = "0";
+    const a = anchorEl.getBoundingClientRect();
+    const { placement: p, offset: o, padding: pad } = opts.current;
+    const pos = computePosition(
+      { x: a.x, y: a.y, width: a.width, height: a.height },
+      { width: floating.offsetWidth, height: floating.offsetHeight },
+      { width: window.innerWidth, height: window.innerHeight },
+      { placement: p, offset: o, padding: pad }
+    );
+    s.left = `${Math.round(pos.x)}px`;
+    s.top = `${Math.round(pos.y)}px`;
+    floating.dataset.placement = pos.placement;
+  }, [anchor, floatingRef]);
+  useIsomorphicLayoutEffect(() => {
+    if (!open) return;
+    reposition();
+    const onScroll = () => reposition();
+    window.addEventListener("scroll", onScroll, { passive: true, capture: true });
+    window.addEventListener("resize", onScroll);
+    return () => {
+      window.removeEventListener("scroll", onScroll, true);
+      window.removeEventListener("resize", onScroll);
+    };
+  }, [open, reposition]);
+  return reposition;
+}
+export {
+  useAnchoredPosition
+};