@zag-js/popper 0.29.0 → 0.31.0

package/dist/index.d.mts

@@ -7,6 +7,17 @@ interface AutoUpdateOptions {
     referenceResize?: boolean;
 }
 
+type MaybeRectElement = HTMLElement | VirtualElement | null;
+type MaybeElement = HTMLElement | null;
+type MaybeFn<T> = T | (() => T);
+type PlacementSide = "top" | "right" | "bottom" | "left";
+type PlacementAlign = "start" | "center" | "end";
+interface AnchorRect {
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+}
 interface PositioningOptions {
     /**
      * The strategy to use for positioning
@@ -27,14 +38,27 @@ interface PositioningOptions {
      * The main axis offset or gap between the reference and floating elements
      */
     gutter?: number;
+    /**
+     * The secondary axis offset or gap between the reference and floating elements
+     */
+    shift?: number;
     /**
      * The virtual padding around the viewport edges to check for overflow
      */
     overflowPadding?: number;
+    /**
+     * The minimum padding between the arrow and the floating element's corner.
+     * @default 4
+     */
+    arrowPadding?: number;
     /**
      * Whether to flip the placement
      */
-    flip?: boolean;
+    flip?: boolean | Placement[];
+    /**
+     * Whether the popover should slide when it overflows.
+     */
+    slide?: boolean;
     /**
      * Whether the floating element can overlap the reference element
      * @default false
@@ -60,17 +84,29 @@ interface PositioningOptions {
      * Function called when the placement is computed
      */
     onComplete?(data: ComputePositionReturn): void;
+    /**
+     * Function called when the floating element is positioned or not
+     */
+    onPositioned?(data: {
+        placed: boolean;
+    }): void;
     /**
      * Function called on cleanup of all listeners
      */
     onCleanup?: VoidFunction;
+    /**
+     *  Function that returns the anchor rect of the combobox
+     */
+    getAnchorRect?: (element: HTMLElement | VirtualElement | null) => AnchorRect | null;
+    /**
+     * A callback that will be called when the popover needs to calculate its
+     * position.
+     */
+    updatePosition?: (data: {
+        updatePosition: () => Promise<void>;
+    }) => void | Promise<void>;
 }
-type BasePlacement = "top" | "right" | "bottom" | "left";
 
-type MaybeRectElement = HTMLElement | VirtualElement | null;
-type MaybeElement = HTMLElement | null;
-type MaybeFn<T> = T | (() => T);
-declare function getBasePlacement(placement: Placement): BasePlacement;
 declare function getPlacement(referenceOrFn: MaybeFn<MaybeRectElement>, floatingOrFn: MaybeFn<MaybeElement>, opts?: PositioningOptions & {
     defer?: boolean;
 }): () => void;
@@ -104,9 +140,12 @@ declare function getPlacementStyles(options?: PositioningOptions): {
         readonly maxHeight: "var(--available-height)" | undefined;
         readonly top: "0px";
         readonly left: "0px";
-        readonly transform: "translate3d(var(--x), var(--y), 0)";
+        readonly transform: "translate3d(var(--x), var(--y), 0)" | "translate3d(0, -100vh, 0)";
         readonly zIndex: "var(--z-index)";
     };
 };
 
-export { AutoUpdateOptions, BasePlacement, GetPlacementStylesOptions, PositioningOptions, getBasePlacement, getPlacement, getPlacementStyles };
+declare function isValidPlacement(v: string): v is Placement;
+declare function getPlacementSide(placement: Placement): PlacementSide;
+
+export { type AnchorRect, type AutoUpdateOptions, type GetPlacementStylesOptions, type PlacementAlign, type PlacementSide, type PositioningOptions, getPlacement, getPlacementSide, getPlacementStyles, isValidPlacement };

package/dist/index.d.ts

@@ -7,6 +7,17 @@ interface AutoUpdateOptions {
     referenceResize?: boolean;
 }
 
