@zag-js/popper 0.30.0 → 0.31.0

package/src/get-anchor.ts

@@ -0,0 +1,42 @@
+import { isHTMLElement } from "@zag-js/dom-query"
+import type { AnchorRect, MaybeRectElement } from "./types"
+
+export function createDOMRect(x = 0, y = 0, width = 0, height = 0) {
+  if (typeof DOMRect === "function") {
+    return new DOMRect(x, y, width, height)
+  }
+  const rect = {
+    x,
+    y,
+    width,
+    height,
+    top: y,
+    right: x + width,
+    bottom: y + height,
+    left: x,
+  }
+  return { ...rect, toJSON: () => rect }
+}
+
+function getDOMRect(anchorRect?: AnchorRect | null) {
+  if (!anchorRect) return createDOMRect()
+  const { x, y, width, height } = anchorRect
+  return createDOMRect(x, y, width, height)
+}
+
+export function getAnchorElement(
+  anchorElement: MaybeRectElement,
+  getAnchorRect?: (anchor: MaybeRectElement) => AnchorRect | null,
+) {
+  return {
+    contextElement: isHTMLElement(anchorElement) ? anchorElement : undefined,
+    getBoundingClientRect: () => {
+      const anchor = anchorElement
+      const anchorRect = getAnchorRect?.(anchor)
+      if (anchorRect || !anchor) {
+        return getDOMRect(anchorRect)
+      }
+      return anchor.getBoundingClientRect()
+    },
+  }
+}

package/src/get-placement.ts

@@ -1,10 +1,12 @@
-import type { Middleware, Placement, VirtualElement } from "@floating-ui/dom"
-import { arrow, computePosition, flip, offset, shift, size, type ComputePositionConfig } from "@floating-ui/dom"
+import type { Middleware } from "@floating-ui/dom"
+import { arrow, computePosition, flip, offset, shift, size } from "@floating-ui/dom"
 import { getWindow, raf } from "@zag-js/dom-query"
-import { callAll, compact } from "@zag-js/utils"
+import { compact, isNull, runIfFn } from "@zag-js/utils"
 import { autoUpdate } from "./auto-update"
