@zag-js/popper 0.9.2 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zag-js/popper",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "Dynamic positioning logic for ui machines",
   "keywords": [
     "js",
@@ -13,7 +13,8 @@
   "repository": "https://github.com/chakra-ui/zag/tree/main/packages/utilities/popper",
   "sideEffects": false,
   "files": [
-    "dist/**/*"
+    "dist",
+    "src"
   ],
   "publishConfig": {
     "access": "public"
@@ -22,10 +23,10 @@
     "url": "https://github.com/chakra-ui/zag/issues"
   },
   "dependencies": {
-    "@floating-ui/dom": "1.2.8",
-    "@zag-js/dom-query": "0.9.2",
-    "@zag-js/element-rect": "0.9.2",
-    "@zag-js/utils": "0.9.2"
+    "@floating-ui/dom": "1.2.9",
+    "@zag-js/dom-query": "0.10.0",
+    "@zag-js/element-rect": "0.10.0",
+    "@zag-js/utils": "0.10.0"
   },
   "devDependencies": {
     "clean-package": "2.2.0"

package/src/auto-update.ts

@@ -0,0 +1,67 @@
+import type { Placement, ReferenceElement } from "@floating-ui/dom"
+import { getOverflowAncestors } from "@floating-ui/dom"
+import { trackElementRect } from "@zag-js/element-rect"
+
+export type { Placement }
+
+export type AutoUpdateOptions = {
+  ancestorScroll?: boolean
+  ancestorResize?: boolean
+  referenceResize?: boolean
+}
+
+type Ancestors = ReturnType<typeof getOverflowAncestors>
+
+const callAll =
+  (...fns: VoidFunction[]) =>
+  () =>
+    fns.forEach((fn) => fn())
+
+const isHTMLElement = (el: any): el is HTMLElement => {
+  return typeof el === "object" && el !== null && el.nodeType === 1
+}
+
+const addDomEvent = (el: HTMLElement, type: string, fn: VoidFunction, options?: boolean | AddEventListenerOptions) => {
+  el.addEventListener(type, fn, options)
+  return () => el.removeEventListener(type, fn, options)
+}
+
+function resolveOptions(option: boolean | AutoUpdateOptions) {
+  const bool = typeof option === "boolean"
+  return {
+    ancestorResize: bool ? option : option.ancestorResize ?? true,
+    ancestorScroll: bool ? option : option.ancestorScroll ?? true,
+    referenceResize: bool ? option : option.referenceResize ?? true,
+  }
+}
+
+export function autoUpdate(
+  reference: ReferenceElement,
+  floating: HTMLElement,
+  update: () => void,
+  options: boolean | AutoUpdateOptions = false,
+) {
+  const { ancestorScroll, ancestorResize, referenceResize } = resolveOptions(options)
+
+  const useAncestors = ancestorScroll || ancestorResize
+  const ancestors: Ancestors = []
+
+  if (useAncestors && isHTMLElement(reference)) {
+    ancestors.push(...getOverflowAncestors(reference))
+  }
+
+  function addResizeListeners() {
+    let cleanups: VoidFunction[] = [trackElementRect(floating, { scope: "size", onChange: update })]
+    if (referenceResize && isHTMLElement(reference)) {
+      cleanups.push(trackElementRect(reference, { onChange: update }))
+    }
+    cleanups.push(callAll(...ancestors.map((el: any) => addDomEvent(el, "resize", update))))
+    return () => cleanups.forEach((fn) => fn())
+  }
+
+  function addScrollListeners() {
+    return callAll(...ancestors.map((el: any) => addDomEvent(el, "scroll", update, { passive: true })))
+  }
+
+  return callAll(addResizeListeners(), addScrollListeners())
+}

package/src/get-placement.ts

@@ -0,0 +1,156 @@
+import type { Middleware, Placement, VirtualElement } from "@floating-ui/dom"
+import { ComputePositionConfig, arrow, computePosition, flip, offset, shift, size } from "@floating-ui/dom"
+import { raf } from "@zag-js/dom-query"
+import { callAll } from "@zag-js/utils"
+import { autoUpdate } from "./auto-update"
+import { shiftArrow, transformOrigin } from "./middleware"
+import type { BasePlacement, PositioningOptions } from "./types"
+
+const defaultOptions: PositioningOptions = {
+  strategy: "absolute",
+  placement: "bottom",
+  listeners: true,
+  gutter: 8,
+  flip: true,
+  sameWidth: false,
+  overflowPadding: 8,
+}
+
+type MaybeRectElement = HTMLElement | VirtualElement | null
+type MaybeElement = HTMLElement | null
+type MaybeFn<T> = T | (() => T)
+
+function getPlacementImpl(reference: MaybeRectElement, floating: MaybeElement, opts: PositioningOptions = {}) {
+  if (!floating || !reference) return
+
+  const options = Object.assign({}, defaultOptions, opts)
+
+  /* -----------------------------------------------------------------------------
+   * The middleware stack
+   * -----------------------------------------------------------------------------*/
+
+  const arrowEl = floating.querySelector<HTMLElement>("[data-part=arrow]")
+  const middleware: Middleware[] = []
+
+  const boundary = typeof options.boundary === "function" ? options.boundary() : options.boundary
+
+  if (options.flip) {
+    middleware.push(
+      flip({
+        boundary,
+        padding: options.overflowPadding,
+      }),
+    )
+  }
+
+  if (options.gutter || options.offset) {
+    const arrowOffset = arrowEl ? arrowEl.offsetHeight / 2 : 0
+    const data = options.gutter ? { mainAxis: options.gutter } : options.offset
+    if (data?.mainAxis != null) data.mainAxis += arrowOffset
+    middleware.push(offset(data))
+  }
+
+  middleware.push(
+    shift({
+      boundary,
+      crossAxis: options.overlap,
+      padding: options.overflowPadding,
+    }),
+  )
+
+  if (arrowEl) {
+    // prettier-ignore
+    middleware.push(
+      arrow({ element: arrowEl, padding: 8 }),
+      shiftArrow({ element: arrowEl }),
+    )
+  }
+
+  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`)
+
+        if (options.sameWidth) {
+          Object.assign(floating.style, {
+            width: `${referenceWidth}px`,
+            minWidth: "unset",
+          })
+        }
+
+        if (options.fitViewport) {
+          Object.assign(floating.style, {
+            maxWidth: `${availableWidth}px`,
+            maxHeight: `${availableHeight}px`,
+          })
+        }
+      },
+    }),
+  )
+
+  /* -----------------------------------------------------------------------------
+   * The actual positioning function
+   * -----------------------------------------------------------------------------*/
+
+  function compute(config: Omit<ComputePositionConfig, "platform"> = {}) {
+    if (!reference || !floating) return
+    const { placement, strategy, onComplete } = options
+
+    computePosition(reference, floating, {
+      placement,
+      middleware,
+      strategy,
+      ...config,
+    }).then((data) => {
+      const x = Math.round(data.x)
+      const y = Math.round(data.y)
+
+      Object.assign(floating.style, {
+        position: data.strategy,
+        top: "0px",
+        left: "0px",
+        transform: `translate3d(${x}px, ${y}px, 0)`,
+      })
+
+      onComplete?.(data)
+    })
+  }
+
+  compute()
+
+  return callAll(
+    options.listeners ? autoUpdate(reference, floating, compute, options.listeners) : undefined,
+    options.onCleanup,
+  )
+}
+
+export function getBasePlacement(placement: Placement): BasePlacement {
+  return placement.split("-")[0] as BasePlacement
+}
+
+export function getPlacement(
+  referenceOrFn: MaybeFn<MaybeRectElement>,
+  floatingOrFn: MaybeFn<MaybeElement>,
+  opts: PositioningOptions & { defer?: boolean } = {},
+) {
+  const { defer, ...restOptions } = 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))
+    }),
+  )
+  return () => {
+    cleanups.forEach((fn) => fn?.())
+  }
+}

package/src/get-styles.ts

@@ -0,0 +1,45 @@
+import type { Placement } from "@floating-ui/dom"
+import { cssVars } from "./middleware"
+
+type Options = {
+  placement?: Placement
+}
+
+const ARROW_FLOATING_STYLE = {
+  bottom: "rotate(45deg)",
+  left: "rotate(135deg)",
+  top: "rotate(225deg)",
+  right: "rotate(315deg)",
+} as const
+
+export function getPlacementStyles(options: Options) {
+  const { placement = "bottom" } = options
+
+  return {
+    arrow: {
+      position: "absolute",
+      width: cssVars.arrowSize.reference,
+      height: cssVars.arrowSize.reference,
+      [cssVars.arrowSizeHalf.variable]: `calc(${cssVars.arrowSize.reference} / 2)`,
+      [cssVars.arrowOffset.variable]: `calc(${cssVars.arrowSizeHalf.reference} * -1)`,
+    } as const,
+
+    arrowTip: {
+      transform: ARROW_FLOATING_STYLE[placement.split("-")[0]],
+      background: cssVars.arrowBg.reference,
+      top: "0",
+      left: "0",
+      width: "100%",
+      height: "100%",
+      position: "absolute",
+      zIndex: "inherit",
+    } as const,
+
+    floating: {
+      position: "absolute",
+      minWidth: "max-content",
+      top: "0px",
+      left: "0px",
+    } as const,
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { getPlacement, getBasePlacement } from "./get-placement"
+export { getPlacementStyles } from "./get-styles"
+export type { Placement, PositioningOptions } from "./types"

package/src/middleware.ts

@@ -0,0 +1,78 @@
+import type { Coords, Middleware } from "@floating-ui/dom"
+
+/* -----------------------------------------------------------------------------
+ * Shared middleware utils
+ * -----------------------------------------------------------------------------*/
+
+const toVar = (value: string) => ({ variable: value, reference: `var(${value})` })
+
+export const cssVars = {
+  arrowSize: toVar("--arrow-size"),
+  arrowSizeHalf: toVar("--arrow-size-half"),
+  arrowBg: toVar("--arrow-background"),
+  transformOrigin: toVar("--transform-origin"),
+  arrowOffset: toVar("--arrow-offset"),
+}
+
+/* -----------------------------------------------------------------------------
+ * Transform Origin Middleware
+ * -----------------------------------------------------------------------------*/
+
+const getTransformOrigin = (arrow?: Partial<Coords>) => ({
+  top: "bottom center",
+  "top-start": arrow ? `${arrow.x}px bottom` : "left bottom",
+  "top-end": arrow ? `${arrow.x}px bottom` : "right bottom",
+  bottom: "top center",
+  "bottom-start": arrow ? `${arrow.x}px top` : "top left",
+  "bottom-end": arrow ? `${arrow.x}px top` : "top right",
+  left: "right center",
+  "left-start": arrow ? `right ${arrow.y}px` : "right top",
+  "left-end": arrow ? `right ${arrow.y}px` : "right bottom",
+  right: "left center",
+  "right-start": arrow ? `left ${arrow.y}px` : "left top",
+  "right-end": arrow ? `left ${arrow.y}px` : "left bottom",
+})
+
+export const transformOrigin: Middleware = {
+  name: "transformOrigin",
+  fn({ placement, elements, middlewareData }) {
+    const { arrow } = middlewareData
+    const transformOrigin = getTransformOrigin(arrow)[placement]
+
+    const { floating } = elements
+    floating.style.setProperty(cssVars.transformOrigin.variable, transformOrigin)
+
+    return {
+      data: { transformOrigin },
+    }
+  },
+}
+
+/* -----------------------------------------------------------------------------
+ * 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) {
+      const { x, y } = middlewareData.arrow
+
+      const dir = placement.split("-")[0] as BasePlacement
+
+      Object.assign(arrow.style, {
+        left: x != null ? `${x}px` : "",
+        top: y != null ? `${y}px` : "",
+        [dir]: `calc(100% + ${cssVars.arrowOffset.reference})`,
+      })
+    }
+
+    return {}
+  },
+})

package/src/types.ts

@@ -0,0 +1,62 @@
+import type { Boundary, ComputePositionReturn, Placement } from "@floating-ui/dom"
+import type { AutoUpdateOptions } from "./auto-update"
+
+export type { Placement }
+
+export type PositioningOptions = {
+  /**
+   * The strategy to use for positioning
+   */
+  strategy?: "absolute" | "fixed"
+  /**
+   * The initial placement of the floating element
+   */
+  placement?: Placement
+  /**
+   * The offset of the floating element
+   */
+  offset?: { mainAxis?: number; crossAxis?: number }
+  /**
+   * The main axis offset or gap between the reference and floating elements
+   */
+  gutter?: number
+  /**
+   * The virtual padding around the viewport edges to check for overflow
+   */
+  overflowPadding?: number
+  /**
+   * Whether to flip the placement
+   */
+  flip?: boolean
+  /**
+   * Whether the floating element can overlap the reference element
+   * @default false
+   */
+  overlap?: boolean
+  /**
+   * Whether to make the floating element same width as the reference element
+   */
+  sameWidth?: boolean
+  /**
+   * Whether the popover should fit the viewport.
+   */
+  fitViewport?: boolean
+  /**
+   * The overflow boundary of the reference element
+   */
+  boundary?: Boundary | (() => Boundary)
+  /**
+   * Options to activate auto-update listeners
+   */
+  listeners?: boolean | AutoUpdateOptions
+  /**
+   * Function called when the placement is computed
+   */
+  onComplete?(data: ComputePositionReturn): void
+  /**
+   * Function called on cleanup of all listeners
+   */
+  onCleanup?: VoidFunction
+}
+
+export type BasePlacement = "top" | "right" | "bottom" | "left"