+type MaybeRectElement = HTMLElement | VirtualElement | null;
+type MaybeElement = HTMLElement | null;
+type MaybeFn<T> = T | (() => T);
+type PlacementSide = "top" | "right" | "bottom" | "left";
+type PlacementAlign = "start" | "center" | "end";
+interface AnchorRect {
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+}
 interface PositioningOptions {
     /**
      * The strategy to use for positioning
@@ -27,14 +38,27 @@ interface PositioningOptions {
      * The main axis offset or gap between the reference and floating elements
      */
     gutter?: number;
+    /**
+     * The secondary axis offset or gap between the reference and floating elements
+     */
+    shift?: number;
     /**
      * The virtual padding around the viewport edges to check for overflow
      */
     overflowPadding?: number;
+    /**
+     * The minimum padding between the arrow and the floating element's corner.
+     * @default 4
+     */
+    arrowPadding?: number;
     /**
      * Whether to flip the placement
      */
-    flip?: boolean;
+    flip?: boolean | Placement[];
+    /**
+     * Whether the popover should slide when it overflows.
+     */
+    slide?: boolean;
     /**
      * Whether the floating element can overlap the reference element
      * @default false
@@ -60,17 +84,29 @@ interface PositioningOptions {
      * Function called when the placement is computed
      */
     onComplete?(data: ComputePositionReturn): void;
+    /**
+     * Function called when the floating element is positioned or not
+     */
+    onPositioned?(data: {
+        placed: boolean;
+    }): void;
     /**
      * Function called on cleanup of all listeners
      */
     onCleanup?: VoidFunction;
+    /**
+     *  Function that returns the anchor rect of the combobox
+     */
+    getAnchorRect?: (element: HTMLElement | VirtualElement | null) => AnchorRect | null;
+    /**
+     * A callback that will be called when the popover needs to calculate its
+     * position.
+     */
+    updatePosition?: (data: {
+        updatePosition: () => Promise<void>;
+    }) => void | Promise<void>;
 }
-type BasePlacement = "top" | "right" | "bottom" | "left";
 
-type MaybeRectElement = HTMLElement | VirtualElement | null;
-type MaybeElement = HTMLElement | null;
-type MaybeFn<T> = T | (() => T);
-declare function getBasePlacement(placement: Placement): BasePlacement;
 declare function getPlacement(referenceOrFn: MaybeFn<MaybeRectElement>, floatingOrFn: MaybeFn<MaybeElement>, opts?: PositioningOptions & {
     defer?: boolean;
 }): () => void;
@@ -104,9 +140,12 @@ declare function getPlacementStyles(options?: PositioningOptions): {
         readonly maxHeight: "var(--available-height)" | undefined;
         readonly top: "0px";
         readonly left: "0px";
-        readonly transform: "translate3d(var(--x), var(--y), 0)";
+        readonly transform: "translate3d(var(--x), var(--y), 0)" | "translate3d(0, -100vh, 0)";
         readonly zIndex: "var(--z-index)";
     };
 };
 
-export { AutoUpdateOptions, BasePlacement, GetPlacementStylesOptions, PositioningOptions, getBasePlacement, getPlacement, getPlacementStyles };
+declare function isValidPlacement(v: string): v is Placement;
+declare function getPlacementSide(placement: Placement): PlacementSide;
+
+export { type AnchorRect, type AutoUpdateOptions, type GetPlacementStylesOptions, type PlacementAlign, type PlacementSide, type PositioningOptions, getPlacement, getPlacementSide, getPlacementStyles, isValidPlacement };

package/dist/index.js

@@ -20,24 +20,23 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
-  getBasePlacement: () => getBasePlacement,
   getPlacement: () => getPlacement,
-  getPlacementStyles: () => getPlacementStyles
+  getPlacementSide: () => getPlacementSide,
+  getPlacementStyles: () => getPlacementStyles,
+  isValidPlacement: () => isValidPlacement
 });
 module.exports = __toCommonJS(src_exports);
 
 // src/get-placement.ts
 var import_dom2 = require("@floating-ui/dom");