-import { shiftArrow, transformOrigin } from "./middleware"
-import type { BasePlacement, PositioningOptions } from "./types"
+import { getAnchorElement } from "./get-anchor"
+import { __shiftArrow, __transformOrigin } from "./middleware"
+import { getPlacementDetails } from "./placement"
+import type { MaybeElement, MaybeFn, MaybeRectElement, PositioningOptions } from "./types"
 
 const defaultOptions: PositioningOptions = {
   strategy: "absolute",
@@ -12,122 +14,159 @@ const defaultOptions: PositioningOptions = {
   listeners: true,
   gutter: 8,
   flip: true,
+  slide: true,
+  overlap: false,
   sameWidth: false,
+  fitViewport: false,
   overflowPadding: 8,
+  arrowPadding: 4,
 }
 
-type MaybeRectElement = HTMLElement | VirtualElement | null
-type MaybeElement = HTMLElement | null
-type MaybeFn<T> = T | (() => T)
+function __dpr(win: Window, value: number) {
+  const dpr = win.devicePixelRatio || 1
+  return Math.round(value * dpr) / dpr
+}
 
-function getPlacementImpl(reference: MaybeRectElement, floating: MaybeElement, opts: PositioningOptions = {}) {
-  if (!floating || !reference) return
+function __boundary(opts: PositioningOptions) {
+  return runIfFn(opts.boundary)
+}
 
-  const options = Object.assign({}, defaultOptions, opts)
+function __arrow(arrowElement: HTMLElement | null, opts: PositioningOptions) {
+  if (!arrowElement) return
+  return arrow({
+    element: arrowElement,
+    padding: opts.arrowPadding,
+  })
+}
 
-  /* -----------------------------------------------------------------------------
-   * The middleware stack
-   * -----------------------------------------------------------------------------*/
+function __offset(arrowElement: HTMLElement | null, opts: PositioningOptions) {
+  if (isNull(opts.offset ?? opts.gutter)) return
+  return offset(({ placement }) => {
+    const arrowOffset = (arrowElement?.clientHeight || 0) / 2
 
-  const arrowEl = floating.querySelector<HTMLElement>("[data-part=arrow]")
-  const middleware: Middleware[] = []
+    const gutter = opts.offset?.mainAxis ?? opts.gutter
+    const mainAxis = typeof gutter === "number" ? gutter + arrowOffset : gutter ?? arrowOffset
 
-  const boundary = typeof options.boundary === "function" ? options.boundary() : options.boundary
+    const { hasAlign } = getPlacementDetails(placement)
 
-  if (options.flip) {
-    middleware.push(
-      flip({
-        boundary,
-        padding: options.overflowPadding,
-      }),
-    )
-  }
+    return compact({
+      crossAxis: hasAlign ? opts.shift : undefined,
+      mainAxis: mainAxis,
+      alignmentAxis: opts.shift,
+    })
+  })
+}
 
-  if (options.gutter || options.offset) {
-    const arrowOffset = arrowEl ? arrowEl.offsetHeight / 2 : 0
+function __flip(opts: PositioningOptions) {
+  if (!opts.flip) return
+  return flip({
+    boundary: __boundary(opts),
+    padding: opts.overflowPadding,
+    fallbackPlacements: opts.flip === true ? undefined : opts.flip,
+  })
+}
 
-    let mainAxis = options.offset?.mainAxis ?? options.gutter
-    let crossAxis = options.offset?.crossAxis
+function __shift(opts: PositioningOptions) {
+  if (!opts.slide && !opts.overlap) return
+  return shift({
+    boundary: __boundary(opts),
+    mainAxis: opts.slide,
+    crossAxis: opts.overlap,
+    padding: opts.overflowPadding,
+  })
+}
 
-    if (mainAxis != null) mainAxis += arrowOffset
+function __size(opts: PositioningOptions) {
+  return 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`)
+    },
+  })
+}
 
-    const offsetOptions = compact({ mainAxis, crossAxis })
-    middleware.push(offset(offsetOptions))
-  }
+function getPlacementImpl(referenceOrVirtual: MaybeRectElement, floating: MaybeElement, opts: PositioningOptions = {}) {
+  const reference = getAnchorElement(referenceOrVirtual, opts.getAnchorRect)
 
-  middleware.push(
-    shift({
-      boundary,
-      crossAxis: options.overlap,
-      padding: options.overflowPadding,
-    }),
-  )
+  if (!floating || !reference) return
 
-  if (arrowEl) {
-    // prettier-ignore
-    middleware.push(
-      arrow({ element: arrowEl, padding: 8 }),
-      shiftArrow({ element: arrowEl }),
-    )
-  }
+  const options = Object.assign({}, defaultOptions, opts)
 
-  middleware.push(transformOrigin)
-
-  middleware.push(
-    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`)
-      },
-    }),
-  )
+  /* -----------------------------------------------------------------------------
+   * The middleware stack
+   * -----------------------------------------------------------------------------*/
+
+  const arrowEl = floating.querySelector<HTMLElement>("[data-part=arrow]")
+
+  const middleware: (Middleware | undefined)[] = [
+    __offset(arrowEl, options),
+    __flip(options),
+    __shift(options),
+    __arrow(arrowEl, options),
+    __shiftArrow(arrowEl),
+    __transformOrigin,
+    __size(options),
+  ]
 
   /* -----------------------------------------------------------------------------
    * The actual positioning function
    * -----------------------------------------------------------------------------*/
 
