@zag-js/popover 0.0.0-dev-20230526205409 → 0.0.0-dev-20230526210710

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zag-js/popover",
-  "version": "0.0.0-dev-20230526205409",
+  "version": "0.0.0-dev-20230526210710",
   "description": "Core logic for the popover widget implemented as a state machine",
   "keywords": [
     "js",
@@ -17,7 +17,8 @@
   "repository": "https://github.com/chakra-ui/zag/tree/main/packages/popover",
   "sideEffects": false,
   "files": [
-    "dist/**/*"
+    "dist",
+    "src"
   ],
   "publishConfig": {
     "access": "public"
@@ -27,16 +28,16 @@
   },
   "dependencies": {
     "focus-trap": "7.4.1",
-    "@zag-js/anatomy": "0.0.0-dev-20230526205409",
-    "@zag-js/aria-hidden": "0.0.0-dev-20230526205409",
-    "@zag-js/core": "0.0.0-dev-20230526205409",
-    "@zag-js/dom-query": "0.0.0-dev-20230526205409",
-    "@zag-js/utils": "0.0.0-dev-20230526205409",
-    "@zag-js/dismissable": "0.0.0-dev-20230526205409",
-    "@zag-js/tabbable": "0.0.0-dev-20230526205409",
-    "@zag-js/popper": "0.0.0-dev-20230526205409",
-    "@zag-js/remove-scroll": "0.0.0-dev-20230526205409",
-    "@zag-js/types": "0.0.0-dev-20230526205409"
+    "@zag-js/anatomy": "0.0.0-dev-20230526210710",
+    "@zag-js/aria-hidden": "0.0.0-dev-20230526210710",
+    "@zag-js/core": "0.0.0-dev-20230526210710",
+    "@zag-js/dom-query": "0.0.0-dev-20230526210710",
+    "@zag-js/utils": "0.0.0-dev-20230526210710",
+    "@zag-js/dismissable": "0.0.0-dev-20230526210710",
+    "@zag-js/tabbable": "0.0.0-dev-20230526210710",
+    "@zag-js/popper": "0.0.0-dev-20230526210710",
+    "@zag-js/remove-scroll": "0.0.0-dev-20230526210710",
+    "@zag-js/types": "0.0.0-dev-20230526210710"
   },
   "devDependencies": {
     "clean-package": "2.2.0"

package/src/index.ts

@@ -0,0 +1,4 @@
+export { anatomy } from "./popover.anatomy"
+export { connect } from "./popover.connect"
+export { machine } from "./popover.machine"
+export type { UserDefinedContext as Context } from "./popover.types"

package/src/popover.anatomy.ts

@@ -0,0 +1,14 @@
+import { createAnatomy } from "@zag-js/anatomy"
+
+export const anatomy = createAnatomy("popover").parts(
+  "arrow",
+  "arrowTip",
+  "anchor",
+  "trigger",
+  "positioner",
+  "content",
+  "title",
+  "description",
+  "closeTrigger",
+)
+export const parts = anatomy.build()

package/src/popover.connect.ts

@@ -0,0 +1,119 @@
+import { dataAttr } from "@zag-js/dom-query"
+import type { PositioningOptions } from "@zag-js/popper"
+import { getPlacementStyles } from "@zag-js/popper"
+import type { NormalizeProps, PropTypes } from "@zag-js/types"
+import { parts } from "./popover.anatomy"
+import { dom } from "./popover.dom"
+import type { Send, State } from "./popover.types"
+
+export function connect<T extends PropTypes>(state: State, send: Send, normalize: NormalizeProps<T>) {
+  const isOpen = state.matches("open")
+
+  const currentPlacement = state.context.currentPlacement
+  const portalled = state.context.currentPortalled
+  const rendered = state.context.renderedElements
+
+  const popperStyles = getPlacementStyles({
+    placement: currentPlacement,
+  })
+
+  return {
+    /**
+     * Whether the popover is portalled
+     */
+    portalled,
+    /**
+     * Whether the popover is open
+     */
+    isOpen,
+    /**
+     * Function to open the popover
+     */
+    open() {
+      send("OPEN")
+    },
+    /**
+     * Function to close the popover
+     */
+    close() {
+      send("CLOSE")
+    },
+    /**
+     * Function to reposition the popover
+     */
+    setPositioning(options: Partial<PositioningOptions> = {}) {
+      send({ type: "SET_POSITIONING", options })
+    },
+
+    arrowProps: normalize.element({
+      id: dom.getArrowId(state.context),
+      ...parts.arrow.attrs,
+      style: popperStyles.arrow,
+    }),
+
+    arrowTipProps: normalize.element({
+      ...parts.arrowTip.attrs,
+      style: popperStyles.arrowTip,
+    }),
+
+    anchorProps: normalize.element({
+      ...parts.anchor.attrs,
+      id: dom.getAnchorId(state.context),
+    }),
+
+    triggerProps: normalize.button({
+      ...parts.trigger.attrs,
+      type: "button",
+      "data-placement": currentPlacement,
+      id: dom.getTriggerId(state.context),
+      "aria-haspopup": "dialog",
+      "aria-expanded": isOpen,
+      "data-expanded": dataAttr(isOpen),
+      "aria-controls": dom.getContentId(state.context),
+      onClick() {
+        send("TOGGLE")
+      },
+      onBlur(event) {
+        send({ type: "TRIGGER_BLUR", target: event.relatedTarget })
+      },
+    }),
+
+    positionerProps: normalize.element({
+      id: dom.getPositionerId(state.context),
+      ...parts.positioner.attrs,
+      style: popperStyles.floating,
+    }),
+
+    contentProps: normalize.element({
+      ...parts.content.attrs,
+      id: dom.getContentId(state.context),
+      tabIndex: -1,
+      role: "dialog",
+      hidden: !isOpen,
+      "data-expanded": dataAttr(isOpen),
+      "aria-labelledby": rendered.title ? dom.getTitleId(state.context) : undefined,
+      "aria-describedby": rendered.description ? dom.getDescriptionId(state.context) : undefined,
+      "data-placement": currentPlacement,
+    }),
+
+    titleProps: normalize.element({
+      ...parts.title.attrs,
+      id: dom.getTitleId(state.context),
+    }),
+
+    descriptionProps: normalize.element({
+      ...parts.description.attrs,
+      id: dom.getDescriptionId(state.context),
+    }),
+
+    closeTriggerProps: normalize.button({
+      ...parts.closeTrigger.attrs,
+      id: dom.getCloseTriggerId(state.context),
+      type: "button",
+      "aria-label": "close",
+      onClick() {
+        send("REQUEST_CLOSE")
+      },
+    }),
+  }
+}

package/src/popover.dom.ts

@@ -0,0 +1,39 @@
+import { createScope } from "@zag-js/dom-query"
+import { getFirstTabbable, getFocusables, getLastTabbable, getTabbables } from "@zag-js/tabbable"
+import { runIfFn } from "@zag-js/utils"
+import type { MachineContext as Ctx } from "./popover.types"
+
+export const dom = createScope({
+  getActiveEl: (ctx: Ctx) => dom.getDoc(ctx).activeElement,
+
+  getAnchorId: (ctx: Ctx) => ctx.ids?.anchor ?? `popover:${ctx.id}:anchor`,
+  getTriggerId: (ctx: Ctx) => ctx.ids?.trigger ?? `popover:${ctx.id}:trigger`,
+  getContentId: (ctx: Ctx) => ctx.ids?.content ?? `popover:${ctx.id}:content`,
+  getPositionerId: (ctx: Ctx) => ctx.ids?.positioner ?? `popover:${ctx.id}:popper`,
+  getArrowId: (ctx: Ctx) => ctx.ids?.arrow ?? `popover:${ctx.id}:arrow`,
+  getTitleId: (ctx: Ctx) => ctx.ids?.title ?? `popover:${ctx.id}:title`,
+  getDescriptionId: (ctx: Ctx) => ctx.ids?.description ?? `popover:${ctx.id}:desc`,
+  getCloseTriggerId: (ctx: Ctx) => ctx.ids?.closeTrigger ?? `popover:${ctx.id}:close`,
+
+  getAnchorEl: (ctx: Ctx) => dom.getById(ctx, dom.getAnchorId(ctx)),
+  getTriggerEl: (ctx: Ctx) => dom.getById(ctx, dom.getTriggerId(ctx)),
+  getContentEl: (ctx: Ctx) => dom.getById(ctx, dom.getContentId(ctx)),
+  getPositionerEl: (ctx: Ctx) => dom.getById(ctx, dom.getPositionerId(ctx)),
+  getTitleEl: (ctx: Ctx) => dom.getById(ctx, dom.getTitleId(ctx)),
+  getDescriptionEl: (ctx: Ctx) => dom.getById(ctx, dom.getDescriptionId(ctx)),
+
+  getFocusableEls: (ctx: Ctx) => getFocusables(dom.getContentEl(ctx)),
+  getFirstFocusableEl: (ctx: Ctx) => dom.getFocusableEls(ctx)[0],
+
+  getDocTabbableEls: (ctx: Ctx) => getTabbables(dom.getDoc(ctx).body),
+  getTabbableEls: (ctx: Ctx) => getTabbables(dom.getContentEl(ctx), "if-empty"),
+  getFirstTabbableEl: (ctx: Ctx) => getFirstTabbable(dom.getContentEl(ctx), "if-empty"),
+  getLastTabbableEl: (ctx: Ctx) => getLastTabbable(dom.getContentEl(ctx), "if-empty"),
+
+  getInitialFocusEl: (ctx: Ctx) => {
+    let el: HTMLElement | null = runIfFn(ctx.initialFocusEl)
+    if (!el && ctx.autoFocus) el = dom.getFirstFocusableEl(ctx)
+    if (!el) el = dom.getContentEl(ctx)
+    return el
+  },
+})

package/src/popover.machine.ts

@@ -0,0 +1,222 @@
+import { ariaHidden } from "@zag-js/aria-hidden"
+import { createMachine } from "@zag-js/core"
+import { trackDismissableElement } from "@zag-js/dismissable"
+import { nextTick, raf } from "@zag-js/dom-query"
+import { getPlacement } from "@zag-js/popper"
+import { preventBodyScroll } from "@zag-js/remove-scroll"
+import { proxyTabFocus } from "@zag-js/tabbable"
+import { compact, runIfFn } from "@zag-js/utils"
+import { FocusTrap, createFocusTrap } from "focus-trap"
+import { dom } from "./popover.dom"
+import type { MachineContext, MachineState, UserDefinedContext } from "./popover.types"
+
+export function machine(userContext: UserDefinedContext) {
+  const ctx = compact(userContext)
+  return createMachine<MachineContext, MachineState>(
+    {
+      id: "popover",
+      initial: ctx.open ? "open" : "closed",
+      context: {
+        closeOnInteractOutside: true,
+        closeOnEsc: true,
+        autoFocus: true,
+        modal: false,
+        positioning: {
+          placement: "bottom",
+          ...ctx.positioning,
+        },
+        currentPlacement: undefined,
+        ...ctx,
+        renderedElements: {
+          title: true,
+          description: true,
+        },
+      },
+
+      computed: {
+        currentPortalled: (ctx) => !!ctx.modal || !!ctx.portalled,
+      },
+
+      watch: {
+        open: ["toggleVisibility"],
+      },
+
+      entry: ["checkRenderedElements"],
+
+      states: {
+        closed: {
+          on: {
+            TOGGLE: {
+              target: "open",
+              actions: ["invokeOnOpen"],
+            },
+            OPEN: {
+              target: "open",
+              actions: ["invokeOnOpen"],
+            },
+          },
+        },
+
+        open: {
+          activities: [
+            "trapFocus",
+            "preventScroll",
+            "hideContentBelow",
+            "trackPositioning",
+            "trackDismissableElement",
+            "proxyTabFocus",
+          ],
+          entry: ["setInitialFocus"],
+          on: {
+            CLOSE: {
+              target: "closed",
+              actions: ["invokeOnClose"],
+            },
+            REQUEST_CLOSE: {
+              target: "closed",
+              actions: ["restoreFocusIfNeeded", "invokeOnClose"],
+            },
+            TOGGLE: {
+              target: "closed",
+              actions: ["invokeOnClose"],
+            },
+            SET_POSITIONING: {
+              actions: "setPositioning",
+            },
+          },
+        },
+      },
+    },
+    {
+      activities: {
+        trackPositioning(ctx) {
+          ctx.currentPlacement = ctx.positioning.placement
+          const anchorEl = dom.getAnchorEl(ctx) ?? dom.getTriggerEl(ctx)
+          const getPositionerEl = () => dom.getPositionerEl(ctx)
+          return getPlacement(anchorEl, getPositionerEl, {
+            ...ctx.positioning,
+            defer: true,
+            onComplete(data) {
+              ctx.currentPlacement = data.placement
+            },
+            onCleanup() {
+              ctx.currentPlacement = undefined
+            },
+          })
+        },
+        trackDismissableElement(ctx, _evt, { send }) {
+          const getContentEl = () => dom.getContentEl(ctx)
+          let restoreFocus = true
+          return trackDismissableElement(getContentEl, {
+            pointerBlocking: ctx.modal,
+            exclude: dom.getTriggerEl(ctx),
+            defer: true,
+            onEscapeKeyDown(event) {
+              ctx.onEscapeKeyDown?.(event)
+              if (ctx.closeOnEsc) return
+              event.preventDefault()
+            },
+            onInteractOutside(event) {
+              ctx.onInteractOutside?.(event)
+              if (event.defaultPrevented) return
+              restoreFocus = !(event.detail.focusable || event.detail.contextmenu)
+              if (!ctx.closeOnInteractOutside) {
+                event.preventDefault()
+              }
+            },
+            onPointerDownOutside(event) {
+              ctx.onPointerDownOutside?.(event)
+            },
+            onFocusOutside(event) {
+              ctx.onFocusOutside?.(event)
+            },
+            onDismiss() {
+              send({ type: "REQUEST_CLOSE", src: "interact-outside", restoreFocus })
+            },
+          })
+        },
+        proxyTabFocus(ctx) {
+          if (ctx.modal || !ctx.portalled) return
+          const getContentEl = () => dom.getContentEl(ctx)
+          return proxyTabFocus(getContentEl, {
+            triggerElement: dom.getTriggerEl(ctx),
+            defer: true,
+            onFocus(el) {
+              el.focus({ preventScroll: true })
+            },
+          })
+        },
+        hideContentBelow(ctx) {
+          if (!ctx.modal) return
+          const getElements = () => [dom.getContentEl(ctx), dom.getTriggerEl(ctx)]
+          return ariaHidden(getElements, { defer: true })
+        },
+        preventScroll(ctx) {
+          if (!ctx.modal) return
+          return preventBodyScroll(dom.getDoc(ctx))
+        },
+        trapFocus(ctx) {
+          if (!ctx.modal) return
+          let trap: FocusTrap | undefined
+          nextTick(() => {
+            const el = dom.getContentEl(ctx)
+            if (!el) return
+            trap = createFocusTrap(el, {
+              escapeDeactivates: false,
+              allowOutsideClick: true,
+              preventScroll: true,
+              returnFocusOnDeactivate: true,
+              document: dom.getDoc(ctx),
+              fallbackFocus: el,
+              initialFocus: runIfFn(ctx.initialFocusEl),
+            })
+            try {
+              trap.activate()
+            } catch {}
+          })
+          return () => trap?.deactivate()
+        },
+      },
+      actions: {
+        setPositioning(ctx, evt) {
+          const anchorEl = dom.getAnchorEl(ctx) ?? dom.getTriggerEl(ctx)
+          const getPositionerEl = () => dom.getPositionerEl(ctx)
+          getPlacement(anchorEl, getPositionerEl, {
+            ...ctx.positioning,
+            ...evt.options,
+            defer: true,
+            listeners: false,
+          })
+        },
+        checkRenderedElements(ctx) {
+          raf(() => {
+            Object.assign(ctx.renderedElements, {
+              title: !!dom.getTitleEl(ctx),
+              description: !!dom.getDescriptionEl(ctx),
+            })
+          })
+        },
+        setInitialFocus(ctx) {
+          raf(() => {
+            dom.getInitialFocusEl(ctx)?.focus({ preventScroll: true })
+          })
+        },
+        restoreFocusIfNeeded(ctx, evt) {
+          if (!evt.restoreFocus) return
+          raf(() => {
+            dom.getTriggerEl(ctx)?.focus({ preventScroll: true })
+          })
+        },
+        invokeOnOpen(ctx) {
+          ctx.onOpen?.()
+        },
+        invokeOnClose(ctx) {
+          ctx.onClose?.()
+        },
+        toggleVisibility(ctx, _evt, { send }) {
+          send({ type: ctx.open ? "OPEN" : "CLOSE", src: "controlled" })
+        },
+      },
+    },
+  )
+}

package/src/popover.types.ts

@@ -0,0 +1,106 @@
+import type { StateMachine as S } from "@zag-js/core"
+import type { DismissableElementHandlers } from "@zag-js/dismissable"
+import type { PositioningOptions, Placement } from "@zag-js/popper"
+import type { CommonProperties, Context, MaybeElement, RequiredBy } from "@zag-js/types"
+
+type ElementIds = Partial<{
+  anchor: string
+  trigger: string
+  content: string
+  title: string
+  description: string
+  closeTrigger: string
+  positioner: string
+  arrow: string
+}>
+
+type PublicContext = DismissableElementHandlers &
+  CommonProperties & {
+    /**
+     * The ids of the elements in the popover. Useful for composition.
+     */
+    ids?: ElementIds
+    /**
+     * Whether the popover should be modal. When set to `true`:
+     * - interaction with outside elements will be disabled
+     * - only popover content will be visible to screen readers
+     * - scrolling is blocked
+     * - focus is trapped within the popover
+     *
+     * @default false
+     */
+    modal?: boolean
+    /**
+     * Whether the popover is rendered in a portal
+     */
+    portalled?: boolean
+    /**
+     * Whether to automatically set focus on the first focusable
+     * content within the popover when opened.
+     */
+    autoFocus?: boolean
+    /**
+     * The element to focus on when the popover is opened.
+     */
+    initialFocusEl?: MaybeElement | (() => MaybeElement)
+    /**
+     * Whether to close the popover when the user clicks outside of the popover.
+     */
+    closeOnInteractOutside?: boolean
+    /**
+     * Whether to close the popover when the escape key is pressed.
+     */
+    closeOnEsc?: boolean
+    /**
+     * Function invoked when the popover is closed
+     */
+    onClose?: VoidFunction
+    /**
+     * Function invoked when the popover is opened
+     */
+    onOpen?: VoidFunction
+    /**
+     * The user provided options used to position the popover content
+     */
+    positioning: PositioningOptions
+    /**
+     * Whether the popover is open
+     */
+    open?: boolean
+  }
+
+export type UserDefinedContext = RequiredBy<PublicContext, "id">
+
+type ComputedContext = Readonly<{
+  /**
+   * @computed
+   * The computed value of `portalled`
+   */
+  currentPortalled: boolean
+}>
+
+type PrivateContext = Context<{
+  /**
+   * @internal
+   * The elements that are rendered on mount
+   */
+  renderedElements: {
+    title: boolean
+    description: boolean
+  }
+  /**
+   * @internal
+   * The computed placement (maybe different from initial placement)
+   */
+  currentPlacement?: Placement
+}>
+
+export type MachineContext = PublicContext & ComputedContext & PrivateContext
+
+export type MachineState = {
+  value: "open" | "closed"
+}
+
+export type State = S.State<MachineContext, MachineState>
+
+export type Send = S.Send<S.AnyEventObject>