-var import_dom_query = require("@zag-js/dom-query");
-var import_utils = require("@zag-js/utils");
+var import_dom_query3 = require("@zag-js/dom-query");
+var import_utils2 = require("@zag-js/utils");
 
 // src/auto-update.ts
 var import_dom = require("@floating-ui/dom");
+var import_dom_query = require("@zag-js/dom-query");
 var import_element_rect = require("@zag-js/element-rect");
-var callAll = (...fns) => () => fns.forEach((fn) => fn());
-var isHTMLElement = (el) => {
-  return typeof el === "object" && el !== null && el.nodeType === 1;
-};
+var import_utils = require("@zag-js/utils");
 var addDomEvent = (el, type, fn, options) => {
   el.addEventListener(type, fn, options);
   return () => el.removeEventListener(type, fn, options);
@@ -54,21 +53,59 @@ function autoUpdate(reference, floating, update, options = false) {
   const { ancestorScroll, ancestorResize, referenceResize } = resolveOptions(options);
   const useAncestors = ancestorScroll || ancestorResize;
   const ancestors = [];
-  if (useAncestors && isHTMLElement(reference)) {
+  if (useAncestors && (0, import_dom_query.isHTMLElement)(reference)) {
     ancestors.push(...(0, import_dom.getOverflowAncestors)(reference));
   }
   function addResizeListeners() {
     let cleanups = [(0, import_element_rect.trackElementRect)(floating, { scope: "size", onChange: update })];
-    if (referenceResize && isHTMLElement(reference)) {
+    if (referenceResize && (0, import_dom_query.isHTMLElement)(reference)) {
       cleanups.push((0, import_element_rect.trackElementRect)(reference, { onChange: update }));
     }
-    cleanups.push(callAll(...ancestors.map((el) => addDomEvent(el, "resize", update))));
+    cleanups.push((0, import_utils.callAll)(...ancestors.map((el) => addDomEvent(el, "resize", update))));
     return () => cleanups.forEach((fn) => fn());
   }
   function addScrollListeners() {
-    return callAll(...ancestors.map((el) => addDomEvent(el, "scroll", update, { passive: true })));
+    return (0, import_utils.callAll)(...ancestors.map((el) => addDomEvent(el, "scroll", update, { passive: true })));
+  }
+  return (0, import_utils.callAll)(addResizeListeners(), addScrollListeners());
+}
+
+// src/get-anchor.ts
+var import_dom_query2 = require("@zag-js/dom-query");
+function createDOMRect(x = 0, y = 0, width = 0, height = 0) {
+  if (typeof DOMRect === "function") {
+    return new DOMRect(x, y, width, height);
   }
-  return callAll(addResizeListeners(), addScrollListeners());
+  const rect = {
+    x,
+    y,
+    width,
+    height,
+    top: y,
+    right: x + width,
+    bottom: y + height,
+    left: x
+  };
+  return { ...rect, toJSON: () => rect };
+}
+function getDOMRect(anchorRect) {
+  if (!anchorRect)
+    return createDOMRect();
+  const { x, y, width, height } = anchorRect;
+  return createDOMRect(x, y, width, height);
+}
+function getAnchorElement(anchorElement, getAnchorRect) {
+  return {
+    contextElement: (0, import_dom_query2.isHTMLElement)(anchorElement) ? anchorElement : void 0,
+    getBoundingClientRect: () => {
+      const anchor = anchorElement;
+      const anchorRect = getAnchorRect?.(anchor);
+      if (anchorRect || !anchor) {
+        return getDOMRect(anchorRect);
+      }
+      return anchor.getBoundingClientRect();
+    }
+  };
 }
 
 // src/middleware.ts
@@ -94,34 +131,49 @@ var getTransformOrigin = (arrow2) => ({
   "right-start": arrow2 ? `left ${arrow2.y}px` : "left top",
   "right-end": arrow2 ? `left ${arrow2.y}px` : "left bottom"
 });
-var transformOrigin = {
+var __transformOrigin = {
   name: "transformOrigin",
   fn({ placement, elements, middlewareData }) {
     const { arrow: arrow2 } = middlewareData;
-    const transformOrigin2 = getTransformOrigin(arrow2)[placement];
+    const transformOrigin = getTransformOrigin(arrow2)[placement];
     const { floating } = elements;
-    floating.style.setProperty(cssVars.transformOrigin.variable, transformOrigin2);
+    floating.style.setProperty(cssVars.transformOrigin.variable, transformOrigin);
     return {
-      data: { transformOrigin: transformOrigin2 }
+      data: { transformOrigin }
     };
   }
 };
-var shiftArrow = (opts) => ({
-  name: "shiftArrow",
-  fn({ placement, middlewareData }) {
-    const { element: arrow2 } = opts;
-    if (middlewareData.arrow) {
+var __shiftArrow = (arrowEl) => {
+  if (!arrowEl)
+    return;
+  return {
+    name: "shiftArrow",
+    fn({ placement, middlewareData }) {
+      if (!middlewareData.arrow)
+        return {};
       const { x, y } = middlewareData.arrow;
       const dir = placement.split("-")[0];
-      Object.assign(arrow2.style, {
+      Object.assign(arrowEl.style, {
         left: x != null ? `${x}px` : "",
         top: y != null ? `${y}px` : "",
         [dir]: `calc(100% + ${cssVars.arrowOffset.reference})`
       });
+      return {};
     }
-    return {};
-  }
-});
+  };
+};
+
+// src/placement.ts
+function isValidPlacement(v) {
+  return /^(?:top|bottom|left|right)(?:-(?:start|end))?$/.test(v);
+}
+function getPlacementDetails(placement) {
+  const [side, align] = placement.split("-");
+  return { side, align, hasAlign: align != null };
+}
+function getPlacementSide(placement) {
+  return placement.split("-")[0];
+}
 
 // src/get-placement.ts
 var defaultOptions = {
@@ -130,99 +182,138 @@ var defaultOptions = {
   listeners: true,
   gutter: 8,
   flip: true,
+  slide: true,
+  overlap: false,
   sameWidth: false,
-  overflowPadding: 8
+  fitViewport: false,
+  overflowPadding: 8,
+  arrowPadding: 4
 };
-function getPlacementImpl(reference, floating, opts = {}) {
+function __dpr(win, value) {
+  const dpr = win.devicePixelRatio || 1;
+  return Math.round(value * dpr) / dpr;
+}
+function __boundary(opts) {
+  return (0, import_utils2.runIfFn)(opts.boundary);
+}
+function __arrow(arrowElement, opts) {
+  if (!arrowElement)
+    return;
+  return (0, import_dom2.arrow)({
+    element: arrowElement,
+    padding: opts.arrowPadding
+  });
+}
+function __offset(arrowElement, opts) {
+  if ((0, import_utils2.isNull)(opts.offset ?? opts.gutter))
+    return;
+  return (0, import_dom2.offset)(({ placement }) => {
+    const arrowOffset = (arrowElement?.clientHeight || 0) / 2;
+    const gutter = opts.offset?.mainAxis ?? opts.gutter;
+    const mainAxis = typeof gutter === "number" ? gutter + arrowOffset : gutter ?? arrowOffset;
+    const { hasAlign } = getPlacementDetails(placement);
+    return (0, import_utils2.compact)({
+      crossAxis: hasAlign ? opts.shift : void 0,
+      mainAxis,
+      alignmentAxis: opts.shift
+    });
+  });
+}
+function __flip(opts) {
+  if (!opts.flip)
+    return;
+  return (0, import_dom2.flip)({
+    boundary: __boundary(opts),
+    padding: opts.overflowPadding,
+    fallbackPlacements: opts.flip === true ? void 0 : opts.flip
+  });
+}
+function __shift(opts) {
+  if (!opts.slide && !opts.overlap)
+    return;
+  return (0, import_dom2.shift)({
+    boundary: __boundary(opts),
+    mainAxis: opts.slide,
+    crossAxis: opts.overlap,
+    padding: opts.overflowPadding
+  });
+}
+function __size(opts) {
+  return (0, import_dom2.size)({
+    padding: opts.overflowPadding,
+    apply({ elements, rects, availableHeight, availableWidth }) {
+      const floating = elements.floating;
+      const referenceWidth = Math.round(rects.reference.width);
+      availableWidth = Math.floor(availableWidth);
+      availableHeight = Math.floor(availableHeight);
+      floating.style.setProperty("--reference-width", `${referenceWidth}px`);
+      floating.style.setProperty("--available-width", `${availableWidth}px`);
+      floating.style.setProperty("--available-height", `${availableHeight}px`);
+    }
+  });
+}
+function getPlacementImpl(referenceOrVirtual, floating, opts = {}) {
+  const reference = getAnchorElement(referenceOrVirtual, opts.getAnchorRect);
   if (!floating || !reference)
     return;
   const options = Object.assign({}, defaultOptions, opts);
   const arrowEl = floating.querySelector("[data-part=arrow]");
-  const middleware = [];
-  const boundary = typeof options.boundary === "function" ? options.boundary() : options.boundary;
-  if (options.flip) {
-    middleware.push(
-      (0, import_dom2.flip)({
-        boundary,
-        padding: options.overflowPadding
-      })
-    );
-  }
-  if (options.gutter || options.offset) {
-    const arrowOffset = arrowEl ? arrowEl.offsetHeight / 2 : 0;
-    let mainAxis = options.offset?.mainAxis ?? options.gutter;
-    let crossAxis = options.offset?.crossAxis;
-    if (mainAxis != null)
-      mainAxis += arrowOffset;
-    const offsetOptions = (0, import_utils.compact)({ mainAxis, crossAxis });
-    middleware.push((0, import_dom2.offset)(offsetOptions));
-  }
-  middleware.push(
-    (0, import_dom2.shift)({
-      boundary,
-      crossAxis: options.overlap,
-      padding: options.overflowPadding
-    })
-  );
-  if (arrowEl) {
-    middleware.push(
-      (0, import_dom2.arrow)({ element: arrowEl, padding: 8 }),
-      shiftArrow({ element: arrowEl })
-    );
-  }
-  middleware.push(transformOrigin);
-  middleware.push(
-    (0, import_dom2.size)({
-      padding: options.overflowPadding,
-      apply({ rects, availableHeight, availableWidth }) {
-        const referenceWidth = Math.round(rects.reference.width);
-        floating.style.setProperty("--reference-width", `${referenceWidth}px`);
-        floating.style.setProperty("--available-width", `${availableWidth}px`);
-        floating.style.setProperty("--available-height", `${availableHeight}px`);
-      }
-    })
-  );
-  function compute(config = {}) {
-    const { placement, strategy, onComplete } = options;
+  const middleware = [
+    __offset(arrowEl, options),
+    __flip(options),
+    __shift(options),
+    __arrow(arrowEl, options),
+    __shiftArrow(arrowEl),
+    __transformOrigin,
+    __size(options)
+  ];
+  const { placement, strategy, onComplete, onPositioned } = options;
+  const updatePosition = async () => {
     if (!reference || !floating)
       return;
-    (0, import_dom2.computePosition)(reference, floating, {
+    const pos = await (0, import_dom2.computePosition)(reference, floating, {
       placement,
       middleware,
-      strategy,
-      ...config
-    }).then((data) => {
-      const x = Math.round(data.x);
-      const y = Math.round(data.y);
-      floating.style.setProperty("--x", `${x}px`);
-      floating.style.setProperty("--y", `${y}px`);
-      const win = (0, import_dom_query.getWindow)(floating);
-      const contentEl = floating.firstElementChild;
-      if (contentEl) {
-        const zIndex = win.getComputedStyle(contentEl).zIndex;
-        floating.style.setProperty("--z-index", zIndex);
-      }
-      onComplete?.(data);
+      strategy
     });
-  }
-  compute();
-  return (0, import_utils.callAll)(
-    options.listeners ? autoUpdate(reference, floating, compute, options.listeners) : void 0,
-    options.onCleanup
-  );
-}
-function getBasePlacement(placement) {
-  return placement.split("-")[0];
+    onComplete?.(pos);
+    onPositioned?.({ placed: true });
+    const win = (0, import_dom_query3.getWindow)(floating);
+    const x = __dpr(win, pos.x);
+    const y = __dpr(win, pos.y);
+    floating.style.setProperty("--x", `${x}px`);
+    floating.style.setProperty("--y", `${y}px`);
+    const contentEl = floating.firstElementChild;
+    if (contentEl) {
+      const zIndex = win.getComputedStyle(contentEl).zIndex;
+      floating.style.setProperty("--z-index", zIndex);
+    }
+  };
+  const update = async () => {
+    if (opts.updatePosition) {
+      await opts.updatePosition({ updatePosition });
+      onPositioned?.({ placed: true });
+    } else {
+      await updatePosition();
+    }
+  };
+  const cancelAutoUpdate = options.listeners ? autoUpdate(reference, floating, update, options.listeners) : void 0;
+  update();
+  return () => {
+    cancelAutoUpdate?.();
+    onPositioned?.({ placed: false });
+    options.onCleanup?.();
+  };
 }
 function getPlacement(referenceOrFn, floatingOrFn, opts = {}) {
-  const { defer, ...restOptions } = opts;
-  const func = defer ? import_dom_query.raf : (v) => v();
+  const { defer, ...options } = opts;
+  const func = defer ? import_dom_query3.raf : (v) => v();
   const cleanups = [];
   cleanups.push(
     func(() => {
       const reference = typeof referenceOrFn === "function" ? referenceOrFn() : referenceOrFn;
       const floating = typeof floatingOrFn === "function" ? floatingOrFn() : floatingOrFn;
-      cleanups.push(getPlacementImpl(reference, floating, restOptions));
+      cleanups.push(getPlacementImpl(reference, floating, options));
     })
   );
   return () => {
@@ -238,7 +329,7 @@ var ARROW_FLOATING_STYLE = {
   right: "rotate(315deg)"
 };
 function getPlacementStyles(options = {}) {
-  const { placement = "bottom", sameWidth, fitViewport, strategy = "absolute" } = options;
+  const { placement, sameWidth, fitViewport, strategy = "absolute" } = options;
   return {
     arrow: {
       position: "absolute",
@@ -248,7 +339,7 @@ function getPlacementStyles(options = {}) {
       [cssVars.arrowOffset.variable]: `calc(${cssVars.arrowSizeHalf.reference} * -1)`
     },
     arrowTip: {
-      transform: ARROW_FLOATING_STYLE[placement.split("-")[0]],
+      transform: placement ? ARROW_FLOATING_STYLE[placement.split("-")[0]] : void 0,
       background: cssVars.arrowBg.reference,
       top: "0",
       left: "0",
@@ -266,15 +357,17 @@ function getPlacementStyles(options = {}) {
       maxHeight: fitViewport ? "var(--available-height)" : void 0,
       top: "0px",
       left: "0px",
-      transform: `translate3d(var(--x), var(--y), 0)`,
+      // move off-screen if placement is not defined
+      transform: placement ? "translate3d(var(--x), var(--y), 0)" : "translate3d(0, -100vh, 0)",
       zIndex: "var(--z-index)"
     }
   };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  getBasePlacement,
   getPlacement,
-  getPlacementStyles
+  getPlacementSide,
+  getPlacementStyles,
+  isValidPlacement
 });
 //# sourceMappingURL=index.js.map