-  function compute(config: Omit<ComputePositionConfig, "platform"> = {}) {
-    const { placement, strategy, onComplete } = options
+  const { placement, strategy, onComplete, onPositioned } = options
 
+  const updatePosition = async () => {
     if (!reference || !floating) return
 
-    computePosition(reference, floating, {
+    const pos = await 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`)
+    onComplete?.(pos)
+    onPositioned?.({ placed: true })
 
-      const win = getWindow(floating)
-      const contentEl = floating.firstElementChild
+    const win = getWindow(floating)
+    const x = __dpr(win, pos.x)
+    const y = __dpr(win, pos.y)
 
-      if (contentEl) {
-        const zIndex = win.getComputedStyle(contentEl).zIndex
-        floating.style.setProperty("--z-index", zIndex)
-      }
+    floating.style.setProperty("--x", `${x}px`)
+    floating.style.setProperty("--y", `${y}px`)
 
-      onComplete?.(data)
-    })
+    const contentEl = floating.firstElementChild
+
+    if (contentEl) {
+      const zIndex = win.getComputedStyle(contentEl).zIndex
+      floating.style.setProperty("--z-index", zIndex)
+    }
   }
 
-  compute()
+  const update = async () => {
+    if (opts.updatePosition) {
+      await opts.updatePosition({ updatePosition })
+      onPositioned?.({ placed: true })
+    } else {
+      await updatePosition()
+    }
+  }
 
-  return callAll(
-    options.listeners ? autoUpdate(reference, floating, compute, options.listeners) : undefined,
-    options.onCleanup,
-  )
-}
+  const cancelAutoUpdate = options.listeners ? autoUpdate(reference, floating, update, options.listeners) : undefined
+
+  update()
 
-export function getBasePlacement(placement: Placement): BasePlacement {
-  return placement.split("-")[0] as BasePlacement
+  return () => {
+    cancelAutoUpdate?.()
+    onPositioned?.({ placed: false })
+    options.onCleanup?.()
+  }
 }
 
 export function getPlacement(
@@ -135,14 +174,14 @@ export function getPlacement(
   floatingOrFn: MaybeFn<MaybeElement>,
   opts: PositioningOptions & { defer?: boolean } = {},
 ) {
-  const { defer, ...restOptions } = opts
+  const { defer, ...options } = opts
   const func = defer ? raf : (v: any) => v()
   const cleanups: (VoidFunction | undefined)[] = []
   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 () => {

package/src/get-styles.ts

@@ -14,7 +14,7 @@ const ARROW_FLOATING_STYLE = {
 } as const
 
 export function getPlacementStyles(options: PositioningOptions = {}) {
-  const { placement = "bottom", sameWidth, fitViewport, strategy = "absolute" } = options
+  const { placement, sameWidth, fitViewport, strategy = "absolute" } = options
 
   return {
     arrow: {
@@ -26,7 +26,7 @@ export function getPlacementStyles(options: PositioningOptions = {}) {
     } as const,
 
     arrowTip: {
-      transform: ARROW_FLOATING_STYLE[placement.split("-")[0]],
+      transform: placement ? ARROW_FLOATING_STYLE[placement.split("-")[0]] : undefined,
       background: cssVars.arrowBg.reference,
       top: "0",
       left: "0",
@@ -45,7 +45,8 @@ export function getPlacementStyles(options: PositioningOptions = {}) {
       maxHeight: fitViewport ? "var(--available-height)" : undefined,
       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)",
     } as const,
   }

package/src/index.ts

@@ -1,10 +1,13 @@
-export { getBasePlacement, getPlacement } from "./get-placement"
+export { getPlacement } from "./get-placement"
 export { getPlacementStyles, type GetPlacementStylesOptions } from "./get-styles"
+export { getPlacementSide, isValidPlacement } from "./placement"
 export type {
+  AnchorRect,
   AutoUpdateOptions,
-  BasePlacement,
   Boundary,
   ComputePositionReturn,
   Placement,
+  PlacementAlign,
+  PlacementSide,
   PositioningOptions,
 } from "./types"

package/src/middleware.ts

@@ -1,4 +1,5 @@
 import type { Coords, Middleware } from "@floating-ui/dom"
+import type { PlacementSide } from "./types"
 
 /* -----------------------------------------------------------------------------
  * Shared middleware utils
@@ -33,7 +34,7 @@ const getTransformOrigin = (arrow?: Partial<Coords>) => ({
   "right-end": arrow ? `left ${arrow.y}px` : "left bottom",
 })
 
-export const transformOrigin: Middleware = {
+export const __transformOrigin: Middleware = {
   name: "transformOrigin",
   fn({ placement, elements, middlewareData }) {
     const { arrow } = middlewareData
@@ -52,27 +53,22 @@ export const transformOrigin: Middleware = {
  * Arrow Middleware
  * -----------------------------------------------------------------------------*/
 
-type ArrowOptions = { element: HTMLElement }
-
-type BasePlacement = "top" | "bottom" | "left" | "right"
-
-export const shiftArrow = (opts: ArrowOptions): Middleware => ({
-  name: "shiftArrow",
-  fn({ placement, middlewareData }) {
-    const { element: arrow } = opts
-
-    if (middlewareData.arrow) {
+export const __shiftArrow = (arrowEl: HTMLElement | null): Middleware | undefined => {
+  if (!arrowEl) return
+  return {
+    name: "shiftArrow",
+    fn({ placement, middlewareData }) {
+      if (!middlewareData.arrow) return {}
       const { x, y } = middlewareData.arrow
+      const dir = placement.split("-")[0] as PlacementSide
 
-      const dir = placement.split("-")[0] as BasePlacement
-
-      Object.assign(arrow.style, {
+      Object.assign(arrowEl.style, {
         left: x != null ? `${x}px` : "",
         top: y != null ? `${y}px` : "",
         [dir]: `calc(100% + ${cssVars.arrowOffset.reference})`,
       })
-    }
 
-    return {}
-  },
-})
+      return {}
+    },
+  }
+}

package/src/placement.ts

@@ -0,0 +1,15 @@
+import type { Placement } from "@floating-ui/dom"
+import type { PlacementAlign, PlacementSide } from "./types"
+
+export function isValidPlacement(v: string): v is Placement {
+  return /^(?:top|bottom|left|right)(?:-(?:start|end))?$/.test(v)
+}
+
+export function getPlacementDetails(placement: Placement) {
+  const [side, align] = placement.split("-") as [PlacementSide, PlacementAlign | undefined]
+  return { side, align, hasAlign: align != null }
+}
+
+export function getPlacementSide(placement: Placement): PlacementSide {
+  return placement.split("-")[0] as PlacementSide
+}

package/src/types.ts

@@ -1,7 +1,21 @@
-import type { Boundary, ComputePositionReturn, Placement } from "@floating-ui/dom"
+import type { Boundary, ComputePositionReturn, Placement, VirtualElement } from "@floating-ui/dom"
 import type { AutoUpdateOptions } from "./auto-update"
 
-export type { Placement, Boundary, ComputePositionReturn, AutoUpdateOptions }
+export type MaybeRectElement = HTMLElement | VirtualElement | null
+
+export type MaybeElement = HTMLElement | null
+
+export type MaybeFn<T> = T | (() => T)
+
+export type PlacementSide = "top" | "right" | "bottom" | "left"
+export type PlacementAlign = "start" | "center" | "end"
+
+export interface AnchorRect {
+  x?: number
+  y?: number
+  width?: number
+  height?: number
+}
 
 export interface PositioningOptions {
   /**
@@ -20,14 +34,27 @@ export 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
@@ -53,10 +80,23 @@ export 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>
 }
 
-export type BasePlacement = "top" | "right" | "bottom" | "left"
+export type { AutoUpdateOptions, Boundary, ComputePositionReturn, Placement }